From a3ae26de49fb4b2de2d1bbfa1312bdaa6220282a Mon Sep 17 00:00:00 2001
From: Pranav Zinzurde <pranav.z@browserstack.com>
Date: Tue, 25 Aug 2026 10:39:35 +0530
Subject: [PATCH 1/4] fix(dom): copy only pseudo-bearing members of a grouped
 selector (PER-10588)

The interactive-states auto-detect path copies every CSS rule whose
selector contains :focus/:focus-within/:hover/:active, rewrites the
pseudo to a data-percy-* attribute, and re-injects the copy. It copied
the rule's ENTIRE selector list, including members with no pseudo-class
at all. Those members already match from their own stylesheet, so the
copy adds nothing -- but it re-ranks them last in the cascade, and any
equal-specificity rule from later in the same sheet that was NOT copied
then loses purely on source order.

A customer's AEM site hit this hard. One 82-selector rule

  .dbk-basic-box ... [class*="__title"], ... ,
  .dbk-basic-box .dbk-basic-box__inner .dbk-readmore__trigger:hover
  { color: #004b6f }

carries exactly one :hover member, so all 82 selectors were re-injected.
The later same-sheet rule that paints those headings white on colored
cards (.dbk-basic-box--blue ... { color: #fff }, identical specificity,
no pseudo) lost the tie -- every heading on a blue/green/yellow card
rendered dark blue on a dark background, illegible.

PER-10077's per-sheet anchoring does not help here: both rules live in
the same stylesheet, so anchoring the copy after that sheet still places
it after the rule it beats. Verified against the customer's captured DOM
+ real CSS: on master the serialized page renders the headings
rgb(0,75,111); with this change it renders rgb(255,255,255), matching
the live page, while the :hover member is still copied.

Split the selector list on top-level commas only (commas inside
:is()/:not(), attribute values and quoted strings are not separators),
keep just the members that carry an interactive pseudo, and rewrite
those. The split doubles as the pseudo filter, so rules with a `:` but
no interactive pseudo (::before, :root, :nth-child) skip as before.

Side effect: the injected <style> shrank 284KB -> 199KB on this page.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 packages/dom/src/serialize-pseudo-classes.js  | 45 +++++++++++++++-
 .../dom/test/serialize-pseudo-classes.test.js | 52 +++++++++++++++++++
 2 files changed, 95 insertions(+), 2 deletions(-)

diff --git a/packages/dom/src/serialize-pseudo-classes.js b/packages/dom/src/serialize-pseudo-classes.js
index a06dde73a..1634242f5 100644
--- a/packages/dom/src/serialize-pseudo-classes.js
+++ b/packages/dom/src/serialize-pseudo-classes.js
@@ -79,6 +79,47 @@ function selectorContainsPseudo(selectorText, pseudoList) {
   });
 }
 
+function splitSelectorList(selectorText) {
+  const parts = [];
+  let depth = 0;
+  let quote = null;
+  let start = 0;
+
+  for (let i = 0; i < selectorText.length; i++) {
+    const char = selectorText[i];
+
+    if (quote) {
+      if (char === '\\') i++;
+      else if (char === quote) quote = null;
+      continue;
+    }
+
+    if (char === '"' || char === "'") quote = char;
+    else if (char === '(' || char === '[') depth++;
+    else if (char === ')' || char === ']') depth--;
+    else if (char === ',' && depth === 0) {
+      parts.push(selectorText.slice(start, i));
+      start = i + 1;
+    }
+  }
+
+  parts.push(selectorText.slice(start));
+  return parts;
+}
+
+function rewritePseudoSelectorList(selectorText, pseudoList) {
+  const pseudoParts = [];
+
+  for (const part of splitSelectorList(selectorText)) {
+    const trimmed = part.trim();
+    if (trimmed && selectorContainsPseudo(trimmed, pseudoList)) {
+      pseudoParts.push(rewritePseudoSelector(trimmed));
+    }
+  }
+
+  return pseudoParts.length ? pseudoParts.join(', ') : null;
+}
+
 export function rewritePseudoSelector(selectorText) {
   let out = selectorText;
   for (const [pseudo, re] of PSEUDO_RES) out = out.replace(re, PSEUDO_TO_ATTR[pseudo]);
@@ -426,9 +467,9 @@ function extractPseudoClassRules(ctx) {
       // interactive pseudo. Skips most rules on most stylesheets without
       // touching the regex bank.
       if (!rule.selectorText.includes(':')) continue;
-      if (!selectorContainsPseudo(rule.selectorText, ALL_INTERACTIVE_PSEUDO)) continue;
 
-      const rewrittenSelector = rewritePseudoSelector(rule.selectorText);
+      const rewrittenSelector = rewritePseudoSelectorList(rule.selectorText, ALL_INTERACTIVE_PSEUDO);
+      if (!rewrittenSelector) continue;
 
       const cssText = `${rewrittenSelector} { ${rule.style.cssText} }`;
       const wrapped = rule.wrapper ? `${rule.wrapper} { ${cssText} }` : cssText;
diff --git a/packages/dom/test/serialize-pseudo-classes.test.js b/packages/dom/test/serialize-pseudo-classes.test.js
index d8240214f..445c5504a 100644
--- a/packages/dom/test/serialize-pseudo-classes.test.js
+++ b/packages/dom/test/serialize-pseudo-classes.test.js
@@ -1499,6 +1499,58 @@ describe('serialize-pseudo-classes', () => {
     });
   });
 
