capybara-simulated 0.2.0 → 0.4.0

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
@@ -503,13 +531,14 @@ module Capybara
       # the find cache (its keys aren't realm-qualified, and a switch is rare).
       #
       # Scope: finds, reads, interactions (click/fill_in/…), evaluate_script,
-      # and a self-targeted navigation (a link / form submit whose default
-      # action loads a new document) all route into the frame — the frame's
-      # realm is rebuilt from the fetched document, leaving the top page
-      # untouched (see `navigate_frame`). Out of scope: `_top` navigates the
-      # main page (correct), but a `_parent` target from a frame nested ≥2
-      # levels navigates the main page rather than the intermediate frame, and
-      # cross-origin frame locality is resolved against the main page's origin.
+      # and navigation (a link / form submit whose default action loads a new
+      # document) all route into the frame — the target frame's realm is rebuilt
+      # from the fetched document, leaving the top page untouched (see
+      # `navigate_frame` / `frame_nav_target_entry`). A `_parent`-targeted link
+      # or form from a frame nested ≥2 levels rebuilds the intermediate parent
+      # frame; `_top` (and a one-level `_parent`, whose parent is the top
+      # context) navigate the main page. Cross-origin frame locality is resolved
+      # against the main page's origin.
       def switch_to_frame(target)
         invalidate_find_cache
         case target
@@ -573,16 +602,27 @@ module Capybara
       end
 
       # Does a link/form `target` load into the CURRENT frame? Empty or `_self`
-      # do; `_top` / `_blank` / `_parent` / a named context do not. `_top`
-      # correctly navigates the main page (it falls through to `navigate`).
-      # `_parent` from a frame nested ≥2 levels would ideally navigate the
-      # intermediate parent frame, not the top page — that ancestor-targeted
-      # case isn't modelled yet (rare); it currently navigates the main page.
+      # do; `_top` / `_blank` / `_parent` / a named context do not.
       def frame_self_target?(target)
         t = target.to_s.downcase
         t.empty? || t == '_self'
       end
 
+      # Resolve a link/form `target` to the frame stack entry its navigation
+      # should rebuild, or nil when it targets the top page / a new context
+      # (the caller then falls through to a full-page `navigate` or aux window).
+      # Only meaningful inside a frame (`@current_realm_id` set):
+      #   - `''` / `_self` → the current frame.
+      #   - `_parent` → the intermediate parent frame, but only when nested ≥2
+      #     levels deep; at one level the parent IS the top browsing context, so
+      #     it returns nil and the full-page path handles it (same as `_top`).
+      def frame_nav_target_entry(target)
+        return nil unless @current_realm_id
+        return @frame_stack.last if frame_self_target?(target)
+        return @frame_stack[-2] if target.to_s.downcase == '_parent' && @frame_stack.size >= 2
+        nil
+      end
+
       def find_css(css, context_handle = nil)
         s = css.to_s
         return find_xpath(s, context_handle) if xpath_shaped?(s)
@@ -689,7 +729,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 /
@@ -847,13 +887,14 @@ module Capybara
         when 'navigate'
           url = action['url'].to_s
           target = action['target'].to_s
-          # Inside a frame, a self-targeted link navigates the FRAME, not the
-          # top page: fetch + rebuild this frame's realm. A pure-fragment link
-          # is already handled in-realm by the frame's own location JS.
-          if @current_realm_id && frame_self_target?(target)
-            unless pure_fragment_navigation?(url)
+          # Inside a frame, a frame-targeted link (self, or `_parent` of a
+          # ≥2-deep frame) navigates that FRAME, not the top page: fetch +
+          # rebuild its realm. A self-targeted pure-fragment link is already
+          # handled in-realm by the frame's own location JS, so skip it.
+          if (frame_entry = frame_nav_target_entry(target))
+            unless frame_entry.equal?(@frame_stack.last) && pure_fragment_navigation?(url)
               tick_real_time
-              navigate_frame(resolve_against_current(url, use_base: true))
+              navigate_frame(resolve_against_current(url, use_base: true), entry: frame_entry)
             end
           # `target="_blank"` (or any non-_self/_top/_parent name) opens
           # in a new browsing context (its own Browser/VM); the primary
@@ -1374,8 +1415,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 +1430,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 +1929,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 +1960,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 +1990,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 +2034,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
@@ -2074,15 +2118,15 @@ module Capybara
             URI.encode_www_form(fields)
           end
         action_url = action.empty? ? (current_browsing_context_url || @default_host) : resolve_against_current(action)
