capybara-simulated 0.3.0 → 0.5.0

data/lib/capybara/simulated/browser.rb

@@ -13,6 +13,7 @@ require 'socket'
 require 'thread'
 require 'time'
 require 'uri'
+require 'uri/idna'   # WHATWG/UTS46 domain-to-ASCII/Unicode (uri-idna gem)
 require_relative 'asset_cache'
 require_relative 'errors'
 require_relative 'stack_resolver'
@@ -315,11 +316,23 @@ module Capybara
         # so long-running compute (e.g. mozjpeg over an 8900×8900 frame)
         # isn't starved by the settle_gen idle gate.
         @worker_in_flight = 0
+        # Workers whose initial script hasn't finished running yet. A worker that
+        # posts immediately on spawn (no main->worker message first) would leave
+        # `@worker_in_flight` at 0, so `worker_pending?` would be false in the gap
+        # between spawn and that first post — and settle / tick_real_time would
+        # stop waiting before the message lands. Count spawned-but-not-initialised
+        # workers so the async drain holds until the initial script has run.
+        @worker_initializing = 0
+        @worker_init_lock = Mutex.new
         # Cross-isolate `blob:` store. Worker isolates can't see the
         # main scope's `__csimBlobs` Map, so we mirror bytes here and
         # workers resolve them through a host fn.
         @blob_registry = {}
         @blob_registry_lock = Mutex.new
+        # url => owning worker handle, for blob URLs created INSIDE a worker. A
+        # worker's blob URL store dies with it, so terminating the worker revokes
+        # them (url-lifetime "Terminating worker revokes its URLs").
+        @blob_owners = {}
         # Postmessage transferable-buffer store. Large Uint8Array /
         # ArrayBuffer payloads cross isolates as a Ruby-side byte ID
         # rather than a JSON base64 string, so peak JS heap stays flat.
@@ -340,6 +353,9 @@ module Capybara
         # `message` event the next time it's active and settles/ticks. Plain
         # array (same thread — windows aren't background-threaded like workers).
         @window_inbox         = []
+        # Cross-window BroadcastChannel messages from OTHER windows, delivered to
+        # this window's matching channels on settle. [{name, data}] (same thread).
+        @broadcast_inbox      = []
       end
 
       # Worker thread polling and termination intervals — split so a
@@ -531,13 +547,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
@@ -601,16 +618,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)
@@ -869,19 +897,21 @@ module Capybara
           # downloads from `click_link` complete inside the click
           # action.
           consume_pending_location
+          consume_pending_frame_nav
           return
         end
         case action['kind']
         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
@@ -890,7 +920,7 @@ module Capybara
           # 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))
+            @driver.open_aux_window(resolve_against_current(url, use_base: true), source: self, blob_snapshot: action['blob'])
           # In-page anchor links (`#frag` / current-page + `#frag`) move
           # the hash but don't fetch a new document. Pure-fragment also
           # short-circuits the `<a>`s test fixtures use as click sinks.
@@ -930,6 +960,7 @@ module Capybara
           # pending; if `@current_url` already changed mid-drain (the
           # navigate landed during a timer fire), skip the form submit
           # entirely — its form handle is in a stale VM by now.
+          consume_pending_frame_nav
           if @pending_location
             consume_pending_location
           elsif @current_url != submit_baseline_url
@@ -1444,7 +1475,7 @@ module Capybara
         url    = pending['url'].to_s
         target = pending['target'].to_s
         if !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))
+          @driver.open_aux_window(resolve_against_current(url, use_base: true), source: self, blob_snapshot: pending['blob'])
         elsif pure_fragment_navigation?(url)
           update_current_hash(url)
         else
@@ -1773,7 +1804,7 @@ module Capybara
         @stack_resolver ||= StackResolver.new(self)
       end
 
-      def log_network(method, url, status) = @trace&.log_network(method, url, status)
+      def log_network(method, url, status, **extra) = @trace&.log_network(method, url, status, **extra)
 
       # `tag#id.class` short description of the handle, for trace
       # `description` fields. One V8 round-trip; only paid when a step
@@ -2105,15 +2136,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
@@ -2126,7 +2157,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
@@ -2141,6 +2172,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}"]
@@ -2236,10 +2295,11 @@ module Capybara
         reset_workers
         reset_websockets
         @window_inbox.clear
+        @broadcast_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 }
+        @blob_registry_lock.synchronize { @blob_registry.clear; @blob_owners.clear }
         # Drop volatile entries from the class-level HTTP asset cache
         # so test-local DB state (TranslationOverride, etc.) reaches
         # the app on subsequent visits. Fingerprinted assets
@@ -2268,6 +2328,14 @@ module Capybara
         reset_hijacked_fetches
         reset_websockets
         @window_inbox.clear
+        @broadcast_inbox.clear
+        # Dispose the JS runtime/isolate itself — for an auxiliary window this
+        # Browser is the isolate's last owner, but V8Runtime registers every
+        # isolate in a process-wide `@@live` set (for at_exit cleanup), which
+        # pins it past a bare GC. Without this, each closed window leaked a live
+        # V8 isolate (RSS climbed across a long suite). Only reached on teardown,
+        # never on the per-test `reset!` path (which keeps the runtime).
+        @runtime.dispose if @runtime.respond_to?(:dispose)
       rescue StandardError
         nil
       end
@@ -2615,10 +2683,16 @@ module Capybara
 
       # `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)
+      # 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
-        ws_write_frame(sock, binary ? 0x2 : 0x1, data.to_s.b)
+        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
@@ -2990,7 +3064,7 @@ module Capybara
       # worker's `__csim_workerPostMessage` host fn closes over its
       # handle and routes outgoing messages onto a shared outbox the
       # main settle drains.
-      def worker_spawn(url)
+      def worker_spawn(url, shared: false)
         handle       = (@worker_seq += 1)
         inbox        = Thread::Queue.new
         outbox       = @worker_outbox
