capybara-simulated 0.1.1 → 0.3.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'
@@ -53,6 +55,11 @@ module Capybara
 
       attr_writer :timers_active
 
+      # The Driver's handle for the window this Browser backs (set right after
+      # construction). Lets host fns name the source window of a cross-window
+      # `postMessage` / `window.open` so the Driver can route to the target.
+      attr_accessor :window_handle
+
       # Sticky window after timers finish: keep polling? true so a
       # setTimeout firing mid-loop doesn't drop Capybara's synchronize
       # before its own default_max_wait_time kicks in. Counted in poll
@@ -221,6 +228,13 @@ module Capybara
         @find_cache_ctx               = nil
         @find_cache_value             = nil
         @document_handle              = 0
+        # `within_frame` state. `@current_realm_id` is the V8 context id of the
+        # active frame realm (nil = the main document); `@frame_stack` records
+        # the enclosing realms so `switch_to_frame(:parent)` can pop one level.
+        # DOM / node / query ops route through `dom_call`, which dispatches to
+        # this realm. nil is the steady state, so the routing is one nil-check.
+        @current_realm_id             = nil
+        @frame_stack                  = []
         @last_tick_ts                 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         @polling_grace                = nil
         @last_polled_gen              = nil
@@ -261,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
@@ -295,6 +326,20 @@ 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
+        # array (same thread — windows aren't background-threaded like workers).
+        @window_inbox         = []
       end
 
       # Worker thread polling and termination intervals — split so a
@@ -351,8 +396,28 @@ module Capybara
 
       def resolve_visit_url(url)
         s = url.to_s