-        # A form submitted inside a frame whose target is the frame itself
-        # navigates the FRAME, not the top page.
-        in_frame = !!@current_realm_id && frame_self_target?(spec['target'])
+        # A form submitted inside a frame whose target is that frame (self, or a
+        # `_parent` of a ≥2-deep frame) navigates the FRAME, not the top page.
+        frame_entry = frame_nav_target_entry(spec['target'])
         if method == 'GET'
           uri = URI.parse(action_url)
           uri.query = body unless body.empty?
-          in_frame ? navigate_frame(uri.to_s) : navigate(uri.to_s)
-        elsif in_frame
-          navigate_frame_post(action_url, body, content_type || enctype)
+          frame_entry ? navigate_frame(uri.to_s, entry: frame_entry) : navigate(uri.to_s)
+        elsif frame_entry
+          navigate_frame_post(action_url, body, content_type || enctype, entry: frame_entry)
         else
           navigate_post(action_url, body, content_type || enctype)
         end
@@ -2095,7 +2139,7 @@ module Capybara
           append_multipart_part(body, boundary, name, value.to_s)
         end
         file_inputs.each do |fi|
-          picks = @file_picks && @file_picks[fi['handle'].to_i] || []
+          picks = file_pick_paths(fi)
           if picks.empty?
             append_multipart_part(body, boundary, fi['name'].to_s, '', filename: '')
           else
@@ -2110,6 +2154,34 @@ module Capybara
         {content_type: "multipart/form-data; boundary=#{boundary}", body: body}
       end
 
+      # The on-disk paths backing a file input's current selection. Each
+      # selected File reports its host-backed source (`handle`/`index` → the
+      # `@file_picks` slot recorded at `attach_file` time); this resolves bytes
+      # even when JS moved a File onto a different input (`input.files =
+      # dataTransfer.files`), whose own handle was never attached to. Falls back
+      # to the input's own handle for older serializer payloads.
+      #
+      # Only host-backed Files (from `attach_file`) resolve here; a purely
+      # in-memory `new File(['bytes'], …)` assigned via JS has no `@file_picks`
+      # slot, so a CLASSIC (non-Turbo) submit drops its bytes — the fetch/XHR
+      # path serializes those in JS (`serializeMultipart` → `blobBytes`) and is
+      # unaffected. This matches the pre-existing behaviour and covers every
+      # realistic upload (host-backed file submitted through Turbo or a plain
+      # form).
+      def file_pick_paths(fi)
+        refs = fi['files']
+        if refs.is_a?(Array) && !refs.empty?
+          refs.filter_map {|ref|
+            handle = ref['handle']
+            next if handle.nil?
+            picks = @file_picks && @file_picks[handle.to_i]
+            picks && picks[ref['index'].to_i]
+          }
+        else
+          (@file_picks && @file_picks[fi['handle'].to_i]) || []
+        end
+      end
+
       def append_multipart_part(body, boundary, name, content, filename: nil, content_type: nil)
         body << "--#{boundary}\r\n"
         disposition = %[form-data; name="#{name}"]
@@ -2203,7 +2275,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 +2296,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 +2592,260 @@ 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). `b64` is set when the bytes arrived base64-
+      # encoded (the QuickJS binary path — raw bytes ≥0x80 don't survive its
+      # host boundary); decode before framing.
+      def ws_send(id, data, binary = false, b64 = false)
+        sock = @websocket_sockets[id.to_i] or return
+        if binary
+          ws_write_frame(sock, 0x2, b64 ? Base64.decode64(data.to_s) : data.to_s.b)
+        else
+          ws_write_frame(sock, 0x1, data.to_s.b)
+        end
+        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 +3230,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
@@ -3247,6 +3613,12 @@ module Capybara
         # the page, discarding all JS state.
         if pure_fragment_navigation?(url)
           update_current_hash(url)
+        elsif @current_realm_id
+          # A JS-driven `location.*` from inside a `within_frame` block
+          # navigates the FRAME, not the top page (same as a self-targeted
+          # link/form there). Gated on the realm, so the main-page path is
+          # untouched.
+          navigate_frame(url)
         else
           navigate(url)
         end
@@ -3405,11 +3777,11 @@ module Capybara
       # Mirrors `navigate` / `navigate_post`'s fetch + redirect-follow but
       # terminates in `reload_current_frame_realm` instead of a main-page boot.
 