@@ -3002,9 +3076,11 @@ module Capybara
         # non-owning thread SEGVs (V8 isolates are thread-
         # bound; quickjs.rb's VM is similarly per-thread).
         body = fetch_worker_script(target)
+        # Pending until the worker's initial script has run (see @worker_initializing).
+        @worker_init_lock.synchronize { @worker_initializing += 1 }
         thread = Thread.new do
           Thread.current.report_on_exception = false
-          run_worker(handle, target, body, inbox, outbox, engine_class)
+          run_worker(handle, target, body, inbox, outbox, engine_class, shared: shared)
         end
         @workers[handle] = {thread: thread, inbox: inbox}
         handle
@@ -3022,13 +3098,21 @@ module Capybara
         return unless w
         w[:inbox] << :terminate
         # Most clean shutdowns are <10 ms; the kill is the fallback
-        # for blocked workers.
+        # for blocked workers. Join again AFTER the kill so the thread is actually
+        # dead before we revoke its URLs — `Thread#kill` is async, and a worker
+        # still running a `createObjectURL` could otherwise re-register a URL after
+        # the revoke and leak it.
         w[:thread].join(WORKER_TERMINATE_GRACE)
-        w[:thread].kill if w[:thread].alive?
+        if w[:thread].alive?
+          w[:thread].kill
+          w[:thread].join(WORKER_TERMINATE_GRACE)
+        end
         # A blocked worker that never returned messages leaves
         # `@worker_in_flight` permanently > 0; reset when no workers
         # remain so `polling?` can short-circuit again.
         @worker_in_flight = 0 if @workers.empty?
+        # The worker is gone — revoke the blob URLs it created.
+        revoke_worker_blobs(handle.to_i)
       end
 
       def deliver_worker_messages
@@ -3042,7 +3126,7 @@ module Capybara
         events.size
       end
 
-      def worker_pending? = !@worker_outbox.empty? || @worker_in_flight > 0
+      def worker_pending? = !@worker_outbox.empty? || @worker_in_flight > 0 || @worker_init_lock.synchronize { @worker_initializing } > 0
 
       # ── Cross-window messaging (window.open / opener / postMessage) ──
       # Each window is a separate Browser/VM/isolate, so a reference to another
@@ -3066,6 +3150,17 @@ module Capybara
       end
 
       def window_location_of(handle)   = @driver.respond_to?(:window_location)     ? @driver.window_location(handle.to_s).to_s     : ''
+      # Cross-window property reads (a WindowProxy `win.foo` / `win.document.foo`):
+      # route to the Driver, which reads a PRIMITIVE off the target window's VM.
+      def window_get(handle, prop)     = (@driver.respond_to?(:window_read) ? @driver.window_read(handle.to_s, prop.to_s, doc: false) : nil)
+      def window_doc_get(handle, prop) = (@driver.respond_to?(:window_read) ? @driver.window_read(handle.to_s, prop.to_s, doc: true)  : nil)
+      # Read a primitive property off THIS window's globalThis / document — called
+      # by the Driver to serve another window's cross-window proxy read.
+      def read_property(prop, doc: false)
+        @runtime.call('__csimReadWindowProp', doc, prop.to_s)
+      rescue StandardError
+        nil
+      end
       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))
@@ -3078,14 +3173,34 @@ module Capybara
         @window_inbox << {'data' => data, 'origin' => origin.to_s, 'sourceHandle' => source_handle.to_s}
       end
 
-      def window_message_pending? = !@window_inbox.empty?
+      # Covers both cross-window postMessage AND BroadcastChannel — the two
+      # cross-window event channels share these drain/pending hooks.
+      def window_message_pending? = !@window_inbox.empty? || !@broadcast_inbox.empty?
+
+      # A BroadcastChannel message from another window, queued for delivery to
+      # this window's channels with the same name.
+      def enqueue_broadcast(name, data) = (@broadcast_inbox << {'name' => name.to_s, 'data' => data})
 
-      # Fire queued cross-window messages as `message` events on window.
+      # Fire queued cross-window messages (postMessage + BroadcastChannel).
       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
+        n = 0
+        unless @window_inbox.empty?
+          events = @window_inbox.slice!(0, @window_inbox.length)
+          @runtime.call('__csim_deliverWindowMessages', events)
+          n += events.size
+        end
+        unless @broadcast_inbox.empty?
+          events = @broadcast_inbox.slice!(0, @broadcast_inbox.length)
+          @runtime.call('__csim_deliverBroadcasts', events)
+          n += events.size
+        end
+        n
+      end
+
+      # `BroadcastChannel.postMessage` in THIS window — fan out to every OTHER
+      # window's matching channels (same-window delivery happens in-VM).
+      def broadcast_to_windows(name, data)
+        @driver.broadcast_channel(self, name.to_s, data) if @driver.respond_to?(:broadcast_channel)
       end
 
       # ── Image decode (libvips) ─────────────────────────────────────
@@ -3148,8 +3263,24 @@ module Capybara
         }
       end
 
-      def blob_register(url, body_b64)
-        @blob_registry_lock.synchronize { @blob_registry[url.to_s] = body_b64.to_s }
+      def blob_register(url, body_b64, owner_realm = nil)
+        # Tag the creating context so the URL is revoked when that context goes
+        # away: a WORKER (separate thread, tagged via Thread.current) when it
+        # terminates ("Terminating worker"), or a FRAME REALM (owner_realm passed
+        # from JS createObjectURL) when the iframe is removed ("Removing an
+        # iframe"). Namespaced ('w:' / 'r:') so a worker handle and a realm id
+        # never collide. Main-realm blobs (no owner) live until clear_volatile.
+        worker = Thread.current[:csim_worker_handle]
+        key = if worker then "w:#{worker}"
+              elsif owner_realm && owner_realm.to_i != 0 then "r:#{owner_realm.to_i}"
+              end
+        @blob_registry_lock.synchronize do
+          @blob_registry[url.to_s] = body_b64.to_s
+          # Keep ownership in sync both ways: a (re-)registration with no owner
+          # (main thread / main realm) must DROP any prior owner, else revoking
+          # that context would wrongly revoke a now-page-owned URL.
+          if key then @blob_owners[url.to_s] = key else @blob_owners.delete(url.to_s) end
+        end
         nil
       end
 