+  describe('grouped selector lists (PER-10588)', () => {
+    function serializeWith(styleText, bodyHTML) {
+      withExample('<style>' + styleText + '</style>' + bodyHTML);
+      ctx = {
+        dom: document,
+        clone: document.implementation.createHTMLDocument('Clone'),
+        warnings: new Set(),
+        cache: new Map(),
+        resources: new Set(),
+        hints: new Set(),
+        shadowRootElements: []
+      };
+      // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
+      ctx.clone.body.innerHTML = document.body.innerHTML;
+      markPseudoClassElements(ctx, null);
+      // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
+      ctx.clone.body.innerHTML = ctx.dom.body.innerHTML;
+      serializePseudoClasses(ctx);
+      let el = ctx.clone.querySelector('style[data-percy-interactive-states]');
+      return el ? el.textContent : null;
+    }
+
+    it('copies only the pseudo-bearing members of a grouped selector', () => {
+      let css = serializeWith(
+        '.card .title, .card .trigger:hover { color: rgb(0, 75, 111) }' +
+        '.card--blue .title { color: rgb(255, 255, 255) }',
+        '<div class="card card--blue"><span class="title">t</span>' +
+        '<a class="trigger" href="#">go</a></div>'
+      );
+      expect(css).toContain('.card .trigger[data-percy-hover]');
+      expect(css).not.toContain('.card .title');
+    });
+
+    it('does not split commas nested in :is()/:not() or attribute values', () => {
+      let css = serializeWith(
+        ':is(.a, .b) .lnk:focus, [data-k="x,y"] .lnk:focus { color: red }',
+        '<div class="a"><a class="lnk" href="#">a</a></div>'
+      );
+      expect(css).toContain(':is(.a, .b) .lnk[data-percy-focus]');
+      expect(css).toContain('[data-k="x,y"] .lnk[data-percy-focus]');
+    });
+
+    it('keeps every member when they all carry a pseudo', () => {
+      let css = serializeWith(
+        '.p:focus, .q:focus { color: red }',
+        '<div><span class="p">p</span><span class="q">q</span></div>'
+      );
+      expect(css).toContain('.p[data-percy-focus]');
+      expect(css).toContain('.q[data-percy-focus]');
+    });
+  });
+
   describe('walkCSSRules charset / import / etc with no selectorText', () => {
     it('skips rules that have neither nested cssRules nor a selector', () => {
       // @charset has no cssRules and no selectorText — exercises the

From 2914b285aead4f3aaaf8e0ce71916bb226d1b3dd Mon Sep 17 00:00:00 2001
From: Pranav Zinzurde <pranav.z@browserstack.com>
Date: Tue, 25 Aug 2026 21:12:44 +0530
Subject: [PATCH 2/4] feat(dom): make interactive-state serialization opt-in,
 default off (PER-10588)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The interactive-state auto-detect path has shipped four regressions in
three months, all of the same shape: it copies customer CSS, rewrites a
pseudo-class to a data-percy-* attribute, and re-injects the copy, which
reorders the cascade for rules nobody asked it to touch.

  PER-9775  (#2324) nested selectors leaked page-wide via a bare `&`
  PER-9836         pseudoClassEnabledElements froze layout/transitions
  PER-10077 (#2342) :checked/:disabled copies recolored Angular Material
                    buttons across 70+ snapshots
  PER-10588         one :hover member of an 82-selector rule repainted
                    every colored-card heading on an AEM site

Adoption does not justify that risk. On the PER-10588 customer's captured
DOM the injected block was 289KB with 629 [data-percy-hover] selectors and
ZERO data-percy-* attributes stamped on any element — nothing it emitted
could match. The feature contributed no correct behavior and all of the
breakage.

Gate both paths behind a new snapshot option,
enablePseudoClassSerialization (default false; snake_case
enable_pseudo_class_serialization also accepted). Configuring
pseudoClassEnabledElements is itself an opt-in and turns the feature on
without the flag, so no existing opt-in user changes behavior. The
predicate is computed once in serializeDOM and carried as
ctx.pseudoClassSerialization — one auditable switch, not a check per
call site. No pseudo-class logic is removed.

Deliberately NOT gated, both verified against percy-renderer:

  - Open-popover stamping. src/script/popover-element-helper.js reopens
    [popover][data-percy-popover-open]; without the stamp an open popover
    renders hidden behind the UA [popover]:not(:popover-open) rule.
  - Custom element :state() rewriting. serialize-custom-states rewrites
    <style> text in place, so it cannot reorder the cascade.

The renderer consumes only shadow-host, injected, popover-open,
dialog-modal, scrolltop/left and freeze-animation-logs attributes — none
of the gated focus/hover/active stamps — so nothing downstream regresses.

Verified end to end on the PER-10588 customer's real page and CSS:

  master          714,774 bytes, injected block, headings rgb(0,75,111)
  gated (default) 429,635 bytes, no block,       headings white
  gated + flag    629,882 bytes, injected block, headings white

@percy/dom is regression-clean against baseline (466 pass vs 459, same 40
pre-existing focus failures on a headless browser without window focus),
plus 7 new specs covering default-off, both opt-in routes, the snake_case
alias, and the two carve-outs.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 packages/core/src/config.js                   |   5 +
 packages/core/src/discovery.js                |   1 +
 packages/core/src/page.js                     |   5 +-
 packages/core/test/percy.test.js              |   2 +-
 packages/dom/src/serialize-dom.js             |   8 +-
 packages/dom/src/serialize-pseudo-classes.js  |  21 ++--
 packages/dom/test/serialize-dom.test.js       |  76 ++++++++++++-
 .../dom/test/serialize-pseudo-classes.test.js | 101 ++++++++++++------
 8 files changed, 173 insertions(+), 46 deletions(-)

diff --git a/packages/core/src/config.js b/packages/core/src/config.js
index 0fcf5abf9..1835b0f9b 100644
--- a/packages/core/src/config.js
+++ b/packages/core/src/config.js
@@ -337,6 +337,10 @@ export const configSchema = {
           minLength: 1
         }
       },
+      enablePseudoClassSerialization: {
+        type: 'boolean',
+        default: false
+      },
       pseudoClassEnabledElements: {
         type: 'object',
         additionalProperties: false,
@@ -571,6 +575,7 @@ export const snapshotSchema = {
         ignoreCanvasSerializationErrors: { $ref: '/config/snapshot#/properties/ignoreCanvasSerializationErrors' },
         ignoreStyleSheetSerializationErrors: { $ref: '/config/snapshot#/properties/ignoreStyleSheetSerializationErrors' },
         ignoreIframeSelectors: { $ref: '/config/snapshot#/properties/ignoreIframeSelectors' },
+        enablePseudoClassSerialization: { $ref: '/config/snapshot#/properties/enablePseudoClassSerialization' },
         pseudoClassEnabledElements: { $ref: '/config/snapshot#/properties/pseudoClassEnabledElements' },
         discovery: {
           type: 'object',
diff --git a/packages/core/src/discovery.js b/packages/core/src/discovery.js
index 5a63c8011..ac030d9bc 100644
--- a/packages/core/src/discovery.js
+++ b/packages/core/src/discovery.js
@@ -80,6 +80,7 @@ function debugSnapshotOptions(snapshot) {
   debugProp(snapshot, 'ignoreCanvasSerializationErrors');
   debugProp(snapshot, 'ignoreStyleSheetSerializationErrors');
   debugProp(snapshot, 'pseudoClassEnabledElements', JSON.stringify);
+  debugProp(snapshot, 'enablePseudoClassSerialization');
   debugProp(snapshot, 'discovery.autoConfigureAllowedHostnames');
 
   if (Array.isArray(snapshot.domSnapshot)) {
diff --git a/packages/core/src/page.js b/packages/core/src/page.js
index 1a5db7aac..97f8e7a59 100644
--- a/packages/core/src/page.js
+++ b/packages/core/src/page.js
@@ -249,7 +249,7 @@ export class Page {
     execute,
     ...snapshot
   }) {
-    let { name, width, enableJavaScript, disableShadowDOM, forceShadowAsLightDOM, domTransformation, reshuffleInvalidTags, ignoreCanvasSerializationErrors, ignoreStyleSheetSerializationErrors, ignoreIframeSelectors, pseudoClassEnabledElements } = snapshot;
+    let { name, width, enableJavaScript, disableShadowDOM, forceShadowAsLightDOM, domTransformation, reshuffleInvalidTags, ignoreCanvasSerializationErrors, ignoreStyleSheetSerializationErrors, ignoreIframeSelectors, pseudoClassEnabledElements, enablePseudoClassSerialization } = snapshot;
     this.log.debug(`Taking snapshot: ${name}${width ? ` @${width}px` : ''}`, this.meta);
 
     // wait for any specified timeout
@@ -329,7 +329,8 @@ export class Page {
       ignoreCanvasSerializationErrors,
       ignoreStyleSheetSerializationErrors,
       ignoreIframeSelectors,
-      pseudoClassEnabledElements
+      pseudoClassEnabledElements,
+      enablePseudoClassSerialization
     });
 
     // Attach readiness diagnostics onto the captured DOM snapshot so the backend/UI can surface
diff --git a/packages/core/test/percy.test.js b/packages/core/test/percy.test.js
index 992d1b0ab..7da647883 100644
--- a/packages/core/test/percy.test.js
+++ b/packages/core/test/percy.test.js
@@ -116,7 +116,7 @@ describe('Percy', () => {
     });
 
     // expect required arguments are passed to PercyDOM.serialize
-    expect(evalSpy.calls.allArgs()[4]).toEqual(jasmine.arrayContaining([jasmine.anything(), { enableJavaScript: undefined, disableShadowDOM: true, domTransformation: undefined, reshuffleInvalidTags: undefined, ignoreCanvasSerializationErrors: undefined, ignoreStyleSheetSerializationErrors: undefined, ignoreIframeSelectors: undefined, forceShadowAsLightDOM: undefined, pseudoClassEnabledElements: undefined }]));
+    expect(evalSpy.calls.allArgs()[4]).toEqual(jasmine.arrayContaining([jasmine.anything(), { enableJavaScript: undefined, disableShadowDOM: true, domTransformation: undefined, reshuffleInvalidTags: undefined, ignoreCanvasSerializationErrors: undefined, ignoreStyleSheetSerializationErrors: undefined, ignoreIframeSelectors: undefined, forceShadowAsLightDOM: undefined, pseudoClassEnabledElements: undefined, enablePseudoClassSerialization: undefined }]));
 
     expect(snapshot.url).toEqual('http://localhost:8000/');
     expect(snapshot.domSnapshot).toEqual(jasmine.objectContaining({
diff --git a/packages/dom/src/serialize-dom.js b/packages/dom/src/serialize-dom.js
index 1d025b505..c9cb0bb6c 100644
--- a/packages/dom/src/serialize-dom.js
+++ b/packages/dom/src/serialize-dom.js
@@ -100,9 +100,12 @@ export function serializeDOM(options) {
     ignoreIframeSelectors = options?.ignore_iframe_selectors,
     maxIframeDepth = options?.max_iframe_depth,
     iframeDepth = options?.iframe_depth ?? 0,
-    pseudoClassEnabledElements = options?.pseudo_class_enabled_elements
+    pseudoClassEnabledElements = options?.pseudo_class_enabled_elements,
+    enablePseudoClassSerialization = options?.enable_pseudo_class_serialization
   } = options || {};
 
+  const pseudoClassSerialization = !!(enablePseudoClassSerialization || pseudoClassEnabledElements);
+
   // keep certain records throughout serialization
   let ctx = {
     resources: new Set(),
@@ -118,7 +121,8 @@ export function serializeDOM(options) {
     ignoreIframeSelectors,
     maxIframeDepth,
     iframeDepth,
-    pseudoClassEnabledElements
+    pseudoClassEnabledElements,
+    pseudoClassSerialization
   };
 
   ctx.dom = dom;
diff --git a/packages/dom/src/serialize-pseudo-classes.js b/packages/dom/src/serialize-pseudo-classes.js
index 1634242f5..06571965f 100644
--- a/packages/dom/src/serialize-pseudo-classes.js
+++ b/packages/dom/src/serialize-pseudo-classes.js
@@ -2,7 +2,14 @@
 
 // Serializes pseudo-class state into Percy's clone via two paths:
 //
-//   1. Auto-detect path (every snapshot). For :focus / :focus-within we
+// Both paths below are gated on ctx.pseudoClassSerialization, which is off
+// unless the snapshot sets enablePseudoClassSerialization or configures
+// pseudoClassEnabledElements. Open-popover stamping and custom element
+// :state() rewriting are NOT gated — the renderer requires
+// data-percy-popover-open, and :state() is rewritten in place so it cannot
+// reorder the cascade.
+//
+//   1. Auto-detect path (when enabled). For :focus / :focus-within we
 //      stamp the live DOM with the corresponding data-percy-* attribute
 //      and rewrite matching CSS rules to use those attribute selectors.
 //      :focus-within stamps the focused element's ancestor chain across
@@ -329,8 +336,9 @@ export function getElementsToProcess(ctx, config, markWithId = false) {
 // the data-attributes are copied through to the clone via cloneNode.
 export function markPseudoClassElements(ctx, config) {
   ctx._liveMutations = [];
-  markInteractiveStates(ctx);
   markOpenPopovers(ctx);
+  if (!ctx.pseudoClassSerialization) return;
+  markInteractiveStates(ctx);
   if (config) getElementsToProcess(ctx, config, true);
 }
 
@@ -531,10 +539,11 @@ function injectAtSheetPosition(scopeRoot, sheet, styleElement, fallbackTarget) {
 }
 
 export function serializePseudoClasses(ctx) {
-  // Auto-detect path runs unconditionally so `:focus`/`:focus-within`
-  // rules are rewritten regardless of whether the user configured a
-  // pseudoClassEnabledElements list (and regardless of whether that list
-  // matched anything on this page).
+  if (!ctx.pseudoClassSerialization) return;
+
+  // Auto-detect path rewrites `:focus`/`:focus-within` rules whether or not
+  // a pseudoClassEnabledElements list was configured (and regardless of
+  // whether that list matched anything on this page).
   extractPseudoClassRules(ctx);
 
   if (!ctx.pseudoClassEnabledElements) return;
diff --git a/packages/dom/test/serialize-dom.test.js b/packages/dom/test/serialize-dom.test.js
index f30697df2..2c322f56e 100644
--- a/packages/dom/test/serialize-dom.test.js
+++ b/packages/dom/test/serialize-dom.test.js
@@ -799,7 +799,7 @@ describe('serializeDOM', () => {
         '<button class="cbtn later">go</button>',
         { withShadow: false }
       );
-      let html = serializeDOM().html;
+      let html = serializeDOM({ enablePseudoClassSerialization: true }).html;
       let sourceIdx = html.indexOf('.cbtn:hover');
       let copyIdx = html.indexOf('[data-percy-hover]');
       let laterIdx = html.indexOf('.cbtn.later');
@@ -809,6 +809,80 @@ describe('serializeDOM', () => {
     });
   });
 
+  describe('interactive-state serialization opt-in gate (PER-10588)', () => {
+    const HOVER_PAGE =
+      '<style>.gbtn:hover { color: red }</style>' +
+      '<button id="gbtn" class="gbtn">go</button>';
+
+    it('is off by default — no rewritten copy and no state stamps', () => {
+      withExample(HOVER_PAGE, { withShadow: false });
+      let html = serializeDOM().html;
+      expect(html).not.toContain('data-percy-interactive-states');
+      expect(html).not.toContain('[data-percy-hover]');
+      expect(html).not.toContain('data-percy-focus');
+    });
+
+    it('is on when enablePseudoClassSerialization is set', () => {
+      withExample(HOVER_PAGE, { withShadow: false });
+      let html = serializeDOM({ enablePseudoClassSerialization: true }).html;
+      expect(html).toContain('data-percy-interactive-states');
+      expect(html).toContain('[data-percy-hover]');
+    });
+
+    it('accepts the snake_case option name', () => {
+      withExample(HOVER_PAGE, { withShadow: false });
+      let html = serializeDOM({ enable_pseudo_class_serialization: true }).html;
+      expect(html).toContain('[data-percy-hover]');
+    });
+
+    it('is on when pseudoClassEnabledElements is configured, without the flag', () => {
+      withExample(HOVER_PAGE, { withShadow: false });
+      let html = serializeDOM({ pseudoClassEnabledElements: { id: ['gbtn'] } }).html;
+      expect(html).toContain('[data-percy-hover]');
+      expect(html).toContain('data-percy-pseudo-element-id');
+    });
+
+    it('stays on for configured elements even when the flag is materialized false', () => {
+      withExample(HOVER_PAGE, { withShadow: false });
+      let html = serializeDOM({
+        enablePseudoClassSerialization: false,
+        pseudoClassEnabledElements: { id: ['gbtn'] }
+      }).html;
+      expect(html).toContain('[data-percy-hover]');
+    });
+
+    it('still stamps open popovers while disabled — the renderer requires it', () => {
+      withExample(
+        '<div id="gpop" popover="manual">hi</div>',
+        { withShadow: false }
+      );
+      let popover = document.getElementById('gpop');
+      if (typeof popover.showPopover !== 'function') return;
+      popover.showPopover();
+
+      let html = serializeDOM().html;
+      expect(html).not.toContain('data-percy-interactive-states');
+      expect(html).toContain('data-percy-popover-open');
+    });
+
+    it('still rewrites custom element :state() while disabled', () => {
+      withExample(
+        '<style>.gstate:state(checked) { color: red }</style><div class="gstate"></div>',
+        { withShadow: false }
+      );
+      let html = serializeDOM().html;
+      expect(html).not.toContain('data-percy-interactive-states');
+      expect(html).toContain('[data-percy-custom-state~="checked"]');
+    });
+
+    it('leaves no data-percy-* state attributes on the live DOM either way', () => {
+      withExample(HOVER_PAGE, { withShadow: false });
+      serializeDOM({ enablePseudoClassSerialization: true });
+      expect(document.querySelector('[data-percy-hover]')).toBeNull();
+      expect(document.querySelector('[data-percy-focus]')).toBeNull();
+    });
+  });
+
   describe('stylesheet <link> stamping (PER-10077 cascade anchoring)', () => {
     it('stamps only stylesheet <link>s with a percy element id', () => {
       // The pseudo-class serializer anchors its rewritten rules after a sheet's
diff --git a/packages/dom/test/serialize-pseudo-classes.test.js b/packages/dom/test/serialize-pseudo-classes.test.js
index 445c5504a..82a3780e8 100644
--- a/packages/dom/test/serialize-pseudo-classes.test.js
+++ b/packages/dom/test/serialize-pseudo-classes.test.js
@@ -26,7 +26,8 @@ describe('serialize-pseudo-classes', () => {
   beforeEach(() => {
     ctx = {
       dom: document,
-      warnings: new Set()
+      warnings: new Set(),
+      pseudoClassSerialization: true
     };
     withExample('<div id="foo" style="color: red;"></div><div class="bar"></div><div id="baz"></div>');
     ctx.clone = document.implementation.createHTMLDocument('Clone');
@@ -179,7 +180,7 @@ describe('serialize-pseudo-classes', () => {
       // We'll temporarily patch getElementsToProcess to expose markWithId
       withExample('<div id="foo"></div>');
       const el = document.getElementById('foo');
-      const ctx2 = { dom: document, warnings: new Set() };
+      const ctx2 = { dom: document, warnings: new Set(), pseudoClassSerialization: true };
       getElementsToProcess(ctx2, { id: ['foo'] });
       expect(el.hasAttribute('data-percy-pseudo-element-id')).toBe(false);
     });
@@ -191,7 +192,7 @@ describe('serialize-pseudo-classes', () => {
     });
 
     it('throws an error if config is null', () => {
-      const ctx2 = { dom: document, warnings: new Set() };
+      const ctx2 = { dom: document, warnings: new Set(), pseudoClassSerialization: true };
       expect(() => {
         getElementsToProcess(ctx2, null);
       }).toThrow();
@@ -476,7 +477,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -531,7 +533,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -562,7 +565,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -679,7 +683,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -709,6 +714,7 @@ describe('serialize-pseudo-classes', () => {
         resources: new Set(),
         hints: new Set(),
         shadowRootElements: [],
+        pseudoClassSerialization: true,
         pseudoClassEnabledElements: { id: ['has-test'] }
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
@@ -738,7 +744,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -763,7 +770,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -793,7 +801,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -836,7 +845,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // Do NOT copy DOM to clone - so the clone element won't be found
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
@@ -873,7 +883,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -908,7 +919,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = '<div>test</div>';
@@ -930,7 +942,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -956,7 +969,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -976,7 +990,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -1004,7 +1019,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // Blur any active element to ensure nothing is focused
       document.activeElement?.blur();
@@ -1025,7 +1041,7 @@ describe('serialize-pseudo-classes', () => {
       let el = document.getElementById('has-percy-id');
       el.setAttribute('data-percy-element-id', '_focus_branch_test');
       withMockedFocus(el, () => {
-        ctx = { dom: document, warnings: new Set() };
+        ctx = { dom: document, warnings: new Set(), pseudoClassSerialization: true };
         markPseudoClassElements(ctx, { id: ['has-percy-id'] });
       });
       expect(el.hasAttribute('data-percy-focus')).toBe(true);
@@ -1078,7 +1094,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -1135,7 +1152,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -1179,7 +1197,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -1234,7 +1253,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -1281,7 +1301,7 @@ describe('serialize-pseudo-classes', () => {
       Object.defineProperty(shadow, 'activeElement', { get: () => deepInput, configurable: true });
       Object.defineProperty(document, 'activeElement', { get: () => host, configurable: true });
       try {
-        ctx = { dom: document, warnings: new Set() };
+        ctx = { dom: document, warnings: new Set(), pseudoClassSerialization: true };
         markPseudoClassElements(ctx, null);
         // The traversal should reach deepInput and stamp [data-percy-focus]
         expect(deepInput.hasAttribute('data-percy-focus')).toBe(true);
@@ -1325,7 +1345,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = '<div id="sh-style-host" data-percy-shadow-host data-percy-element-id="_sh_style_1"></div>';
@@ -1371,7 +1392,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // Clone host exists but WITHOUT a shadow root attached
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
@@ -1447,7 +1469,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -1485,6 +1508,7 @@ describe('serialize-pseudo-classes', () => {
         resources: new Set(),
         hints: new Set(),
         shadowRootElements: [],
+        pseudoClassSerialization: true,
         pseudoClassEnabledElements: { id: ['cm3-btn'] }
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
@@ -1509,7 +1533,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -1566,7 +1591,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -1595,7 +1621,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -1631,7 +1658,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = ctx.dom.body.innerHTML;
@@ -1661,7 +1689,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // Clone intentionally does NOT mirror the source <style>, so no anchor.
       markPseudoClassElements(ctx, null);
@@ -1694,7 +1723,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -1742,6 +1772,7 @@ describe('serialize-pseudo-classes', () => {
         resources: new Set(),
         hints: new Set(),
         shadowRootElements: [],
+        pseudoClassSerialization: true,
         pseudoClassEnabledElements: { id: ['dv'] }
       };
       expect(() => serializePseudoClasses(ctx)).not.toThrow();
@@ -1767,7 +1798,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;
@@ -1927,7 +1959,8 @@ describe('serialize-pseudo-classes', () => {
         cache: new Map(),
         resources: new Set(),
         hints: new Set(),
-        shadowRootElements: []
+        shadowRootElements: [],
+        pseudoClassSerialization: true
       };
       // nosemgrep: javascript.browser.security.insecure-document-method.insecure-document-method
       ctx.clone.body.innerHTML = document.body.innerHTML;

From e6d5d30af64fd2400b7dbdf78090c91f241837ed Mon Sep 17 00:00:00 2001
From: Pranav Zinzurde <pranav.z@browserstack.com>
Date: Thu, 27 Aug 2026 15:31:45 +0530
Subject: [PATCH 3/4] fix(dom): propagate the pseudo-class gate into iframe
 serialization (PER-10588)

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 packages/dom/src/serialize-frames.js       |  6 ++-
 packages/dom/test/serialize-frames.test.js | 53 ++++++++++++++++++++++
 2 files changed, 57 insertions(+), 2 deletions(-)

diff --git a/packages/dom/src/serialize-frames.js b/packages/dom/src/serialize-frames.js
index 8e7114f15..595aaf15c 100644
--- a/packages/dom/src/serialize-frames.js
+++ b/packages/dom/src/serialize-frames.js
@@ -67,7 +67,7 @@ function clampIframeDepth(raw) {
 // 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).
-export function serializeFrames({ dom, clone, warnings, resources, enableJavaScript, disableShadowDOM, ignoreIframeSelectors, forceShadowAsLightDOM, maxIframeDepth, iframeDepth = 0 }) {
+export function serializeFrames({ dom, clone, warnings, resources, enableJavaScript, disableShadowDOM, ignoreIframeSelectors, forceShadowAsLightDOM, maxIframeDepth, iframeDepth = 0, pseudoClassEnabledElements, pseudoClassSerialization }) {
   maxIframeDepth = clampIframeDepth(maxIframeDepth);
 
   for (let frame of dom.querySelectorAll('iframe')) {
@@ -131,7 +131,9 @@ export function serializeFrames({ dom, clone, warnings, resources, enableJavaScr
         forceShadowAsLightDOM,
         ignoreIframeSelectors,
         maxIframeDepth,
-        iframeDepth: iframeDepth + 1
+        iframeDepth: iframeDepth + 1,
+        pseudoClassEnabledElements,
+        enablePseudoClassSerialization: pseudoClassSerialization
       });
 
       // append serialized warnings and resources
diff --git a/packages/dom/test/serialize-frames.test.js b/packages/dom/test/serialize-frames.test.js
index e9b27c375..8ec0e902f 100644
--- a/packages/dom/test/serialize-frames.test.js
+++ b/packages/dom/test/serialize-frames.test.js
@@ -554,3 +554,56 @@ describe('serializeFrames', () => {
     });
   });
 });
+
+describe('serializeFrames - pseudo-class option propagation', () => {
+  let $container;
+
+  const srcdocOfFrame = (options) => {
+    let $ = parseDOM(serializeDOM(options).html, 'plain');
+    let el = $('#frame-pseudo')[0];
+    let raw = el?.getAttribute('srcdoc') || '';
+    let decoder = document.createElement('textarea');
+    decoder.innerHTML = raw;
+    return decoder.value;
+  };
+
+  beforeEach(async () => {
+    $container = document.createElement('div');
+    $container.id = 'pseudo-frame-host';
+    $container.innerHTML = '<iframe id="frame-pseudo" srcdoc="<style>.ibtn:hover { color: rgb(1, 2, 3); }</style><div class=\'ibtn\'>x</div>"></iframe>';
+    document.body.appendChild($container);
+
+    await when(() => {
+      let $frame = $container.querySelector('#frame-pseudo');
+      assert($frame?.contentDocument?.querySelector('.ibtn'), '#frame-pseudo did not load in time');
+      return $frame;
+    }, 5000);
+  }, 0);
+
+  afterEach(() => {
+    $container?.remove();
+    $container = null;
+  });
+
+  it('does not serialize iframe interactive states by default', () => {
+    let inner = srcdocOfFrame();
+    expect(inner).not.toContain('data-percy-interactive-states');
+    expect(inner).not.toContain('data-percy-hover');
+  });
+
+  it('serializes iframe interactive states when the flag is enabled', () => {
+    let inner = srcdocOfFrame({ enablePseudoClassSerialization: true });
+    expect(inner).toContain('data-percy-interactive-states');
+    expect(inner).toContain('[data-percy-hover]');
+  });
+
+  it('serializes iframe interactive states via the snake_case alias', () => {
+    let inner = srcdocOfFrame({ enable_pseudo_class_serialization: true });
+    expect(inner).toContain('[data-percy-hover]');
+  });
+
+  it('serializes iframe interactive states when pseudoClassEnabledElements is configured', () => {
+    let inner = srcdocOfFrame({ pseudoClassEnabledElements: { selectors: ['.ibtn'] } });
+    expect(inner).toContain('[data-percy-hover]');
+  });
+});

From 60de756fcdb083742d74b9f8bdacf09fba073907 Mon Sep 17 00:00:00 2001
From: Pranav Zinzurde <pranav.z@browserstack.com>
Date: Thu, 27 Aug 2026 16:18:18 +0530
Subject: [PATCH 4/4] test(core): add enablePseudoClassSerialization to the
 snapshot defaults assertion (PER-10588)

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 packages/core/test/percy.test.js | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/core/test/percy.test.js b/packages/core/test/percy.test.js
index 7da647883..bb62dc6f4 100644
--- a/packages/core/test/percy.test.js
+++ b/packages/core/test/percy.test.js
@@ -89,7 +89,8 @@ describe('Percy', () => {
       ignoreCanvasSerializationErrors: false,
       ignoreStyleSheetSerializationErrors: false,
       forceShadowAsLightDOM: false,
-      ignoreIframeSelectors: []
+      ignoreIframeSelectors: [],
+      enablePseudoClassSerialization: false
     });
   });