+        # `about:blank` (and other authority-less schemes) have no `//`, so the
+        # `scheme://` test below would treat them as relative paths and prepend
+        # the host root. `navigate` handles `about:blank` specially — pass it
+        # through untouched (open_new_window opens an about:blank tab).
+        return s if s.match?(/\Aabout:/i)
         unless s =~ %r{\A[a-z]+://}i
-          host_root = (begin URI.parse(@current_url) rescue nil end)&.tap {|u| u.path = ''; u.query = nil; u.fragment = nil }&.to_s || @default_host
+          # Strip path/query/fragment off the current URL to get the origin
+          # root. An opaque or host-less current URL (e.g. `about:blank` in a
+          # freshly-opened window) can't yield an origin — fall back to the
+          # default host so a subsequent relative `visit` still resolves.
+          host_root =
+            begin
+              u = URI.parse(@current_url.to_s)
+              if u.opaque || u.host.nil?
+                @default_host
+              else
+                u.path = ''; u.query = nil; u.fragment = nil
+                u.to_s
+              end
+            rescue URI::InvalidURIError
+              @default_host
+            end
           host_root = host_root.sub(/\/+$/, '')
           s = "/#{s}" unless s.start_with?('/')
           s = "#{host_root}#{s}"
@@ -429,11 +494,128 @@ module Capybara
         @recent_urls_last_push_at = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
       end
 
+      attr_reader :current_realm_id
+
+      # DOM / node / query host-fn dispatch. Inside a `within_frame` block it
+      # routes to the active frame realm's context; otherwise straight to the
+      # main context. Handle integers are per-realm (each realm is a full
+      # bridge with its own registry), so an op on a frame node must run in the
+      # realm the handle came from — which, per Capybara's within_frame
+      # contract, is the current realm for the block's duration. Hot path:
+      # `@current_realm_id` is nil outside frames, so this is one nil-check over
+      # a direct `@runtime.call`.
+      def dom_call(name, *args)
+        return @runtime.call(name, *args) if @current_realm_id.nil?
+        # The active frame's realm was torn down mid-block (the iframe was
+        # removed or re-navigated). Surface a stale element so Capybara
+        # retries / reports, rather than letting realm_call fall back to the
+        # main context where this frame handle would mis-resolve.
+        unless @runtime.frame_realm_alive?(@current_realm_id)
+          raise Capybara::Simulated::StaleElement,
+            "frame browsing context #{@current_realm_id} was torn down (frame removed or re-navigated)"
+        end
+        @runtime.realm_call(@current_realm_id, name, *args)
+      end
+
+      # Root for a context-less find: the active frame's document (handle 0 ⇒
+      # the realm's own `globalThis.document`) when in a frame, else the main
+      # document handle.
+      def current_document_handle
+        @current_realm_id ? 0 : @document_handle
+      end
+
+      # Capybara `switch_to_frame`. `target` is an `<iframe>` handle in the
+      # CURRENT realm, or `:parent` / `:top`. Entering builds (or reuses) the
+      # frame's V8 realm and routes subsequent DOM ops there; `:parent` pops one
+      # level, `:top` returns to the main document. Frame switches invalidate
+      # 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.
+      def switch_to_frame(target)
+        invalidate_find_cache
+        case target
+        when :parent
+          @frame_stack.pop
+          @current_realm_id = @frame_stack.last && @frame_stack.last[:realm_id]
+        when :top
+          reset_frame_scope
+        else
+          # Per-frame realms are a V8-engine feature; QuickJS has no nested
+          # browsing context to route into. Distinguish that (unsupported
+          # engine) from a frame that simply failed to build (below), so the
+          # error doesn't misattribute a load failure to the engine.
+          unless @runtime.respond_to?(:realm_call)
+            raise Capybara::Simulated::FrameNotSupported,
+              'within_frame needs a per-frame browsing context, which only the ' \
+              'V8 (rusty_racer) engine provides; QuickJS keeps a same-realm fallback.'
+          end
+          parent_realm = @current_realm_id
+          tick_real_time
+          rid = dom_call('__csimEnsureFrameRealm', target.to_i).to_i
+          if rid.zero?
+            raise Capybara::Simulated::StaleElement,
+              "could not enter frame ##{target} (not a frame element, or its document failed to load)"
+          end
+          # Record the iframe handle + the realm it lives in so a frame-scoped
+          # navigation can rebuild this exact frame (`reload_current_frame_realm`).
+          @frame_stack.push({realm_id: rid, iframe_handle: target.to_i, parent_realm_id: parent_realm})
+          @current_realm_id = rid
+          # Let the freshly built realm's inline scripts / load handlers settle
+          # so a find immediately inside the block sees the loaded document.
+          settle
+        end
+      end
+
+      # Return DOM-op routing to the main document and drop any frame stack.
+      # Called by `switch_to_frame(:top)`, per-test `reset!`, and every full
+      # page (re)build (which disposes all frame realms) — anything that
+      # invalidates the active `within_frame` scope.
+      def reset_frame_scope
+        @current_realm_id = nil
+        @frame_stack.clear
+      end
+
+      # The active browsing context's own URL: the frame document's URL inside
+      # a `within_frame` block, else the main page URL. Used to resolve a
+      # frame-relative navigation and to set its request referrer, so
+      # `resolve_against_current` / `pure_fragment_navigation?` work the same
+      # whether the navigation originates in the main page or a frame.
+      def current_browsing_context_url
+        return @current_url unless @current_realm_id
+        href = dom_call('__csimLocationHref').to_s
+        href.empty? ? @current_url : href
+      end
+
+      # Public entry for the Driver to resolve a `window.open` / cross-window
+      # `location` URL against THIS window's document (the internal resolver is
+      # private). Honours `<base href>` like the page's own links do.
+      def resolve_document_url(url)
+        resolve_against_current(url, use_base: true)
+      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.
+      def frame_self_target?(target)
+        t = target.to_s.downcase
+        t.empty? || t == '_self'
+      end
+
       def find_css(css, context_handle = nil)
         s = css.to_s
         return find_xpath(s, context_handle) if xpath_shaped?(s)
         find_with_timer_fallback(:css, s, context_handle) do
-          @runtime.call('__csimQuery', context_handle || @document_handle, s).to_a
+          dom_call('__csimQuery', context_handle || current_document_handle, s).to_a
         rescue StandardError => e
           # Invalid selector → empty result. Callers that genuinely
           # need the throw go through `evaluate_script`.
@@ -445,7 +627,7 @@ module Capybara
       def find_first_css(css, context_handle = nil)
         s = css.to_s
         find_with_timer_fallback(:css_first, s, context_handle) do
-          h = @runtime.call('__csimQueryOne', context_handle || @document_handle, s).to_i
+          h = dom_call('__csimQueryOne', context_handle || current_document_handle, s).to_i
           h.zero? ? nil : h
         rescue StandardError => e
           raise unless syntax_or_invalid_selector_error?(e)
@@ -481,7 +663,7 @@ module Capybara
       def find_xpath(xpath, context_handle = nil)
         xpath_str = xpath.to_s
         find_with_timer_fallback(:xpath, xpath_str, context_handle) do
-          @runtime.call('__csimEvaluateXPath', xpath_str, context_handle || 0).to_a
+          dom_call('__csimEvaluateXPath', xpath_str, context_handle || 0).to_a
         end
       end
 
@@ -535,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?
+        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 /
@@ -569,23 +751,23 @@ module Capybara
         @find_cache_dirty = true
       end
 
-      def text(handle)        = @runtime.call('__csimText', handle).to_s
-      def tag(handle)         = @runtime.call('__csimTag', handle).to_s
-      def attr(handle, name)  = @runtime.call('__csimAttr', handle, name.to_s)
-      def inner_html(handle)  = @runtime.call('__csimInnerHTML', handle).to_s
-      def outer_html(handle)  = @runtime.call('__csimOuterHTML', handle).to_s
+      def text(handle)        = dom_call('__csimText', handle).to_s
+      def tag(handle)         = dom_call('__csimTag', handle).to_s
+      def attr(handle, name)  = dom_call('__csimAttr', handle, name.to_s)
+      def inner_html(handle)  = dom_call('__csimInnerHTML', handle).to_s
+      def outer_html(handle)  = dom_call('__csimOuterHTML', handle).to_s
       def file_input?(handle)
         tag(handle) == 'input' && attr(handle, 'type').to_s.downcase == 'file'
       end
-      def visible?(handle)    = @runtime.call('__csimVisible', handle) ? true : false
+      def visible?(handle)    = dom_call('__csimVisible', handle) ? true : false
 
       # Capybara::Driver::Node surface — Node calls `check_stale`
       # before each read, and that advances the virtual clock.
       def all_text(handle)     = text(handle)
-      def visible_text(handle) = @runtime.call('__csimVisibleText', handle).to_s
+      def visible_text(handle) = dom_call('__csimVisibleText', handle).to_s
       def tag_name(handle)     = tag(handle)
-      def value(handle)        = @runtime.call('__csimValue', handle)
-      def disabled?(handle)    = @runtime.call('__csimDisabled', handle)
+      def value(handle)        = dom_call('__csimValue', handle)
+      def disabled?(handle)    = dom_call('__csimDisabled', handle)
       # HTML spec: `<option>.selected` IDL is true when the `selected`
       # *attribute* is set OR when no sibling option has `selected` and
       # this is the first non-disabled option of a single-select
@@ -595,28 +777,28 @@ module Capybara
       # `<option selected>` reports no selected options and the matcher
       # fails even though the first option *is* the currently chosen
       # one in real browsers.
-      def option_selected?(h)  = !!@runtime.call('__csimOptionSelected', h)
+      def option_selected?(h)  = !!dom_call('__csimOptionSelected', h)
       def shadow_root_handle(handle)
-        h = @runtime.call('__csimShadowRoot', handle).to_i
+        h = dom_call('__csimShadowRoot', handle).to_i
         h.zero? ? nil : h
       end
       def computed_style(handle, names)
         tick_real_time
-        result = @runtime.call('__csimComputedStyle', handle, names.map(&:to_s))
+        result = dom_call('__csimComputedStyle', handle, names.map(&:to_s))
         return names.to_h {|n| [n, ''] } unless result.is_a?(Hash)
         result.transform_keys(&:to_s)
       end
-      def node_path(handle)    = @runtime.call('__csimNodePath', handle).to_s
+      def node_path(handle)    = dom_call('__csimNodePath', handle).to_s
 
       def lookup_node(handle)
-        handle if @runtime.call('__csimAlive', handle)
+        handle if dom_call('__csimAlive', handle)
       end
 
       def check_stale(handle, initial, gen = nil)
-        return if initial && (gen.nil? || gen == @context_gen) && @runtime.call('__csimAlive', handle)
+        return if initial && (gen.nil? || gen == @context_gen) && dom_call('__csimAlive', handle)
 
         tick_real_time
-        return if initial && (gen.nil? || gen == @context_gen) && @runtime.call('__csimAlive', handle)
+        return if initial && (gen.nil? || gen == @context_gen) && dom_call('__csimAlive', handle)
 
         raise Capybara::Simulated::StaleElement, "Element with handle #{handle} is no longer attached to the document"
       end
@@ -630,7 +812,7 @@ module Capybara
       # silently no-op (or, in the case of `__csimClickResolve`,
       # dispatch on a detached node whose listeners no longer matter).
       def ensure_alive_after_tick(handle)
-        return if @runtime.call('__csimAlive', handle)
+        return if dom_call('__csimAlive', handle)
         raise Capybara::Simulated::StaleElement, "Element with handle #{handle} is no longer attached to the document"
       end
 
@@ -646,11 +828,11 @@ module Capybara
             # Wall-sleep between mousedown and mouseup so click handlers
             # reading `Date.now()` see the elapsed gap (selenium parity).
             init['mouseDownOnly'] = true
-            partial = @runtime.call('__csimClickResolve', handle, init)
+            partial = dom_call('__csimClickResolve', handle, init)
             sleep delay
-            @runtime.call('__csimClickFinish', handle, partial.is_a?(Hash) ? partial['base'] : init)
+            dom_call('__csimClickFinish', handle, partial.is_a?(Hash) ? partial['base'] : init)
           else
-            @runtime.call('__csimClickResolve', handle, init)
+            dom_call('__csimClickResolve', handle, init)
           end
         unless action.is_a?(Hash)
           settle
@@ -693,11 +875,21 @@ 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)
+              tick_real_time
+              navigate_frame(resolve_against_current(url, use_base: true))
+            end
           # `target="_blank"` (or any non-_self/_top/_parent name) opens