@@ -3157,11 +3288,73 @@ module Capybara
         @blob_registry_lock.synchronize { @blob_registry[url.to_s] }
       end
 
+      # WHATWG URL "domain to ASCII" — the JS tr46 stub delegates non-ASCII / xn--
+      # hosts here (the ASCII fast path stays in-VM). Returns the punycode form, or
+      # nil on an IDNA failure (so whatwg-url reports "domain to ASCII failed").
+      # `be_strict: false` is the URL parser's mode (UseSTD3ASCIIRules and
+      # VerifyDnsLength off) — empty middle labels (`x..y`) and `_`/etc. are
+      # allowed, matching whatwg-url's `domainToASCII(domain, false)`.
+      def domain_to_ascii(domain)
+        URI::IDNA.whatwg_to_ascii(domain.to_s, be_strict: false)
+      rescue URI::IDNA::Error
+        nil   # a genuine IDNA failure (bad punycode / disallowed codepoint) — let
+              # whatwg-url report "domain to ASCII failed". Non-IDNA errors propagate.
+      end
+
+      # WHATWG URL "domain to Unicode" — best-effort (never fails the parse per
+      # spec), so on an IDNA error fall back to the input domain (unlike to_ascii,
+      # which signals failure with nil — the asymmetry is intentional).
+      def domain_to_unicode(domain)
+        URI::IDNA.whatwg_to_unicode(domain.to_s, be_strict: false)
+      rescue URI::IDNA::Error
+        domain.to_s
+      end
+
+      # Read a blob URL's bytes + content type from THIS window's VM (its local
+      # blob store) — the Driver uses it to load a blob: document into a fresh aux
+      # window opened by this window. Returns {bytes:, type:} or nil.
+      def read_blob_for_window(url)
+        r = @runtime.call('__csimReadBlobForWindow', url.to_s)
+        return nil unless r.is_a?(Hash) && r['b64']
+        { bytes: Base64.decode64(r['b64'].to_s), type: r['type'].to_s }
+      rescue StandardError
+        nil
+      end
+
+      # Load a blob: document (bytes from the opener) as THIS window's top-level
+      # document — for `window.open(blobURL)` / a blob: aux-window navigation,
+      # where the blob isn't rack-navigable and lives in the opener's isolate.
+      def boot_blob_document(url, bytes, content_type)
+        @current_url = url.to_s
+        ct = content_type.to_s.empty? ? 'text/html' : content_type.to_s
+        # Blob string parts are UTF-8-encoded; when the Blob type carries no
+        # charset, decode the document as UTF-8 (not the windows-1252 HTML locale
+        # default, which is an HTTP concept that doesn't apply to in-memory blobs —
+        # matches the iframe blob: path's decodeBlobBody). A charset in the Blob
+        # type (url-charset) is preserved so it can override <meta charset>.
+        ct = "#{ct};charset=utf-8" unless ct.downcase.include?('charset')
+        record_response(200, {'content-type' => ct})
+        boot_response_into_ctx(bytes)
+      end
+
       def blob_unregister(url)
-        @blob_registry_lock.synchronize { @blob_registry.delete(url.to_s) }
+        @blob_registry_lock.synchronize { @blob_registry.delete(url.to_s); @blob_owners.delete(url.to_s) }
         nil
       end
 
+      # Revoke every blob URL owned by a context that's going away (its blob URL
+      # store is part of the global being torn down).
+      def revoke_owned_blobs(key)
+        @blob_registry_lock.synchronize do
+          urls = @blob_owners.select {|_url, owner| owner == key }.keys
+          urls.each {|url| @blob_registry.delete(url); @blob_owners.delete(url) }
+        end
+      end
+      # Keys are normalized with `.to_i` on BOTH sides (register tags
+      # "r:#{owner_realm.to_i}") so a marshalled Float/String id still matches.
+      def revoke_worker_blobs(handle) = revoke_owned_blobs("w:#{handle.to_i}")
+      def revoke_realm_blobs(realm_id) = revoke_owned_blobs("r:#{realm_id.to_i}")
+
       # ── postMessage transferable-buffer registry ───────────────────
       #
       # Large Uint8Array / ArrayBuffer payloads cross isolates by ID;
@@ -3300,7 +3493,20 @@ module Capybara
       # `build_worker` factory, evaluates the worker script, then
       # loops draining microtasks + timers + inbox until `:terminate`
       # lands or an exception propagates.
-      private def run_worker(handle, url, body, inbox, outbox, engine_class)
+      private def run_worker(handle, url, body, inbox, outbox, engine_class, shared: false)
+        # Release the spawn-time `@worker_initializing` count exactly once, however
+        # this method exits (normal start, `self.close()`, or an exception), so
+        # worker_pending? doesn't stay stuck true forever.
+        initializing = true
+        release_init = lambda do
+          next unless initializing
+          initializing = false
+          @worker_init_lock.synchronize { @worker_initializing -= 1 }
+        end
+        # Tag this thread so blob URLs created by the worker's script are owned by
+        # this handle and revoked on terminate (see blob_register / revoke_worker_blobs).
+        Thread.current[:csim_worker_handle] = handle
+        rt = nil
         raise "worker script not found: #{url}" unless body
         # The worker SCRIPT is text; the Rack-fetched body arrives
         # BINARY-tagged (see `RuntimeShared.utf8_text`).
@@ -3313,16 +3519,34 @@ module Capybara
         # the snapshot-time `http://placeholder/`.
         rt.eval("globalThis.__csimUpdateLocation(#{JSON.generate(url.to_s)});")
         rt.eval(body)
