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

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 {
@@ -1026,7 +1523,6 @@
 
     // Serializes a document and returns the resulting DOM string.
     function serializeDOM(options) {
-      var _ctx$clone$body;
       let {
         dom = document,
         // allow snake_case or camelCase
@@ -1038,6 +1534,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 +1552,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percy/dom",
-  "version": "1.31.14-beta.2",
+  "version": "1.31.14-beta.3",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -35,5 +35,5 @@
   "devDependencies": {
     "interactor.js": "^2.0.0-beta.10"
   },
-  "gitHead": "e4fce73023453b77cdef50aac1a9bd5eb70cd01a"
+  "gitHead": "a17d4a1453c6bef282fd3da38082b670e125a5be"
 }