-          # in a new browsing context. URL-only multi-window mode
-          # records the URL against a fresh aux handle; the primary
-          # stays put (per HTML spec — original window is unaffected).
-          if !target.empty? && !%w[_self _top _parent].include?(target.downcase) && @driver.respond_to?(:open_aux_window)
+          # in a new browsing context (its own Browser/VM); the primary
+          # stays put (per HTML spec — original window is unaffected). No
+          # `opener_handle` is passed: modern browsers default `target=_blank`
+          # to `noopener` (so `window.opener` is null), unlike JS `window.open`
+          # which keeps the opener — see `open_window_from_js`.
+          elsif !target.empty? && !%w[_self _top _parent].include?(target.downcase) && @driver.respond_to?(:open_aux_window)
             @driver.open_aux_window(resolve_against_current(url, use_base: true))
           # In-page anchor links (`#frag` / current-page + `#frag`) move
           # the hash but don't fetch a new document. Pure-fragment also
@@ -772,10 +964,11 @@ module Capybara
 
       def pure_fragment_navigation?(url)
         return true  if url.start_with?('#')
-        return false if @current_url.nil?
+        doc_url = current_browsing_context_url
+        return false if doc_url.nil?
         target = resolve_against_current(url)
         a = URI.parse(target)
-        b = URI.parse(@current_url)
+        b = URI.parse(doc_url)
         # Same-document iff everything but the fragment matches AND the
         # fragment actually changes — `a.fragment != b.fragment` covers
         # both adding/changing a fragment and *clearing* one (target has