-        loop do
-          msg = pop_with_timeout(inbox, WORKER_POLL_INTERVAL)
-          break if msg == :terminate
-          rt.call('__csim_workerOnMessage', msg) if msg
+        rt.drain_microtasks
+        # A SharedWorker fires `connect` AFTER its script set `self.onconnect`; the
+        # connect handler's port post lands in the outbox before release_init, so
+        # worker_pending? stays true until it's delivered.
+        if shared
+          rt.eval('typeof __csimFireSharedWorkerConnect === "function" && __csimFireSharedWorkerConnect();')
           rt.drain_microtasks
-          rt.drain_timers if rt.has_ready_timer?
+        end
+        # Initial script has run (and any immediate postMessage is in the outbox).
+        release_init.call
+        # A worker that called `self.close()` in its top-level script stops here —
+        # the script ran (and may have posted), but no further messages are pulled.
+        unless rt.eval('!!globalThis.__csimWorkerClosed')
+          loop do
+            msg = pop_with_timeout(inbox, WORKER_POLL_INTERVAL)
+            break if msg == :terminate
+            if msg
+              rt.call('__csim_workerOnMessage', msg)
+              rt.drain_microtasks
+              rt.drain_timers if rt.has_ready_timer?
+              break if rt.eval('!!globalThis.__csimWorkerClosed')
+            end
+          end
         end
       rescue StandardError => e
         outbox << {handle: handle, kind: '__error', message: "#{e.class}: #{e.message}"}
       ensure
+        release_init.call   # guarantee the init count is released on an early raise
         rt&.dispose
       end
 
@@ -3332,10 +3556,31 @@ module Capybara
       # circuit to the JS-side blob registry instead. Http(s) URLs
       # fall through to the regular Rack path.
       private def fetch_worker_script(url)
-        return rack_fetch_body(url) unless url.to_s.start_with?('blob:')
-        b64 = @runtime.call('__csimReadBlobBase64', url)
-        return nil unless b64
-        Base64.decode64(b64.to_s)
+        u = url.to_s
+        if u.start_with?('blob:')
+          b64 = @runtime.call('__csimReadBlobBase64', u)
+          return nil unless b64
+          return Base64.decode64(b64.to_s)
+        end
+        # `data:[<mediatype>][;base64],<data>` worker scripts (a worker created
+        # from a data: URL — its origin is opaque, so its blob: URLs serialize
+        # with a 'null' origin). Decode inline; Rack can't serve a data: URL.
+        return decode_data_url_body(u) if u.start_with?('data:')
+        rack_fetch_body(u)
+      end
+
+      # The decoded body of a `data:[<mediatype>][;base64],<data>` URL (RFC 2397):
+      # base64-decoded when the `;base64` flag is present, else percent-decoded.
+      private def decode_data_url_body(url)
+        comma = url.index(',')
+        return '' unless comma
+        meta    = url[5...comma]
+        payload = url[(comma + 1)..]
+        if meta =~ /;base64\s*\z/i
+          Base64.decode64(payload)
+        else
+          CGI.unescape(payload)
+        end
       end
 
       # `Thread::Queue#pop(timeout:)` blocks releasing the GVL — fine
@@ -3420,12 +3665,14 @@ module Capybara
           headers = headers.reject {|k, _| k == 'X-Csim-Body-B64' }
         end
         MAX_FETCH_REDIRECTS.times do
+          t0 = @trace && Process.clock_gettime(Process::CLOCK_MONOTONIC)
           # GET-only cache shortcut (RFC 9111). Fresh hit → skip @app.call
           # entirely; stale-but-revalidatable → fall through with conditional
           # headers added so the server can return 304.
           cache_entry = method == 'GET' ? @@asset_cache.lookup(target) : nil
           if cache_entry&.fresh?
-            log_network(method, target, cache_entry.status)
+            # Cached static asset — log headers/type/size but skip the (boring) body.
+            trace_network(method, target, cache_entry.status, headers, body, cache_entry.headers, nil, t0, false)
             return response_hash(cache_entry.status, cache_entry.headers, cache_entry.body, target, redirected)
           end
 
@@ -3436,14 +3683,16 @@ module Capybara
           env.merge!(env_extras) if env_extras
           status, resp_headers, resp_body = dispatch_rack_or_http(target, env, method: method, body: body)
           merge_set_cookie(resp_headers)
-          log_network(method, target, status)
           if status == 304 && cache_entry
+            trace_network(method, target, cache_entry.status, headers, body, cache_entry.headers, nil, t0, false)
             resp_body.close if resp_body.respond_to?(:close)
             @@asset_cache.refresh(cache_entry, resp_headers)
             return response_hash(cache_entry.status, cache_entry.headers, cache_entry.body, target, redirected)
           end
           if redirect_mode != 'manual' && (loc = redirect_location(status, resp_headers))
             raise StandardError, '[capybara-simulated] fetch: redirect blocked by redirect=error mode' if redirect_mode == 'error'
+            # Log this hop (3xx) before method/body are rewritten for the next.
+            trace_network(method, target, status, headers, body, resp_headers, nil, t0, true)
             redirected = true
             preserve = [307, 308].include?(status)
             next_url = resolve_against(loc, target)
@@ -3454,6 +3703,7 @@ module Capybara
             next
           end
           body_str = read_rack_body(resp_body)
+          trace_network(method, target, status, headers, body, resp_headers, body_str, t0, false)
           @@asset_cache.store(target, status, resp_headers, body_str) if method == 'GET'
           return response_hash(status, resp_headers, body_str, target, redirected)
         end
@@ -3463,6 +3713,63 @@ module Capybara
         nil
       end
 
