diff --git a/lib/percy.rb b/lib/percy.rb
index 08d4971..8e9b915 100644
--- a/lib/percy.rb
+++ b/lib/percy.rb
@@ -1,11 +1,36 @@
 require 'uri'
 require 'json'
+require 'set'
 require 'version'
 require 'net/http'
 require 'selenium-webdriver'
 require_relative 'driver_metadata'
 
 module Percy
+  # Maximum nesting depth for cross-origin iframe recursion. Bounds the cost
+  # of pathological pages and prevents runaway recursion on cyclic frame trees.
+  DEFAULT_MAX_FRAME_DEPTH = 10
+
+  # Absolute ceiling on iframe nesting depth, regardless of user config. Mirrors
+  # the canonical sibling SDKs (Nightwatch/Protractor shims cap at 25).
+  HARD_MAX_FRAME_DEPTH = 25
+
+  # Iframe src prefixes / sentinels we never attempt to switch into -- these
+  # represent either browser-internal documents, non-HTTP URI schemes, or
+  # placeholder values that have no meaningful CORS content to capture.
+  UNSUPPORTED_IFRAME_SRCS = %w[
+    about: chrome: chrome-extension: devtools: edge: opera: view-source:
+    data: javascript: blob: vbscript: file:
+  ].freeze
+
+  # Raised when a nested-frame restoration step fails and we can no longer
+  # trust that subsequent driver.switch_to / find_elements calls will resolve
+  # against the correct frame context. Carries any iframes captured before
+  # the loss so the caller can still preserve partial work.
+  class PercyContextLost < StandardError
+    attr_accessor :partial_capture
+  end
+
   CLIENT_INFO = "percy-selenium-ruby/#{VERSION}".freeze
   ENV_INFO = "selenium/#{Selenium::WebDriver::VERSION} ruby/#{RUBY_VERSION}".freeze
 
@@ -79,6 +104,9 @@ def self.snapshot(driver, name, options = {})
     begin
       percy_dom_script = fetch_percy_dom
       driver.execute_script(percy_dom_script)
+      # Expose closed shadow roots via CDP before serialization so PercyDOM
+      # can pierce them. No-op for non-Chromium drivers / when CDP fails.
+      expose_closed_shadow_roots(driver)
       dom_snapshot = if responsive_snapshot_capture?(options)
         capture_responsive_dom(driver, options, percy_dom_script: percy_dom_script)
       else
@@ -108,6 +136,88 @@ def self.snapshot(driver, name, options = {})
     end
   end
 
+  # Use CDP to discover closed shadow roots and expose them to
+  # PercyDOM.serialize(). Closed shadow roots are inaccessible from JavaScript
+  # (element.shadowRoot is null), but CDP's DOM domain can pierce them. For
+  # each closed shadow root we resolve both the host and the shadow root to JS
+  # objects, then store the shadow in a host-keyed WeakMap that clone-dom.js
+  # reads during serialization. Three CDP calls per closed root:
+  # DOM.getDocument (once, deep+pierce), then resolveNode + resolveNode +
+  # Runtime.callFunctionOn per pair. Non-fatal on any failure -- closed shadow
+  # DOM simply won't be captured (the existing behavior).
+  def self.expose_closed_shadow_roots(driver)
+    return unless driver.respond_to?(:execute_cdp)
+
+    begin
+      result = driver.execute_cdp('DOM.getDocument', depth: -1, pierce: true)
+    rescue StandardError => e
+      log("CDP unavailable for closed shadow root discovery: #{e}", 'debug')
+      return
+    end
+
+    root = result.is_a?(Hash) ? (result['root'] || result[:root]) : nil
+    return unless root
+
+    closed_pairs = []
+    walker = lambda do |node|
+      return if node.nil?
+      # Skip nodes inside child frame documents -- cross-frame closed shadow
+      # roots are not yet supported (their execution context lacks the WeakMap)
+      return if node['contentDocument'] || node[:contentDocument]
+
+      shadow_roots = node['shadowRoots'] || node[:shadowRoots]
+      if shadow_roots.is_a?(Array)
+        shadow_roots.each do |sr|
+          type = sr['shadowRootType'] || sr[:shadowRootType]
+          if type == 'closed'
+            closed_pairs << {
+              host_backend_id: node['backendNodeId'] || node[:backendNodeId],
+              shadow_backend_id: sr['backendNodeId'] || sr[:backendNodeId],
+            }
+          end
+          walker.call(sr)
+        end
+      end
+
+      children = node['children'] || node[:children]
+      children.each(&walker) if children.is_a?(Array)
+    end
+    walker.call(root)
+
+    return if closed_pairs.empty?
+
+    log("Found #{closed_pairs.length} closed shadow root(s), exposing via CDP", 'debug')
+
+    begin
+      driver.execute_script(
+        'window.__percyClosedShadowRoots = window.__percyClosedShadowRoots || new WeakMap();',
+      )
+
+      closed_pairs.each do |pair|
+        host = driver.execute_cdp('DOM.resolveNode', backendNodeId: pair[:host_backend_id])
+        shadow = driver.execute_cdp('DOM.resolveNode', backendNodeId: pair[:shadow_backend_id])
+        host_obj = host.is_a?(Hash) ? (host['object'] || host[:object]) : nil
+        shadow_obj = shadow.is_a?(Hash) ? (shadow['object'] || shadow[:object]) : nil
+        next unless host_obj && shadow_obj
+
+        host_id = host_obj['objectId'] || host_obj[:objectId]
+        shadow_id = shadow_obj['objectId'] || shadow_obj[:objectId]
+        next unless host_id && shadow_id
+
+        driver.execute_cdp(
+          'Runtime.callFunctionOn',
+          functionDeclaration:
+            'function(shadowRoot) { window.__percyClosedShadowRoots.set(this, shadowRoot); }',
+          objectId: host_id,
+          arguments: [{objectId: shadow_id}],
+        )
+      end
+    rescue StandardError => e
+      # Non-fatal -- closed shadow DOM just won't be captured
+      log("Could not expose closed shadow roots via CDP: #{e}", 'debug')
+    end
+  end
+
   def self.get_browser_instance(driver)
     if driver.respond_to?(:driver) && driver.driver.respond_to?(:browser)
       return driver.driver.browser.manage
@@ -184,50 +294,276 @@ def self.get_serialized_dom(driver, options, percy_dom_script: nil)
     # wait_for_ready upstream, not a PercyDOM.serialize argument.
     serialize_options = options.reject { |k, _| k.to_s == 'readiness' }
     dom_snapshot = driver.execute_script("return PercyDOM.serialize(#{serialize_options.to_json})")
+    # Guard against a non-Hash serialize result (nil/old PercyDOM) before we
+    # index into it below for readiness_diagnostics / corsIframes / cookies.
+    # Matches canonical Nightwatch behaviour (`if (!domSnapshot) domSnapshot = {}`).
+    dom_snapshot = {} unless dom_snapshot.is_a?(Hash)
     # `!nil?` preserves legitimate falsy returns like {} ("gate ran, no
     # notable diagnostics").
     if !readiness_diagnostics.nil? && dom_snapshot.is_a?(Hash)
       dom_snapshot['readiness_diagnostics'] = readiness_diagnostics
     end
+    if percy_dom_script
+      max_depth = resolve_max_frame_depth(options, @cli_config)
+      ignore_selectors = resolve_ignore_selectors(options, @cli_config)
+      ctx = {
+        max_frame_depth: max_depth,
+        ignore_selectors: ignore_selectors,
+        serialize_options: options,
+        percy_dom_script: percy_dom_script,
+      }
+      processed = capture_cors_iframes(driver, ctx)
+      dom_snapshot['corsIframes'] = processed if processed.any?
+    end
+
+    dom_snapshot['cookies'] = get_browser_instance(driver).all_cookies
+    dom_snapshot
+  end
+
+  # Top-level entry: enumerate iframes from the page document, filter the
+  # ones we should never enter (browser-internal, srcdoc, same-origin,
+  # ignored), then recurse into each one through process_frame_tree. A
+  # PercyContextLost raised by a deeper frame aborts further sibling
+  # iteration but preserves whatever we already captured.
+  def self.capture_cors_iframes(driver, ctx)
+    page_url = driver.current_url
+    page_origin = begin
+                    get_origin(page_url)
+                  rescue StandardError
+                    nil
+                  end
+    iframes_meta = enumerate_iframes(driver, ctx[:ignore_selectors])
+    return [] if iframes_meta.empty?
+
+    cors = []
+    iframes_meta.each do |meta|
+      next if should_skip_iframe?(meta, page_origin)
+
+      element = find_iframe_by_percy_id(driver, meta['percyElementId'])
+      next if element.nil?
+
+      begin
+        entries = process_frame_tree(driver, element, meta, 1,
+          Set.new([page_url].compact), ctx,)
+        cors.concat(entries) if entries.any?
+      rescue PercyContextLost => e
+        log('Aborting further nested CORS capture due to lost frame context', 'debug')
+        cors.concat(e.partial_capture) if e.partial_capture&.any?
+        break
+      end
+    end
+
+    cors
+  rescue StandardError => e
+    log("Failed to process cross-origin iframes: #{e}", 'debug')
     begin
-      page_origin = get_origin(driver.current_url)
-      iframes = percy_dom_script ? driver.find_elements(:tag_name, 'iframe') : []
-      if iframes.any?
-        processed_frames = []
-        iframes.each do |frame|
-          frame_src = frame.attribute('src')
-          next if unsupported_iframe_src?(frame_src)
+      driver.switch_to.default_content
+    rescue StandardError
+      nil
+    end
+    []
+  end
 
-          begin
-            frame_origin = get_origin(URI.join(driver.current_url, frame_src).to_s)
-          rescue StandardError => e
-            log("Skipping iframe \"#{frame_src}\": #{e}", 'debug')
-            next
-          end
+  def self.enumerate_iframes(driver, ignore_selectors)
+    result = driver.execute_script("return #{enumerate_iframes_script(ignore_selectors)}")
+    result.is_a?(Array) ? result : []
+  rescue StandardError => e
+    log("Failed to enumerate iframes: #{e}", 'debug')
+    []
+  end
 
