capybara-simulated 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 692a6a8f67870e2078ba815a0698831f3cec4ada4dc3d79d9af795156107e37b
-  data.tar.gz: 734a4cfe94f4cd93367b95082619e10729cb4ebf1f83a890b4d87c78ce5fd3cf
+  metadata.gz: 02f56bfd3215e67c4a8faa799352e0ae3c399557f928926cafcdc9dde7dd2b9c
+  data.tar.gz: 12e88e441d93de921d0727bfae9e3728cc56d100f8e32e525e37e21a28f0e273
 SHA512:
-  metadata.gz: 9c9bfde944aad7339e4d7153e2d49b3b6834662fc5bcaf945a63899ca580493d1c67bfbd625ce7e06683bdbfacab83fa8192af7f02a73d5228f080dc22fc1dda
-  data.tar.gz: da6971ee07edd867e00baa4e6d382ff291d5d0c8c437084f6f4d7dba50ae5c0596e4726db9be58f1d7a6847340fccff847d06d0056fdb8de3847a703887a4c28
+  metadata.gz: a1f22b4a5d7ffec1b33080982aa169b5b3356c014d49a399de4cf5b5a430021eec7fb1ba4d624b00769640ffdcd314e55df765afdd44ac90575c88cb137519c9
+  data.tar.gz: 04d95fd0e7215800124d4d81de11247b814e352c0b511d550bb9bb1557a0af069c1261b52a570e82f6100cab90e07d627b18b7a02267f193dd92c4c98c92e2cd

data/README.md

@@ -44,7 +44,9 @@ browser:
   `elementFromPoint()` isn't implemented, so visual hit-testing,
   coordinate drag-and-drop, and sticky-scroll math don't work.
 - **Real networking** — `fetch` / XHR are synchronous through Rack: no
-  streaming, no concurrency, no WebSocket.
+  streaming, no HTTP concurrency. (`EventSource` and `WebSocket` *do*
+  work — they ride real reader threads / the in-process `rack.hijack`
+  socket; see below.)
 - **Screenshots**.
 
 **`within_frame` / `switch_to_frame`** work on the V8 (rusty_racer) engine:
@@ -356,9 +358,21 @@ referenced page-specific DOM.
   but there's no real network, no streaming, no `Request#body`
   ReadableStream, and no concurrent requests. XHR is implemented
   with the same Rack pass-through.
-- **WebSocket, screenshots, and drag pixel coordinates** are out of
-  scope by design — use Selenium / Cuprite. (EventSource and Web
-  Workers *are* implemented.)
+- **WebSocket** works in-process: `new WebSocket(url)` rides the
+  `rack.hijack` socket the Rack app hijacks, with a hand-rolled RFC6455
+  client (handshake + subprotocol negotiation, masked client frames,
+  ping/pong, close handshake). Frames deliver as `message` events when
+  the page next settles, like SSE. **Action Cable** works end-to-end on
+  this: the real `@rails/actioncable` consumer connects, subscribes, and
+  receives server broadcasts (so `turbo_stream_from` live updates are
+  reachable) — Action Cable hijacks the connection just as csim drives
+  it. Caveats: server pushes land at settle (not instant); the app must
+  use the **async / in-process** Cable adapter (a real Redis adapter
+  would need real Redis); binary frames are V8-only (QuickJS corrupts
+  raw bytes across the host boundary — text, hence Action Cable, is fine
+  on both). `EventSource` and Web Workers are likewise implemented.
+- **Screenshots and drag pixel coordinates** are out of scope by
+  design — use Selenium / Cuprite.
 - **`within_frame` / `switch_to_frame`** work on the V8 engine: each
   `<iframe>` runs in its own per-frame realm and the DSL routes finds,
   reads, interactions, `evaluate_script`, and self-targeted navigation
@@ -376,9 +390,11 @@ referenced page-specific DOM.
   across windows (delivered as a `message` event when the target window next
   settles). Caveats: `target="_blank"` opens with no opener (modern-browser
   no-opener default); cross-window `postMessage` data is JSON-shaped, not a