+      # Cap per-body capture so one big asset/response can't bloat the
+      # trace. Generous (this is a local debugging artifact).
+      NETWORK_BODY_CAP = 256 * 1024
+
+      # Enriched network log for the trace: response content-type / byte
+      # size / elapsed ms / redirect flag, plus request + response headers
+      # and bodies (devtools-style). No-ops — and skips all the lookups —
+      # unless a trace is recording, so the fetch hot path is unaffected
+      # when tracing is off.
+      def trace_network(method, url, status, req_headers, req_body, resp_headers, resp_body, t0, redirected)
+        return unless @trace
+        ct = resp_headers && (resp_headers['content-type'] || resp_headers['Content-Type'])
+        ct = ct.first if ct.is_a?(Array)  # Rack 3 permits array-valued header fields
+        ct = ct.split(';', 2).first.strip if ct.is_a?(String)
+        size = if resp_body
+                 resp_body.bytesize
+               elsif (cl = resp_headers && (resp_headers['content-length'] || resp_headers['Content-Length']))
+                 (cl.is_a?(Array) ? cl.first : cl).to_i
+               end
+        log_network(method, url, status,
+                    content_type:     (ct if ct.is_a?(String)),
+                    size:             size,
+                    duration_ms:      (t0 && ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round),
+                    redirected:       (redirected || nil),
+                    request_headers:  normalize_trace_headers(req_headers),
+                    request_body:     (req_body && !req_body.to_s.empty? ? cap_trace_body(req_body) : nil),
+                    response_headers: normalize_trace_headers(resp_headers),
+                    response_body:    (resp_body ? cap_trace_body(resp_body) : nil))
+      rescue StandardError => e
+        # A trace-logging bug must NEVER break the real fetch: rack_fetch's
+        # own `rescue StandardError` would otherwise swallow it and return
+        # nil, so the asset (e.g. jQuery) silently fails to load. Drop the
+        # log entry instead.
+        warn "capybara-simulated: trace network log failed: #{e.class}: #{e.message}"
+      end
+
+      # JSON-safe body for the trace: binary (non-UTF-8) bodies become a
+      # placeholder rather than mojibake, and long bodies are truncated
+      # (scrubbed so a mid-codepoint cut can't yield invalid UTF-8).
+      #
+      # Rack response bodies are ASCII-8BIT (BINARY); reinterpret the bytes as
+      # UTF-8 up front and keep working in UTF-8 throughout. Otherwise a body
+      # whose bytes ARE valid UTF-8 but stays BINARY-tagged would flow out of
+      # here still BINARY, and the first concat with a UTF-8 string (the
+      # truncation marker here, or the trace-buffer / JSON serialization
+      # downstream) raises Encoding::CompatibilityError on any byte ≥ 0x80.
+      def cap_trace_body(body)
+        s = body.to_s.dup.force_encoding('UTF-8')
+        return "[binary, #{s.bytesize} bytes]" unless s.valid_encoding?
+        s.bytesize > NETWORK_BODY_CAP ? (s.byteslice(0, NETWORK_BODY_CAP).scrub + "\n…[truncated, #{s.bytesize} bytes total]") : s
+      end
+
+      def normalize_trace_headers(headers)
+        return nil unless headers
+        headers.each_with_object({}) {|(k, v), out| out[k.to_s] = v.is_a?(Array) ? v.join(', ') : v.to_s }
+      end
+
       # CGI convention: `Content-Type` and `Content-Length` land in env
       # *without* the HTTP_ prefix. Rails / Rack params parsing reads
       # `CONTENT_TYPE` and dispatches JSON / multipart parsers off it;
@@ -3499,7 +3806,14 @@ module Capybara
         # encoding per the HTML "decode" algorithm and is removed). The real
         # bytes for binary consumers ride `body_b64`; the Rack body arrives
         # BINARY-tagged (see `RuntimeShared.utf8_text`).
-        text = RuntimeShared.utf8_text(is_text ? decode_response_bom(raw) : raw)
+        bom_charset = nil
+        text =
+          if is_text
+            decoded, bom_charset = decode_response_bom(raw)
+            RuntimeShared.utf8_text(decoded)
+          else
+            RuntimeShared.utf8_text(raw)
+          end
         out = {
           'status'     => status,
           'headers'    => hdrs,
@@ -3508,29 +3822,66 @@ module Capybara
           'redirected' => redirected,
           'type'       => 'basic'
         }
+        # The BOM-detected encoding (if any) — a frame load pins its document's
+        # characterSet to it (see __csimFrameWindow); highest-precedence signal.
+        out['charset']  = bom_charset if bom_charset
         out['body_b64'] = Base64.strict_encode64(raw) unless is_text
         out
       end
 