-          next if frame_origin == page_origin
+  # Look up an <iframe> WebElement by its percyElementId (set by PercyDOM.serialize
+  # on the parent document). Using a stable identifier instead of positional
+  # alignment against driver.find_elements(:tag_name, 'iframe') eliminates a
+  # race window where a DOM mutation between the JS enumerate_iframes call and
+  # the Selenium find_elements call would silently shuffle meta -> element
+  # mappings and ship one iframe's content under another's percyElementId.
+  def self.find_iframe_by_percy_id(driver, percy_element_id)
+    return nil if percy_element_id.nil? || percy_element_id.to_s.empty?
+
+    # CSS attribute selectors don't accept arbitrary unescaped quotes; the
+    # percyElementId is a UUID-like value emitted by PercyDOM, so a simple
+    # equality match is sufficient in practice. We still CSS-escape backslashes
+    # and double-quotes defensively so a non-UUID id can't break the selector
+    # or open an injection vector. Anything beyond that which still trips the
+    # parser falls through to the rescue below and returns nil.
+    # Single-pass escape so backslash and quote escaping can't tangle: each
+    # match is replaced with itself prefixed by a backslash.
+    escaped = percy_element_id.to_s.gsub(/[\\"]/) { |c| "\\#{c}" }
+    driver.find_element(css: %(iframe[data-percy-element-id="#{escaped}"]))
+  rescue StandardError => e
+    log("Could not locate iframe by percyElementId #{percy_element_id}: #{e}", 'debug')
+    nil
+  end
 
-          result = process_frame(driver, frame, options, percy_dom_script)
-          processed_frames << result if result
+  def self.should_skip_iframe?(meta, parent_origin)
+    src = meta['src']
+    # data-percy-ignore lets page authors opt a single iframe out of capture
+    # without needing a project-wide selector configuration.
+    if meta['dataPercyIgnore']
+      log("Skipping iframe marked with data-percy-ignore: #{src || '(no src)'}", 'debug')
+      return true
+    end
+    # ignoreIframeSelectors is project- or call-level config -- selector match
+    # is computed in-browser by enumerate_iframes_script against the page's
+    # current DOM, so we just trust the flag here.
+    if meta['matchesIgnoreSelector']
+      log("Skipping iframe matching ignoreIframeSelectors: #{src || '(no src)'}", 'debug')
+      return true
+    end
+    return true if is_unsupported_iframe_src?(src)
+    return true if meta['srcdoc'] && !meta['srcdoc'].to_s.empty?
+    return true if meta['percyElementId'].nil? || meta['percyElementId'].to_s.empty?
+
+    frame_origin = begin
+                     get_origin(src)
+                   rescue StandardError
+                     nil
+                   end
+    return true if frame_origin.nil?
+    return true if frame_origin == parent_origin
+
+    false
+  end
+
+  # Switch into iframe_element, serialize its document, then recurse into
+  # nested cross-origin iframes that live inside it. Depth-capped against
+  # ctx[:max_frame_depth] and guarded against cyclic frame trees by
+  # ancestor_urls. Restores the parent frame on exit; if that restoration
+  # fails inside a nested call, raises PercyContextLost carrying the partial
+  # capture so the caller can preserve work done before the loss.
+  def self.process_frame_tree(driver, iframe_element, meta, depth, ancestor_urls, ctx)
+    if depth > ctx[:max_frame_depth]
+      log("Reached max iframe nesting depth (#{ctx[:max_frame_depth]}); " \
+          "stopping at #{meta['src']}", 'debug',)
+      return []
+    end
+    if ancestor_urls.include?(meta['src'])
+      log("Skipping cyclic iframe (#{meta['src']} appears in ancestor chain)", 'debug')
+      return []
+    end
+
+    collected = []
+    switched_in = false
+
+    begin
+      driver.switch_to.frame(iframe_element)
+      switched_in = true
+
+      driver.execute_script(ctx[:percy_dom_script])
+
+      # Post-switch URL re-check: failed cross-origin navigations land on
+      # about:blank or chrome-error://... in the iframe's *document* context.
+      # The pre-switch shouldSkipIframe filter on meta['src'] can't see this --
+      # the attribute still holds the original https:// URL. Drop these so we
+      # don't ship browser error pages as "captured" content.
+      frame_url = begin
+                    driver.execute_script('return document.URL')
+                  rescue StandardError
+                    meta['src']
+                  end
+      if is_unsupported_iframe_src?(frame_url)
+        log("Skipping iframe whose document loaded an unsupported URL: #{frame_url}", 'debug')
+        return collected
+      end
+
+      iframe_options = (ctx[:serialize_options] || {}).merge('enableJavaScript' => true)
+      iframe_snapshot =
+        driver.execute_script("return PercyDOM.serialize(#{iframe_options.to_json})")
+
+      if iframe_snapshot.nil?
+        log("Serialization returned empty result for frame: #{meta['src']}", 'debug')
+        return collected
+      end
+
+      collected << {
+        'iframeData' => {'percyElementId' => meta['percyElementId']},
+        'iframeSnapshot' => iframe_snapshot,
+        'frameUrl' => frame_url || meta['src'],
+      }
+      log("Captured cross-origin iframe (depth #{depth}): #{frame_url || meta['src']}", 'debug')
+
+      if depth < ctx[:max_frame_depth]
+        current_origin = begin
+                           get_origin(frame_url || meta['src'])
+                         rescue StandardError
+                           nil
+                         end
+        child_metas = enumerate_iframes(driver, ctx[:ignore_selectors])
+        next_ancestors = ancestor_urls.dup
+        next_ancestors.add(meta['src'])
+        next_ancestors.add(frame_url) if frame_url
+        child_metas.each do |child_meta|
+          next if should_skip_iframe?(child_meta, current_origin)
+
+          child_element = find_iframe_by_percy_id(driver, child_meta['percyElementId'])
+          next if child_element.nil?
+
+          nested = process_frame_tree(driver, child_element, child_meta, depth + 1,
+            next_ancestors, ctx,)
+          collected.concat(nested) if nested.any?
         end
-        dom_snapshot['corsIframes'] = processed_frames if processed_frames.any?
       end
+
+      collected
+    rescue PercyContextLost => e
+      # Merge any partial capture from the inner level into ours before propagating
+      if e.partial_capture&.any?
+        collected.concat(e.partial_capture)
+      end
+      e.partial_capture = collected
+      raise
     rescue StandardError => e
-      log("Failed to process cross-origin iframes: #{e}", 'debug')
-      begin
-        driver.switch_to.default_content
-      rescue StandardError
-        nil
+      log("Failed to process cross-origin iframe #{meta['src']}: #{e}", 'debug')
+      collected
+    ensure
+      if switched_in
+        # Step up exactly one level so an outer recursion continues from its
+        # own context. If parent_frame fails we have no reliable way to land
+        # in the correct parent -- fall back to default_content and raise
+        # PercyContextLost so the caller stops iterating siblings whose
+        # enumeration was performed in a now-lost context. We raise regardless
+        # of depth (matching canonical Nightwatch/Protractor): even at depth=1
+        # the outer capture_cors_iframes loop is mid-iteration over sibling
+        # iframe references resolved against the now-stale parent context, so
+        # silently continuing risks attaching one iframe's serialized content
+        # under another's percyElementId (a silent cross-attachment bug).
+        begin
+          driver.switch_to.parent_frame
+        rescue StandardError => e
+          log("Failed to switch back to parent frame: #{e}", 'debug')
+          begin
+            driver.switch_to.default_content
+          rescue StandardError
+            nil
+          end
+          err = PercyContextLost.new("Lost parent frame context: #{e.message}")
+          err.partial_capture = collected
+          raise err
+        end
       end
     end
+  end
 
-    dom_snapshot['cookies'] = get_browser_instance(driver).all_cookies
-    dom_snapshot
+  # Inlined helper: returns true for srcs we should never attempt to switch
+  # into (browser-internal, non-HTTP schemes, or placeholders). Also used
+  # post-switch on document.URL to catch about:blank / error-page redirects
+  # that aren't visible in the static src attribute.
+  # rubocop:disable Naming/PredicateName
+  def self.is_unsupported_iframe_src?(src)
+    return true if src.nil? || src.to_s.empty?
+
+    # Match case-insensitively so mixed-case schemes (JavaScript:, FILE://,
+    # ABOUT:BLANK) are caught -- mirrors every sibling SDK, which lowercases
+    # the src before the prefix check.
+    s = src.to_s.downcase
+    UNSUPPORTED_IFRAME_SRCS.any? { |prefix| s.start_with?(prefix) }
   end
+  # rubocop:enable Naming/PredicateName
 
+  # Backwards-compatible alias for the original method name.
   def self.unsupported_iframe_src?(src)
-    src.nil? || src.empty? || src == 'about:blank' ||
-      src.start_with?('javascript:') || src.start_with?('data:') || src.start_with?('vbscript:')
+    is_unsupported_iframe_src?(src)
   end
 
   def self.get_origin(url)
@@ -240,53 +576,77 @@ def self.get_origin(url)
     "#{uri.scheme}://#{netloc}"
   end
 
-  def self.process_frame(driver, frame_element, options, percy_dom_script)
-    frame_url = frame_element.attribute('src') || 'unknown-src'
-    iframe_snapshot = nil
+  # Clamp a user-supplied iframe depth to a sane range. Negative or non-numeric
+  # input falls back to the default; very large values are capped to avoid
+  # unbounded recursion on degenerate pages.
+  def self.clamp_frame_depth(depth, default: DEFAULT_MAX_FRAME_DEPTH)
+    return default if depth.nil?
 
-    begin
-      driver.switch_to.frame(frame_element)
-      begin
-        driver.execute_script(percy_dom_script)
-        iframe_options = options.merge('enableJavaScript' => true)
-        iframe_snapshot =
-          driver.execute_script("return PercyDOM.serialize(#{iframe_options.to_json})")
-      rescue StandardError => e
-        log("Failed to process cross-origin frame #{frame_url}: #{e}", 'debug')
-      ensure
-        begin
-          driver.switch_to.default_content
+    n = begin
+          Integer(depth)
         rescue StandardError
-          begin
-            driver.switch_to.parent_frame
-          rescue StandardError
-            nil
-          end
+          nil
         end
-      end
-    rescue StandardError => e
-      log("Failed to switch to frame #{frame_url}: #{e}", 'debug')
-      begin
-        driver.switch_to.default_content
-      rescue StandardError
-        nil
-      end
-      return nil
-    end
+    return default if n.nil?
+    return 0 if n < 0
 
-    return nil if iframe_snapshot.nil?
+    [n, HARD_MAX_FRAME_DEPTH].min
+  end
 
-    percy_element_id = frame_element.attribute('data-percy-element-id')
-    unless percy_element_id
-      log("Skipping frame #{frame_url}: no matching percyElementId found", 'debug')
-      return nil
-    end
+  # Accept selector input as String, Array, or nil and produce a flat array of
+  # non-empty strings. Lets the user pass either a single selector or many.
+  def self.normalize_ignore_selectors(input)
+    return [] if input.nil?
 
-    {
-      'iframeData' => {'percyElementId' => percy_element_id},
-      'iframeSnapshot' => iframe_snapshot,
-      'frameUrl' => frame_url,
-    }
+    arr = input.is_a?(Array) ? input : [input]
+    arr.flat_map { |s| s.is_a?(Array) ? s : [s] }
+      .reject { |s| s.nil? || s.to_s.strip.empty? }
+      .map(&:to_s)
+  end
+
+  def self.resolve_max_frame_depth(options, config = nil)
+    val = options[:maxIframeDepth] || options[:max_iframe_depth] ||
+      config&.dig('snapshot', 'maxIframeDepth')
+    clamp_frame_depth(val)
+  end
+
+  def self.resolve_ignore_selectors(options, config = nil)
+    val = options[:ignoreIframeSelectors] || options[:ignore_iframe_selectors] ||
+      config&.dig('snapshot', 'ignoreIframeSelectors') || []
+    normalize_ignore_selectors(val)
+  end
+
+  # Browser-side script that enumerates all <iframe> elements and returns a
+  # plain-data array describing each, including data-percy-ignore attribute
+  # state and which configured ignoreIframeSelectors it matches. We do all
+  # filtering off this snapshot rather than re-querying the DOM repeatedly.
+  def self.enumerate_iframes_script(selectors)
+    selectors_json = (selectors || []).to_json
+    <<~JS
+      (function() {
+        var selectors = #{selectors_json};
+        var iframes = document.querySelectorAll('iframe');
+        var result = [];
+        for (var i = 0; i < iframes.length; i++) {
+          var frame = iframes[i];
+          var matchesIgnore = false;
+          if (selectors && selectors.length) {
+            for (var j = 0; j < selectors.length; j++) {
+              try { if (frame.matches(selectors[j])) { matchesIgnore = true; break; } } catch (e) {}
+            }
+          }
+          result.push({
+            src: frame.src || '',
+            srcdoc: frame.getAttribute('srcdoc'),
+            percyElementId: frame.getAttribute('data-percy-element-id'),
+            dataPercyIgnore: frame.hasAttribute('data-percy-ignore'),
+            matchesIgnoreSelector: matchesIgnore,
+            index: i
+          });
+        }
+        return result;
+      })();
+    JS
   end
 
   def self.get_responsive_widths(widths = [])
@@ -384,6 +744,9 @@ def self.capture_responsive_dom(driver, options, percy_dom_script: nil)
           end
           percy_dom_script = fetch_percy_dom
           driver.execute_script(percy_dom_script)
+          # Re-prime the closed-shadow-root WeakMap -- page.refresh creates a
+          # new document and erases window.__percyClosedShadowRoots.
+          expose_closed_shadow_roots(driver)
           driver.execute_script('PercyDOM.waitForResize()')
           resize_count = 0
         end
diff --git a/spec/lib/percy/percy_spec.rb b/spec/lib/percy/percy_spec.rb
index eed4a05..a32c904 100644
--- a/spec/lib/percy/percy_spec.rb
+++ b/spec/lib/percy/percy_spec.rb
@@ -497,6 +497,30 @@
       expect(Percy.unsupported_iframe_src?('vbscript:MsgBox()')).to be true
     end
 
+    it 'returns true for file: src' do
+      expect(Percy.unsupported_iframe_src?('file:///etc/passwd')).to be true
+    end
+
+    it 'returns true for view-source: src' do
+      expect(Percy.unsupported_iframe_src?('view-source:https://example.com')).to be true
+    end
+
+    it 'returns true for any about: prefix (e.g. about:newtab)' do
+      expect(Percy.unsupported_iframe_src?('about:newtab')).to be true
+    end
+
+    it 'returns true for devtools:, edge:, and opera: schemes' do
+      expect(Percy.unsupported_iframe_src?('devtools://devtools/bundled')).to be true
+      expect(Percy.unsupported_iframe_src?('edge://settings')).to be true
+      expect(Percy.unsupported_iframe_src?('opera://about')).to be true
+    end
+
+    it 'matches case-insensitively (mixed-case schemes still caught)' do
+      expect(Percy.unsupported_iframe_src?('JavaScript:alert(1)')).to be true
+      expect(Percy.unsupported_iframe_src?('ABOUT:BLANK')).to be true
+      expect(Percy.unsupported_iframe_src?('FILE:///etc/passwd')).to be true
+    end
+
     it 'returns false for a valid https url' do
       expect(Percy.unsupported_iframe_src?('https://example.com/page')).to be false
     end
@@ -504,6 +528,62 @@
     it 'returns false for a relative url' do
       expect(Percy.unsupported_iframe_src?('/embed.html')).to be false
     end
+
+    it 'returns false for a src whose first segment is the literal "blank"' do
+      # Regression: only the documented scheme prefixes (ending in ':') should
+      # match. A plain https host like blanket.com or a "blank-canvas" scheme
+      # must not be filtered just because they start with the letters "blank".
+      # The about:blank / about:newtab cases stay covered by the about: prefix.
+      expect(Percy.unsupported_iframe_src?('https://blanket.com/page')).to be false
+      expect(Percy.unsupported_iframe_src?('blank-canvas://x')).to be false
+    end
+  end
+
+  describe '.find_iframe_by_percy_id' do
+    let(:driver) { instance_double('Selenium::WebDriver::Driver') }
+
+    it 'returns nil when percyElementId is nil or empty' do
+      expect(Percy.find_iframe_by_percy_id(driver, nil)).to be_nil
+      expect(Percy.find_iframe_by_percy_id(driver, '')).to be_nil
+    end
+
+    it 'queries the driver via the data-percy-element-id attribute selector' do
+      element = instance_double('Selenium::WebDriver::Element')
+      expect(driver).to receive(:find_element)
+        .with(css: 'iframe[data-percy-element-id="abc-123"]')
+        .and_return(element)
+      expect(Percy.find_iframe_by_percy_id(driver, 'abc-123')).to eq(element)
+    end
+
+    it 'returns nil when the lookup raises (no matching element)' do
+      allow(driver).to receive(:find_element)
+        .and_raise(Selenium::WebDriver::Error::NoSuchElementError.new('no match'))
+      expect(Percy.find_iframe_by_percy_id(driver, 'missing-id')).to be_nil
+    end
+
+    it 'CSS-escapes embedded double-quotes and backslashes in percyElementId' do
+      # Defensive hardening: if a percyElementId ever leaks an unescaped quote
+      # or backslash, the selector should be escaped rather than broken (or
+      # injectable). If the underlying driver still can't resolve it, the
+      # rescue path returns nil cleanly without raising.
+      element = instance_double('Selenium::WebDriver::Element')
+      expect(driver).to receive(:find_element)
+        .with(css: 'iframe[data-percy-element-id="abc\\\\def\\"ghi"]')
+        .and_return(element)
+
+      expect {
+        result = Percy.find_iframe_by_percy_id(driver, 'abc\\def"ghi')
+        expect(result).to eq(element)
+      }.to_not raise_error
+    end
+
+    it 'returns nil cleanly when an escaped lookup still fails' do
+      allow(driver).to receive(:find_element)
+        .and_raise(Selenium::WebDriver::Error::NoSuchElementError.new('no match'))
+      expect {
+        expect(Percy.find_iframe_by_percy_id(driver, 'weird"id\\value')).to be_nil
+      }.to_not raise_error
+    end
   end
 
   describe '.get_origin' do
@@ -540,133 +620,622 @@
     end
   end
 
-  describe '.process_frame' do
+  describe '.expose_closed_shadow_roots' do
+    let(:driver) { double('driver') }
+
+    before(:each) do
+      allow(Percy).to receive(:log)
+    end
+
+    it 'no-ops when driver does not respond to execute_cdp' do
+      allow(driver).to receive(:respond_to?).with(:execute_cdp).and_return(false)
+      expect(driver).to_not receive(:execute_cdp)
+      Percy.expose_closed_shadow_roots(driver)
+    end
+
+    it 'returns silently when DOM.getDocument fails' do
+      allow(driver).to receive(:respond_to?).with(:execute_cdp).and_return(true)
+      allow(driver).to receive(:execute_cdp).with('DOM.getDocument', anything)
+        .and_raise(StandardError, 'CDP not available')
+      expect { Percy.expose_closed_shadow_roots(driver) }.to_not raise_error
+    end
+
+    it 'is a no-op when no closed shadow roots are present' do
+      allow(driver).to receive(:respond_to?).with(:execute_cdp).and_return(true)
+      allow(driver).to receive(:execute_cdp).with('DOM.getDocument', anything)
+        .and_return({'root' => {'children' => []}})
+      expect(driver).to_not receive(:execute_script)
+      Percy.expose_closed_shadow_roots(driver)
+    end
+
+    it 'walks the tree, resolves both nodes, and registers via Runtime.callFunctionOn' do
+      tree = {
+        'root' => {
+          'backendNodeId' => 1,
+          'children' => [{
+            'backendNodeId' => 2,
+            'shadowRoots' => [{
+              'backendNodeId' => 3,
+              'shadowRootType' => 'closed',
+            }],
+          }],
+        },
+      }
+      allow(driver).to receive(:respond_to?).with(:execute_cdp).and_return(true)
+      allow(driver).to receive(:execute_cdp).with('DOM.getDocument', anything).and_return(tree)
+      allow(driver).to receive(:execute_cdp).with('DOM.resolveNode', backendNodeId: 2)
+        .and_return({'object' => {'objectId' => 'host-obj'}})
+      allow(driver).to receive(:execute_cdp).with('DOM.resolveNode', backendNodeId: 3)
+        .and_return({'object' => {'objectId' => 'shadow-obj'}})
+      expect(driver).to receive(:execute_script)
+        .with(/__percyClosedShadowRoots/)
+      expect(driver).to receive(:execute_cdp).with(
+        'Runtime.callFunctionOn',
+        hash_including(objectId: 'host-obj'),
+      )
+      Percy.expose_closed_shadow_roots(driver)
+    end
+
+    it 'skips contentDocument subtrees (cross-frame closed roots not supported)' do
+      tree = {
+        'root' => {
+          'children' => [{
+            'backendNodeId' => 10,
+            'contentDocument' => {
+              'shadowRoots' => [{
+                'backendNodeId' => 11,
+                'shadowRootType' => 'closed',
+              }],
+            },
+          }],
+        },
+      }
+      allow(driver).to receive(:respond_to?).with(:execute_cdp).and_return(true)
+      allow(driver).to receive(:execute_cdp).with('DOM.getDocument', anything).and_return(tree)
+      expect(driver).to_not receive(:execute_script)
+      Percy.expose_closed_shadow_roots(driver)
+    end
+  end
+
+  describe '.process_frame_tree' do
     let(:driver)        { double('driver') }
     let(:frame_element) { double('frame_element') }
     let(:switch_to)     { double('switch_to') }
+    let(:ctx) do
+      {
+        max_frame_depth: Percy::DEFAULT_MAX_FRAME_DEPTH,
+        ignore_selectors: [],
+        serialize_options: {},
+        percy_dom_script: 'percy_dom_script',
+      }
+    end
 
     before(:each) do
       allow(driver).to receive(:switch_to).and_return(switch_to)
       allow(switch_to).to receive(:frame)
       allow(switch_to).to receive(:parent_frame)
       allow(switch_to).to receive(:default_content)
+      allow(Percy).to receive(:log)
     end
 
-    it 'returns a hash with iframeData, iframeSnapshot, and frameUrl on success' do
-      allow(frame_element).to receive(:attribute).with('src')
-        .and_return('https://other.example.com/page')
-      allow(frame_element).to receive(:attribute).with('data-percy-element-id')
-        .and_return('elem-123')
-      allow(driver).to receive(:execute_script).and_return(nil, {'html' => '<html/>'})
-
-      result = Percy.process_frame(driver, frame_element, {}, 'percy_dom_script')
-
-      expect(result).to_not be_nil
-      expect(result['iframeData']['percyElementId']).to eq('elem-123')
-      expect(result['iframeSnapshot']).to eq({'html' => '<html/>'})
-      expect(result['frameUrl']).to eq('https://other.example.com/page')
+    def meta_for(src:, percy_id: 'elem-123', ignore: false, matches_ignore: false, srcdoc: nil)
+      {
+        'src' => src,
+        'srcdoc' => srcdoc,
+        'percyElementId' => percy_id,
+        'dataPercyIgnore' => ignore,
+        'matchesIgnoreSelector' => matches_ignore,
+        'index' => 0,
+      }
     end
 
-    it 'returns nil when data-percy-element-id attribute is missing' do
-      allow(frame_element).to receive(:attribute).with('src').and_return('https://other.example.com/page')
-      allow(frame_element).to receive(:attribute).with('data-percy-element-id').and_return(nil)
-      allow(driver).to receive(:execute_script).and_return(nil, {'html' => '<html/>'})
+    it 'returns a hash with iframeData, iframeSnapshot, and frameUrl on success' do
+      meta = meta_for(src: 'https://other.example.com/page', percy_id: 'elem-123')
+      allow(driver).to receive(:execute_script) do |script|
+        if script.include?('document.URL')
+          'https://other.example.com/page'
+        elsif script.include?('PercyDOM.serialize')
+          {'html' => '<html/>'}
+        elsif script.include?('querySelectorAll')
+          []
+        end
+      end
+      allow(driver).to receive(:find_elements).with(css: 'iframe').and_return([])
 
-      result = Percy.process_frame(driver, frame_element, {}, 'percy_dom_script')
-      expect(result).to be_nil
+      result = Percy.process_frame_tree(driver, frame_element, meta, 1, Set.new, ctx)
+
+      expect(result.length).to eq(1)
+      expect(result[0]['iframeData']['percyElementId']).to eq('elem-123')
+      expect(result[0]['iframeSnapshot']).to eq({'html' => '<html/>'})
+      expect(result[0]['frameUrl']).to eq('https://other.example.com/page')
     end
 
-    it 'returns nil when execute_script raises inside the iframe' do
-      allow(frame_element).to receive(:attribute).with('src').and_return('https://other.example.com/page')
+    it 'returns empty array when execute_script raises inside the iframe' do
+      meta = meta_for(src: 'https://other.example.com/page')
       allow(driver).to receive(:execute_script).and_raise(StandardError, 'injection error')
 
-      result = Percy.process_frame(driver, frame_element, {}, 'percy_dom_script')
-      expect(result).to be_nil
+      result = Percy.process_frame_tree(driver, frame_element, meta, 1, Set.new, ctx)
+      expect(result).to eq([])
     end
 
-    it 'returns nil when switching to the frame fails' do
-      allow(frame_element).to receive(:attribute).with('src').and_return('https://other.example.com/page')
+    it 'returns empty array when switching to the frame fails' do
+      meta = meta_for(src: 'https://other.example.com/page')
       allow(switch_to).to receive(:frame).and_raise(StandardError, 'no such frame')
 
-      result = Percy.process_frame(driver, frame_element, {}, 'percy_dom_script')
-      expect(result).to be_nil
-    end
-
-    it 'uses unknown-src fallback when frame has no src attribute' do
-      allow(frame_element).to receive(:attribute).with('src').and_return(nil)
-      allow(frame_element).to receive(:attribute).with('data-percy-element-id')
-        .and_return('elem-nosrc')
-      allow(driver).to receive(:execute_script).and_return(nil, {'html' => '<html/>'})
-
-      result = Percy.process_frame(driver, frame_element, {}, 'percy_dom_script')
-      expect(result['frameUrl']).to eq('unknown-src')
+      result = Percy.process_frame_tree(driver, frame_element, meta, 1, Set.new, ctx)
+      expect(result).to eq([])
     end
 
     it 'merges enableJavaScript into the PercyDOM.serialize call' do
-      allow(frame_element).to receive(:attribute).with('src')
-        .and_return('https://other.example.com/page')
-      allow(frame_element).to receive(:attribute).with('data-percy-element-id')
-        .and_return('elem-abc')
-
+      meta = meta_for(src: 'https://other.example.com/page', percy_id: 'elem-abc')
       captured_serialize_call = nil
-      call_count = 0
       allow(driver).to receive(:execute_script) do |script|
-        call_count += 1
-        if call_count == 2
+        if script.include?('document.URL')
+          'https://other.example.com/page'
+        elsif script.include?('PercyDOM.serialize')
           captured_serialize_call = script
           {'html' => '<html/>'}
+        elsif script.include?('querySelectorAll')
+          []
         end
       end
+      allow(driver).to receive(:find_elements).with(css: 'iframe').and_return([])
 
-      Percy.process_frame(driver, frame_element, {someOpt: 1}, 'percy_dom_script')
+      custom_ctx = ctx.merge(serialize_options: {someOpt: 1})
+      Percy.process_frame_tree(driver, frame_element, meta, 1, Set.new, custom_ctx)
 
       expect(captured_serialize_call).to include('enableJavaScript')
       expect(captured_serialize_call).to include('true')
     end
 
-    it 'always switches back to default content even when script injection fails' do
-      allow(frame_element).to receive(:attribute).with('src')
-        .and_return('https://other.example.com/page')
-      expect(switch_to).to receive(:default_content).once
+    it 'always returns to the parent frame even when script injection fails' do
+      meta = meta_for(src: 'https://other.example.com/page')
+      expect(switch_to).to receive(:parent_frame).once
       allow(driver).to receive(:execute_script).and_raise(StandardError, 'error')
 
-      Percy.process_frame(driver, frame_element, {}, 'percy_dom_script')
+      Percy.process_frame_tree(driver, frame_element, meta, 1, Set.new, ctx)
     end
 
-    it 'falls back to parent_frame when default_content fails in the inner ensure' do
-      allow(frame_element).to receive(:attribute).with('src')
-        .and_return('https://other.example.com/page')
-      allow(frame_element).to receive(:attribute).with('data-percy-element-id')
-        .and_return('elem-pf')
-      allow(driver).to receive(:execute_script).and_return(nil, {'html' => '<html/>'})
-      allow(switch_to).to receive(:default_content).and_raise(StandardError, 'dc boom')
-      expect(switch_to).to receive(:parent_frame).once
+    it 'stops descending once max_frame_depth is exceeded' do
+      meta = meta_for(src: 'https://other.example.com/page')
+      shallow_ctx = ctx.merge(max_frame_depth: 1)
 
-      result = Percy.process_frame(driver, frame_element, {}, 'percy_dom_script')
-      expect(result['frameUrl']).to eq('https://other.example.com/page')
+      result = Percy.process_frame_tree(driver, frame_element, meta, 2, Set.new, shallow_ctx)
+      expect(result).to eq([])
     end
 
-    it 'swallows a parent_frame failure during inner-ensure recovery' do
-      allow(frame_element).to receive(:attribute).with('src')
-        .and_return('https://other.example.com/page')
-      allow(frame_element).to receive(:attribute).with('data-percy-element-id')
-        .and_return('elem-pf2')
-      allow(driver).to receive(:execute_script).and_return(nil, {'html' => '<html/>'})
-      allow(switch_to).to receive(:default_content).and_raise(StandardError, 'dc boom')
-      allow(switch_to).to receive(:parent_frame).and_raise(StandardError, 'pf boom')
+    it 'skips cyclic iframes that appear in the ancestor chain' do
+      meta = meta_for(src: 'https://other.example.com/page')
+      ancestors = Set.new(['https://other.example.com/page'])
 
-      expect { Percy.process_frame(driver, frame_element, {}, 'percy_dom_script') }
-        .to_not raise_error
+      result = Percy.process_frame_tree(driver, frame_element, meta, 1, ancestors, ctx)
+      expect(result).to eq([])
     end
 
-    it 'swallows a default_content failure in the outer rescue when frame switch fails' do
-      allow(frame_element).to receive(:attribute).with('src')
-        .and_return('https://other.example.com/page')
-      allow(switch_to).to receive(:frame).and_raise(StandardError, 'no such frame')
-      allow(switch_to).to receive(:default_content).and_raise(StandardError, 'dc boom')
+    it 'skips frames whose document.URL post-switch is about:blank' do
+      meta = meta_for(src: 'https://other.example.com/error-page', percy_id: 'elem-err')
+      # The unsupported-URL check fires right after document.URL is read, so the
+      # frame is dropped before PercyDOM.serialize / child enumeration run.
+      allow(driver).to receive(:execute_script) do |script|
+        'about:blank' if script.include?('document.URL') # cross-origin nav failed
+      end
+      allow(driver).to receive(:find_elements).with(css: 'iframe').and_return([])
+
+      result = Percy.process_frame_tree(driver, frame_element, meta, 1, Set.new, ctx)
+      expect(result).to eq([])
+    end
+
+    it 'resolves nested child iframes by percyElementId (not by index)' do
+      # Regression: the child-level lookup must use find_element with the
+      # data-percy-element-id selector, matching the same stable-id contract
+      # used at the top level. A positional alignment against
+      # find_elements(:tag_name, 'iframe') would silently mis-pair meta to
+      # element if the DOM mutated between enumerate_iframes and find_elements.
+      meta = meta_for(src: 'https://other.example.com/parent', percy_id: 'parent-id')
+      child_meta = {
+        'src' => 'https://third.example.com/child',
+        'srcdoc' => nil,
+        'percyElementId' => 'child-pid',
+        'dataPercyIgnore' => false,
+        'matchesIgnoreSelector' => false,
+        'index' => 0,
+      }
 
-      result = Percy.process_frame(driver, frame_element, {}, 'percy_dom_script')
-      expect(result).to be_nil
+      allow(driver).to receive(:execute_script) do |script|
+        if script.include?('document.URL')
+          'https://other.example.com/parent'
+        elsif script.include?('PercyDOM.serialize')
+          {'html' => '<parent/>'}
+        elsif script.include?('querySelectorAll') || script.include?('iframe')
+          [child_meta]
+        end
+      end
+
+      child_element = double('child_element')
+      expect(driver).to_not receive(:find_elements)
+      expect(driver).to receive(:find_element)
+        .with(css: 'iframe[data-percy-element-id="child-pid"]')
+        .and_return(child_element)
+
+      # Short-circuit the recursive descent into the child so we only verify
+      # the child-level lookup path.
+      original = Percy.method(:process_frame_tree)
+      allow(Percy).to receive(:process_frame_tree).and_wrap_original do |_m, *args|
+        if args[1] == child_element
+          []
+        else
+          original.call(*args)
+        end
+      end
+
+      Percy.process_frame_tree(driver, frame_element, meta, 1, Set.new, ctx)
+    end
+
+    it 'raises PercyContextLost when parent_frame fails inside a nested frame' do
+      meta = meta_for(src: 'https://other.example.com/page', percy_id: 'elem-deep')
+      allow(driver).to receive(:execute_script) do |script|
+        if script.include?('document.URL')
+          'https://other.example.com/page'
+        elsif script.include?('PercyDOM.serialize')
+          {'html' => '<deep/>'}
+        elsif script.include?('querySelectorAll')
+          []
+        end
+      end
+      allow(driver).to receive(:find_elements).with(css: 'iframe').and_return([])
+      allow(switch_to).to receive(:parent_frame).and_raise(StandardError, 'lost context')
+
+      expect {
+        Percy.process_frame_tree(driver, frame_element, meta, 2, Set.new, ctx)
+      }.to raise_error(Percy::PercyContextLost) { |err|
+        expect(err.partial_capture.length).to eq(1)
+      }
+    end
+
+    it 'raises PercyContextLost when parent_frame fails even at depth 1' do
+      # Regression (aligns with canonical Nightwatch/Protractor): at depth=1 the
+      # outer capture_cors_iframes loop is still iterating sibling iframe
+      # references resolved against the now-stale parent. Silently continuing
+      # would risk attaching a later iframe's content under an earlier iframe's
+      # percyElementId, so we must abort the sibling walk rather than swallow.
+      meta = meta_for(src: 'https://other.example.com/page', percy_id: 'elem-top')
+      allow(driver).to receive(:execute_script) do |script|
+        if script.include?('document.URL')
+          'https://other.example.com/page'
+        elsif script.include?('PercyDOM.serialize')
+          {'html' => '<top/>'}
+        elsif script.include?('querySelectorAll')
+          []
+        end
+      end
+      allow(driver).to receive(:find_elements).with(css: 'iframe').and_return([])
+      allow(switch_to).to receive(:parent_frame).and_raise(StandardError, 'lost context')
+
+      expect {
+        Percy.process_frame_tree(driver, frame_element, meta, 1, Set.new, ctx)
+      }.to raise_error(Percy::PercyContextLost) { |err|
+        expect(err.partial_capture.length).to eq(1)
+      }
+    end
+  end
+
+  describe '.process_frame_tree (error-recovery branches)' do
+    let(:driver)        { double('driver') }
+    let(:frame_element) { double('frame_element') }
+    let(:switch_to)     { double('switch_to') }
+    let(:ctx) do
+      {
+        max_frame_depth: Percy::DEFAULT_MAX_FRAME_DEPTH,
+        ignore_selectors: [],
+        serialize_options: {},
+        percy_dom_script: 'percy_dom_script',
+      }
+    end
+
+    before(:each) do
+      allow(driver).to receive(:switch_to).and_return(switch_to)
+      allow(switch_to).to receive(:frame)
+      allow(switch_to).to receive(:parent_frame)
+      allow(switch_to).to receive(:default_content)
+      allow(Percy).to receive(:log)
+    end
+
+    def meta_for(src:, percy_id: 'elem-123')
+      {
+        'src' => src,
+        'srcdoc' => nil,
+        'percyElementId' => percy_id,
+        'dataPercyIgnore' => false,
+        'matchesIgnoreSelector' => false,
+        'index' => 0,
+      }
+    end
+
+    it 'falls back to meta src when reading document.URL post-switch raises' do
+      meta = meta_for(src: 'https://other.example.com/page', percy_id: 'elem-url')
+      allow(driver).to receive(:execute_script) do |script|
+        raise StandardError, 'document.URL unavailable' if script.include?('document.URL')
+
+        if script.include?('PercyDOM.serialize')
+          {'html' => '<frame/>'}
+        elsif script.include?('querySelectorAll')
+          []
+        end
+      end
+      allow(driver).to receive(:find_elements).with(css: 'iframe').and_return([])
+
+      result = Percy.process_frame_tree(driver, frame_element, meta, 1, Set.new, ctx)
+
+      expect(result.length).to eq(1)
+      # frame_url fell back to meta['src'] since document.URL read failed
+      expect(result[0]['frameUrl']).to eq('https://other.example.com/page')
+    end
+
+    it 'returns the partial collection when serialize returns nil' do
+      meta = meta_for(src: 'https://other.example.com/page', percy_id: 'elem-nil')
+      # serialize returns nil -> method returns early, so the child
+      # enumeration (querySelectorAll) is never reached.
+      allow(driver).to receive(:execute_script) do |script|
+        script.include?('document.URL') ? 'https://other.example.com/page' : nil
+      end
+
+      result = Percy.process_frame_tree(driver, frame_element, meta, 1, Set.new, ctx)
+      expect(result).to eq([])
+    end
+
+    it 'still recurses into children when the frame origin cannot be parsed' do
+      # frame_url contains a space so get_origin raises URI::InvalidURIError;
+      # current_origin falls back to nil, but the descent still proceeds.
+      meta = meta_for(src: 'https://other.example.com/page', percy_id: 'elem-badorigin')
+      allow(driver).to receive(:execute_script) do |script|
+        if script.include?('document.URL')
+          'http://exa mple.com/frame' # unparseable -> get_origin raises -> nil
+        elsif script.include?('PercyDOM.serialize')
+          {'html' => '<frame/>'}
+        elsif script.include?('querySelectorAll')
+          [] # no children
+        end
+      end
+      allow(driver).to receive(:find_elements).with(css: 'iframe').and_return([])
+
+      result = Percy.process_frame_tree(driver, frame_element, meta, 1, Set.new, ctx)
+      expect(result.length).to eq(1)
+    end
+
+    it 'merges an inner PercyContextLost partial capture and re-raises with the union' do
+      # A nested process_frame_tree raises PercyContextLost carrying its own
+      # partial capture. The outer level must concat that into whatever it had
+      # collected, stamp the merged set onto the error, and re-raise.
+      meta = meta_for(src: 'https://other.example.com/parent', percy_id: 'parent-id')
+      child_meta = meta_for(src: 'https://third.example.com/child', percy_id: 'child-id')
+
+      allow(driver).to receive(:execute_script) do |script|
+        if script.include?('document.URL')
+          'https://other.example.com/parent'
+        elsif script.include?('PercyDOM.serialize')
+          {'html' => '<parent/>'}
+        elsif script.include?('querySelectorAll')
+          [child_meta]
+        end
+      end
+      child_element = double('child_element')
+      allow(driver).to receive(:find_element)
+        .with(css: 'iframe[data-percy-element-id="child-id"]')
+        .and_return(child_element)
+
+      inner_partial = [{
+        'iframeData' => {'percyElementId' => 'inner-pid'},
+        'iframeSnapshot' => {'html' => '<inner/>'},
+        'frameUrl' => 'https://third.example.com/child',
+      }]
+      inner_err = Percy::PercyContextLost.new('inner loss')
+      inner_err.partial_capture = inner_partial
+
+      original = Percy.method(:process_frame_tree)
+      allow(Percy).to receive(:process_frame_tree).and_wrap_original do |_m, *args|
+        raise inner_err if args[1] == child_element
+
+        original.call(*args)
+      end
+
+      expect {
+        Percy.process_frame_tree(driver, frame_element, meta, 1, Set.new, ctx)
+      }.to raise_error(Percy::PercyContextLost) { |err|
+        # Union: the parent's own captured frame + the inner partial.
+        expect(err.partial_capture.length).to eq(2)
+        expect(err.partial_capture.map { |c| c['iframeData']['percyElementId'] })
+          .to contain_exactly('parent-id', 'inner-pid')
+      }
+    end
+
+    it 'still raises PercyContextLost when the default_content recovery also fails' do
+      # parent_frame fails, so we attempt default_content as a recovery -- but
+      # that ALSO raises. The inner failure is swallowed and PercyContextLost is
+      # raised regardless, carrying whatever was collected.
+      meta = meta_for(src: 'https://other.example.com/page', percy_id: 'elem-fallback')
+      allow(driver).to receive(:execute_script) do |script|
+        if script.include?('document.URL')
+          'https://other.example.com/page'
+        elsif script.include?('PercyDOM.serialize')
+          {'html' => '<frame/>'}
+        elsif script.include?('querySelectorAll')
+          []
+        end
+      end
+      allow(driver).to receive(:find_elements).with(css: 'iframe').and_return([])
+      allow(switch_to).to receive(:parent_frame).and_raise(StandardError, 'lost parent')
+      # The recovery attempt itself blows up -- must be swallowed.
+      allow(switch_to).to receive(:default_content)
+        .and_raise(StandardError, 'cannot reach default content')
+
+      expect {
+        Percy.process_frame_tree(driver, frame_element, meta, 2, Set.new, ctx)
+      }.to raise_error(Percy::PercyContextLost) { |err|
+        expect(err.partial_capture.length).to eq(1)
+      }
+    end
+  end
+
+  describe '.enumerate_iframes' do
+    let(:driver) { double('driver') }
+
+    before(:each) { allow(Percy).to receive(:log) }
+
+    it 'returns the array produced by the in-browser enumeration script' do
+      metas = [{'src' => 'https://a.example.com/', 'percyElementId' => 'p1'}]
+      allow(driver).to receive(:execute_script).and_return(metas)
+      expect(Percy.enumerate_iframes(driver, [])).to eq(metas)
+    end
+
+    it 'returns [] when the script returns a non-array' do
+      allow(driver).to receive(:execute_script).and_return(nil)
+      expect(Percy.enumerate_iframes(driver, [])).to eq([])
+    end
+
+    it 'swallows execute_script failures, logs at debug, and returns []' do
+      allow(driver).to receive(:execute_script)
+        .and_raise(StandardError, 'enumeration boom')
+      expect(Percy).to receive(:log)
+        .with(/Failed to enumerate iframes: enumeration boom/, 'debug')
+      expect(Percy.enumerate_iframes(driver, [])).to eq([])
+    end
+  end
+
+  describe '.should_skip_iframe? (unparseable src)' do
+    before(:each) { allow(Percy).to receive(:log) }
+
+    it 'skips the iframe when get_origin(src) raises (treated as origin nil)' do
+      # A src that passes the unsupported-scheme filter but cannot be parsed
+      # by URI -> get_origin raises -> frame_origin is nil -> skip.
+      meta = {
+        'src' => 'http://exa mple.com/page',
+        'srcdoc' => nil,
+        'percyElementId' => 'elem-bad',
+        'dataPercyIgnore' => false,
+        'matchesIgnoreSelector' => false,
+      }
+      expect(Percy.should_skip_iframe?(meta, 'http://main.example.com')).to be(true)
+    end
+  end
+
+  describe '.capture_cors_iframes (outer error recovery)' do
+    let(:driver)    { double('driver') }
+    let(:switch_to) { double('switch_to') }
+    let(:ctx) do
+      {
+        max_frame_depth: Percy::DEFAULT_MAX_FRAME_DEPTH,
+        ignore_selectors: [],
+        serialize_options: {},
+        percy_dom_script: 'percy_dom_script',
+      }
+    end
+
+    before(:each) do
+      allow(driver).to receive(:switch_to).and_return(switch_to)
+      allow(switch_to).to receive(:default_content)
+      allow(Percy).to receive(:log)
+    end
+
+    it 'swallows an unexpected failure, restores default_content, and returns []' do
+      # current_url raises -> outer rescue -> default_content restore -> [].
+      allow(driver).to receive(:current_url).and_raise(StandardError, 'driver gone')
+      expect(switch_to).to receive(:default_content)
+      expect(Percy).to receive(:log)
+        .with(/Failed to process cross-origin iframes: driver gone/, 'debug')
+
+      expect(Percy.capture_cors_iframes(driver, ctx)).to eq([])
+    end
+
+    it 'still returns [] when the default_content restore itself raises' do
+      allow(driver).to receive(:current_url).and_raise(StandardError, 'driver gone')
+      allow(switch_to).to receive(:default_content)
+        .and_raise(StandardError, 'cannot restore')
+
+      expect(Percy.capture_cors_iframes(driver, ctx)).to eq([])
+    end
+  end
+
+  describe '.clamp_frame_depth' do
+    it 'returns the default for nil input' do
+      expect(Percy.clamp_frame_depth(nil)).to eq(Percy::DEFAULT_MAX_FRAME_DEPTH)
+    end
+
+    it 'returns the default for non-numeric garbage' do
+      expect(Percy.clamp_frame_depth('not-a-number')).to eq(Percy::DEFAULT_MAX_FRAME_DEPTH)
+    end
+
+    it 'honours a custom default for unparseable input' do
+      expect(Percy.clamp_frame_depth({}, default: 4)).to eq(4)
+    end
+
+    it 'floors negative depths to zero' do
+      expect(Percy.clamp_frame_depth(-7)).to eq(0)
+    end
+
+    it 'caps oversized depths at HARD_MAX_FRAME_DEPTH' do
+      expect(Percy.clamp_frame_depth(10_000)).to eq(Percy::HARD_MAX_FRAME_DEPTH)
+    end
+
+    it 'passes through a valid in-range depth' do
+      expect(Percy.clamp_frame_depth(3)).to eq(3)
+    end
+
+    it 'coerces a numeric string within range' do
+      expect(Percy.clamp_frame_depth('5')).to eq(5)
+    end
+  end
+
+  describe '.expose_closed_shadow_roots (CDP registration failure)' do
+    let(:driver) { double('driver') }
+
+    before(:each) { allow(Percy).to receive(:log) }
+
+    it 'swallows a CDP failure during registration and logs at debug' do
+      # A closed shadow root is found, but the Runtime call to register it
+      # raises -- the whole registration block is non-fatal and only logged.
+      tree = {
+        'root' => {
+          'backendNodeId' => 1,
+          'children' => [{
+            'backendNodeId' => 2,
+            'shadowRoots' => [{
+              'backendNodeId' => 3,
+              'shadowRootType' => 'closed',
+            }],
+          }],
+        },
+      }
+      allow(driver).to receive(:respond_to?).with(:execute_cdp).and_return(true)
+      allow(driver).to receive(:execute_cdp).with('DOM.getDocument', anything).and_return(tree)
+      allow(driver).to receive(:execute_script)
+        .and_raise(StandardError, 'WeakMap setup failed')
+
+      expect(Percy).to receive(:log)
+        .with(/Could not expose closed shadow roots via CDP: WeakMap setup failed/, 'debug')
+      expect { Percy.expose_closed_shadow_roots(driver) }.to_not raise_error
+    end
+  end
+
+  describe 'Percy::PercyContextLost' do
+    # Regression: previous code paths could overwrite the original backtrace
+    # by re-raising a new error. The exception's backtrace must point at the
+    # raise site, not nil and not at the rescue site.
+    it 'preserves the original backtrace when raised then rescued' do
+      raised_line = nil
+      err = nil
+      begin
+        raised_line = __LINE__ + 1
+        raise Percy::PercyContextLost, 'simulated context loss'
+      rescue Percy::PercyContextLost => e
+        err = e
+      end
+
+      expect(err).to be_a(Percy::PercyContextLost)
+      expect(err.backtrace).to_not be_nil
+      expect(err.backtrace).to_not be_empty
+      # The top frame of the backtrace should point at the raise line in this file
+      expect(err.backtrace.first).to include(__FILE__)
+      expect(err.backtrace.first).to include(":#{raised_line}:")
     end
   end
 
@@ -675,6 +1244,17 @@
     let(:manage)    { double('manage') }
     let(:switch_to) { double('switch_to') }
 
+    def iframe_meta(src:, percy_id: 'cid-1', ignore: false, matches_ignore: false, srcdoc: nil)
+      {
+        'src' => src,
+        'srcdoc' => srcdoc,
+        'percyElementId' => percy_id,
+        'dataPercyIgnore' => ignore,
+        'matchesIgnoreSelector' => matches_ignore,
+        'index' => 0,
+      }
+    end
+
     before(:each) do
       allow(driver).to receive(:manage).and_return(manage)
       allow(manage).to receive(:all_cookies).and_return([])
@@ -682,15 +1262,23 @@
       allow(switch_to).to receive(:frame)
       allow(switch_to).to receive(:parent_frame)
       allow(switch_to).to receive(:default_content)
-      # Readiness gate runs execute_async_script before serialize; stub it so
-      # these unit tests exercise serialization without a real browser.
+      allow(Percy).to receive(:log)
+      # The PER-7348 readiness gate runs PercyDOM.waitForReady via
+      # execute_async_script before serialize. Tests that aren't specifically
+      # about readiness still hit that path, so provide a harmless default
+      # no-op stub (returns nil = "gate ran, no diagnostics"). Readiness-specific
+      # tests below override this stub with their own expectations.
       allow(driver).to receive(:execute_async_script).and_return(nil)
     end
 
     it 'returns the serialized dom with cookies when no iframes present' do
-      allow(driver).to receive(:execute_script).and_return({'html' => '<html/>'})
+      # Called without percy_dom_script, so capture_cors_iframes (and thus the
+      # iframe enumeration script) never runs -- only the top-level serialize.
+      allow(driver).to receive(:execute_script) do |script|
+        {'html' => '<html/>'} if script.include?('PercyDOM.serialize')
+      end
       allow(driver).to receive(:current_url).and_return('http://main.example.com/')
-      allow(driver).to receive(:find_elements).and_return([])
+      allow(driver).to receive(:find_elements).with(css: 'iframe').and_return([])
 
       dom = Percy.get_serialized_dom(driver, {})
       expect(dom['html']).to eq('<html/>')
@@ -700,20 +1288,23 @@
 
     it 'populates corsIframes for cross-origin frames' do
       frame = double('frame')
-      allow(frame).to receive(:attribute).with('src').and_return('https://cross.example.com/page')
-      allow(frame).to receive(:attribute).with('data-percy-element-id').and_return('cid-1')
-
-      call_count = 0
-      allow(driver).to receive(:execute_script) do
-        call_count += 1
-        case call_count
-        when 1 then {'html' => '<main/>'}
-        when 2 then nil
-        when 3 then {'html' => '<frame/>'}
+
+      script_calls = 0
+      allow(driver).to receive(:execute_script) do |script|
+        script_calls += 1
+        if script_calls == 1
+          {'html' => '<main/>'} # top-level serialize
+        elsif script.include?('querySelectorAll')
+          [iframe_meta(src: 'https://cross.example.com/page', percy_id: 'cid-1')]
+        elsif script.include?('document.URL')
+          'https://cross.example.com/page'
+        elsif script.include?('PercyDOM.serialize')
+          {'html' => '<frame/>'}
         end
       end
       allow(driver).to receive(:current_url).and_return('http://main.example.com/')
-      allow(driver).to receive(:find_elements).and_return([frame])
+      allow(driver).to receive(:find_element)
+        .with(css: 'iframe[data-percy-element-id="cid-1"]').and_return(frame)
 
       dom = Percy.get_serialized_dom(driver, {}, percy_dom_script: 'percy_dom_script')
 
@@ -726,10 +1317,17 @@
 
     it 'skips same-origin iframes' do
       frame = double('frame')
-      allow(frame).to receive(:attribute).with('src').and_return('http://main.example.com/inner.html')
-      allow(driver).to receive(:execute_script).and_return({'html' => '<html/>'})
+      script_calls = 0
+      allow(driver).to receive(:execute_script) do |script|
+        script_calls += 1
+        if script_calls == 1
+          {'html' => '<html/>'}
+        elsif script.include?('querySelectorAll')
+          [iframe_meta(src: 'http://main.example.com/inner.html')]
+        end
+      end
       allow(driver).to receive(:current_url).and_return('http://main.example.com/')
-      allow(driver).to receive(:find_elements).and_return([frame])
+      allow(driver).to receive(:find_elements).with(css: 'iframe').and_return([frame])
 
       dom = Percy.get_serialized_dom(driver, {}, percy_dom_script: 'percy_dom_script')
       expect(dom).to_not have_key('corsIframes')
@@ -737,10 +1335,17 @@
 
     it 'skips iframes with about:blank src' do
       frame = double('frame')
-      allow(frame).to receive(:attribute).with('src').and_return('about:blank')
-      allow(driver).to receive(:execute_script).and_return({'html' => '<html/>'})
+      script_calls = 0
+      allow(driver).to receive(:execute_script) do |script|
+        script_calls += 1
+        if script_calls == 1
+          {'html' => '<html/>'}
+        elsif script.include?('querySelectorAll')
+          [iframe_meta(src: 'about:blank')]
+        end
+      end
       allow(driver).to receive(:current_url).and_return('http://main.example.com/')
-      allow(driver).to receive(:find_elements).and_return([frame])
+      allow(driver).to receive(:find_elements).with(css: 'iframe').and_return([frame])
 
       dom = Percy.get_serialized_dom(driver, {}, percy_dom_script: 'percy_dom_script')
       expect(dom).to_not have_key('corsIframes')
@@ -757,20 +1362,22 @@
 
     it 'treats same host with different scheme as cross-origin' do
       frame = double('frame')
-      allow(frame).to receive(:attribute).with('src').and_return('https://main.example.com/widget')
-      allow(frame).to receive(:attribute).with('data-percy-element-id').and_return('percy-id-1')
-
-      call_count = 0
-      allow(driver).to receive(:execute_script) do
-        call_count += 1
-        if call_count == 1
+      script_calls = 0
+      allow(driver).to receive(:execute_script) do |script|
+        script_calls += 1
+        if script_calls == 1
           {'html' => '<html/>'}
-        else
-          call_count == 2 ? nil : {'html' => '<frame/>'}
+        elsif script.include?('querySelectorAll')
+          [iframe_meta(src: 'https://main.example.com/widget', percy_id: 'percy-id-1')]
+        elsif script.include?('document.URL')
+          'https://main.example.com/widget'
+        elsif script.include?('PercyDOM.serialize')
+          {'html' => '<frame/>'}
         end
       end
       allow(driver).to receive(:current_url).and_return('http://main.example.com/')
-      allow(driver).to receive(:find_elements).and_return([frame])
+      allow(driver).to receive(:find_element)
+        .with(css: 'iframe[data-percy-element-id="percy-id-1"]').and_return(frame)
 
       dom = Percy.get_serialized_dom(driver, {}, percy_dom_script: 'script')
       expect(dom).to have_key('corsIframes')
@@ -778,20 +1385,22 @@
 
     it 'treats same host with different port as cross-origin' do
       frame = double('frame')
-      allow(frame).to receive(:attribute).with('src').and_return('http://main.example.com:4000/widget')
-      allow(frame).to receive(:attribute).with('data-percy-element-id').and_return('percy-id-port')
-
-      call_count = 0
-      allow(driver).to receive(:execute_script) do
-        call_count += 1
-        if call_count == 1
+      script_calls = 0
+      allow(driver).to receive(:execute_script) do |script|
+        script_calls += 1
+        if script_calls == 1
           {'html' => '<html/>'}
-        else
-          call_count == 2 ? nil : {'html' => '<frame/>'}
+        elsif script.include?('querySelectorAll')
+          [iframe_meta(src: 'http://main.example.com:4000/widget', percy_id: 'percy-id-port')]
+        elsif script.include?('document.URL')
+          'http://main.example.com:4000/widget'
+        elsif script.include?('PercyDOM.serialize')
+          {'html' => '<frame/>'}
         end
       end
       allow(driver).to receive(:current_url).and_return('http://main.example.com:3000/')
-      allow(driver).to receive(:find_elements).and_return([frame])
+      allow(driver).to receive(:find_element)
+        .with(css: 'iframe[data-percy-element-id="percy-id-port"]').and_return(frame)
 
       dom = Percy.get_serialized_dom(driver, {}, percy_dom_script: 'script')
       expect(dom).to have_key('corsIframes')
@@ -802,31 +1411,111 @@
       allow(manage).to receive(:all_cookies).and_return(cookies_data)
       allow(driver).to receive(:execute_script).and_return({'html' => '<html/>'})
       allow(driver).to receive(:current_url).and_return('http://main.example.com/')
-      allow(driver).to receive(:find_elements).and_return([])
+      allow(driver).to receive(:find_elements).with(css: 'iframe').and_return([])
 
       dom = Percy.get_serialized_dom(driver, {})
       expect(dom['cookies']).to eq(cookies_data)
     end
 
-    it 'skips same-origin frame and processes only cross-origin frame' do
-      same_frame = double('same_frame')
-      allow(same_frame).to receive(:attribute).with('src').and_return('http://main.example.com/inner')
+    it 'preserves partial capture when PercyContextLost is raised mid-walk' do
+      frame_a = double('frame_a')
+      frame_b = double('frame_b')
+
+      partial = [{
+        'iframeData' => {'percyElementId' => 'partial-id'},
+        'iframeSnapshot' => {'html' => '<partial/>'},
+        'frameUrl' => 'https://partial.example.com/',
+      }]
+      err = Percy::PercyContextLost.new('lost context mid-walk')
+      err.partial_capture = partial
 
+      script_calls = 0
+      allow(driver).to receive(:execute_script) do |script|
+        script_calls += 1
+        if script_calls == 1
+          {'html' => '<html/>'}
+        elsif script.include?('querySelectorAll')
+          [
+            iframe_meta(src: 'https://a.example.com/x', percy_id: 'cid-a'),
+            iframe_meta(src: 'https://b.example.com/y', percy_id: 'cid-b'),
+          ]
+        end
+      end
+      allow(driver).to receive(:current_url).and_return('http://main.example.com/')
+      allow(driver).to receive(:find_element)
+        .with(css: 'iframe[data-percy-element-id="cid-a"]').and_return(frame_a)
+      allow(driver).to receive(:find_element)
+        .with(css: 'iframe[data-percy-element-id="cid-b"]').and_return(frame_b)
+      # First frame raises PercyContextLost with partial capture
+      allow(Percy).to receive(:process_frame_tree).and_raise(err)
+
+      dom = Percy.get_serialized_dom(driver, {}, percy_dom_script: 'script')
+      expect(dom['corsIframes']).to eq(partial)
+    end
+
+    it 'skips iframes matching ignoreIframeSelectors option' do
+      frame = double('frame')
+      captured_selectors = nil
+      script_calls = 0
+      allow(driver).to receive(:execute_script) do |script|
+        script_calls += 1
+        if script_calls == 1
+          {'html' => '<html/>'}
+        elsif script.include?('querySelectorAll')
+          captured_selectors = script
+          [iframe_meta(src: 'https://cross.example.com/x', percy_id: 'cid-z',
+                       matches_ignore: true,)]
+        end
+      end
+      allow(driver).to receive(:current_url).and_return('http://main.example.com/')
+      allow(driver).to receive(:find_elements).with(css: 'iframe').and_return([frame])
+
+      dom = Percy.get_serialized_dom(driver, {ignoreIframeSelectors: '.ad'},
+        percy_dom_script: 'script',)
+      expect(dom).to_not have_key('corsIframes')
+      # The selector list flows through to the in-browser script
+      expect(captured_selectors).to include('".ad"')
+    end
+
+    it 'skips iframes marked with data-percy-ignore' do
+      frame = double('frame')
+      script_calls = 0
+      allow(driver).to receive(:execute_script) do |script|
+        script_calls += 1
+        if script_calls == 1
+          {'html' => '<html/>'}
+        elsif script.include?('querySelectorAll')
+          [iframe_meta(src: 'https://cross.example.com/x', percy_id: 'cid-y', ignore: true)]
+        end
+      end
+      allow(driver).to receive(:current_url).and_return('http://main.example.com/')
+      allow(driver).to receive(:find_elements).with(css: 'iframe').and_return([frame])
+
+      dom = Percy.get_serialized_dom(driver, {}, percy_dom_script: 'script')
+      expect(dom).to_not have_key('corsIframes')
+    end
+
+    it 'skips same-origin frame and processes only cross-origin frame' do
       cross_frame = double('cross_frame')
-      allow(cross_frame).to receive(:attribute).with('src').and_return('https://other.example.com/page')
-      allow(cross_frame).to receive(:attribute).with('data-percy-element-id').and_return('cid-x')
-
-      call_count = 0
-      allow(driver).to receive(:execute_script) do
-        call_count += 1
-        if call_count == 1
-          {'html' => '<main/>'}
-        else
-          call_count == 2 ? nil : {'html' => '<cross/>'}
+
+      top_metas = [
+        iframe_meta(src: 'http://main.example.com/inner', percy_id: 'cid-same'),
+        iframe_meta(src: 'https://other.example.com/page', percy_id: 'cid-x'),
+      ]
+      enum_call = 0
+      allow(driver).to receive(:execute_script) do |script|
+        if script.include?('PercyDOM.serialize')
+          enum_call.zero? ? {'html' => '<main/>'} : {'html' => '<cross/>'}
+        elsif script.include?('querySelectorAll')
+          enum_call += 1
+          enum_call == 1 ? top_metas : [] # no nested children inside the cross frame
+        elsif script.include?('document.URL')
+          'https://other.example.com/page'
         end
       end
       allow(driver).to receive(:current_url).and_return('http://main.example.com/')
-      allow(driver).to receive(:find_elements).and_return([same_frame, cross_frame])
+      allow(driver).to receive(:find_element)
+        .with(css: 'iframe[data-percy-element-id="cid-x"]').and_return(cross_frame)
 
       dom = Percy.get_serialized_dom(driver, {}, percy_dom_script: 'script')
       expect(dom['corsIframes'].length).to eq(1)
@@ -857,7 +1546,7 @@
       allow(driver).to receive(:current_url).and_return('http://main.example.com/')
       allow(driver).to receive(:find_elements).and_return([])
 
-      Percy.get_serialized_dom(driver, readiness: {preset: 'strict', stabilityWindowMs: 500})
+      Percy.get_serialized_dom(driver, {readiness: {preset: 'strict', stabilityWindowMs: 500}})
       expect(driver).to have_received(:execute_async_script) do |script| # rubocop:disable RSpec/MessageSpies
         expect(script).to include('"preset":"strict"')
         expect(script).to include('"stabilityWindowMs":500')
@@ -870,7 +1559,7 @@
       allow(driver).to receive(:find_elements).and_return([])
       expect(driver).to_not receive(:execute_async_script)
 
-      dom = Percy.get_serialized_dom(driver, readiness: {preset: 'disabled'})
+      dom = Percy.get_serialized_dom(driver, {readiness: {preset: 'disabled'}})
       expect(dom).to_not have_key('readiness_diagnostics')
       expect(dom['html']).to eq('<html/>')
     end
@@ -899,7 +1588,7 @@
       expect(timeouts).to receive(:script_timeout=).with(10.0).ordered
       expect(timeouts).to receive(:script_timeout=).with(30).ordered
 
-      Percy.get_serialized_dom(driver, readiness: {timeoutMs: 8000})
+      Percy.get_serialized_dom(driver, {readiness: {timeoutMs: 8000}})
     end
 
     it 'proceeds when reading/setting the script timeout is unsupported' do
@@ -911,7 +1600,7 @@
       allow(driver).to receive(:current_url).and_return('http://main.example.com/')
       allow(driver).to receive(:find_elements).and_return([])
 
-      expect { Percy.get_serialized_dom(driver, readiness: {timeoutMs: 5000}) }.to_not raise_error
+      expect { Percy.get_serialized_dom(driver, {readiness: {timeoutMs: 5000}}) }.to_not raise_error
     end
 
     it 'skips an iframe whose src cannot be resolved against the page url' do
@@ -1103,6 +1792,7 @@
         )
         allow(driver).to receive(:navigate).and_return(navigate)
         allow(navigate).to receive(:refresh)
+        allow(driver).to receive(:respond_to?).with(:execute_cdp).and_return(false)
       end
 
       it 'calls driver.navigate.refresh once per width' do
@@ -1564,6 +2254,45 @@ def stub_web_healthcheck
     Percy._clear_cache!
   end
 
+  describe '.capture_cors_iframes (lookup by percyElementId)' do
+    let(:driver) { instance_double('Selenium::WebDriver::Driver') }
+
+    before(:each) do
+      allow(driver).to receive(:current_url).and_return('https://example.com/')
+      # enumerate_iframes calls driver.execute_script -- return a same-origin
+      # entry followed by a CORS entry so the loop has something to skip and
+      # something to process.
+      allow(driver).to receive(:execute_script).and_return([
+        {'src' => 'https://example.com/same', 'percyElementId' => 'pid-same'},
+        {'src' => 'https://other.com/cors',   'percyElementId' => 'pid-cors'},
+      ])
+    end
+
+    it 'looks up the iframe element by data-percy-element-id, not by index' do
+      # Regression: positional alignment between the JS enumerate_iframes
+      # result and driver.find_elements(:tag_name, 'iframe') could ship one
+      # iframe's content under another's percyElementId if the DOM mutated
+      # between the two reads. The new code resolves by stable id and never
+      # calls find_elements on the iframe collection.
+      cors_element = instance_double('Selenium::WebDriver::Element')
+
+      expect(driver).to_not receive(:find_elements)
+      expect(driver).to receive(:find_element)
+        .with(css: 'iframe[data-percy-element-id="pid-cors"]')
+        .and_return(cors_element)
+
+      # Short-circuit process_frame_tree so we only verify the lookup path.
+      allow(Percy).to receive(:process_frame_tree).and_return([])
+
+      Percy.capture_cors_iframes(driver, {
+                                   max_frame_depth: 5,
+                                   ignore_selectors: [],
+                                   percy_dom_script: '',
+                                   serialize_options: {},
+                                 },)
+    end
+  end
+
   describe '.snapshot (mocked driver)' do
     let(:driver)    { double('driver') }
     let(:manage)    { double('manage') }
@@ -1583,6 +2312,10 @@ def stub_web_snapshot_healthcheck
       allow(driver).to receive(:manage).and_return(manage)
       allow(manage).to receive(:all_cookies).and_return([])
       allow(driver).to receive(:respond_to?).with(:driver).and_return(false)
+      # This branch's snapshot path calls expose_closed_shadow_roots, which
+      # checks driver.respond_to?(:execute_cdp). Stub it to false so the
+      # closed-shadow-DOM CDP path no-ops for this non-Chromium mock driver.
+      allow(driver).to receive(:respond_to?).with(:execute_cdp).and_return(false)
       allow(driver).to receive(:switch_to).and_return(switch_to)
       allow(switch_to).to receive(:default_content)
       allow(driver).to receive(:execute_async_script).and_return(nil)
diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb
index 070742f..183dff8 100644
--- a/spec/spec_helper.rb
+++ b/spec/spec_helper.rb
@@ -9,6 +9,17 @@
 require 'capybara/rspec'
 require 'selenium-webdriver'
 
+# Capybara's :selenium_headless driver registers an at_exit handler that quits
+# the browser session via a real `DELETE http://127.0.0.1:4444/session/...` to
+# the local WebDriver. webmock/rspec blocks all net connections by default, so
+# that teardown raised WebMock::NetConnectNotAllowedError and failed the whole
+# process with exit code 1 even when every example passed (only intermittently,
+# because `config.order = :random` controls whether a session-starting spec runs
+# before exit). Allow localhost so session teardown and the Capybara Puma test
+# server can connect; stubbed requests still take precedence, so external HTTP
+# stays blocked.
+WebMock.disable_net_connect!(allow_localhost: true)
+
 RSpec.configure do |config|
   config.expect_with :rspec do |expectations|
     # This option will default to `true` in RSpec 4.