@@ -854,14 +1047,14 @@ module Capybara
               'lastModified' => stat ? (stat.mtime.to_f * 1000).to_i : 0
             }
           }
-          @runtime.call('__csimSetFiles', handle, file_infos)
+          dom_call('__csimSetFiles', handle, file_infos)
           # Mirror real browser: <input type=file>.value reflects only
           # the filename of the first chosen file (security-faked path).
           # __csimSetValue dispatches input + change synchronously.
           js_value = paths.first ? File.basename(paths.first) : ''
-          @runtime.call('__csimSetValue', handle, js_value)
+          dom_call('__csimSetValue', handle, js_value)
         else
-          @runtime.call('__csimSetValue', handle, coerced)
+          dom_call('__csimSetValue', handle, coerced)
         end
         drain_after_user_action
       end
@@ -919,10 +1112,10 @@ module Capybara
         invalidate_find_cache
         ensure_alive_after_tick(handle)
         init = {'bubbles' => true, 'cancelable' => true, 'button' => 2, 'which' => 3}.merge(click_event_init(handle, keys, opts))
-        @runtime.call('__csimDispatchEvent', handle, 'mousedown', init)
+        dom_call('__csimDispatchEvent', handle, 'mousedown', init)
         sleep opts[:delay].to_f if opts[:delay].to_f > 0
-        @runtime.call('__csimDispatchEvent', handle, 'mouseup',     init)
-        @runtime.call('__csimDispatchEvent', handle, 'contextmenu', init)
+        dom_call('__csimDispatchEvent', handle, 'mouseup',     init)
+        dom_call('__csimDispatchEvent', handle, 'contextmenu', init)
       end
 
       # HTML5 drag-and-drop simulation. Capybara routes `Element#drop`
@@ -934,7 +1127,7 @@ module Capybara
         invalidate_find_cache
         ensure_alive_after_tick(handle)
         items = args.flat_map {|arg| drop_items(arg) }
-        @runtime.call('__csimDropOnto', handle, items)
+        dom_call('__csimDropOnto', handle, items)
       end
 
       # Element-to-element drag. Capybara's `Element#drag_to(target,
@@ -950,7 +1143,7 @@ module Capybara
         invalidate_find_cache
         ensure_alive_after_tick(source_handle)
         ensure_alive_after_tick(target_handle)
-        @runtime.call('__csimDragOnto', source_handle, target_handle)
+        dom_call('__csimDragOnto', source_handle, target_handle)
         drain_after_user_action
       end
       def drop_items(arg)
@@ -975,14 +1168,14 @@ module Capybara
         # UI Events spec: two full mousedown→mouseup→click chains
         # before the trailing `dblclick`. Jspreadsheet (table-builder's
         # `.jss_worksheet`) enters edit mode on the inner mousedown.
