@percy/dom 1.31.14-beta.2 → 1.31.14-beta.4

package/dist/bundle.js

@@ -6,6 +6,16 @@
     process.env = process.env || {};
     process.env.__PERCY_BROWSERIFIED__ = true;
 
+    // Custom element names are required by spec to contain a hyphen. Returns
+    // false for text/comment nodes (which don't have a tagName). This is the
+    // single source of truth used across prepare-dom, clone-dom, and the
+    // serializers — keep checks consistent by importing this rather than
+    // inlining `tagName?.includes('-')`.
+    function isCustomElement(element) {
+      var _element$tagName;
+      return !!(element !== null && element !== void 0 && (_element$tagName = element.tagName) !== null && _element$tagName !== void 0 && _element$tagName.includes('-'));
+    }
+
     // Creates a resource object from an element's unique ID and data URL
     function resourceFromDataURL(uid, dataURL) {
       // split dataURL into desired parts
@@ -165,20 +175,80 @@
       (_dom$querySelector = dom.querySelector('head')) === null || _dom$querySelector === void 0 || _dom$querySelector.prepend($base);
     }
 
-    // Recursively serializes iframe documents into srcdoc attributes.
+    // Per-spec: nested iframes are captured up to a configurable depth (default 3).
+    // Beyond that we skip recursion to bound runtime and prevent pathological pages
+    // (e.g. cyclic iframe trees) from blowing the call stack.
+    //
+    // MIRROR: these constants + `clampIframeDepth` are duplicated in
+    // @percy/sdk-utils/src/index.js (where external SDKs read them to clamp their
+    // own pre-CLI config to the same bounds). The values must stay aligned —
+    // drift is enforced by a parity test in @percy/sdk-utils/test/index.test.js.
+    // Don't change one without changing the other.
+    const DEFAULT_MAX_IFRAME_DEPTH = 3;
+    // Hard ceiling for any user-supplied maxIframeDepth — values above this are
+    // clamped down. 10 levels is well past any realistic UI nesting and keeps
+    // the recursion cost predictable.
+    const HARD_MAX_IFRAME_DEPTH = 10;
+    function clampIframeDepth(raw) {
+      let n = Number(raw);
+      if (!Number.isFinite(n) || n < 1) return DEFAULT_MAX_IFRAME_DEPTH;
+      return Math.min(Math.floor(n), HARD_MAX_IFRAME_DEPTH);
+    }
+
+    // Recursively serializes iframe documents into srcdoc attributes. `iframeDepth`
+    // is the current nesting level (0 at the top-level document, +1 per recursion).
+    // The default fires for direct callers that don't set it (e.g. tests, or
+    // any future caller that doesn't go through serializeDOM).
     function serializeFrames({
       dom,
       clone,
       warnings,
       resources,
       enableJavaScript,
-      disableShadowDOM
+      disableShadowDOM,
+      ignoreIframeSelectors,
+      forceShadowAsLightDOM,
+      maxIframeDepth,
+      iframeDepth = 0
     }) {
+      maxIframeDepth = clampIframeDepth(maxIframeDepth);
       for (let frame of dom.querySelectorAll('iframe')) {
         var _clone$head;
         let percyElementId = frame.getAttribute('data-percy-element-id');
         let cloneEl = clone.querySelector(`[data-percy-element-id="${percyElementId}"]`);
+
+        // Skip iframes with data-percy-ignore attribute or matching configured selectors
+        let matchesSelector = (ignoreIframeSelectors === null || ignoreIframeSelectors === void 0 ? void 0 : ignoreIframeSelectors.length) && ignoreIframeSelectors.some(sel => {
+          try {
+            return frame.matches(sel);
+          } catch {
+            return false;
+          }
+        });
+        if (frame.hasAttribute('data-percy-ignore') || matchesSelector) {
+          cloneEl === null || cloneEl === void 0 || cloneEl.remove();
+          continue;
+        }
         let builtWithJs = !frame.srcdoc && (!frame.src || frame.src.split(':')[0] === 'javascript');
+        let sandboxAttr = frame.getAttribute('sandbox');
+
+        // Warn about sandboxed iframes lacking the permissions Percy needs to
+        // render with fidelity. Fully-permissive sandboxes (allow-scripts +
+        // allow-same-origin) capture fine.
+        if (sandboxAttr !== null) {
+          let frameLabel = frame.id || frame.src || frame.getAttribute('name') || '<unnamed iframe>';
+          let tokens = sandboxAttr.split(/\s+/).filter(Boolean);
+          if (tokens.length === 0) {
+            warnings.add(`Sandboxed iframe "${frameLabel}" has no permissions — content may not render with full fidelity in Percy`);
+          } else {
+            if (!tokens.includes('allow-scripts')) {
+              warnings.add(`Sandboxed iframe "${frameLabel}" has scripts disabled — JS-dependent content will not render in Percy`);
+            }
+            if (!tokens.includes('allow-same-origin')) {
+              warnings.add(`Sandboxed iframe "${frameLabel}" lacks allow-same-origin — styles and resources may not load correctly in Percy`);
+            }
+          }
+        }
 
         // delete frames within the head since they usually break pages when
         // rerendered and do not effect the visuals of a page
@@ -193,12 +263,22 @@
           // the frame has yet to load and wasn't built with js, it is unsafe to serialize
           if (!builtWithJs && !frame.contentWindow.performance.timing.loadEventEnd) continue;
 
-          // recersively serialize contents
+          // Bound recursion at the configured depth so nested iframes can't
+          // blow the call stack on pathological pages.
+          if (iframeDepth + 1 >= maxIframeDepth) continue;
+
+          // recersively serialize contents — propagate ignoreIframeSelectors,
+          // forceShadowAsLightDOM, and the depth counter so nested iframes/shadow
+          // trees honor the same user options as the top-level capture.
           let serialized = serializeDOM({
             domTransformation: dom => setBaseURI(dom, warnings),
             dom: frame.contentDocument,
             enableJavaScript,
-            disableShadowDOM
+            disableShadowDOM,
+            forceShadowAsLightDOM,
+            ignoreIframeSelectors,
+            maxIframeDepth,
+            iframeDepth: iframeDepth + 1
           });
 
           // append serialized warnings and resources
@@ -221,6 +301,55 @@
       }
     }
 