-  full structured clone (no `DataCloneError`, `undefined`→`null`); and only
-  the active window's event loop runs, so a message is delivered when you
-  switch to its window. Window viewport APIs (`maximize` / `fullscreen` /
+  full structured clone (no `DataCloneError`, `undefined`→`null`) — but a
+  buffer in the `transfer` list moves **zero-copy** (its backing store crosses
+  isolates by token and the source is detached); and only the active window's
+  event loop runs, so a message is delivered when you switch to its window.
+  Window viewport APIs (`maximize` / `fullscreen` /
   pixel-exact `resize_to`) are no-ops — no layout engine.
 
 ## Architecture

data/lib/capybara/simulated/browser.rb

@@ -2,11 +2,13 @@
 
 require 'base64'
 require 'date'
+require 'digest'
 require 'fileutils'
 require 'json'
 require 'net/http'
 require 'openssl'
 require 'rack/mock'
+require 'securerandom'
 require 'socket'
 require 'thread'
 require 'time'
@@ -273,6 +275,23 @@ module Capybara
         @event_source_seq     = 0
         @event_source_threads = {}
         @event_source_queue   = Thread::Queue.new
+        # WebSocket — per-Browser handle counter, background frame-reader
+        # threads, the csim-side socket end of each connection (for writing
+        # client→server frames), and a Queue of lifecycle / message events
+        # awaiting delivery into the VM. Same model as SSE: the reader thread
+        # does the blocking socket read; the main thread drains the Queue in
+        # `settle` and dispatches via `__csim_deliverWebSocketEvents`. The
+        # connection rides the in-process `rack.hijack` socket Action Cable
+        # (and any Rack WebSocket middleware) takes over.
+        @websocket_seq        = 0
+        @websocket_threads    = {}
+        @websocket_sockets    = {}   # id → csim's socket end (main thread owns this hash)
+        @websocket_app_sockets = {}  # id → the app's hijack end (closed on teardown)
+        @websocket_queue      = Thread::Queue.new
+        # All frame writes (the reader thread's pong replies + the main thread's
+        # send/close) go through one socket; serialise them so two threads can't
+        # interleave bytes into a corrupt frame.
+        @websocket_write_lock = Mutex.new
         # Hijacked-XHR delivery — per-Browser handle counter,
         # background threads, and a Queue of completed responses for
         # Rack calls where the middleware used `rack.hijack` to hold
@@ -307,6 +326,15 @@ module Capybara
         @transfer_buffer_lock = Mutex.new
         @transfer_buffers     = {}
         @transfer_buffer_seq  = 0
+        # Zero-copy postMessage transfer tokens (rusty_racer >= 0.1.6
+        # `RustyRacer.transferOut`): a buffer in a `postMessage` transfer list
+        # crosses isolates by token (no byte copy), its source detached. A token
+        # parked but never imported pins its backing store PROCESS-WIDE, so we
+        # record every issued token (reported from JS, possibly on a worker
+        # thread — hence the lock) and `transferDrop` the lot on `reset!`
+        # (idempotent: an already-imported token no-ops).
+        @transfer_tokens      = []
+        @transfer_tokens_lock = Mutex.new
         # Cross-window `postMessage` inbox. Another window's `target.postMessage`
         # routes through the Driver and lands here; this window drains it into a
         # `message` event the next time it's active and settles/ticks. Plain
@@ -689,7 +717,7 @@ module Capybara
       # drain that channel, without paying an unconditional drain on
       # timer-driven runloop pages.
       def async_io_pending?
-        worker_pending? || event_source_pending? || hijack_fetch_pending? || window_message_pending?
+        worker_pending? || event_source_pending? || hijack_fetch_pending? || window_message_pending? || websocket_pending?
       end
 
       # Single-slot cache for the most recent find_xpath / find_css /
@@ -1374,8 +1402,9 @@ module Capybara
           deliver_worker_messages
           deliver_hijacked_fetches
           deliver_window_messages
+          deliver_websocket_events
           break if @runtime.settle_gen > start_gen
-          break unless @timers_active || event_source_pending? || worker_pending? || hijack_fetch_pending? || window_message_pending?
+          break unless @timers_active || event_source_pending? || worker_pending? || hijack_fetch_pending? || window_message_pending? || websocket_pending?
           # ONE event-loop step replaces the old drain_microtasks(4)+drain_timers(32)
           # pair: it fires due timers, runs a per-task microtask checkpoint (so
           # chained .then / MutationObserver delivery interleave spec-correctly),
@@ -1388,13 +1417,14 @@ module Capybara
           deliver_worker_messages
           deliver_hijacked_fetches
           deliver_window_messages
+          deliver_websocket_events
           break if @runtime.settle_gen > start_gen
           # No progress this iter (no DOM/URL change observed) — the
           # remaining timers are queued for the future; bail and let
           # Capybara's wall-clock-driven poll loop drive the next tick
           # via `tick_real_time`. SSE / Worker channels keep us in
           # the loop as long as background threads have data queued.
-          break if @runtime.settle_gen == prev_gen && !@runtime.has_ready_timer? && !event_source_pending? && !worker_pending? && !hijack_fetch_pending? && !window_message_pending?
+          break if @runtime.settle_gen == prev_gen && !@runtime.has_ready_timer? && !event_source_pending? && !worker_pending? && !hijack_fetch_pending? && !window_message_pending? && !websocket_pending?
           prev_gen = @runtime.settle_gen
         end
         @find_cache_dirty = true
@@ -1886,7 +1916,7 @@ module Capybara
         # Background-thread work (workers, EventSource, MessageBus
         # long-poll) keeps the settle loop alive even when settle_gen
         # is otherwise idle.
-        return true if worker_pending? || event_source_pending? || hijack_fetch_pending? || window_message_pending?
+        return true if worker_pending? || event_source_pending? || hijack_fetch_pending? || window_message_pending? || websocket_pending?
         if @timers_active
           gen = @runtime.settle_gen
           if @last_polled_gen.nil? || gen != @last_polled_gen
@@ -1917,7 +1947,7 @@ module Capybara
       # `Kernel#sleep`) and by `Playwright::Page#wait_for_timeout` to step a
       # precise virtual duration.
       def tick_real_time(step_ms: nil)
-        return unless @timers_active || worker_pending? || event_source_pending? || hijack_fetch_pending? || window_message_pending?
+        return unless @timers_active || worker_pending? || event_source_pending? || hijack_fetch_pending? || window_message_pending? || websocket_pending?
         # Re-entrancy guard. Capybara's `Result#each` triggers nested
         # finds (visible? per element); the outermost tick has already
         # advanced the clock, the inner calls would only re-drain
@@ -1947,6 +1977,7 @@ module Capybara
           @find_cache_dirty = true if deliver_event_source_events > 0
           @find_cache_dirty = true if deliver_hijacked_fetches > 0
           @find_cache_dirty = true if deliver_window_messages > 0
+          @find_cache_dirty = true if deliver_websocket_events > 0
         ensure
           @ticking = false
         end
@@ -1990,7 +2021,7 @@ module Capybara
         end
         # (1) Background async (cheap Ruby-side checks, no V8 crossing) we must let
         #     land before jumping the clock: advance one fixed step, reset the guard.
-        if worker_pending? || event_source_pending? || hijack_fetch_pending?
+        if worker_pending? || event_source_pending? || hijack_fetch_pending? || websocket_pending?
           @ff_transient_polls = 0
           return POLL_TICK_STEP_MS
         end
@@ -2203,7 +2234,11 @@ module Capybara
         reset_event_sources
         reset_hijacked_fetches
         reset_workers
+        reset_websockets
         @window_inbox.clear
+        # Free any zero-copy transfer backing stores that went unimported
+        # (worker killed before draining its inbox, etc.) before the rebuild.
+        drop_pending_transfers
         @blob_registry_lock.synchronize { @blob_registry.clear }
         # Drop volatile entries from the class-level HTTP asset cache
         # so test-local DB state (TranslationOverride, etc.) reaches
@@ -2220,6 +2255,23 @@ module Capybara
         invalidate_find_cache
       end
 
+      # Tear down an auxiliary window's Browser when its window closes (the
+      # Driver calls this on close_window / reset!). Releases what a bare GC of
+      # the isolate would NOT: live background threads (worker / SSE / hijacked-
+      # fetch / WebSocket readers) and any parked zero-copy transfer backing
+      # stores this window issued (the transfer registry is process-wide). Runs
+      # while the runtime is still alive so the transferDrop call lands.
+      def dispose
+        drop_pending_transfers
+        reset_workers
+        reset_event_sources
+        reset_hijacked_fetches
+        reset_websockets
+        @window_inbox.clear
+      rescue StandardError
+        nil
+      end
+
       # ── Host-fn callbacks invoked by bridge.js ──────────────────
 
       def rack_fetch_body(url)
@@ -2499,6 +2551,254 @@ module Capybara
         @event_source_queue.clear
       end
 
+      # ── WebSocket (RFC6455 over in-process rack.hijack) ────────────
+      #
+      # A real browser's WebSocket connects, upgrades, and stays open for
+      # bidirectional framing. Action Cable (and any Rack WebSocket
+      # middleware) handles the upgrade by HIJACKING the connection and
+      # speaking frames over that socket — the same in-process `rack.hijack`
+      # mechanism the long-poll path already uses, but bidirectional. So we:
+      #   1. build the upgrade request as a Rack env (the server reads the
+      #      handshake from the env, like websocket-driver's rack helper),
+      #   2. hand the app a `Socket.pair` end via `rack.hijack` and call it,
+      #   3. the app writes the 101 + frames to its end; we read/write ours.
+      # The frame reader runs on a background thread (engine access stays on
+      # the main thread — events drain into the VM at `settle`, like SSE).
+      WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
+      private_constant :WS_GUID
+
+      def ws_open(url, protocols = nil)
+        id       = (@websocket_seq += 1)
+        # ws:// → http://, wss:// → https:// for the Rack env; resolve relative
+        # against the current document (Action Cable's consumer builds an
+        # absolute ws URL, but be tolerant).
+        http_url = url.to_s.sub(/\Awss/i, 'https').sub(/\Aws/i, 'http')
+        target   = resolve_against_current(http_url)
+        key      = SecureRandom.base64(16)
+        csim_io, app_io = Socket.pair(:UNIX, :STREAM, 0)
+        env = Rack::MockRequest.env_for(target, method: 'GET')
+        apply_default_request_env(env, referer: @current_url)
+        env['HTTP_UPGRADE']               = 'websocket'
+        env['HTTP_CONNECTION']            = 'Upgrade'
+        env['HTTP_SEC_WEBSOCKET_KEY']     = key
+        env['HTTP_SEC_WEBSOCKET_VERSION'] = '13'
+        list = Array(protocols).map(&:to_s).reject(&:empty?)
+        env['HTTP_SEC_WEBSOCKET_PROTOCOL'] = list.join(', ') unless list.empty?
+        env['rack.hijack?']  = true
+        env['rack.hijack']   = -> { app_io }
+        env['rack.hijack_io'] = app_io
+        # The app hijacks + writes the 101 (synchronously, or on its own event
+        # loop thread — Action Cable handles the upgrade on a separate thread, so
+        # `@app.call` may return before the handshake bytes appear; the reader
+        # blocks until they do). Run it on the main thread like the long-poll
+        # hijack so we don't race a second concurrent `@app.call`. (No handshake
+        # timeout: a server that never writes the 101 leaks the reader+socket
+        # until `reset_websockets` — acceptable, real servers always respond.)
+        @app.call(env)
+        @websocket_sockets[id]     = csim_io
+        @websocket_app_sockets[id] = app_io
+        accept = Digest::SHA1.base64digest(key + WS_GUID)
+        queue  = @websocket_queue
+        @websocket_threads[id] = Thread.new do
+          Thread.current.report_on_exception = false
+          run_websocket_reader(id, csim_io, accept, queue)
+        end
+        id
+      rescue StandardError => e
+        # Nothing was registered for cleanup yet — close both pair ends here so
+        # a failed upgrade (mis-routed URL, app error) doesn't leak fds.
+        csim_io.close rescue nil
+        app_io.close  rescue nil
+        @websocket_queue << {id: id, type: '__error', message: "#{e.class}: #{e.message}"}
+        id
+      end
+
+      # `binary` is set by the JS side (it knows whether `send` was given a
+      # string or an ArrayBuffer/view) → opcode 0x2 vs the text 0x1. Action
+      # Cable is text-only (JSON). The payload's bytes are written as-is.
+      def ws_send(id, data, binary = false)
+        sock = @websocket_sockets[id.to_i] or return
+        ws_write_frame(sock, binary ? 0x2 : 0x1, data.to_s.b)
+        nil
+      rescue StandardError
+        nil
+      end
+
+      def ws_close(id, code = 1000, reason = '')
+        sock = @websocket_sockets[id.to_i] or return
+        # Send the close frame and let the close HANDSHAKE complete: the server
+        # replies with its own close frame, which the reader thread surfaces as
+        # the `__close` event (carrying the agreed code) before tearing the
+        # socket down in its `ensure`. Force teardown is `reset_websockets`'s job.
+        payload = [code.to_i].pack('n') + reason.to_s.b
+        ws_write_frame(sock, 0x8, payload) rescue nil
+        nil
+      end
+
+      def websocket_pending? = !@websocket_queue.empty?
+
+      def deliver_websocket_events
+        return 0 if @websocket_threads.empty? && @websocket_queue.empty?
+        events = drain_queue(@websocket_queue)
+        return 0 if events.empty?
+        @runtime.call('__csim_deliverWebSocketEvents', events)
+        events.size
+      end
+
+      def reset_websockets
+        @websocket_threads.each_value(&:kill)
+        @websocket_threads.clear
+        # Close BOTH pair ends: csim's read/write end and the app's hijack end
+        # (the app may abandon its end without closing it — e.g. its connection
+        # thread was just killed), so neither leaks across tests.
+        @websocket_sockets.each_value     {|s| s.close rescue nil }
+        @websocket_app_sockets.each_value {|s| s.close rescue nil }
+        @websocket_sockets.clear
+        @websocket_app_sockets.clear
+        @websocket_queue.clear
+      end
+
+      # Background-thread frame reader: verify the 101 handshake, then loop
+      # decoding server→client frames into queue events until close / EOF.
+      private def run_websocket_reader(id, sock, expected_accept, queue)
+        ok, protocol = ws_read_handshake(sock, expected_accept)
+        unless ok
+          queue << {id: id, type: '__error', message: 'websocket handshake failed'}
+          return
+        end
+        # Carry the negotiated subprotocol — Action Cable's client closes the
+        # connection in its `onopen` unless `webSocket.protocol` is one it knows
+        # (`actioncable-v1-json`).
+        queue << {id: id, type: '__open', protocol: protocol}
+        loop do
+          frame = ws_read_message(sock, queue, id)
+          break if frame.nil?                       # EOF
+          opcode, payload = frame
+          if opcode == :close
+            code   = payload.bytesize >= 2 ? payload[0, 2].unpack1('n') : 1005
+            reason = payload.bytesize > 2 ? RuntimeShared.utf8_text(payload[2..]) : ''
+            queue << {id: id, type: '__close', code: code, reason: reason}
+            break
+          end
+          # Binary frames cross to JS as raw bytes (wrap_binary) tagged so the
+          # JS side decodes them per `binaryType`; text is UTF-8.
+          if opcode == 0x2
+            queue << {id: id, type: 'message', binary: true, data: @runtime.wrap_binary(payload)}
+          else
+            queue << {id: id, type: 'message', data: RuntimeShared.utf8_text(payload)}
+          end
+        end
+      rescue StandardError => e
+        queue << {id: id, type: '__close', code: 1006, reason: e.message.to_s[0, 120]}
+      ensure
+        # Only the socket (a local) is closed here — the `@websocket_*` hashes
+        # are mutated solely on the main thread (`reset_websockets`) to avoid a
+        # cross-thread Hash race; a closed entry just no-ops on the next access.
+        sock.close rescue nil
+      end
+
+      # Read + validate the 101 Switching Protocols response (status line +
+      # headers up to the blank line). Returns `[accept_ok, negotiated_protocol]`
+      # — the accept hash must match the handshake key, and the negotiated
+      # `Sec-WebSocket-Protocol` (nil if none) is surfaced so `webSocket.protocol`
+      # is set (Action Cable's client requires `actioncable-v1-json`).
+      private def ws_read_handshake(sock, expected_accept)
+        status = sock.gets
+        return [false, nil] unless status && status =~ %r{\AHTTP/1\.1 101}i
+        accept_ok = false
+        protocol  = nil
+        while (line = sock.gets)
+          line = line.chomp
+          break if line.empty?
+          k, v = line.split(':', 2)
+          next unless k
+          key = k.strip.downcase
+          val = v.to_s.strip
+          accept_ok = true if key == 'sec-websocket-accept'   && val == expected_accept
+          # utf8_text: socket reads are BINARY, and a BINARY string marshals to a
+          # JS Uint8Array — the protocol must reach JS as a real string so
+          # `webSocket.protocol` compares equal to `actioncable-v1-json`.
+          protocol  = RuntimeShared.utf8_text(val) if key == 'sec-websocket-protocol' && !val.empty?
+        end
+        [accept_ok, protocol]
+      end
+
+      # Read one complete message (reassembling continuation frames), handling
+      # interleaved control frames inline. Returns `[opcode, payload]` (opcode
+      # 0x1 text / 0x2 binary, or `:close`), or nil on EOF.
+      private def ws_read_message(sock, queue, id)
+        data       = +''.b
+        msg_opcode = nil
+        loop do
+          hdr = ws_read_n(sock, 2) or return nil
+          b0, b1 = hdr.bytes
+          fin    = (b0 & 0x80) != 0
+          opcode = b0 & 0x0f
+          masked = (b1 & 0x80) != 0
+          len    = b1 & 0x7f
+          if len == 126
+            ext = ws_read_n(sock, 2) or return nil
+            len = ext.unpack1('n')
+          elsif len == 127
+            ext = ws_read_n(sock, 8) or return nil
+            len = ext.unpack1('Q>')
+          end
+          mask = nil
+          if masked
+            mask = ws_read_n(sock, 4) or return nil
+          end
+          if len.zero?
+            payload = ''.b
+          else
+            payload = ws_read_n(sock, len) or return nil
+          end
+          payload = ws_mask(payload, mask) if mask  # server frames shouldn't be masked, but be defensive
+          case opcode
+          when 0x8 then return [:close, payload]
+          when 0x9 then ws_write_frame(sock, 0xA, payload); next   # ping → pong
+          when 0xA then next                                       # pong → ignore
+          when 0x0 then data << payload                            # continuation
+          else          msg_opcode = opcode; data << payload       # 0x1 text / 0x2 binary
+          end
+          return [msg_opcode || opcode, data] if fin
+        end
+      end
+
+      # Read exactly `n` bytes, or nil if the stream ends first (EOF, or a short
+      # read on a mid-frame close). `IO#read(n)` blocks for n bytes on a stream
+      # socket and only returns nil / fewer at EOF, so a nil-or-short result is
+      # a closed/broken connection — bail and let the caller surface a close.
+      private def ws_read_n(sock, n)
+        buf = sock.read(n)
+        buf if buf && buf.bytesize == n
+      end
+
+      # Write one frame. Client→server frames MUST be masked (RFC6455 §5.3);
+      # csim is always the client, so every frame it writes is masked. Holds the
+      # per-connection write lock so the reader thread's pong and the main
+      # thread's send/close can't interleave bytes on the shared socket.
+      private def ws_write_frame(sock, opcode, payload)
+        payload = payload.to_s.b
+        len     = payload.bytesize
+        out     = [0x80 | opcode].pack('C')
+        if len < 126
+          out << [0x80 | len].pack('C')
+        elsif len < 65_536
+          out << [0x80 | 126, len].pack('Cn')
+        else
+          out << [0x80 | 127, len].pack('CQ>')
+        end
+        key = SecureRandom.random_bytes(4)
+        out << key
+        out << ws_mask(payload, key)
+        @websocket_write_lock.synchronize { sock.write(out) }
+      end
+
+      private def ws_mask(payload, key)
+        kb = key.bytes
+        payload.bytes.each_with_index.map {|byte, i| byte ^ kb[i & 3] }.pack('C*')
+      end
+
       # ── Hijack-aware async XHR ─────────────────────────────────────
       #
       # Real browsers' long-poll keeps the request socket open across
@@ -2883,6 +3183,25 @@ module Capybara
         @transfer_buffer_lock.synchronize { @transfer_buffers.delete(id.to_i) }
       end
 
+      # JS reports each zero-copy transfer token it mints (`RustyRacer.transferOut`)
+      # so we can release any that go unimported. Callable from a worker thread.
+      def transfer_token_issued(token)
+        t = token.to_i
+        @transfer_tokens_lock.synchronize { @transfer_tokens << t } if t > 0
+        nil
+      end
+
+      # Release every outstanding transfer token's backing store. The transfer
+      # registry is process-wide (it bridges isolates) and survives isolate
+      # teardown, so an unimported token would leak across the whole run; drop
+      # them on `reset!` via the (still-live) main context — `transferDrop` is
+      # idempotent, so dropping already-imported tokens is a harmless no-op.
+      def drop_pending_transfers
+        toks = @transfer_tokens_lock.synchronize { ts = @transfer_tokens; @transfer_tokens = []; ts }
+        return if toks.empty?
+        @runtime.call('__csimTransferDropAll', toks) rescue nil
+      end
+
       # Wraps the raw bytes in whatever binary shape the ACTIVE runtime can
       # marshal to a JS Uint8Array (V8: the BINARY-tagged string itself —
       # tag-driven marshalling crosses it as a Uint8Array; QuickJS: base64

data/lib/capybara/simulated/js/bridge.bundle.js

@@ -417,7 +417,7 @@
       this._currentTarget = v;
     }
   });