-        2.times { @runtime.call('__csimClickResolve', handle, opts) }
+        2.times { dom_call('__csimClickResolve', handle, opts) }
         init = {'bubbles' => true, 'cancelable' => true}.merge(click_event_init(handle, keys, opts))
-        @runtime.call('__csimDispatchEvent', handle, 'dblclick', init)
+        dom_call('__csimDispatchEvent', handle, 'dblclick', init)
         # Real browsers' default-action on dblclick selects the word
         # under the cursor — ProseMirror / Tiptap "paste URL over
         # selection wraps with link" tests rely on the word being
         # selected before the paste.
-        @runtime.call('__csimSelectWordAt', handle)
+        dom_call('__csimSelectWordAt', handle)
         settle
       end
 
@@ -1015,7 +1208,7 @@ module Capybara
         has_xy = opts[:x] || opts[:y]
         center = opts[:offset] == :center || !has_xy
         if has_xy || center
-          rect = @runtime.call('__csimElementRect', handle)
+          rect = dom_call('__csimElementRect', handle)
           base_x = rect['x'].to_f + (center ? rect['width'].to_f  / 2.0 : 0.0)
           base_y = rect['y'].to_f + (center ? rect['height'].to_f / 2.0 : 0.0)
           out['clientX'] = base_x + opts[:x].to_f
@@ -1038,14 +1231,14 @@ module Capybara
         # double-eval recursion the inlined `globalThis.document.
         # _hoverElement = ...` triggered (the eval string ran inside
         # a fresh microtask that re-entered the hover listeners).
-        @runtime.call('__csimSetHover', handle)
+        dom_call('__csimSetHover', handle)
       end
 
       def dispatch_event(handle, type, init = {})
         tick_real_time
         invalidate_find_cache
         ensure_alive_after_tick(handle)
-        @runtime.call('__csimDispatchEvent', handle, type.to_s, init)
+        dom_call('__csimDispatchEvent', handle, type.to_s, init)
       end
 
       # Capybara's `send_keys` accepts Strings and Symbols (special
@@ -1097,20 +1290,20 @@ module Capybara
         # before the next char arrives. Plain `<input>` / `<textarea>`
         # don't need this — keep the single batched call there.
         has_multichar_text = atoms.any? {|a| a['kind'] == 'text' && a['value'].to_s.length > 1 }
-        if has_multichar_text && @runtime.call('__csimIsContentEditable', handle)
+        if has_multichar_text && dom_call('__csimIsContentEditable', handle)
           per_char = atoms.flat_map {|a|
             next a unless a['kind'] == 'text' && a['value'].to_s.length > 1
             a['value'].to_s.each_char.map {|c| {'kind' => 'text', 'value' => c} }
           }
           head, *tail = per_char
-          @runtime.call('__csimSendKeys', handle, [head])
+          dom_call('__csimSendKeys', handle, [head])
           tail.each {|atom|
             tick_real_time
-            @runtime.call('__csimSendKeys', handle, [atom])
+            dom_call('__csimSendKeys', handle, [atom])
             settle
           }
         else
-          @runtime.call('__csimSendKeys', handle, atoms)
+          dom_call('__csimSendKeys', handle, atoms)
         end
         drain_after_user_action
       end
@@ -1119,7 +1312,7 @@ module Capybara
         mark_action_baseline
         tick_real_time
         invalidate_find_cache
-        @runtime.call('__csimSelectOption', handle)
+        dom_call('__csimSelectOption', handle)
         tick_real_time
         drain_after_user_action
       end
@@ -1133,11 +1326,11 @@ module Capybara
         # the JS side whether the option's parent select is `multiple`
         # before issuing the unselect; the answer doubles as the
         # "found the right ancestor" check.
-        info = @runtime.call('__csimOptionContext', handle)
+        info = dom_call('__csimOptionContext', handle)
         if info.is_a?(Hash) && info['hasSelect'] && !info['multiple']
           raise Capybara::UnselectNotAllowed, 'Cannot unselect option from single select box.'
         end
-        @runtime.call('__csimUnselectOption', handle)
+        dom_call('__csimUnselectOption', handle)
         tick_real_time
         drain_after_user_action
       end
@@ -1208,8 +1401,10 @@ module Capybara
           deliver_event_source_events
           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?
+          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),
@@ -1221,13 +1416,15 @@ module Capybara
           deliver_event_source_events
           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?
+          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
@@ -1285,7 +1482,7 @@ module Capybara
       def submit_form(handle)
         tick_real_time
         invalidate_find_cache