-      # Strip + decode a single leading byte-order mark, mapping the body to a
-      # UTF-8 Ruby string. No BOM → return the bytes untouched (the hot path:
-      # just a 2–3 byte prefix check). One BOM is consumed; any further BOMs are
-      # ordinary U+FEFF characters in the decoded text (per spec the parser does
-      # not strip them again).
+      # Strip + decode a single leading byte-order mark, returning
+      # `[utf8_text, charset]` — `charset` is the BOM-selected Encoding-standard
+      # name (highest-precedence encoding signal) or nil when there's no BOM (the
+      # hot path: just a 2–3 byte prefix check). One BOM is consumed; any further
+      # BOMs are ordinary U+FEFF characters in the decoded text (per spec the
+      # parser does not strip them again).
+      # An XML-family document (XHTML / SVG / application+text/xml). Its encoding
+      # default is UTF-8 — the windows-1252 locale default is HTML-only.
+      def xml_content_type?(content_type)
+        mime = content_type.to_s.split(';', 2).first.to_s.strip.downcase
+        mime.end_with?('+xml') || mime == 'application/xml' || mime == 'text/xml'
+      end
+
+      # Does the response carry an explicit encoding signal (so the default
+      # windows-1252 decode must NOT apply)? A `charset=` in the Content-Type, or
+      # a `<meta charset>` / `<meta http-equiv=content-type … charset=…>` in the
+      # HTML prescan window (the first 1024 bytes, per the HTML sniffing algorithm).
+      # The `charset` must start a real attribute / content-charset (preceded by
+      # whitespace, a quote, or `;`), so hyphenated look-alikes — `data-charset=`,
+      # `accept-charset=` — don't false-trigger the signal.
+      def html_charset_signal?(content_type, raw)
+        return true if /;\s*charset\s*=/i.match?(content_type.to_s)
+        head = raw.to_s.b[0, 1024].to_s
+        /<meta\b[^>]*[\s"';]charset\s*=/i.match?(head)
+      end
+
+      # Decode bytes as windows-1252 (the HTML locale-default encoding) to a UTF-8
+      # Ruby string. Replaces undefined slots rather than raising.
+      def decode_windows1252(s)
+        s.to_s.b.dup.force_encoding(Encoding::WINDOWS_1252)
+         .encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+      rescue StandardError
+        RuntimeShared.utf8_text(s)
+      end
+
       def decode_response_bom(s)
         b = s.b
         if b.start_with?("\xEF\xBB\xBF".b)
-          b.byteslice(3..).force_encoding(Encoding::UTF_8)
+          [b.byteslice(3..).force_encoding(Encoding::UTF_8), 'UTF-8']
         elsif b.start_with?("\xFF\xFE".b) || b.start_with?("\xFE\xFF".b)
           # Generic UTF-16: the BOM picks endianness and is dropped by the decoder.
           # Replace malformed units rather than raising (a truncated/odd-length
           # body still yields readable UTF-8 instead of falling back to raw bytes).
-          b.force_encoding(Encoding::UTF_16).encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+          # A UTF-32LE BOM (FF FE 00 00) is matched here as UTF-16LE too — which is
+          # exactly what browsers do (UTF-32 unsupported; the leading FF FE is read
+          # as the UTF-16LE BOM).
+          charset = b.start_with?("\xFF\xFE".b) ? 'UTF-16LE' : 'UTF-16BE'
+          [b.force_encoding(Encoding::UTF_16).encode(Encoding::UTF_8, invalid: :replace, undef: :replace), charset]
         else
-          s
+          [s, nil]
         end
       rescue StandardError
-        s
+        [s, nil]
       end
 
       def text_response?(headers)
@@ -3566,10 +3917,52 @@ 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
       end
+      # A nested browsing context navigating its OWN `location` (the frame's
+      # `location.href`/assign/replace/`location=`, incl. cross-frame
+      # `iframe.contentWindow.location.href = …`). `realm_id` is the frame's realm.
+      # Deferred like location_assign: applying it re-navigates the owning iframe,
+      # which disposes that realm — illegal while the frame's location setter is
+      # still on the V8 stack — so we stash and drain from `tick_real_time`.
+      def frame_navigate_self(url, realm_id)
+        return if realm_id.nil? || realm_id.zero?
+        # Keyed by realm id (last URL wins per frame) so two different frames each
+        # navigating in one turn both apply — a single slot would drop one.
+        (@pending_frame_nav ||= {})[realm_id] = url.to_s
+      end
+      def consume_pending_frame_nav
+        return if @pending_frame_nav.nil? || @pending_frame_nav.empty?
+        navs = @pending_frame_nav
+        @pending_frame_nav = nil
+        navs.each do |realm_id, url|
+          invalidate_find_cache
+          # If this frame is on the entered `within_frame` stack, navigate it
+          # through `navigate_frame` — it does the full fetch (redirects /
+          # downloads / cookies) AND updates `@frame_stack` / `@current_realm_id`
+          # so the enclosing `within_frame` block sees the new document. Otherwise
+          # (a parent's `iframe.contentWindow.location.href = …`) re-navigate the
+          # owning iframe by realm id via the src-reassignment path. Top-level
+          # frames live in the main document; a nested non-entered frame's element
+          # is in its parent realm's DOM (not yet routed — documented gap).
+          entry = @frame_stack.find {|e| e[:realm_id] == realm_id }
+          if entry
+            navigate_frame(url, entry: entry)
+          else
+            @runtime.call('__csimNavigateFrameByRealm', realm_id, url)
+          end
+        rescue StandardError => e
+          log_console('warn', "frame self-navigation failed: #{e.message}")
+        end
+      end
       # Mirror of `location_assign`'s deferral for `location.reload()`:
       # the JS call lands here from `__locationReload`; running
       # `browser.refresh` directly would `navigate` (rebuilding the
@@ -3582,10 +3975,156 @@ module Capybara
         @pending_reload = false
         refresh
       end
+      # `frame.contentWindow.location.reload()` from a nested browsing context.
+      # Like `frame_navigate_self`, the JS side flags the initiating realm here
+      # and we defer (so the child realm isn't disposed mid-reload()). Keyed by
+      # realm id so two frames reloading in one turn both apply.
+      def frame_reload_self(realm_id)
+        return if realm_id.nil? || realm_id.zero?
+        (@pending_frame_reload ||= []) << realm_id
+      end
+      def consume_pending_frame_reload
+        return if @pending_frame_reload.nil? || @pending_frame_reload.empty?
+        realm_ids = @pending_frame_reload.uniq
+        @pending_frame_reload = nil
+        realm_ids.each do |realm_id|
+          invalidate_find_cache
+          # An entered `within_frame` frame reloads through `navigate_frame` (keeps
+          # the frame stack in sync) — re-fetching its current document URL, which
+          # we read from the still-alive realm. (A blob: URL entered this way is
+          # re-fetched through Rack and so does NOT reuse retained bytes — reloading
+          # an *entered* revoked-blob frame is an accepted gap; the common parent-
+          # held path below reuses bytes via reloadFrame.) Otherwise (a parent's
+          # `iframe.contentWindow.location.reload()`, empty href, or a realm torn
+          # down between flag and drain) re-navigate the owning iframe by realm id
+          # JS-side, reusing the retained content so blob bytes survive a revoke.
+          entry = @frame_stack.find {|e| e[:realm_id] == realm_id }
+          url   = entry && @runtime.frame_realm_alive?(realm_id) ? @runtime.realm_call(realm_id, '__csimLocationHref').to_s : ''
+          if entry && !url.empty?
+            navigate_frame(url, entry: entry)
+          else
+            @runtime.call('__csimReloadFrameByRealm', realm_id)
+          end
+        rescue StandardError => e
+          log_console('warn', "frame self-reload failed: #{e.message}")
+        end
+      end
+      # A <form> submitted from INSIDE a nested browsing context (a frame realm
+      # reached via `contentWindow`, not an entered `within_frame` block). The
+      # pending-submit slot lives on the initiating realm's globalThis, which no
+      # top-page drain reads, so the JS side flags the realm here (mirrors
+      # `frame_navigate_self`). Keyed by realm id; deferred + drained from
+      # `drain_pending_navigation` so we never serialize/navigate while the
+      # form's `submit()` is still on the V8 stack.
+      def frame_submit_self(realm_id)
+        return if realm_id.nil? || realm_id.zero?
+        (@pending_frame_submit ||= []) << realm_id
+      end
+      def consume_pending_frame_submit
+        return if @pending_frame_submit.nil? || @pending_frame_submit.empty?
+        realm_ids = @pending_frame_submit.uniq
+        @pending_frame_submit = nil
+        realm_ids.each do |realm_id|
+          next unless @runtime.frame_realm_alive?(realm_id)
+          sub = @runtime.realm_call(realm_id, '__csimTakePendingFormSubmit')
+          next unless sub.is_a?(Hash) && sub['formHandle']
+          invalidate_find_cache
+          submit_form_in_realm(realm_id, sub['formHandle'], sub['submitterHandle'])
+        rescue StandardError => e
+          log_console('warn', "nested-context form submission failed: #{e.message}")
+        end
+      end
+      # Serialize + route a form submitted inside frame realm `realm_id`. We
+      # serialize in the INITIATING realm (so shadow-tree controls are excluded
+      # and relative URLs resolve against that document), then route by target:
+      #   - a NAMED frame within that context (a sibling iframe) — reassign its src;
+      #   - self / _self / '' — navigate the initiating frame itself, same as a
+      #     self-targeted link there (within_frame → navigate_frame; a frame
+      #     reached via contentWindow → re-navigate its owning iframe by realm id).
+      # GET fully supported. POST to a self frame needs the entered stack
+      # (navigate_frame_post); POST-to-named and other targets from a nested
+      # context aren't modeled (no in-scope need) — logged rather than dropped.
+      def submit_form_in_realm(realm_id, form_handle, submitter_handle)
+        spec = @runtime.realm_call(realm_id, '__csimFormSerialize', form_handle, submitter_handle || 0)
+        return unless spec.is_a?(Hash)
+        method = spec['method'].to_s.upcase
+        method = 'GET' if method.empty?
+        target = spec['target'].to_s
+        action = spec['action'].to_s
+        fields = (spec['fields'] || []).map {|pair| [pair[0].to_s, pair[1].to_s] }
+        # Non-multipart file inputs contribute the filename only (mirror submit_form_handle's GET path).
+        (spec['fileInputs'] || []).each do |fi|
+          picks = @file_picks && @file_picks[fi['handle'].to_i] || []
+          fields << [fi['name'].to_s, picks.first ? File.basename(picks.first) : '']
+        end
+        body    = URI.encode_www_form(fields)
+        get_url = form_get_url(action, body)
+        if frame_self_target?(target)
+          navigate_realm_self(realm_id, get_url, action, method, body, spec['enctype'].to_s)
+        elsif %w[_parent _top _blank].include?(target.downcase)
+          log_console('warn', "nested-context form submit (target=#{target.inspect}) is not modeled")
+        elsif method == 'GET'
+          # Named sibling frame, GET. realm_call returns false when no frame of
+          # that name exists in the initiating document (e.g. it lives in an
+          # ancestor/top context, which HTML target resolution would reach but
+          # we don't); surface it rather than dropping silently.
+          found = @runtime.realm_call(realm_id, '__csimNavigateNamedFrame', target, get_url)
+          log_console('warn', "nested-context form submit: no frame named #{target.inspect} in the submitting document") unless found
+        else
+          log_console('warn', "nested-context form submit (target=#{target.inspect}, method=POST) is not modeled")
+        end
+      end
+      # HTML form-submission "mutate action URL" for GET: REPLACE the action
+      # URL's query with the serialized entry list (dropping any pre-existing
+      # query), preserving a trailing #fragment. String-based so it works on the
+      # raw (possibly relative) action attribute without URI.parse fragility;
+      # the absolute equivalent of submit_form_handle's `uri.query = body`.
+      def form_get_url(action, body)
+        return action if body.empty?
+        base, _hash, frag = action.partition('#')
+        path = base.split('?', 2).first
+        url  = "#{path}?#{body}"
+        frag.empty? ? url : "#{url}##{frag}"
+      end
+      # Navigate the initiating frame realm itself (a self-targeted form submit).
+      def navigate_realm_self(realm_id, get_url, action, method, body, enctype)
+        entry = @frame_stack.find {|e| e[:realm_id] == realm_id }
+        if method == 'GET'
+          if entry
+            navigate_frame(resolve_against_current(get_url), entry: entry)
+          else
+            # A frame reached via contentWindow (not on the entered stack): its
+            # owning iframe lives in the parent document — re-navigate by realm id
+            # (relative get_url resolves against the frame's base on rebuild).
+            @runtime.call('__csimNavigateFrameByRealm', realm_id, get_url)
+          end
+        elsif entry
+          navigate_frame_post(resolve_against_current(action), body, enctype, entry: entry)
+        else
+          log_console('warn', "nested-context self-form POST (realm #{realm_id}) is not modeled")
+        end
+      end
       def drain_pending_navigation
         consume_pending_location
+        consume_pending_frame_nav
+        consume_pending_frame_submit
+        consume_pending_frame_reload
         consume_pending_reload
         consume_pending_history_traverse
+        consume_pending_aux_window
+      end
+
+      # A script-driven `anchor.click()` / `target=_blank` navigation with no
+      # Capybara action behind it (e.g. a WPT test) — open the aux window from the
+      # event-loop drain. Safe mid-call (builds a separate Browser). Same-window /
+      # frame navs are left untouched (handled by drain_after_user_action).
+      def consume_pending_aux_window
+        pending = @runtime.call('__csimTakePendingAuxWindow')
+        return unless pending.is_a?(Hash) && pending['url'] && @driver.respond_to?(:open_aux_window)
+        @driver.open_aux_window(resolve_against_current(pending['url'].to_s, use_base: true),
+                                source: self, blob_snapshot: pending['blob'])
+      rescue StandardError => e
+        log_console('warn', "aux-window open failed: #{e.message}")
       end
       # POST-after-POST resubmits with the original body; GET-after-GET
        # is just a re-GET. Replay the current history entry.
@@ -3724,11 +4263,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')
@@ -3738,16 +4277,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)
@@ -3761,31 +4300,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
@@ -3912,11 +4473,31 @@ module Capybara
         # `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