+    // Shared traversal helpers for walking a document plus every shadow root
+    // it contains (open or closed-via-CDP). Centralizes access to the
+    // closed-shadow WeakMap so each call site honors the *iframe's* runtime
+    // window — a top-level `window.__percyClosedShadowRoots` lookup misses
+    // shadow roots stored on per-document WeakMaps inside iframes.
+
+    // Resolve the runtime window for any node (Document/Element/ShadowRoot).
+    // For a node inside an iframe, returns the iframe's window — which is where
+    // the per-document closed-shadow WeakMap is installed. Returns null when
+    // imported outside a browser realm (Node/Worker) so callers can no-op.
+    function getRuntime(node) {
+      const doc = (node === null || node === void 0 ? void 0 : node.ownerDocument) || node;
+      if (doc !== null && doc !== void 0 && doc.defaultView) return doc.defaultView;
+      /* istanbul ignore next: the global-window fallback only fires when this
+         module is imported outside a browser realm (Node/Worker). The karma
+         browser test runner always has a global window, so neither branch of
+         this final fallback is reachable from tests. */
+      return typeof window !== 'undefined' ? window : null;
+    }
+
+    // Closed-shadow-root WeakMap installed by exposeClosedShadowRoots via CDP,
+    // scoped to the node's owning document.
+    function getClosedShadowRoot(host) {
+      var _getRuntime;
+      return ((_getRuntime = getRuntime(host)) === null || _getRuntime === void 0 || (_getRuntime = _getRuntime.__percyClosedShadowRoots) === null || _getRuntime === void 0 ? void 0 : _getRuntime.get(host)) || null;
+    }
+    function hasClosedShadowRoot(host) {
+      var _getRuntime2;
+      return !!((_getRuntime2 = getRuntime(host)) !== null && _getRuntime2 !== void 0 && (_getRuntime2 = _getRuntime2.__percyClosedShadowRoots) !== null && _getRuntime2 !== void 0 && _getRuntime2.has(host));
+    }
+
+    // Resolve a shadow host's root, including closed roots captured via CDP.
+    // Returns null when the host has no shadow root reachable.
+    function getShadowRoot(host) {
+      if (host !== null && host !== void 0 && host.shadowRoot) return host.shadowRoot;
+      return getClosedShadowRoot(host);
+    }
+
+    // Walk root + every shadow root descendant, calling visit(scope) on each.
+    // `scope` is either the original root or a shadow root.
+    function walkShadowDOM(root, visit) {
+      visit(root);
+      if (!root.querySelectorAll) return;
+      for (const host of root.querySelectorAll('[data-percy-shadow-host]')) {
+        const shadow = getShadowRoot(host);
+        if (shadow) walkShadowDOM(shadow, visit);
+      }
+    }
+
     // Returns a mostly random uid.
     function uid() {
       return `_${Math.random().toString(36).substr(2, 9)}`;
@@ -228,14 +357,17 @@
     function markElement(domElement, disableShadowDOM, forceShadowAsLightDOM) {
       var _domElement$tagName;
       // Mark elements that are to be serialized later with a data attribute.
-      if (['input', 'textarea', 'select', 'iframe', 'canvas', 'video', 'style', 'dialog'].includes((_domElement$tagName = domElement.tagName) === null || _domElement$tagName === void 0 ? void 0 : _domElement$tagName.toLowerCase())) {
+      // Custom elements with ElementInternals or closed shadow roots also get
+      // stamped so the post-clone state-fallback can locate their clones.
+      if (['input', 'textarea', 'select', 'iframe', 'canvas', 'video', 'style', 'dialog'].includes((_domElement$tagName = domElement.tagName) === null || _domElement$tagName === void 0 ? void 0 : _domElement$tagName.toLowerCase()) || isCustomElement(domElement)) {
         if (!domElement.getAttribute('data-percy-element-id')) {
           domElement.setAttribute('data-percy-element-id', uid());
         }
       }
 
-      // add special marker for shadow host
-      if (!disableShadowDOM && domElement.shadowRoot) {
+      // add special marker for shadow host (including closed shadow roots captured via CDP)
+      let shadowRoot = getShadowRoot(domElement);
+      if (!disableShadowDOM && shadowRoot) {
         // When forceShadowAsLightDOM is true, don't mark as shadow host
         if (!forceShadowAsLightDOM) {
           domElement.setAttribute('data-percy-shadow-host', '');
@@ -505,9 +637,214 @@
       }
     }
 
+    // Serializes ElementInternals custom-element :state() into Percy's clone
+
+    // State names that survive into the rewritten attribute selector. Anything
+    // else (quotes, brackets, '</style>') would let a hostile page CSS escape
+    // the rewritten <style> block or inject extra rules.
+    const SAFE_STATE_NAME_RE = /^[-\w]+$/;
+    const STATE_ATTR_TEMPLATE = name => `[data-percy-custom-state~="${name}"]`;
+    function rewriteCustomStateCSS(ctx) {
+      const stateNames = new Set();
+      const styleElements = collectStyleElements(ctx.clone);
+      for (const style of styleElements) {
+        const css = style.textContent;
+        if (!css) continue;
+        const modified = rewriteCustomStateSelectors(css, stateNames);
+        if (modified !== css) {
+          // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
+          style.textContent = modified;
+        }
+      }
+      if (stateNames.size > 0) {
+        addCustomStateAttributes(ctx, stateNames);
+      }
+    }
+
+    // Rewrites `:state(name)` and the legacy `:--name` to attribute selectors.
+    // Names are validated against SAFE_STATE_NAME_RE; unsafe names are left
+    // alone so authors notice the bad input rather than getting silent
+    // zero-match rules.
+    function rewriteCustomStateSelectors(text, stateNames) {
+      text = text.replace(/:state\(([^)]+)\)/g, (m, name) => {
+        name = name.trim();
+        if (!SAFE_STATE_NAME_RE.test(name)) return m;
+        stateNames.add(name);
+        return STATE_ATTR_TEMPLATE(name);
+      });
+      text = text.replace(/:--([a-zA-Z][\w-]*)/g, (m, name) => {
+        stateNames.add(name);
+        return STATE_ATTR_TEMPLATE(name);
+      });
+      return text;
+    }
+
+    // Collect <style> elements from the document and every shadow root.
+    function collectStyleElements(root) {
+      const styles = [];
+      walkShadowDOM(root, scope => {
+        if (!scope.querySelectorAll) return;
+        for (const el of scope.querySelectorAll('style')) styles.push(el);
+      });
+      return styles;
+    }
+
+    // :state() supports both the function form and the legacy :--name form.
+    // element.matches() may throw on unsupported syntax; tolerate and try both.
+    function elementInState(el, name) {
+      for (const sel of [`:state(${name})`, `:--${name}`]) {
+        try {
+          if (el.matches(sel)) return true;
+        } catch (e) {
+          // not supported in this browser — try the next form
+        }
+      }
+      return false;
+    }
+
+    // Test live custom elements against :state(name) for each state name found
+    // in CSS, and stamp data-percy-custom-state on the matching clone element.
+    //
+    // Builds a percyId → cloneEl Map in one walk over the clone tree so the
+    // per-element lookup is O(1) — a naive per-element ctx.clone.querySelector
+    // scan is O(N × T) for N custom elements and a tree of size T.
+    function addCustomStateAttributes(ctx, stateNames) {
+      // ctx.clone is a DocumentFragment we constructed ourselves and shadow
+      // roots always have querySelectorAll, so the visitor doesn't need the
+      // defensive guard the live-DOM walk (below) uses.
+      const cloneByPercyId = new Map();
+      walkShadowDOM(ctx.clone, scope => {
+        for (const el of scope.querySelectorAll('[data-percy-element-id]')) {
+          cloneByPercyId.set(el.getAttribute('data-percy-element-id'), el);
+        }
+      });
+      walkShadowDOM(ctx.dom, scope => {
+        if (!scope.querySelectorAll) return;
+        for (const el of scope.querySelectorAll('*')) {
+          if (!isCustomElement(el)) continue;
+          const percyId = el.getAttribute('data-percy-element-id');
+          if (!percyId) continue;
+          const cloneEl = cloneByPercyId.get(percyId);
+          if (!cloneEl || cloneEl.hasAttribute('data-percy-custom-state')) continue;
+          const matchedStates = [];
+          for (const name of stateNames) {
+            if (elementInState(el, name)) matchedStates.push(name);
+          }
+          if (matchedStates.length > 0) {
+            cloneEl.setAttribute('data-percy-custom-state', matchedStates.join(' '));
+          }
+        }
+      });
+    }
+
     /* global XPathResult */
-    const PSEDUO_ELEMENT_MARKER_ATTR = 'data-percy-pseudo-element-id';
+    const PSEUDO_ELEMENT_MARKER_ATTR = 'data-percy-pseudo-element-id';
     const POPOVER_OPEN_ATTR = 'data-percy-popover-open';
+    const FOCUS_ATTR = 'data-percy-focus';
+    const FOCUS_WITHIN_ATTR = 'data-percy-focus-within';
+    const CHECKED_ATTR = 'data-percy-checked';
+    const DISABLED_ATTR = 'data-percy-disabled';
+    const HOVER_ATTR = 'data-percy-hover';
+    const ACTIVE_ATTR = 'data-percy-active';
+    const ALL_INTERACTIVE_PSEUDO = [':focus', ':focus-within', ':checked', ':disabled', ':hover', ':active'];
+    const PSEUDO_TO_ATTR = {
+      ':focus': '[data-percy-focus]',
+      ':focus-within': '[data-percy-focus-within]',
+      ':checked': '[data-percy-checked]',
+      ':disabled': '[data-percy-disabled]',
+      ':hover': '[data-percy-hover]',
+      ':active': '[data-percy-active]'
+    };
+
+    // Boundary regex per pseudo-class. Lookahead `(?![-\w])` prevents :focus
+    // from matching the start of :focus-within / :focus-visible. Order matters:
+    // longer pseudos (:focus-within) are listed first so they win over :focus.
+    const PSEUDO_RES = [[':focus-within', /:focus-within(?![-\w])/g], [':focus', /:focus(?![-\w])/g], [':checked', /:checked(?![-\w])/g], [':disabled', /:disabled(?![-\w])/g], [':hover', /:hover(?![-\w])/g], [':active', /:active(?![-\w])/g]];
+    function selectorContainsPseudo(selectorText, pseudoList) {
+      return pseudoList.some(pc => {
+        const re = PSEUDO_RES.find(([p]) => p === pc)[1];
+        re.lastIndex = 0;
+        return re.test(selectorText);
+      });
+    }
+    function rewritePseudoSelector(selectorText) {
+      let out = selectorText;
+      for (const [pseudo, re] of PSEUDO_RES) out = out.replace(re, PSEUDO_TO_ATTR[pseudo]);
+      return out;
+    }
+
+    // Record a live-DOM mutation so cleanup can undo it. Callers must ensure
+    // ctx._liveMutations exists — markPseudoClassElements and getElementsToProcess
+    // both initialize it upfront.
+    function stampOnce(ctx, element, attr, value) {
+      if (element.hasAttribute(attr)) return;
+      element.setAttribute(attr, value);
+      ctx._liveMutations.push([element, attr]);
+    }
+
+    // Walk into shadow roots (including closed ones captured via CDP) to find
+    // the deepest focused element, so we can stamp it with FOCUS_ATTR.
+    function findDeepActiveElement(dom) {
+      let active = dom.activeElement;
+      let root = active && getShadowRoot(active);
+      while ((_root = root) !== null && _root !== void 0 && _root.activeElement) {
+        var _root;
+        active = root.activeElement;
+        root = getShadowRoot(active);
+      }
+      return active;
+    }
+
+    // Walk the focused element's ancestor chain across shadow root boundaries
+    // stamping FOCUS_WITHIN_ATTR on each. :focus-within rules in CSS will be
+    // rewritten to [data-percy-focus-within] and match these stamps.
+    function markFocusWithinAncestors(ctx, focused) {
+      let node = focused === null || focused === void 0 ? void 0 : focused.parentNode;
+      while (node) {
+        if (node.nodeType === 1 /* ELEMENT_NODE */) {
+          stampOnce(ctx, node, FOCUS_WITHIN_ATTR, 'true');
+          node = node.parentNode;
+        } else if (node.nodeType === 11 /* DOCUMENT_FRAGMENT_NODE — shadow root */) {
+          // Shadow roots always have a host per spec; if a future detached
+          // fragment ever lacked one, the next iteration's nodeType checks
+          // both fail and the else cascade nulls node anyway.
+          node = node.host;
+        } else {
+          node = null;
+        }
+      }
+    }
+    function markInteractiveStates(ctx) {
+      const focused = findDeepActiveElement(ctx.dom);
+      if (focused && focused !== ctx.dom.body && focused !== ctx.dom.documentElement) {
+        stampOnce(ctx, focused, FOCUS_ATTR, 'true');
+        markFocusWithinAncestors(ctx, focused);
+      }
+
+      // Single walk of ctx.dom + shadow roots collecting BOTH :checked and
+      // :disabled in one pass. Previously two separate queryShadowAll calls
+      // each walked the tree and re-traversed every [data-percy-shadow-host]
+      // — on pages with many shadow hosts this doubled the per-snapshot
+      // walk cost. Also tracks which states were observed so the CSS rule
+      // extractor can skip work for selectors that have no matched elements.
+      ctx._stampedInteractive = ctx._stampedInteractive || new Set();
+      // walkShadowDOM only invokes the visitor with Document/Element/ShadowRoot
+      // scopes — each has querySelectorAll, so no defensive guard is needed here.
+      walkShadowDOM(ctx.dom, scope => {
+        try {
+          for (const el of scope.querySelectorAll(':checked')) {
+            stampOnce(ctx, el, CHECKED_ATTR, 'true');
+            ctx._stampedInteractive.add('checked');
+          }
+        } catch (e) {/* selector unsupported in this scope */}
+        try {
+          for (const el of scope.querySelectorAll(':disabled')) {
+            stampOnce(ctx, el, DISABLED_ATTR, 'true');
+            ctx._stampedInteractive.add('disabled');
+          }
+        } catch (e) {/* selector unsupported in this scope */}
+      });
+    }
     function isPopoverOpen(ctx, element) {
       try {
         return element.matches(':popover-open');
@@ -516,54 +853,62 @@
         return false;
       }
     }
-    function markElementIfNeeded(ctx, element, markWithId) {
-      if (!markWithId) return;
-      if (element.hasAttribute('popover') && isPopoverOpen(ctx, element) && !element.hasAttribute(POPOVER_OPEN_ATTR)) {
-        element.setAttribute(POPOVER_OPEN_ATTR, 'true');
+    function markPopoverIfOpen(ctx, element) {
+      if (element.hasAttribute('popover') && isPopoverOpen(ctx, element)) {
+        stampOnce(ctx, element, POPOVER_OPEN_ATTR, 'true');
       }
-      if (!element.getAttribute(PSEDUO_ELEMENT_MARKER_ATTR)) {
-        element.setAttribute(PSEDUO_ELEMENT_MARKER_ATTR, uid());
+    }
+    function stampPseudoElementId(ctx, element) {
+      if (!element.getAttribute(PSEUDO_ELEMENT_MARKER_ATTR)) {
+        element.setAttribute(PSEUDO_ELEMENT_MARKER_ATTR, uid());
+        ctx._liveMutations.push([element, PSEUDO_ELEMENT_MARKER_ATTR]);
       }
     }
 
-    /**
-     * Get all elements matching the pseudoClassEnabledElements configuration
-     * @param {Document} dom - The document to search
-     * @param {Object} config - Configuration with id, className, and xpath arrays
-     * @param {boolean} markWithId - Whether to mark elements with PSEDUO_ELEMENT_MARKER_ATTR
-     * @returns {Array} Array of elements found
-     */
+    // Configured elements get :hover/:active stamped unconditionally — opting in
+    // IS the request to capture those forced states. :focus/:checked/:disabled
+    // are already covered by the page-wide markInteractiveStates pass.
+    function markElementInteractiveStates(ctx, element) {
+      stampOnce(ctx, element, HOVER_ATTR, 'true');
+      stampOnce(ctx, element, ACTIVE_ATTR, 'true');
+    }
     function getElementsToProcess(ctx, config, markWithId = false) {
       const {
         dom
       } = ctx;
       const elements = [];
-      if (config.id && Array.isArray(config.id)) {
+      const stamp = el => {
+        if (markWithId) {
+          markPopoverIfOpen(ctx, el);
+          markElementInteractiveStates(ctx, el);
+          stampPseudoElementId(ctx, el);
+        }
+      };
+      if (Array.isArray(config.id)) {
         for (const id of config.id) {
           const element = dom.getElementById(id);
           if (!element) {
             ctx.warnings.add(`No element found with ID: ${id} for pseudo-class serialization`);
             continue;
           }
-          markElementIfNeeded(ctx, element, markWithId);
+          stamp(element);
           elements.push(element);
         }
       }
-
-      // Process only first match per class name
-      if (config.className && Array.isArray(config.className)) {
+      if (Array.isArray(config.className)) {
         for (const className of config.className) {
-          const elementCollection = dom.getElementsByClassName(className);
-          if (!elementCollection.length) {
+          const collection = dom.getElementsByClassName(className);
+          if (!collection.length) {
             ctx.warnings.add(`No element found with class name: ${className} for pseudo-class serialization`);
             continue;
           }
-          const element = elementCollection[0];
-          markElementIfNeeded(ctx, element, markWithId);
+          // Process only first match per class name (preserves prior behavior).
+          const element = collection[0];
+          stamp(element);
           elements.push(element);
         }
       }
-      if (config.xpath && Array.isArray(config.xpath)) {
+      if (Array.isArray(config.xpath)) {
         for (const xpathExpression of config.xpath) {
           try {
             const element = dom.evaluate(xpathExpression, dom, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
@@ -571,14 +916,14 @@
               ctx.warnings.add(`No element found for XPath: ${xpathExpression} for pseudo-class serialization`);
               continue;
             }
-            markElementIfNeeded(ctx, element, markWithId);
+            stamp(element);
           } catch (err) {
             ctx.warnings.add(`Invalid XPath expression "${xpathExpression}" for pseudo-class serialization. Error: ${err.message}`);
             console.warn(`Invalid XPath expression "${xpathExpression}". Error: ${err.message}`);
           }
         }
       }
-      if (config.selectors && Array.isArray(config.selectors)) {
+      if (Array.isArray(config.selectors)) {
         for (const selector of config.selectors) {
           try {
             const matched = Array.from(dom.querySelectorAll(selector));
@@ -587,7 +932,7 @@
               continue;
             }
             matched.forEach(el => {
-              markElementIfNeeded(ctx, el, markWithId);
+              stamp(el);
               elements.push(el);
             });
           } catch (err) {
@@ -599,67 +944,209 @@
       return elements;
     }
 
-    /**
-     * Mark pseudo-class enabled elements with data-percy-element-id before cloning
-     * This must be called before the DOM is cloned
-     * @param {Document} dom - The document to mark
-     * @param {Object} config - Configuration with id and xpath arrays
-     */
+    // Pre-clone marking pass. Runs on the live DOM before cloneNodeAndShadow so
+    // the data-attributes are copied through to the clone via cloneNode.
     function markPseudoClassElements(ctx, config) {
-      if (!config) return;
-      getElementsToProcess(ctx, config, true);
+      ctx._liveMutations = [];
+      markInteractiveStates(ctx);
+      if (config) getElementsToProcess(ctx, config, true);
     }
 
-    /**
-     * Convert CSSStyleDeclaration to CSS text with !important declarations
-     * @param {CSSStyleDeclaration} styles - Computed style declaration
-     * @returns {string} CSS text
-     */
+    // Reverse every setAttribute we made on the live DOM during marking. Called
+    // at the end of serializeDOM so the customer's page is left clean — SDK
+    // mode runs in the customer's actual browser tab and leaks would persist
+    // past the snapshot.
+    function cleanupInteractiveStateMarkers(ctx) {
+      if (!ctx._liveMutations) return;
+      for (const [element, attr] of ctx._liveMutations) {
+        try {
+          element.removeAttribute(attr);
+        } catch (e) {
+          // Element detached or attribute already gone — fine
+        }
+      }
+      ctx._liveMutations = [];
+    }
     function stylesToCSSText(styles) {
-      const cssProperties = [];
+      const decls = [];
       for (let i = 0; i < styles.length; i++) {
         const property = styles[i];
-        const value = styles.getPropertyValue(property);
-        cssProperties.push(`${property}: ${value} !important;`);
+        decls.push(`${property}: ${styles.getPropertyValue(property)} !important;`);
       }
-      return cssProperties.join(' ');
+      return decls.join(' ');
     }
 
-    /**
-     * Process pseudo-class elements and add percy-pseudo-class CSS
-     * @param {Object} ctx - Serialization context
-     */
-    function serializePseudoClasses(ctx) {
-      if (!ctx.pseudoClassEnabledElements) {
-        return;
+    // Walk a CSSRule list yielding every reachable style rule. Nested rules
+    // inside @media/@layer/@supports are emitted with the at-rule prelude
+    // preserved as a wrapper string; flat-emitting would drop the guard.
+    function walkCSSRules(ruleList) {
+      const result = [];
+      for (let i = 0; i < ruleList.length; i++) {
+        const rule = ruleList[i];
+        const hasNested = !!(rule.cssRules && rule.cssRules.length);
+        if (hasNested) {
+          var _rule$media;
+          const conditionText = rule.conditionText || ((_rule$media = rule.media) === null || _rule$media === void 0 ? void 0 : _rule$media.mediaText);
+          const atRulePrelude = conditionText && rule.cssText ? rule.cssText.split('{')[0].trim() : null;
+          for (const inner of walkCSSRules(rule.cssRules)) {
+            if (atRulePrelude && inner.selectorText) {
+              result.push({
+                selectorText: inner.selectorText,
+                style: inner.style,
+                wrapper: atRulePrelude
+              });
+            } else {
+              result.push(inner);
+            }
+          }
+        } else if (rule.selectorText) {
+          // Rules without nested cssRules and without selectorText (@font-face,
+          // @charset, @counter-style, etc.) are skipped — they can't contain
+          // interactive pseudos.
+          result.push({
+            selectorText: rule.selectorText,
+            style: rule.style,
+            wrapper: null
+          });
+        }
       }
-      const elements = ctx.dom.querySelectorAll(`[${PSEDUO_ELEMENT_MARKER_ATTR}]`);
-      if (elements.length === 0) {
-        return;
+      return result;
+    }
+
+    // Collect { sheet, owner } entries for every stylesheet in the document
+    // and inside every shadow root. owner is the shadow host (or null for
+    // document-level sheets) so we know which clone scope to inject into.
+    function collectStyleSheets(doc) {
+      const entries = [];
+      walkShadowDOM(doc, scope => {
+        let sheets;
+        try {
+          sheets = scope.styleSheets;
+        } catch (e) {
+          return;
+        }
+        if (!sheets) return;
+        const owner = scope === doc ? null : scope.host;
+        for (const sheet of sheets) entries.push({
+          sheet,
+          owner
+        });
+      });
+      return entries;
+    }
+    function extractPseudoClassRules(ctx) {
+      const sheetEntries = collectStyleSheets(ctx.dom);
+      const rulesByOwner = new Map();
+
+      // Short-circuit per pseudo: when markInteractiveStates ran first (the
+      // production path via markPseudoClassElements), `ctx._stampedInteractive`
+      // records which interactive states were actually observed. Rules for
+      // `:checked` / `:disabled` selectors that found no live elements can't
+      // match anything in the clone after rewriting, so we drop them from the
+      // filter and avoid the rewrite cost. When the marker is absent (unit
+      // tests that call serializePseudoClasses directly), fall back to the
+      // full pseudo list to preserve prior behavior. `:focus`, `:focus-within`,
+      // `:hover`, `:active` are kept regardless either way.
+      const activePseudos = ctx._stampedInteractive ? ALL_INTERACTIVE_PSEUDO.filter(p => {
+        if (p === ':checked') return ctx._stampedInteractive.has('checked');
+        if (p === ':disabled') return ctx._stampedInteractive.has('disabled');
+        return true;
+      }) : ALL_INTERACTIVE_PSEUDO;
+      for (const {
+        sheet,
+        owner
+      } of sheetEntries) {
+        let rules;
+        try {
+          rules = sheet.cssRules;
+        } catch (e) {
+          // Cross-origin stylesheet — skip
+          continue;
+        }
+        if (!rules) continue;
+        for (const rule of walkCSSRules(rules)) {
+          // Cheapest possible filter: a selector with no `:` can't contain any
+          // interactive pseudo. Skips most rules on most stylesheets without
+          // touching the regex bank.
+          if (!rule.selectorText.includes(':')) continue;
+          if (!selectorContainsPseudo(rule.selectorText, activePseudos)) continue;
+          const rewrittenSelector = rewritePseudoSelector(rule.selectorText);
+          const cssText = `${rewrittenSelector} { ${rule.style.cssText} }`;
+          const wrapped = rule.wrapper ? `${rule.wrapper} { ${cssText} }` : cssText;
+          if (!rulesByOwner.has(owner)) rulesByOwner.set(owner, []);
+          rulesByOwner.get(owner).push(wrapped);
+        }
+      }
+
+      // Build a percyId → cloneEl index once for shadow-host injection — only
+      // when there is at least one non-null owner in the collected rules.
+      let cloneByPercyId = null;
+      for (const owner of rulesByOwner.keys()) {
+        if (owner !== null) {
+          cloneByPercyId = new Map();
+          for (const el of ctx.clone.querySelectorAll('[data-percy-element-id]')) {
+            cloneByPercyId.set(el.getAttribute('data-percy-element-id'), el);
+          }
+          break;
+        }
+      }
+      for (const [owner, rewrittenRules] of rulesByOwner) {
+        const styleElement = ctx.clone.createElement ? ctx.clone.createElement('style') : ctx.dom.createElement('style');
+        styleElement.setAttribute('data-percy-interactive-states', 'true');
+        // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
+        styleElement.textContent = rewrittenRules.join('\n');
+        if (owner === null) {
+          const head = ctx.clone.head || ctx.clone.querySelector('head');
+          if (head) head.appendChild(styleElement);
+        } else {
+          const percyId = owner.getAttribute('data-percy-element-id');
+          const cloneHost = cloneByPercyId.get(percyId);
+          if (cloneHost && cloneHost.shadowRoot) {
+            cloneHost.shadowRoot.appendChild(styleElement);
+          }
+        }
+      }
+    }
+    function serializePseudoClasses(ctx) {
+      // Auto-detect path runs unconditionally so `:focus`/`:checked`/`:disabled`
+      // rules are rewritten regardless of whether the user configured a
+      // pseudoClassEnabledElements list (and regardless of whether that list
+      // matched anything on this page).
+      extractPseudoClassRules(ctx);
+      if (!ctx.pseudoClassEnabledElements) return;
+      const elements = ctx.dom.querySelectorAll(`[${PSEUDO_ELEMENT_MARKER_ATTR}]`);
+      if (elements.length === 0) return;
+
+      // pseudoElementId → cloneEl index, built once. The previous shape did a
+      // ctx.clone.querySelector per element which is O(N × T).
+      const cloneByPseudoId = new Map();
+      for (const el of ctx.clone.querySelectorAll(`[${PSEUDO_ELEMENT_MARKER_ATTR}]`)) {
+        cloneByPseudoId.set(el.getAttribute(PSEUDO_ELEMENT_MARKER_ATTR), el);
       }
       const cssRules = [];
       for (const element of elements) {
-        const percyElementId = element.getAttribute(PSEDUO_ELEMENT_MARKER_ATTR);
-        const cloneElement = ctx.clone.querySelector(`[${PSEDUO_ELEMENT_MARKER_ATTR}="${percyElementId}"]`);
+        const percyElementId = element.getAttribute(PSEUDO_ELEMENT_MARKER_ATTR);
+        const cloneElement = cloneByPseudoId.get(percyElementId);
         if (!cloneElement) {
           ctx.warnings.add(`Element not found for pseudo-class serialization with percy-element-id: ${percyElementId}`);
           continue;
         }
         try {
-          // Get all computed styles including pseudo-classes
-          const computedStyles = window.getComputedStyle(element);
+          // ctx.dom.defaultView is the iframe's window for nested-frame contexts;
+          // fall back to the global window when ctx.dom is the top document or a
+          // synthetic root that doesn't expose defaultView (e.g. tests).
+          const win = ctx.dom.defaultView || window;
+          const computedStyles = win.getComputedStyle(element);
           const cssText = stylesToCSSText(computedStyles);
-          const selector = `[${PSEDUO_ELEMENT_MARKER_ATTR}="${percyElementId}"]`;
-          cssRules.push(`${selector} { ${cssText} }`);
+          cssRules.push(`[${PSEUDO_ELEMENT_MARKER_ATTR}="${percyElementId}"] { ${cssText} }`);
         } catch (err) {
           console.warn('Could not get computed styles for element', element, err);
         }
       }
-
-      // Inject CSS into cloned document
       if (cssRules.length > 0) {
         const styleElement = ctx.dom.createElement('style');
         styleElement.setAttribute('data-percy-pseudo-class-styles', 'true');
+        // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
         styleElement.textContent = cssRules.join('\n');
         const head = ctx.clone.head || ctx.clone.querySelector('head');
         if (head) {
@@ -790,13 +1277,16 @@
     const ignoreTags = ['NOSCRIPT'];
 
     /**
-     * if a custom element has attribute callback then cloneNode calls a callback that can
-     * increase CPU load or some other change.
-     * So we want to make sure that it is not called when doing serialization.
-    */
+     * Clone an element without triggering custom element lifecycle callbacks.
+     * Custom elements with callbacks or closed shadow roots are cloned as proxy elements
+     * to prevent constructors from running (which could call attachShadow, fetch data, etc).
+     */
     function cloneElementWithoutLifecycle(element) {
-      if (!element.attributeChangedCallback || !element.tagName.includes('-')) {
-        return element.cloneNode(); // Standard clone for non-custom elements
+      let isCustom = isCustomElement(element);
+      let hasClosedShadow = isCustom && hasClosedShadowRoot(element);
+      let hasCallbacks = isCustom && element.attributeChangedCallback;
+      if (!isCustom || !hasCallbacks && !hasClosedShadow) {
+        return element.cloneNode();
       }
       const cloned = document.createElement('data-percy-custom-element-' + element.tagName);
 
@@ -841,6 +1331,10 @@
           markElement(node, disableShadowDOM, forceShadowAsLightDOM);
           let clone = cloneElementWithoutLifecycle(node);
 
+          // Custom-element :state() is captured by the fallback path in
+          // serialize-custom-states.js (live el.matches against state names
+          // discovered in CSS) — no clone-time fast path remains.
+
           // Handle <style> tag specifically for media queries
           if (node.nodeName === 'STYLE' && !enableJavaScript) {
             var _node$textContent;
@@ -872,11 +1366,13 @@
             Array.from(clone.children).forEach(child => clone.removeChild(child));
           }
 
-          // clone shadow DOM
-          if (node.shadowRoot && !disableShadowDOM) {
+          // clone shadow DOM (including closed shadow roots captured via CDP
+          // and stored on window.__percyClosedShadowRoots)
+          let nodeShadowRoot = node.shadowRoot || getClosedShadowRoot(node);
+          if (nodeShadowRoot && !disableShadowDOM) {
             if (forceShadowAsLightDOM) {
               // When forceShadowAsLightDOM is true, treat shadow content as normal DOM
-              walkTree(node.shadowRoot.firstChild, clone);
+              walkTree(nodeShadowRoot.firstChild, clone);
             } else {
               // create shadowRoot
               if (clone.shadowRoot) {
@@ -889,7 +1385,7 @@
                 });
               }
               // clone dom elements
-              walkTree(node.shadowRoot.firstChild, clone.shadowRoot);
+              walkTree(nodeShadowRoot.firstChild, clone.shadowRoot);
             }
           }
 
@@ -992,13 +1488,14 @@
         for (const shadowHost of ctx.dom.querySelectorAll('[data-percy-shadow-host]')) {
           let percyElementId = shadowHost.getAttribute('data-percy-element-id');
           let cloneShadowHost = ctx.clone.querySelector(`[data-percy-element-id="${percyElementId}"]`);
-          if (shadowHost.shadowRoot && cloneShadowHost.shadowRoot) {
+          let origShadow = shadowHost.shadowRoot || getClosedShadowRoot(shadowHost);
+          if (origShadow && cloneShadowHost.shadowRoot) {
             // getHTML requires shadowRoot to be passed explicitly
             // to serialize the shadow elements properly
             ctx.shadowRootElements.push(cloneShadowHost.shadowRoot);
             serializeElements({
               ...ctx,
-              dom: shadowHost.shadowRoot,
+              dom: origShadow,
               clone: cloneShadowHost.shadowRoot
             });
           } else {
@@ -1024,9 +1521,9 @@
       window.resizeCount = 0;
     }
 
-    // Serializes a document and returns the resulting DOM string.
+    // Synchronous DOM serializer. For readiness gating, call `PercyDOM.waitForReady(config)`
+    // before this — see readiness.js.
     function serializeDOM(options) {
-      var _ctx$clone$body;
       let {
         dom = document,
         // allow snake_case or camelCase
@@ -1038,6 +1535,9 @@
         ignoreCanvasSerializationErrors = options === null || options === void 0 ? void 0 : options.ignore_canvas_serialization_errors,
         ignoreStyleSheetSerializationErrors = options === null || options === void 0 ? void 0 : options.ignore_style_sheet_serialization_errors,
         forceShadowAsLightDOM = options === null || options === void 0 ? void 0 : options.force_shadow_dom_as_light_dom,
+        ignoreIframeSelectors = options === null || options === void 0 ? void 0 : options.ignore_iframe_selectors,
+        maxIframeDepth = options === null || options === void 0 ? void 0 : options.max_iframe_depth,
+        iframeDepth = (options === null || options === void 0 ? void 0 : options.iframe_depth) ?? 0,
         pseudoClassEnabledElements = options === null || options === void 0 ? void 0 : options.pseudo_class_enabled_elements
       } = options || {};
 
@@ -1053,53 +1553,67 @@
         ignoreCanvasSerializationErrors,
         ignoreStyleSheetSerializationErrors,
         forceShadowAsLightDOM,
+        ignoreIframeSelectors,
+        maxIframeDepth,
+        iframeDepth,
         pseudoClassEnabledElements
       };
       ctx.dom = dom;
-      markPseudoClassElements(ctx, pseudoClassEnabledElements);
-      ctx.clone = cloneNodeAndShadow(ctx);
-      serializeElements(ctx);
 
-      // STEP 4: Process pseudo-class enabled elements
-      serializePseudoClasses(ctx);
-      if (domTransformation) {
+      // markPseudoClassElements writes data-percy-* attributes onto the LIVE DOM.
+      // Wrap it AND everything that follows in try/finally so cleanup runs even
+      // if any step (mark, clone, serialize, transform, html) throws — otherwise
+      // partially-stamped attributes leak into the customer's page (SDK mode
+      // runs in the customer's tab). _liveMutations is appended to incrementally
+      // by stampOnce, so cleanup finds whatever was stamped before the throw.
+      try {
+        var _ctx$clone$body;
+        markPseudoClassElements(ctx, pseudoClassEnabledElements);
+        ctx.clone = cloneNodeAndShadow(ctx);
+        serializeElements(ctx);
+        serializePseudoClasses(ctx);
+        rewriteCustomStateCSS(ctx);
+        if (domTransformation) {
+          try {
+            // eslint-disable-next-line no-eval
+            if (typeof domTransformation === 'string') domTransformation = window.eval(domTransformation);
+            domTransformation(ctx.clone.documentElement);
+          } catch (err) {
+            let errorMessage = `Could not transform the dom: ${err.message}`;
+            ctx.warnings.add(errorMessage);
+            console.error(errorMessage);
+          }
+        }
+        if (reshuffleInvalidTags) {
+          let clonedBody = ctx.clone.body;
+          while (clonedBody.nextSibling) {
+            let sibling = clonedBody.nextSibling;
+            clonedBody.append(sibling);
+          }
+        } else if ((_ctx$clone$body = ctx.clone.body) !== null && _ctx$clone$body !== void 0 && _ctx$clone$body.nextSibling) {
+          ctx.hints.add('DOM elements found outside </body>');
+        }
+        let cookies = '';
+        // Collecting cookies fail for about://blank page
         try {
-          // eslint-disable-next-line no-eval
-          if (typeof domTransformation === 'string') domTransformation = window.eval(domTransformation);
-          domTransformation(ctx.clone.documentElement);
-        } catch (err) {
-          let errorMessage = `Could not transform the dom: ${err.message}`;
+          cookies = dom.cookie;
+        } catch (err) /* istanbul ignore next */ /* Tested this part in discovery.test.js with about:blank page */{
+          const errorMessage = `Could not capture cookies: ${err.message}`;
           ctx.warnings.add(errorMessage);
           console.error(errorMessage);
         }
+        let result = {
+          html: serializeHTML(ctx),
+          cookies: cookies,
+          userAgent: navigator.userAgent,
+          warnings: Array.from(ctx.warnings),
+          resources: Array.from(ctx.resources),
+          hints: Array.from(ctx.hints)
+        };
+        return stringifyResponse ? JSON.stringify(result) : result;
+      } finally {
+        cleanupInteractiveStateMarkers(ctx);
       }
-      if (reshuffleInvalidTags) {
-        let clonedBody = ctx.clone.body;
-        while (clonedBody.nextSibling) {
-          let sibling = clonedBody.nextSibling;
-          clonedBody.append(sibling);
-        }
-      } else if ((_ctx$clone$body = ctx.clone.body) !== null && _ctx$clone$body !== void 0 && _ctx$clone$body.nextSibling) {
-        ctx.hints.add('DOM elements found outside </body>');
-      }
-      let cookies = '';
-      // Collecting cookies fail for about://blank page
-      try {
-        cookies = dom.cookie;
-      } catch (err) /* istanbul ignore next */ /* Tested this part in discovery.test.js with about:blank page */{
-        const errorMessage = `Could not capture cookies: ${err.message}`;
-        ctx.warnings.add(errorMessage);
-        console.error(errorMessage);
-      }
-      let result = {
-        html: serializeHTML(ctx),
-        cookies: cookies,
-        userAgent: navigator.userAgent,
-        warnings: Array.from(ctx.warnings),
-        resources: Array.from(ctx.resources),
-        hints: Array.from(ctx.hints)
-      };
-      return stringifyResponse ? JSON.stringify(result) : result;
     }
 
     function getSrcsets(dom) {
@@ -1148,10 +1662,683 @@
       return allImgTags;
     }
 
+    /* eslint-disable no-undef */
+    // Browser globals (performance, MutationObserver, document, window, getComputedStyle)
+    // are available in the browser execution context where this code runs.
+
+    // Readiness check presets
+    //
+    // `js_idle_window_ms` is separate from `stability_window_ms` on purpose:
+    // DOM stability and main-thread idleness measure different things. With
+    // the `strict` preset we want a long DOM-stability window (1000ms) but
+    // not necessarily 1000ms of no long tasks — that would cause unnecessary
+    // timeouts on pages with normal JS activity. Both windows are
+    // independently configurable but default to reasonable values per preset.
+    const PRESETS = {
+      balanced: {
+        stability_window_ms: 300,
+        js_idle_window_ms: 300,
+        network_idle_window_ms: 200,
+        timeout_ms: 10000,
+        dom_stability: true,
+        image_ready: true,
+        font_ready: true,
+        js_idle: true
+      },
+      strict: {
+        stability_window_ms: 1000,
+        js_idle_window_ms: 500,
+        network_idle_window_ms: 500,
+        timeout_ms: 30000,
+        dom_stability: true,
+        image_ready: true,
+        font_ready: true,
+        js_idle: true
+      },
+      fast: {
+        stability_window_ms: 100,
+        js_idle_window_ms: 100,
+        network_idle_window_ms: 100,
+        timeout_ms: 5000,
+        dom_stability: true,
+        image_ready: false,
+        font_ready: true,
+        js_idle: true
+      }
+    };
+    const LAYOUT_ATTRIBUTES = new Set(['class', 'width', 'height', 'display', 'visibility', 'position', 'src']);
+    const LAYOUT_STYLE_PROPS = /^(width|height|top|left|right|bottom|margin|padding|display|position|visibility|flex|grid|min-|max-|inset|gap|order|float|clear|overflow|z-index|columns)/;
+
+    // Exported for direct unit testing — logic is deterministic and does not
+    // depend on browser timing, so it should not be covered only indirectly
+    // through MutationObserver-driven integration tests.
+    function isLayoutMutation(mutation) {
+      if (mutation.type === 'childList') return true;
+      if (mutation.type === 'attributes') {
+        let attr = mutation.attributeName;
+        if (attr.startsWith('data-') || attr.startsWith('aria-')) return false;
+        if (attr === 'style') {
+          let oldStyle = mutation.oldValue || '';
+          let newStyle = mutation.target.getAttribute('style') || '';
+          return hasLayoutStyleChange(oldStyle, newStyle);
+        }
+        // href is only layout-affecting on <link> elements (stylesheets).
+        // On <a> tags changing href is a no-op for layout.
+        if (attr === 'href') return mutation.target.tagName === 'LINK';
+        if (LAYOUT_ATTRIBUTES.has(attr)) return true;
+      }
+      return false;
+    }
+    function hasLayoutStyleChange(oldStyle, newStyle) {
+      if (oldStyle === newStyle) return false;
+      let oldProps = parseStyleProps(oldStyle);
+      let newProps = parseStyleProps(newStyle);
+      let allKeys = new Set([...Object.keys(oldProps), ...Object.keys(newProps)]);
+      for (let key of allKeys) {
+        if (LAYOUT_STYLE_PROPS.test(key) && oldProps[key] !== newProps[key]) return true;
+      }
+      return false;
+    }
+    function parseStyleProps(styleStr) {
+      let props = {};
+      if (!styleStr) return props;
+      for (let part of styleStr.split(';')) {
+        let i = part.indexOf(':');
+        if (i > 0) {
+          let key = part.slice(0, i).trim().toLowerCase();
+          if (key) props[key] = part.slice(i + 1).trim();
+        }
+      }
+      return props;
+    }
+
+    // Resolve a single ready/notPresent selector to a DOM Element. Accepts:
+    //   - CSS string:                  '.app-loaded'
+    //   - XPath string:                '//div[@id="root"]'  (sniffed by leading /, //, ./, (/, (./)
+    //   - Object form (explicit):      { css: '.foo' } | { xpath: '//bar' }
+    // Returns the matched Element, or null when no element matches, the
+    // selector is malformed, or it resolves to a non-Element node.
+    //
+    // Exported for direct unit testing.
+    const XPATH_SNIFF = /^\(?\.?\//;
+    function resolveSelector(selector) {
+      if (!selector) return null;
+      let xpath = null;
+      let css = null;
+      if (typeof selector === 'object') {
+        if (selector.xpath) xpath = selector.xpath;else if (selector.css) css = selector.css;else return null;
+      } else if (typeof selector === 'string') {
+        if (XPATH_SNIFF.test(selector)) xpath = selector;else css = selector;
+      } else {
+        return null;
+      }
+      try {
+        let el = xpath ? document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue : document.querySelector(css);
+        return el instanceof Element ? el : null;
+      } catch (e) {
+        // Malformed XPath or invalid CSS — treat as no-match so the selector
+        // gate keeps polling rather than blowing up the entire readiness gate.
+        return null;
+      }
+    }
+
+    // Subscribe to PerformanceObserver entries of a given type. Returns the
+    // observer (for the caller to disconnect) or null when PerformanceObserver
+    // (or the requested entry type) is unavailable, so callers can fall back.
+    //
+    // Used by checkNetworkIdle (`resource`) and checkJSIdle (`longtask`) to
+    // avoid duplicating the try/observe/disconnect boilerplate.
+    function observePerformance(type, onEntries) {
+      try {
+        let observer = new PerformanceObserver(list => onEntries(list.getEntries()));
+        observer.observe({
+          type,
+          buffered: false
+        });
+        return observer;
+      } catch (e) /* istanbul ignore next: PerformanceObserver is available in Chrome/Firefox; catch is for old browsers */{
+        return null;
+      }
+    }
+
+    // --- Individual Checks ---
+    // Each check accepts an `aborted` object ({ value: boolean }) so the orchestrator
+    // can signal cancellation on timeout. Checks must clean up timers/observers on abort.
+
+    function checkDOMStability(stabilityWindowMs, aborted) {
+      return new Promise(resolve => {
+        let startTime = performance.now();
+        let timer = null;
+        let mutationCount = 0;
+        let lastMutationType = null;
+        let observer = new MutationObserver(mutations => {
+          /* istanbul ignore next: abort disconnects the observer synchronously, defensive dead code in tests */
+          if (aborted.value) return;
+          let hasLayout = false;
+          for (let m of mutations) {
+            if (isLayoutMutation(m)) {
+              hasLayout = true;
+              mutationCount++;
+              lastMutationType = m.type;
+            }
+          }
+          /* istanbul ignore next: timer is always set before observer fires */
+          if (hasLayout) {
+            if (timer) clearTimeout(timer);
+            timer = setTimeout(settle, stabilityWindowMs);
+          }
+        });
+        function settle() {
+          observer.disconnect();
+          resolve({
+            passed: true,
+            duration_ms: Math.round(performance.now() - startTime),
+            mutations_observed: mutationCount,
+            last_mutation_type: lastMutationType
+          });
+        }
+        observer.observe(document.documentElement, {
+          childList: true,
+          attributes: true,
+          attributeOldValue: true,
+          subtree: true,
+          attributeFilter: [...LAYOUT_ATTRIBUTES, 'style', 'href']
+        });
+        timer = setTimeout(settle, stabilityWindowMs);
+
+        // Cleanup on abort
+        aborted.onAbort(() => {
+          /* istanbul ignore next: timer is always set at line 124 before abort can fire */
+          if (timer) clearTimeout(timer);
+          observer.disconnect();
+        });
+      });
+    }
+    function checkNetworkIdle(networkIdleWindowMs, aborted) {
+      return new Promise(resolve => {
+        let startTime = performance.now();
+        let timer = null;
+        let pollInterval = null;
+        function settle() {
+          /* istanbul ignore next: observer is only null on fallback path (itself ignored) */
+          if (observer) observer.disconnect();
+          /* istanbul ignore next: fallback polling path only used when PerformanceObserver is unavailable */
+          if (pollInterval) clearInterval(pollInterval);
+          resolve({
+            passed: true,
+            duration_ms: Math.round(performance.now() - startTime)
+          });
+        }
+        function resetIdleTimer() {
+          /* istanbul ignore next: timer is always set before any resource entry arrives */
+          if (timer) clearTimeout(timer);
+          timer = setTimeout(settle, networkIdleWindowMs);
+        }
+
+        /* istanbul ignore next: observer callback body only runs if a network resource loads during the idle window */
+        let observer = observePerformance('resource', entries => {
+          if (aborted.value) return;
+          if (entries.length > 0) resetIdleTimer();
+        });
+
+        /* istanbul ignore next: PerformanceObserver fallback only triggers in older browsers */
+        if (!observer) {
+          let lastCount = performance.getEntriesByType('resource').length;
+          pollInterval = setInterval(() => {
+            if (aborted.value) {
+              clearInterval(pollInterval);
+              return;
+            }
+            let count = performance.getEntriesByType('resource').length;
+            if (count !== lastCount) {
+              lastCount = count;
+              resetIdleTimer();
+            }
+          }, 50);
+        }
+
+        // Start the initial idle window.
+        timer = setTimeout(settle, networkIdleWindowMs);
+        aborted.onAbort(() => {
+          /* istanbul ignore next: observer is only null on fallback path (itself ignored) */
+          if (observer) observer.disconnect();
+          /* istanbul ignore next: pollInterval is only set on the fallback path */
+          if (pollInterval) clearInterval(pollInterval);
+          /* istanbul ignore next: timer is always set before abort can fire */
+          if (timer) clearTimeout(timer);
+        });
+      });
+    }
+    function checkFontReady(aborted) {
+      var _document$fonts;
+      let start = performance.now();
+      /* istanbul ignore next: cannot mock document.fonts API in browser tests */
+      if (!((_document$fonts = document.fonts) !== null && _document$fonts !== void 0 && _document$fonts.ready)) return Promise.resolve({
+        passed: true,
+        duration_ms: 0,
+        skipped: true
+      });
+      let fontTimer;
+      let resolveAbort;
+      // Resolve deterministically on abort so the race is settled by the orchestrator's timeout
+      // path and doesn't get retroactively flipped to { passed: true } when document.fonts.ready
+      // settles late. Important if we ever begin reading checks.font_ready post-timeout.
+      let abortPromise = new Promise(r => {
+        resolveAbort = r;
+      });
+      let result = Promise.race([document.fonts.ready.then(() => ({
+        passed: true,
+        duration_ms: Math.round(performance.now() - start)
+      })), /* istanbul ignore next: font timeout requires 5s delay, impractical in tests */
+      new Promise(r => {
+        fontTimer = setTimeout(() => r({
+          passed: false,
+          duration_ms: 5000,
+          timed_out: true
+        }), 5000);
+      }), abortPromise]);
+      /* istanbul ignore next: abort path not deterministically testable */
+      if (aborted) {
+        aborted.onAbort(() => {
+          if (fontTimer) clearTimeout(fontTimer);
+          resolveAbort({
+            passed: false,
+            duration_ms: Math.round(performance.now() - start),
+            aborted: true
+          });
+        });
+      }
+      return result;
+    }
+    function checkImageReady(aborted) {
+      return new Promise(resolve => {
+        let start = performance.now();
+        let vh = window.innerHeight;
+        function getIncomplete() {
+          let imgs = document.querySelectorAll('img');
+          let incomplete = [];
+          for (let img of imgs) {
+            let r = img.getBoundingClientRect();
+            /* istanbul ignore else: test images are always placed in the viewport with non-zero dimensions */
+            if (r.top < vh && r.bottom > 0 && r.width > 0 && r.height > 0) {
+              if (!img.complete || img.naturalWidth === 0) incomplete.push(img);
+            }
+          }
+          return incomplete;
+        }
+        let total = document.querySelectorAll('img').length;
+        let incStart = getIncomplete().length;
+        if (incStart === 0) {
+          resolve({
+            passed: true,
+            duration_ms: 0,
+            images_checked: total,
+            images_incomplete_at_start: 0
+          });
+          return;
+        }
+        let interval = setInterval(() => {
+          /* istanbul ignore next: abort clears the interval synchronously, defensive dead code in tests */
+          if (aborted.value) {
+            clearInterval(interval);
+            return;
+          }
+          /* istanbul ignore next: requires network latency — images load synchronously in tests with data: URLs */
+          if (getIncomplete().length === 0) {
+            clearInterval(interval);
+            resolve({
+              passed: true,
+              duration_ms: Math.round(performance.now() - start),
+              images_checked: total,
+              images_incomplete_at_start: incStart
+            });
+          }
+        }, 100);
+
+        /* istanbul ignore next: abort-on-timeout path; only fires when images never load in time */
+        aborted.onAbort(() => clearInterval(interval));
+      });
+    }
+    function checkJSIdle(idleWindowMs, aborted) {
+      // Three-tier JS idle detection — purely observational, no monkey-patching:
+      // Tier 1: Long Task API (PerformanceObserver) — detects main-thread tasks >50ms
+      // Tier 2: requestIdleCallback — confirms browser idle (fallback: setTimeout 200ms)
+      // Tier 3: Double-requestAnimationFrame — ensures render/paint cycle is complete
+      return new Promise(resolve => {
+        let start = performance.now();
+        let longTaskCount = 0;
+        let idleTimer = null;
+        let observer = null;
+        let settled = false;
+        let observing = false;
+
+        // Tier 1: Long Task API — reset idle timer on each observed long task.
+        // observePerformance returns null on older browsers; we degrade to the
+        // rIC/rAF-only path in that case.
+        /* istanbul ignore next: longtask callback fires only on CPU-heavy >50ms tasks, not reliable in tests */
+        observer = observePerformance('longtask', entries => {
+          if (!observing || settled || aborted.value) return;
+          for (let entry of entries) {
+            if (entry.entryType === 'longtask') {
+              longTaskCount++;
+              if (idleTimer) clearTimeout(idleTimer);
+              idleTimer = setTimeout(confirmIdle, idleWindowMs);
+            }
+          }
+        });
+        function cleanup() {
+          settled = true;
+          /* istanbul ignore next: defensive — observer is always set except when Long Task API fails (itself ignored) */
+          if (observer) observer.disconnect();
+          /* istanbul ignore next: defensive — idleTimer may be null between cleanup calls from multiple abort paths */
+          if (idleTimer) clearTimeout(idleTimer);
+        }
+        function done(idleCallbackUsed) {
+          /* istanbul ignore next: defensive — re-entry guard for race between done/cleanup/abort */
+          if (settled || aborted.value) return;
+          cleanup();
+          resolve({
+            passed: true,
+            duration_ms: Math.round(performance.now() - start),
+            long_tasks_observed: longTaskCount,
+            idle_callback_used: idleCallbackUsed
+          });
+        }
+
+        // Tier 2: requestIdleCallback confirmation (or fallback)
+        function confirmIdle() {
+          /* istanbul ignore next: defensive re-entry guard — confirmIdle can be scheduled multiple times */
+          if (settled || aborted.value) return;
+          /* istanbul ignore else: rIC is available in modern Chrome/Firefox — fallback is for older browsers */
+          if (typeof requestIdleCallback === 'function') {
+            /* istanbul ignore next: rIC timeout only fires if requestIdleCallback takes longer than idleWindowMs * 2 — cleared by rIC callback in normal runs */
+            let ricTimer = setTimeout(() => doubleRAF(false), idleWindowMs * 2);
+            requestIdleCallback(() => {
+              clearTimeout(ricTimer);
+              doubleRAF(true);
+            });
+            aborted.onAbort(() => clearTimeout(ricTimer));
+          } else {
+            let fallbackTimer = setTimeout(() => doubleRAF(false), 200);
+            aborted.onAbort(() => clearTimeout(fallbackTimer));
+          }
+        }
+
+        // Tier 3: Double-rAF render gate
+        function doubleRAF(usedRIC) {
+          /* istanbul ignore next: defensive re-entry guard — doubleRAF can be scheduled from multiple paths */
+          if (settled || aborted.value) return;
+          requestAnimationFrame(() => {
+            requestAnimationFrame(() => {
+              done(usedRIC);
+            });
+          });
+        }
+
+        // Start: skip first frame to avoid detecting Percy's own insertPercyDom() setup,
+        // then begin idle window
+        requestAnimationFrame(() => {
+          /* istanbul ignore next: abort only fires during timeout race, not on first rAF in tests */
+          if (aborted.value) return;
+          observing = true;
+          idleTimer = setTimeout(confirmIdle, idleWindowMs);
+        });
+        aborted.onAbort(() => cleanup());
+      });
+    }
+    function checkReadySelectors(selectors, aborted) {
+      /* istanbul ignore next: orchestrator only calls this when selectors.length > 0; defensive for direct callers */
+      if (!(selectors !== null && selectors !== void 0 && selectors.length)) return Promise.resolve({
+        passed: true,
+        duration_ms: 0,
+        selectors: []
+      });
+      return new Promise(resolve => {
+        let start = performance.now();
+        function check() {
+          for (let s of selectors) {
+            let el = resolveSelector(s);
+            if (!el) return false;
+            if (el.offsetParent === null && getComputedStyle(el).position !== 'fixed' && getComputedStyle(el).position !== 'sticky') return false;
+          }
+          return true;
+        }
+        if (check()) {
+          resolve({
+            passed: true,
+            duration_ms: 0,
+            selectors
+          });
+          return;
+        }
+        let interval = setInterval(() => {
+          /* istanbul ignore next: abort clears the interval synchronously, defensive dead code in tests */
+          if (aborted.value) {
+            clearInterval(interval);
+            return;
+          }
+          if (check()) {
+            clearInterval(interval);
+            resolve({
+              passed: true,
+              duration_ms: Math.round(performance.now() - start),
+              selectors
+            });
+          }
+        }, 100);
+        aborted.onAbort(() => clearInterval(interval));
+      });
+    }
+    function checkNotPresentSelectors(selectors, aborted) {
+      /* istanbul ignore next: orchestrator only calls this when selectors.length > 0; defensive for direct callers */
+      if (!(selectors !== null && selectors !== void 0 && selectors.length)) return Promise.resolve({
+        passed: true,
+        duration_ms: 0,
+        selectors: []
+      });
+      return new Promise(resolve => {
+        let start = performance.now();
+        function check() {
+          for (let s of selectors) {
+            if (resolveSelector(s)) return false;
+          }
+          return true;
+        }
+        if (check()) {
+          resolve({
+            passed: true,
+            duration_ms: 0,
+            selectors
+          });
+          return;
+        }
+        let interval = setInterval(() => {
+          /* istanbul ignore next: abort clears the interval synchronously, defensive dead code in tests */
+          if (aborted.value) {
+            clearInterval(interval);
+            return;
+          }
+          if (check()) {
+            clearInterval(interval);
+            resolve({
+              passed: true,
+              duration_ms: Math.round(performance.now() - start),
+              selectors
+            });
+          }
+        }, 100);
+
+        /* istanbul ignore next: abort-on-timeout path; only fires when the excluded selector never disappears */
+        aborted.onAbort(() => clearInterval(interval));
+      });
+    }
+
+    // --- Orchestrator ---
+
+    // Simple abort controller for browser context (no AbortController dependency).
+    // Exported for direct unit testing.
+    function createAbortHandle() {
+      let callbacks = [];
+      return {
+        value: false,
+        onAbort(fn) {
+          callbacks.push(fn);
+        },
+        abort() {
+          this.value = true;
+          callbacks.forEach(fn => fn());
+          callbacks = [];
+        }
+      };
+    }
+    async function runAllChecks(config, result, aborted) {
+      var _config$ready_selecto, _config$not_present_s;
+      let checks = [];
+      let expected = [];
+      // dom_stability: false is an explicit kill switch for the MutationObserver
+      // check. Use it on heavy SPA pages where the observer itself can drive
+      // CPU/memory pressure. Other checks (js_idle, image/font ready, selectors)
+      // continue to run, so capture is still gated — just not on raw mutation rate.
+      if (config.dom_stability !== false && config.stability_window_ms > 0) {
+        expected.push('dom_stability');
+        checks.push(checkDOMStability(config.stability_window_ms, aborted).then(r => {
+          result.checks.dom_stability = r;
+        }));
+      }
+      if (config.network_idle_window_ms > 0) {
+        expected.push('network_idle');
+        checks.push(checkNetworkIdle(config.network_idle_window_ms, aborted).then(r => {
+          result.checks.network_idle = r;
+        }));
+      }
+      if (config.font_ready !== false) {
+        expected.push('font_ready');
+        checks.push(checkFontReady(aborted).then(r => {
+          result.checks.font_ready = r;
+        }));
+      }
+      if (config.image_ready !== false) {
+        expected.push('image_ready');
+        checks.push(checkImageReady(aborted).then(r => {
+          result.checks.image_ready = r;
+        }));
+      }
+      if (config.js_idle !== false) {
+        expected.push('js_idle');
+        // Fall back to stability_window_ms if js_idle_window_ms is not set.
+        // All built-in presets set js_idle_window_ms, so this fallback only
+        // fires when a caller passes a custom config that predates the
+        // dedicated option — preserves backward compatibility.
+        /* istanbul ignore next: fallback only hit by pre-js_idle_window_ms configs; built-in presets always set it */
+        let jsIdleWindow = config.js_idle_window_ms ?? config.stability_window_ms;
+        checks.push(checkJSIdle(jsIdleWindow, aborted).then(r => {
+          result.checks.js_idle = r;
+        }));
+      }
+      if ((_config$ready_selecto = config.ready_selectors) !== null && _config$ready_selecto !== void 0 && _config$ready_selecto.length) {
+        expected.push('ready_selectors');
+        checks.push(checkReadySelectors(config.ready_selectors, aborted).then(r => {
+          result.checks.ready_selectors = r;
+        }));
+      }
+      if ((_config$not_present_s = config.not_present_selectors) !== null && _config$not_present_s !== void 0 && _config$not_present_s.length) {
+        expected.push('not_present_selectors');
+        checks.push(checkNotPresentSelectors(config.not_present_selectors, aborted).then(r => {
+          result.checks.not_present_selectors = r;
+        }));
+      }
+      result._expectedChecks = expected;
+      await Promise.all(checks);
+    }
+
+    // Normalize camelCase config keys (from .percy.yml / SDK options) to the
+    // snake_case keys used internally. Accepts either naming.
+    // Exported for direct unit testing.
+    function normalizeOptions(options = {}) {
+      return {
+        preset: options.preset,
+        stability_window_ms: options.stabilityWindowMs ?? options.stability_window_ms,
+        js_idle_window_ms: options.jsIdleWindowMs ?? options.js_idle_window_ms,
+        network_idle_window_ms: options.networkIdleWindowMs ?? options.network_idle_window_ms,
+        timeout_ms: options.timeoutMs ?? options.timeout_ms,
+        dom_stability: options.domStability ?? options.dom_stability,
+        image_ready: options.imageReady ?? options.image_ready,
+        font_ready: options.fontReady ?? options.font_ready,
+        js_idle: options.jsIdle ?? options.js_idle,
+        ready_selectors: options.readySelectors ?? options.ready_selectors,
+        not_present_selectors: options.notPresentSelectors ?? options.not_present_selectors,
+        max_timeout_ms: options.maxTimeoutMs ?? options.max_timeout_ms
+      };
+    }
+    async function waitForReady(options = {}) {
+      let presetName = options.preset || 'balanced';
+      if (presetName === 'disabled') return {
+        passed: true,
+        timed_out: false,
+        skipped: true,
+        checks: {}
+      };
+      let preset = PRESETS[presetName] || PRESETS.balanced;
+      // Normalize user options to snake_case, then merge. Only overrides
+      // where user explicitly provided a value (undefined keys don't overwrite).
+      let userOptions = normalizeOptions(options);
+      let config = {
+        ...preset
+      };
+      for (let key of Object.keys(userOptions)) {
+        if (userOptions[key] !== undefined) config[key] = userOptions[key];
+      }
+      let effectiveTimeout = config.max_timeout_ms ? Math.min(config.timeout_ms, config.max_timeout_ms) : config.timeout_ms;
+      let startTime = performance.now();
+      let result = {
+        passed: false,
+        timed_out: false,
+        preset: presetName,
+        checks: {}
+      };
+      let settled = false;
+      let aborted = createAbortHandle();
+      try {
+        await Promise.race([runAllChecks(config, result, aborted).then(() => {
+          settled = true;
+        }), new Promise(resolve => setTimeout(() => {
+          if (!settled) {
+            result.timed_out = true;
+            // Abort all running checks — clears intervals, disconnects observers
+            aborted.abort();
+          }
+          resolve();
+        }, effectiveTimeout))]);
+      } catch (error) {
+        /* istanbul ignore next: safety net for unexpected errors in readiness checks */
+        result.error = error.message || String(error);
+      }
+
+      // Mark any checks that didn't complete before timeout as failed.
+      // `_expectedChecks` is always set by runAllChecks, but coverage here
+      // depends on whether any expected check was skipped due to timeout.
+      /* istanbul ignore next: only falsy when the catch block above fires before runAllChecks sets _expectedChecks */
+      if (result._expectedChecks) {
+        for (let name of result._expectedChecks) {
+          if (!result.checks[name]) {
+            result.checks[name] = {
+              passed: false,
+              timed_out: true
+            };
+          }
+        }
+        delete result._expectedChecks;
+      }
+      result.total_duration_ms = Math.round(performance.now() - startTime);
+      result.passed = !result.timed_out && !result.error && Object.values(result.checks).every(c => c.passed);
+      return result;
+    }
+
     exports["default"] = serializeDOM;
     exports.loadAllSrcsetLinks = loadAllSrcsetLinks;
     exports.serialize = serializeDOM;
     exports.serializeDOM = serializeDOM;
+    exports.waitForReady = waitForReady;
     exports.waitForResize = waitForResize;
 
     Object.defineProperty(exports, '__esModule', { value: true });