-        form_handle = @runtime.call('__csimAncestorForm', handle).to_i
+        form_handle = dom_call('__csimAncestorForm', handle).to_i
         return if form_handle.zero?
         submit_form_handle(form_handle, nil)
       end
@@ -1295,9 +1492,11 @@ module Capybara
         @runtime.call('__csimDocumentTitle').to_s
       end
 
+      # `page.html` inside a `within_frame` block returns the frame document's
+      # source (Selenium parity), so route through the active realm.
       def html
         tick_real_time
-        @runtime.call('__csimDocumentHtml').to_s
+        dom_call('__csimDocumentHtml').to_s
       end
 
       def status_code      = (@last_response_status || 200)
@@ -1449,7 +1648,7 @@ module Capybara
       end
       def active_element_handle
         tick_real_time
-        h = @runtime.call('__csimActiveElement').to_i
+        h = dom_call('__csimActiveElement').to_i
         h.zero? ? nil : h
       end
       # Session-level keystroke. Tab / shift-tab cycle focus; everything
@@ -1467,12 +1666,12 @@ module Capybara
         Array(keys).each do |k|
           sym = k.is_a?(Symbol) ? k : (k.respond_to?(:to_sym) ? k.to_sym : nil)
           if sym == :tab || sym == :backtab
-            @runtime.call('__csimAdvanceFocus', sym == :backtab)
+            dom_call('__csimAdvanceFocus', sym == :backtab)
           elsif sym && MODIFIER_KEY_NAMES.include?(sym)
             held << sym
           else
             handle = active_element_handle
-            handle = @document_handle if handle.nil? || handle.zero?
+            handle = current_document_handle if handle.nil? || handle.zero?
             atom = held.empty? ? k : (held + [k])
             send_keys(handle, [atom])
           end
@@ -1582,7 +1781,7 @@ module Capybara
       # description Proc).
       def describe_node_handle(handle)
         return "handle=#{handle}" if handle.nil? || handle.zero?
-        info = @runtime.call('__csimDescribeNode', handle)
+        info = dom_call('__csimDescribeNode', handle)
         return "handle=#{handle}" unless info.is_a?(Hash)
         s = info['tag'].to_s
         s += "##{info['id']}"  unless info['id'].to_s.empty?
@@ -1597,7 +1796,9 @@ module Capybara
         # to be active.
         tick_real_time
         invalidate_find_cache
-        result = @runtime.call('__csimEvalScript', code.to_s, marshal_args(args || []))
+        # Routes to the active frame realm inside `within_frame` (Selenium
+        # parity: `evaluate_script` runs in the current browsing context).
+        result = dom_call('__csimEvalScript', code.to_s, marshal_args(args || []))
         drain_pending_navigation
         result
       end
@@ -1609,7 +1810,7 @@ module Capybara
       def execute_script(code, args = [])
         tick_real_time
         invalidate_find_cache
-        @runtime.call('__csimExecScript', code.to_s, marshal_args(args || []))
+        dom_call('__csimExecScript', code.to_s, marshal_args(args || []))
         drain_pending_navigation
         nil
       end
@@ -1666,14 +1867,17 @@ module Capybara
       def evaluate_async_script(code, args = [])
         tick_real_time
         invalidate_find_cache
-        @runtime.call('__evalAsyncScript', code.to_s, marshal_args(args || []))
+        # Runs in the active frame realm inside `within_frame` (Selenium
+        # parity), same as evaluate_script; the result slot is realm-local so
+        # the poll below must read from the same realm.
+        dom_call('__evalAsyncScript', code.to_s, marshal_args(args || []))
         # Pump virtual time so any setTimeout-driven completion lands.
         # Capybara's polling can't help here — we're inside one session
         # call, not a retry loop.
         deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) +
                    Capybara.default_max_wait_time.to_f
         loop do
-          result = @runtime.call('__pollAsyncResult')
+          result = dom_call('__pollAsyncResult')
           return result['value'] if result.is_a?(Hash) && result.key?('value')
           break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
           sleep 0.01
@@ -1712,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?
+        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
@@ -1743,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?
+        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
@@ -1772,6 +1976,8 @@ module Capybara
           @find_cache_dirty = true if deliver_worker_messages > 0
           @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
@@ -1815,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
@@ -1875,7 +2081,7 @@ module Capybara
       # drives the Rack app via `navigate` (for GET) or a POST.
       def submit_form_handle(form_handle, submitter_handle)
         invalidate_find_cache
-        spec = @runtime.call('__csimFormSerialize', form_handle, submitter_handle || 0)
+        spec = dom_call('__csimFormSerialize', form_handle, submitter_handle || 0)
         return unless spec.is_a?(Hash)
         action  = spec['action'].to_s
         method  = spec['method'].to_s.upcase