-        # fuller story; UTF-8 + scrub matches observable browser behavior
-        # for the suites we run.
-        html = RuntimeShared.utf8_text(html)
+        # The response content type drives both the parser choice (XML vs HTML —
+        # XHTML/XML/SVG parse case-sensitively, no html/head/body skeleton,
+        # `isHtmlDocument` false) and the encoding's HTTP-charset signal.
+        ct = (@last_response_headers || {}).find {|k, _| k.to_s.downcase == 'content-type' }&.last
+        ct = ct.first if ct.is_a?(Array)
+        # HTML document encoding sniffing (the body arrives BINARY-tagged; see
+        # `RuntimeShared.utf8_text`). A leading BOM wins (over <meta charset>) and
+        # is stripped. Otherwise, for an HTML document with NO encoding signal — no
+        # charset in the Content-Type AND no <meta charset> in the prescan — the
+        # locale default is windows-1252 and the bytes decode as such; there is NO
+        # UTF-8 sniffing (WPT encoding/sniffing). A declared charset keeps the
+        # UTF-8 + scrub path (the JS side reports it from the meta; a declared
+        # non-UTF-8 multibyte charset is still UTF-8-decoded — legacy multibyte
+        # tables are out of scope). The windows-1252 default is HTML-only: an XML
+        # document (XHTML/SVG/application+text/xml) defaults to UTF-8, and an empty
+        # body (about:blank, a blank 200) stays UTF-8 too.
+        decoded, doc_charset = decode_response_bom(html)
+        if doc_charset
+          html = RuntimeShared.utf8_text(decoded)
+        elsif html.to_s.empty? || xml_content_type?(ct) || html_charset_signal?(ct, html)
+          html = RuntimeShared.utf8_text(html)
+        else
+          html = decode_windows1252(html)
+          doc_charset = 'windows-1252'
+        end
         opts = {
           'traceActive'        => !@trace.nil?,
           'timezone'           => ENV['TZ'].to_s,
@@ -3924,12 +4505,13 @@ module Capybara
           'url'                => @current_url.to_s,
           'html'               => html
         }