-  var DOMException = class _DOMException extends Error {
+  var DOMException2 = class _DOMException extends Error {
     static {
       __name(this, "DOMException");
     }
@@ -480,8 +480,8 @@
     INVALID_NODE_TYPE_ERR: 24,
     DATA_CLONE_ERR: 25
   }).forEach(([k, v]) => {
-    Object.defineProperty(DOMException, k, { value: v, enumerable: true });
-    Object.defineProperty(DOMException.prototype, k, { value: v, enumerable: true });
+    Object.defineProperty(DOMException2, k, { value: v, enumerable: true });
+    Object.defineProperty(DOMException2.prototype, k, { value: v, enumerable: true });
   });
   var CustomEvent = class extends Event {
     static {
@@ -4532,6 +4532,18 @@
     return globalThis.__csim_transferStash(view) | 0;
   }
   __name(stashTransfer, "stashTransfer");
+  function detachTransferables(transferList) {
+    if (!Array.isArray(transferList)) return;
+    for (const t of transferList) {
+      if (t instanceof ArrayBuffer && typeof t.transfer === "function") {
+        try {
+          t.transfer();
+        } catch (_) {
+        }
+      }
+    }
+  }
+  __name(detachTransferables, "detachTransferables");
 
   // lib/capybara/simulated/js/src/workers.js
   function hasWorkers() {
@@ -4540,28 +4552,51 @@
   }
   __name(hasWorkers, "hasWorkers");
   var TRANSFER_STASH_MIN = 64 * 1024;
-  function encode(data) {
+  function transferSetFrom(transferList) {
+    if (!transferList || !transferList.length) return null;
+    const set = /* @__PURE__ */ new Set();
+    for (const t of transferList) set.add(t instanceof ArrayBuffer ? t : t && t.buffer || t);
+    return set;
+  }
+  __name(transferSetFrom, "transferSetFrom");
+  function encode(data, transferSet) {
+    const NS = globalThis.RustyRacer;
+    const canTransfer = transferSet && NS && typeof NS.transferOut === "function";
     return JSON.stringify(data, function(_key, value) {
       const isU8 = value instanceof Uint8Array;
       const isAB = !isU8 && value instanceof ArrayBuffer;
       if (!isU8 && !isAB) return value;
+      const type = isU8 ? "Uint8Array" : "ArrayBuffer";
+      const buf = isU8 ? value.buffer : value;
+      if (canTransfer && transferSet.has(buf)) {
+        const token = NS.transferOut(value) | 0;
+        if (token > 0) {
+          if (globalThis.__csim_transferIssued) globalThis.__csim_transferIssued(token);
+          return isU8 ? { __csimType: type, xfer: token, byteOffset: value.byteOffset, length: value.length } : { __csimType: type, xfer: token };
+        }
+      }
       const view = isU8 ? value : new Uint8Array(value);
       if (view.byteLength >= TRANSFER_STASH_MIN) {
         const refId = stashTransfer(view);
-        if (refId > 0) return { __csimType: isU8 ? "Uint8Array" : "ArrayBuffer", refId };
+        if (refId > 0) return { __csimType: type, refId };
       }
-      return {
-        __csimType: isU8 ? "Uint8Array" : "ArrayBuffer",
-        b64: globalThis.btoa(bytesToLatin1(view))
-      };
+      return { __csimType: type, b64: globalThis.btoa(bytesToLatin1(view)) };
     });
   }
   __name(encode, "encode");
   function decode(s) {
+    const NS = globalThis.RustyRacer;
     return JSON.parse(s, function(_key, value) {
       if (!value || typeof value !== "object") return value;
       const tag = value.__csimType;
       if (tag !== "Uint8Array" && tag !== "ArrayBuffer") return value;
+      if (value.xfer != null && NS && typeof NS.transferIn === "function") {
+        const ab = NS.transferIn(value.xfer);
+        if (ab) {
+          return tag === "ArrayBuffer" ? ab : new Uint8Array(ab, value.byteOffset || 0, value.length != null ? value.length : ab.byteLength);
+        }
+        return tag === "ArrayBuffer" ? new ArrayBuffer(0) : new Uint8Array(0);
+      }
       const u = fetchTransfer(value.refId) || latin1ToBytes(globalThis.atob(value.b64 || ""));
       return tag === "ArrayBuffer" ? u.buffer : u;
     });
@@ -4585,15 +4620,16 @@
           this._handle = globalThis.__csim_workerSpawn(this.url) | 0;
           if (this._handle > 0) byHandle.set(this._handle, this);
         }
-        postMessage(data, _transferList) {
+        postMessage(data, transferList) {
           if (this._handle <= 0) return;
           let payload;
           try {
-            payload = encode(data);
+            payload = encode(data, transferSetFrom(transferList));
           } catch (_) {
             payload = "null";
           }
           globalThis.__csim_workerPostToWorker(this._handle, payload);
+          detachTransferables(transferList);
         }
         terminate() {
           if (this._handle <= 0) return;
@@ -4658,14 +4694,15 @@
     globalThis.DedicatedWorkerGlobalScope = globalThis.DedicatedWorkerGlobalScope || /* @__PURE__ */ __name(function DedicatedWorkerGlobalScope() {
     }, "DedicatedWorkerGlobalScope");
     if (typeof globalThis.postMessage !== "function") {
-      globalThis.postMessage = function(data, _transferList) {
+      globalThis.postMessage = function(data, transferList) {
         let payload;
         try {
-          payload = encode(data);
+          payload = encode(data, transferSetFrom(transferList));
         } catch (_) {
           payload = "null";
         }
         globalThis.__csim_workerPostMessage(payload);
+        detachTransferables(transferList);
       };
     }
     globalThis.importScripts = function(...urls) {
@@ -10843,8 +10880,8 @@
   function windowNamedLookup(name) {
     const doc = globalThis.document;
     if (!doc) return void 0;
-    const byId2 = doc.getElementById && doc.getElementById(name);
-    if (byId2) return byId2;
+    const byId3 = doc.getElementById && doc.getElementById(name);
+    if (byId3) return byId3;
     if (!WINDOW_NAME_VALUES.has(name)) return void 0;
     let found;
     walkSubtree(doc, (el) => {
@@ -13162,7 +13199,7 @@
 
   // lib/capybara/simulated/js/src/abort.js
   function defaultAbortReason() {
-    return new DOMException("signal is aborted without reason", "AbortError");
+    return new DOMException2("signal is aborted without reason", "AbortError");
   }
   __name(defaultAbortReason, "defaultAbortReason");
   var AbortSignal = class _AbortSignal extends EventTarget {
@@ -13194,7 +13231,7 @@
     // AbortSignal.timeout(ms)}` is the canonical timeout idiom.
     static timeout(ms) {
       const s = new _AbortSignal();
-      globalThis.setTimeout(() => s._markAborted(new DOMException("signal timed out", "TimeoutError")), Number(ms) || 0);
+      globalThis.setTimeout(() => s._markAborted(new DOMException2("signal timed out", "TimeoutError")), Number(ms) || 0);
       return s;
     }
     // Spec: returns a signal that aborts when any input signal aborts.
@@ -14137,6 +14174,109 @@
   };
   globalThis.EventSource = EventSource;
 
+  // lib/capybara/simulated/js/src/websocket.js
+  var byId2 = /* @__PURE__ */ new Map();
+  globalThis.__csim_webSocketById = byId2;
+  var WebSocket = class extends EventTarget {
+    static {
+      __name(this, "WebSocket");
+    }
+    constructor(url, protocols) {
+      super();
+      this.url = String(url);
+      this.readyState = 0;
+      this.bufferedAmount = 0;
+      this.extensions = "";
+      this.protocol = "";
+      this.binaryType = "blob";
+      this.onopen = null;
+      this.onmessage = null;
+      this.onclose = null;
+      this.onerror = null;
+      const list = protocols == null ? [] : Array.isArray(protocols) ? protocols.map(String) : [String(protocols)];
+      this._id = globalThis.__csim_wsOpen(this.url, list) | 0;
+      if (this._id > 0) byId2.set(this._id, this);
+    }
+    send(data) {
+      if (this.readyState === 0) throw new DOMException("Failed to execute 'send' on 'WebSocket': Still in CONNECTING state.", "InvalidStateError");
+      if (this.readyState !== 1) return;
+      if (typeof data === "string") {
+        globalThis.__csim_wsSend(this._id, data, false);
+        return;
+      }
+      let bytes;
+      if (data instanceof ArrayBuffer) bytes = new Uint8Array(data);
+      else if (ArrayBuffer.isView(data)) bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+      else bytes = new Uint8Array(0);
+      globalThis.__csim_wsSend(this._id, bytes, true);
+    }
+    close(code, reason) {
+      if (this.readyState === 2 || this.readyState === 3) return;
+      this.readyState = 2;
+      if (this._id > 0) globalThis.__csim_wsClose(this._id, code == null ? 1e3 : code | 0, reason == null ? "" : String(reason));
+    }
+  };
+  WebSocket.CONNECTING = 0;
+  WebSocket.OPEN = 1;
+  WebSocket.CLOSING = 2;
+  WebSocket.CLOSED = 3;
+  globalThis.__csim_deliverWebSocketEvents = function(events) {
+    if (!events || !events.length) return 0;
+    let delivered = 0;
+    for (const e of events) {
+      const ws = byId2.get(e.id | 0);
+      if (!ws) continue;
+      if (e.type === "__open") {
+        if (ws.readyState === 0) {
+          ws.readyState = 1;
+          if (e.protocol) ws.protocol = String(e.protocol);
+          dispatchWithOnHandler(ws, new Event("open"));
+          delivered++;
+        }
+        continue;
+      }
+      if (e.type === "__close" || e.type === "__error") {
+        if (e.type === "__error") {
+          const err = new Event("error");
+          if (e.message) try {
+            err.message = String(e.message);
+          } catch (_) {
+          }
+          dispatchWithOnHandler(ws, err);
+        }
+        if (ws.readyState !== 3) {
+          ws.readyState = 3;
+          const ev = new Event("close");
+          try {
+            ev.code = e.code == null ? 1006 : e.code | 0;
+            ev.reason = e.reason == null ? "" : String(e.reason);
+            ev.wasClean = e.type === "__close" && e.code != null;
+          } catch (_) {
+          }
+          dispatchWithOnHandler(ws, ev);
+        }
+        byId2.delete(e.id | 0);
+        delivered++;
+        continue;
+      }
+      let data;
+      if (e.binary) {
+        const bytes = fetchedToBytes(e.data) || new Uint8Array(0);
+        if (ws.binaryType === "arraybuffer") {
+          data = bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength ? bytes.buffer : bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+        } else {
+          data = typeof globalThis.Blob === "function" ? new globalThis.Blob([bytes]) : bytes.buffer;
+        }
+      } else {
+        data = e.data == null ? "" : e.data;
+      }
+      dispatchWithOnHandler(ws, new MessageEvent("message", { data, origin: ws.url }));
+      delivered++;
+    }
+    return delivered;
+  };
+  globalThis.WebSocket = WebSocket;
+
   // lib/capybara/simulated/js/src/request-body.js
   function setContentTypeIfMissing(headers, value) {
     if (!("Content-Type" in headers) && !("content-type" in headers)) {
@@ -17885,7 +18025,55 @@
     }
   };
   globalThis.BroadcastChannel = BroadcastChannel;
+  globalThis.__csimTransferDropAll = function(tokens) {
+    const NS = globalThis.RustyRacer;
+    if (!tokens || !NS || typeof NS.transferDrop !== "function") return;
+    for (let i = 0; i < tokens.length; i++) NS.transferDrop(tokens[i]);
+  };
   var __csimWindowProxies = /* @__PURE__ */ new Map();
+  function csimMaybeTransferOut(data, transfer) {
+    if (!transfer || !transfer.length) return null;
+    const NS = globalThis.RustyRacer;
+    if (!NS || typeof NS.transferOut !== "function") return null;
+    const isAB = data instanceof ArrayBuffer;
+    const isView = !isAB && ArrayBuffer.isView(data);
+    if (!isAB && !isView) return null;
+    const buf = isAB ? data : data.buffer;
+    let inList = false;
+    for (let i = 0; i < transfer.length; i++) {
+      const t = transfer[i];
+      if (t === buf || t && t.buffer === buf) {
+        inList = true;
+        break;
+      }
+    }
+    if (!inList) return null;
+    const token = NS.transferOut(data) | 0;
+    if (token <= 0) return null;
+    if (globalThis.__csim_transferIssued) globalThis.__csim_transferIssued(token);
+    return isAB ? { __csimXfer: token, kind: "ArrayBuffer" } : {
+      __csimXfer: token,
+      kind: data.constructor && data.constructor.name || "Uint8Array",
+      byteOffset: data.byteOffset,
+      length: data.length
+    };
+  }
+  __name(csimMaybeTransferOut, "csimMaybeTransferOut");
+  function csimMaybeTransferIn(data) {
+    if (!data || typeof data !== "object" || data.__csimXfer == null) return data;
+    const NS = globalThis.RustyRacer;
+    if (!NS || typeof NS.transferIn !== "function") return data;
+    const ab = NS.transferIn(data.__csimXfer);
+    if (!ab) return new ArrayBuffer(0);
+    if (data.kind === "ArrayBuffer") return ab;
+    const Ctor = globalThis[data.kind] || globalThis.Uint8Array;
+    try {
+      return new Ctor(ab, data.byteOffset || 0, data.length);
+    } catch (_) {
+      return new Uint8Array(ab);
+    }
+  }
+  __name(csimMaybeTransferIn, "csimMaybeTransferIn");
   function csimWindowProxy(handle) {
     if (handle == null || handle === "") return null;
     let proxy = __csimWindowProxies.get(handle);
@@ -17925,8 +18113,10 @@
       // lost — fine for the JSON-ish payloads postMessage carries in practice.
       // `targetOrigin` is accepted but, like the single-origin model elsewhere,
       // not enforced.
-      postMessage(data, targetOrigin, _transfer) {
-        globalThis.__csimWindowPostMessage(handle, data, String(targetOrigin == null ? "*" : targetOrigin));
+      postMessage(data, targetOrigin, transfer) {
+        const xfer = csimMaybeTransferOut(data, transfer);
+        globalThis.__csimWindowPostMessage(handle, xfer || data, String(targetOrigin == null ? "*" : targetOrigin));
+        detachTransferables(transfer);
       },
       get location() {
         return location;
@@ -17972,7 +18162,7 @@
     for (const ev of events) {
       const source = ev && ev.sourceHandle ? csimWindowProxy(ev.sourceHandle) : null;
       dispatchWithOnHandler(globalThis, new MessageEvent("message", {
-        data: ev ? ev.data : void 0,
+        data: csimMaybeTransferIn(ev ? ev.data : void 0),
         origin: ev && ev.origin || "",
         source,
         lastEventId: "",
@@ -18966,7 +19156,7 @@
   (function() {
     "use strict";
     globalThis.Event = Event;
-    globalThis.DOMException = DOMException;
+    globalThis.DOMException = DOMException2;
     globalThis.CustomEvent = CustomEvent;
     globalThis.MouseEvent = MouseEvent;
     globalThis.KeyboardEvent = KeyboardEvent;

data/lib/capybara/simulated/runtime_shared.rb

@@ -66,6 +66,9 @@ module Capybara
         '__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_wsOpen'              => ->(b, *a) { b.ws_open(a[0], a[1]) },
+        '__csim_wsSend'              => ->(b, *a) { b.ws_send(a[0], a[1], a[2]); nil },
+        '__csim_wsClose'             => ->(b, *a) { b.ws_close(a[0], a[1], a[2]); 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 },
         # Cross-window references (window.open / opener / postMessage). Each
@@ -87,6 +90,8 @@ module Capybara
         '__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]) },
+        # Zero-copy postMessage transfer-token bookkeeping (see Browser#drop_pending_transfers).
+        '__csim_transferIssued'      => ->(b, *a) { b.transfer_token_issued(a[0]); nil },
         '__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

data/lib/capybara/simulated/version.rb

@@ -2,6 +2,6 @@
 
 module Capybara
   module Simulated
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capybara-simulated
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Keita Urashima