@@ -1898,11 +2104,16 @@ module Capybara
             end
             URI.encode_www_form(fields)
           end
-        action_url = action.empty? ? (@current_url || @default_host) : resolve_against_current(action)
+        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'])
         if method == 'GET'
           uri = URI.parse(action_url)
           uri.query = body unless body.empty?
-          navigate(uri.to_s)
+          in_frame ? navigate_frame(uri.to_s) : navigate(uri.to_s)
+        elsif in_frame
+          navigate_frame_post(action_url, body, content_type || enctype)
         else
           navigate_post(action_url, body, content_type || enctype)
         end
@@ -2001,6 +2212,10 @@ module Capybara
         end
         @current_url     = nil
         @document_handle = 0
+        # A test may leave a frame switched-to without switching back
+        # (Capybara's reset_session spec covers exactly this); start the
+        # next test back on the main document.
+        reset_frame_scope
         @history.clear
         @history_idx     = -1
         @file_picks      = {} if @file_picks
@@ -2019,6 +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
@@ -2035,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)
@@ -2314,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
@@ -2559,6 +3044,50 @@ module Capybara
 
       def worker_pending? = !@worker_outbox.empty? || @worker_in_flight > 0
 
+      # ── Cross-window messaging (window.open / opener / postMessage) ──
+      # Each window is a separate Browser/VM/isolate, so a reference to another
+      # window can only be a proxy that forwards through the Driver. These
+      # forward host-fn calls (invoked from THIS window's VM) to the Driver,
+      # which routes to the target window's Browser.
+
+      # `window.open(url, name)` from JS — returns the new (or reused, by name)
+      # window's handle, or nil. The URL is resolved against THIS document so a
+      # relative `window.open('/x')` targets the right origin/path.
+      def open_child_window(url, name)
+        return nil unless @driver.respond_to?(:open_window_from_js)
+        @driver.open_window_from_js(self, url.to_s, name.to_s)
+      end
+
+      # `targetWindow.postMessage(data, origin)` — route to the target window's
+      # inbox, tagged with this window as the source.
+      def post_message_to_window(target_handle, data, origin)
+        return unless @driver.respond_to?(:window_post_message)
+        @driver.window_post_message(self, target_handle.to_s, data, origin.to_s)
+      end
+
+      def window_location_of(handle)   = @driver.respond_to?(:window_location)     ? @driver.window_location(handle.to_s).to_s     : ''
+      def set_window_location(handle, url) = (@driver.window_set_location(handle.to_s, url.to_s) if @driver.respond_to?(:window_set_location))
+      def window_closed?(handle)       = @driver.respond_to?(:window_closed?)      ? @driver.window_closed?(handle.to_s)           : true
+      def close_child_window(handle)   = (@driver.close_window(handle.to_s) if @driver.respond_to?(:close_window))
+      def opener_handle                = @driver.respond_to?(:opener_handle_of)    ? @driver.opener_handle_of(self)                : nil
+
+      # Queue a cross-window message for delivery into THIS window's VM (called
+      # by the Driver on the target Browser). Delivered as a `message` event the
+      # next time this window settles / ticks.
+      def enqueue_window_message(data, origin, source_handle)
+        @window_inbox << {'data' => data, 'origin' => origin.to_s, 'sourceHandle' => source_handle.to_s}
+      end
+
+      def window_message_pending? = !@window_inbox.empty?
+
+      # Fire queued cross-window messages as `message` events on window.
+      def deliver_window_messages
+        return 0 if @window_inbox.empty?
+        events = @window_inbox.slice!(0, @window_inbox.length)
+        @runtime.call('__csim_deliverWindowMessages', events)
+        events.size
+      end
+
       # ── Image decode (libvips) ─────────────────────────────────────
       #
       # Called by the JS bridge whenever a Canvas / OffscreenCanvas
@@ -2654,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
@@ -3169,6 +3717,95 @@ module Capybara
 
       # Fetch via the Rack app and hand the body to V8 for parsing.
       # Only follows 3xx redirects up to a small depth.