-        # Carry the response content type so the JS side can pick the XML vs
-        # HTML parser (XHTML / XML / SVG documents parse case-sensitively, with
-        # no html/head/body skeleton, and report `isHtmlDocument` false).
-        ct = (@last_response_headers || {}).find {|k, _| k.to_s.downcase == 'content-type' }&.last
-        ct = ct.first if ct.is_a?(Array)
         opts['contentType'] = ct.to_s if ct && !ct.to_s.empty?
+        # The detected document encoding pins document.characterSet (over meta).
+        opts['charset'] = doc_charset if doc_charset
+        # `document.lastModified` reflects the response Last-Modified header (parsed
+        # to local time); absent → the current time (handled JS-side).
+        lm = response_headers['Last-Modified']   # response_headers normalizes keys to Capitalized-Dash form
+        opts['lastModified'] = lm if lm && !lm.to_s.empty?
         if @viewport_width && @viewport_height
           opts['viewportW'] = @viewport_width
           opts['viewportH'] = @viewport_height
@@ -3950,9 +4532,12 @@ module Capybara
       # timer can't abort loading the next page (the page it would affect is
       # being discarded on the very next line).
       def flush_outgoing_page_init
-        saved_location = @pending_location
-        saved_reload   = @pending_reload
-        saved_traverse = @pending_history_traverse
+        saved_location     = @pending_location
+        saved_reload       = @pending_reload
+        saved_traverse     = @pending_history_traverse
+        saved_frame_nav    = @pending_frame_nav
+        saved_frame_submit = @pending_frame_submit
+        saved_frame_reload = @pending_frame_reload
         begin
           @runtime.run_loop_step(0, SETTLE_MAX_ITER_TASKS, yield_on_gen: false)
         rescue StandardError
@@ -3961,6 +4546,13 @@ module Capybara
           @pending_location         = saved_location
           @pending_reload           = saved_reload
           @pending_history_traverse = saved_traverse
+          # Don't let a frame-nav / frame-submit / frame-reload intent stashed by
+          # an outgoing-page timer leak into the fresh page — its realm id belongs
+          # to the discarded page (and a reused context id could mis-fire against
+          # an unrelated realm on the new page).
+          @pending_frame_nav        = saved_frame_nav
+          @pending_frame_submit     = saved_frame_submit
+          @pending_frame_reload     = saved_frame_reload
         end
       end