-      def navigate_frame(url, depth: 0)
+      def navigate_frame(url, depth: 0, entry: @frame_stack.last)
         raise 'too many redirects' if depth > 10
         invalidate_find_cache
         if url.to_s.match?(%r{\Aabout:blank(?:[?#]|\z)}i)
-          reload_current_frame_realm('about:blank', '', 'text/html')
+          reload_current_frame_realm('about:blank', '', 'text/html', entry: entry)
           return
         end
         env = Rack::MockRequest.env_for(url, method: 'GET')
@@ -3419,16 +3791,16 @@ module Capybara
         if (loc = redirect_location(status, headers))
           next_url = carry_fragment(url, resolve_against_current(loc))
           body.close if body.respond_to?(:close)
-          return navigate_frame(next_url, depth: depth + 1)
+          return navigate_frame(next_url, depth: depth + 1, entry: entry)
         end
         if download_response?(headers)
           save_downloaded_response(url, headers, body)
           return
         end
-        reload_current_frame_realm(url.to_s, read_rack_body(body), response_content_type(headers))
+        reload_current_frame_realm(url.to_s, read_rack_body(body), response_content_type(headers), entry: entry)
       end
 
-      def navigate_frame_post(url, body, content_type, depth: 0)
+      def navigate_frame_post(url, body, content_type, depth: 0, entry: @frame_stack.last)
         raise 'too many redirects' if depth > 10
         invalidate_find_cache
         env = Rack::MockRequest.env_for(url, method: 'POST', input: body)
@@ -3442,31 +3814,53 @@ module Capybara
           resp_body.close if resp_body.respond_to?(:close)
           # 301/302/303 → GET; 307/308 preserve method + body (same as navigate_post).
           if [307, 308].include?(status)
-            return navigate_frame_post(next_url, body, content_type, depth: depth + 1)
+            return navigate_frame_post(next_url, body, content_type, depth: depth + 1, entry: entry)
           else
-            return navigate_frame(next_url, depth: depth + 1)
+            return navigate_frame(next_url, depth: depth + 1, entry: entry)
           end
         end
         if download_response?(headers)
           save_downloaded_response(url, headers, resp_body)
           return
         end
-        reload_current_frame_realm(url.to_s, read_rack_body(resp_body), response_content_type(headers))
-      end
-
-      # Tear down the active frame's realm and rebuild it from `html`, then
-      # re-point the iframe element at the new realm. The iframe lives in the
-      # PARENT realm, so the rebind host fn runs there.
-      def reload_current_frame_realm(url, html, content_type)
-        entry = @frame_stack.last
+        reload_current_frame_realm(url.to_s, read_rack_body(resp_body), response_content_type(headers), entry: entry)
+      end
+
+      # Tear down a frame's realm and rebuild it from `html`, then re-point the
+      # iframe element at the new realm. The iframe lives in the PARENT realm, so
+      # the rebind host fn runs there. `entry` defaults to the active frame; a
+      # `_parent`-targeted navigation passes an ancestor entry instead — every
+      # frame below it in the stack is destroyed along with the ancestor's old
+      # document, so we dispose those realms and leave `@current_realm_id` on the
+      # (now-gone) current frame, surfacing StaleElement for the rest of the open
+      # `within_frame` block. Its `ensure` pops back to `entry`, whose `realm_id`
+      # we've updated to the rebuilt realm.
+      #
+      # Teardown reaches the realms on the entered `@frame_stack` (the ones a
+      # find could route into). Like the self-nav path, descendant realms of the
+      # rebuilt frame that were entered-then-popped earlier (so they no longer
+      # sit on the stack) aren't disposed here — they linger, unreferenced and
+      # un-stepped, until the next full-page rebuild's `dispose_frame_realms`. A
+      # bounded per-test leak, only reachable by re-entering a sibling subframe
+      # before an ancestor `_parent` nav; not worth a JS descendant walk on this
+      # path's perf budget.
+      def reload_current_frame_realm(url, html, content_type, entry: @frame_stack.last)
         return unless entry
         old_id = entry[:realm_id]
         parent = entry[:parent_realm_id]
         new_id = @runtime.reload_frame_realm(old_id, parent.to_i, url, RuntimeShared.utf8_text(html), content_type).to_i
         return if new_id.zero?
         rebind_frame_realm(parent, entry[:iframe_handle], old_id, new_id)
-        entry[:realm_id]  = new_id
-        @current_realm_id = new_id
+        if entry.equal?(@frame_stack.last)
+          entry[:realm_id]  = new_id
+          @current_realm_id = new_id
+        else
+          # Match by object identity (the branch was chosen by `equal?`); index
+          # by `==` could collide if two entries were ever structurally equal.
+          idx = @frame_stack.index {|e| e.equal?(entry) }
+          @frame_stack[(idx + 1)..].each {|descendant| @runtime.dispose_frame_realm(descendant[:realm_id]) }
+          entry[:realm_id] = new_id
+        end
         invalidate_find_cache
         settle
       end