+      # ── Frame-scoped navigation ─────────────────────────────────
+      # A self-targeted link click / form submit INSIDE a `within_frame` block
+      # navigates just that frame: fetch the document and rebuild the frame's
+      # own realm, leaving the top page (its URL, history, status) untouched.
+      # 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)
+        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')
+          return
+        end
+        env = Rack::MockRequest.env_for(url, method: 'GET')
+        apply_default_request_env(env, referer: current_browsing_context_url)
+        status, headers, body = dispatch_rack_or_http(url, env, method: 'GET')
+        merge_set_cookie(headers)
+        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)
+        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))
+      end
+
+      def navigate_frame_post(url, body, content_type, depth: 0)
+        raise 'too many redirects' if depth > 10
+        invalidate_find_cache
+        env = Rack::MockRequest.env_for(url, method: 'POST', input: body)
+        env['CONTENT_TYPE']   = content_type.to_s.empty? ? 'application/x-www-form-urlencoded' : content_type
+        env['CONTENT_LENGTH'] = body.bytesize.to_s
+        apply_default_request_env(env, referer: current_browsing_context_url)
+        status, headers, resp_body = dispatch_rack_or_http(url, env, method: 'POST', body: body)
+        merge_set_cookie(headers)
+        if (loc = redirect_location(status, headers))
+          next_url = resolve_against_current(loc)
+          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)
+          else
+            return navigate_frame(next_url, depth: depth + 1)
+          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
+        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
+        invalidate_find_cache
+        settle
+      end
+
+      def rebind_frame_realm(parent_realm_id, iframe_handle, old_id, new_id)
+        if parent_realm_id.nil? || parent_realm_id.zero?
+          @runtime.call('__csimRebindFrameRealm', iframe_handle, old_id, new_id)
+        else
+          @runtime.realm_call(parent_realm_id, '__csimRebindFrameRealm', iframe_handle, old_id, new_id)
+        end
+      end
+
+      # Response content-type, defaulting to text/html. Header values can be a
+      # bare string or a one-element array (Rack 3 tuple form).
+      def response_content_type(headers)
+        ct = headers.find {|k, _| k.to_s.downcase == 'content-type' }&.last
+        ct = ct.first if ct.is_a?(Array)
+        ct.to_s.empty? ? 'text/html' : ct.to_s
+      end
+
       def navigate(url, depth: 0, referer: @current_url, from_history: false)
         raise 'too many redirects' if depth > 10
         invalidate_find_cache
@@ -3194,6 +3831,18 @@ module Capybara
         prior_navigating = @navigating
         @navigating = true unless from_history
         begin
+          # `about:blank` names an empty, network-less document — there's
+          # nothing to fetch. Rack::MockRequest.env_for can't parse the `about:`
+          # scheme (no host/path → nil[]); route straight to an empty document.
+          # `location = 'about:blank'` and navigating an iframe to about:blank
+          # both land here. Mirrors rack_fetch's non-http(s) guard. (Narrow to
+          # about:blank specifically — about:srcdoc carries its own markup.)
+          if url.to_s.match?(%r{\Aabout:blank(?:[?#]|\z)}i)
+            @current_url = url.to_s
+            record_response(200, {'content-type' => 'text/html'})
+            boot_response_into_ctx('')
+            return
+          end
           record_history({method: :get, url: url}) unless from_history || depth > 0
           env = Rack::MockRequest.env_for(url, method: 'GET')
           apply_default_request_env(env, referer: referer)
@@ -3259,6 +3908,9 @@ module Capybara
         # finish before the next document loads; this is the in-process analogue.
         flush_outgoing_page_init if @timers_active
         @runtime.rebuild_ctx
+        # A full page (re)build disposes every frame realm, so any active
+        # `within_frame` scope is now stale — fall back to the main document.
+        reset_frame_scope
         reset_timer_state
         # The DOCUMENT is text; the Rack body arrives BINARY-tagged (see
         # `RuntimeShared.utf8_text`). Charset-header-driven decode is the
@@ -3509,6 +4161,9 @@ module Capybara
 
       def resolve_against_current(url, use_base: false)
         return url if url =~ %r{\A[a-z]+://}i
+        # Inside a `within_frame` block the "current document" is the frame's,
+        # so links / form actions resolve against the frame's URL + <base href>.
+        doc_url = current_browsing_context_url || @default_host
         base =
           if use_base && (bh = base_href) && !bh.empty?
             # The document's `<base href>` takes precedence over the
@@ -3516,17 +4171,19 @@ module Capybara
             # being resolved — HTML's base-tag semantics. `visit` skips
             # this branch so an address-bar navigation reaches the URL
             # the test typed.
-            URI.join(@current_url || @default_host, bh).to_s
+            URI.join(doc_url, bh).to_s
           else
-            @current_url || @default_host
+            doc_url
           end
         URI.join(base, url.to_s).to_s
       rescue URI::InvalidURIError, URI::BadURIError
         url
       end
 
+      # The active document's `<base href>` — routed to the current frame realm
+      # inside `within_frame`, else the main document.
       def base_href
-        @runtime.call('__csimBaseHref').to_s
+        dom_call('__csimBaseHref').to_s
       end
 
       def carry_fragment(from_url, to_url)