From 0a4710f678f3f771035790c53abc5fa667bd90ef Mon Sep 17 00:00:00 2001
From: Pranav Zinzurde <pranav.z@browserstack.com>
Date: Thu, 27 Aug 2026 20:25:49 +0530
Subject: [PATCH] fix(dom): stop stamping live stylesheet <link>s, duplicating
 them (PER-10610)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reported as percy/cli#2398: since @percy/cli 1.32.6, some archived DOM
snapshots contain the same stylesheet <link> twice, changing the effective
CSS source order so unintended styles win. 1.32.5 emits it once.

packages/dom changed in exactly one functional commit across 1.32.5 →
1.32.7 — 5c39872a (PR #2342, PER-10077) — and nothing in packages/dom/src
changed at all in 1.32.7, which matches the reporter seeing it in both.
That commit added the only write @percy/dom has ever made to a live
stylesheet <link>:

  prepare-dom.js markElement() stamps data-percy-element-id on
  <link rel=stylesheet> so injectAtSheetPosition can find the sheet's
  clone and anchor its rewritten interactive-state rules there.

Nothing in the package emits a second <link> for an http(s) sheet — every
<link>-creating site was audited (serialize-cssom's blob and adopted
branches only, both pre-1.32.6 and neither matching the report). The
duplicate is created by the page itself: unlike the pseudo-class markers,
which stampOnce records on ctx._liveMutations for
cleanupInteractiveStateMarkers to undo, this setAttribute is raw and never
cleaned off. Head-managing frameworks (next/head's head-manager,
react-helmet, vue-meta) reconcile <head> children with isEqualNode(), so a
managed <link> carrying an unexpected attribute compares unequal and the
manager re-inserts its own copy at the end of <head> — a duplicate href in
a new cascade position. Because markElement runs inside the synchronous
clone walk, the reconcile lands after that snapshot: the first is clean and
every later one carries the duplicate, which is why only *some* archived
DOMs showed it.

Fix the cause rather than the symptom: don't touch the live page at all.
cloneNodeAndShadow now records a live→clone WeakMap (ctx.styleSheetClones)
for every <style>/<link> as it clones them, and injectAtSheetPosition
resolves its anchor by node identity through that map. PER-10077's cascade
anchoring is fully preserved — verified by spec — and no stylesheet <link>
is mutated or stamped, on the live page or in the output. serialize-cssom
repoints the map when it rebuilds a <style> clone in place, so the anchor
never lands on a detached node; the data-percy-element-id lookup remains as
a fallback (<style> is still stamped, unchanged from 1.32.5), then the
pre-PER-10077 end-of-<head> append. sheet.ownerNode is now null-guarded,
which the previous code dereferenced unconditionally.

Contained to @percy/dom: no other package reads data-percy-element-id off a
<link> (core/webdriver-utils reference it only for iframes).

Four specs in the PER-10610 block, three of which fail with the stamp
restored and pass without it — including one that reproduces the reported
symptom end to end by reconciling a head-managed <link> between two
serializeDOM passes and asserting the href still appears exactly once.
The inverted PER-10077 spec that asserted links *are* stamped is replaced.

@percy/dom is at parity with the pre-change baseline: identical set of 81
pre-existing failures on ChromeHeadless (readiness font/js_idle, video
poster timeouts, focus specs needing real window focus), 0 new. eslint
clean.

Note: this is independent of PER-10588, which gates the interactive-state
injection but leaves markElement's <link> stamp unconditional.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 packages/dom/src/clone-dom.js                |  6 ++-
 packages/dom/src/prepare-dom.js              |  7 ---
 packages/dom/src/serialize-cssom.js          |  3 +-
 packages/dom/src/serialize-dom.js            |  1 +
 packages/dom/src/serialize-pseudo-classes.js | 21 ++++----
 packages/dom/test/assets/hover-anchor.css    |  1 +
 packages/dom/test/serialize-dom.test.js      | 57 +++++++++++++++++---
 7 files changed, 72 insertions(+), 24 deletions(-)
 create mode 100644 packages/dom/test/assets/hover-anchor.css

diff --git a/packages/dom/src/clone-dom.js b/packages/dom/src/clone-dom.js
index 2f7c8b491..d7844b974 100644
--- a/packages/dom/src/clone-dom.js
+++ b/packages/dom/src/clone-dom.js
@@ -49,7 +49,7 @@ function cloneElementWithoutLifecycle(element) {
 }
 
 export function cloneNodeAndShadow(ctx) {
-  let { dom, disableShadowDOM, forceShadowAsLightDOM, resources, cache, enableJavaScript } = ctx;
+  let { dom, disableShadowDOM, forceShadowAsLightDOM, resources, cache, enableJavaScript, styleSheetClones } = ctx;
   // clones shadow DOM and light DOM for a given node
   let cloneNode = (node, parent) => {
     try {
@@ -73,6 +73,10 @@ export function cloneNodeAndShadow(ctx) {
 
       let clone = cloneElementWithoutLifecycle(node);
 
+      if (styleSheetClones && (node.nodeName === 'LINK' || node.nodeName === 'STYLE')) {
+        styleSheetClones.set(node, clone);
+      }
+
       // 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.
diff --git a/packages/dom/src/prepare-dom.js b/packages/dom/src/prepare-dom.js
index fe10a496a..bf494866f 100644
--- a/packages/dom/src/prepare-dom.js
+++ b/packages/dom/src/prepare-dom.js
@@ -11,15 +11,8 @@ export function markElement(domElement, disableShadowDOM, forceShadowAsLightDOM)
   // Custom elements with ElementInternals or closed shadow roots also get
   // stamped so the post-clone state-fallback can locate their clones.
   let tagName = domElement.tagName?.toLowerCase();
-  // Stylesheet <link>s are stamped so the pseudo-class serializer can locate
-  // the sheet's clone element and anchor its rewritten interactive-state rules
-  // immediately after it — preserving the sheet's original cascade position
-  // instead of appending at the end of <head> (PER-10077).
-  let isStylesheetLink = tagName === 'link' &&
-    /(^|\s)stylesheet(\s|$)/i.test(domElement.getAttribute('rel') || '');
   if (
     ['input', 'textarea', 'select', 'iframe', 'canvas', 'video', 'style', 'dialog'].includes(tagName) ||
-    isStylesheetLink ||
     isCustomElement(domElement)
   ) {
     if (!domElement.getAttribute('data-percy-element-id')) {
diff --git a/packages/dom/src/serialize-cssom.js b/packages/dom/src/serialize-cssom.js
index fb8cbc23c..3f2caae89 100644
--- a/packages/dom/src/serialize-cssom.js
+++ b/packages/dom/src/serialize-cssom.js
@@ -51,7 +51,7 @@ function createStyleResource(styleSheet) {
 }
 
 export function serializeCSSOM(ctx) {
-  let { dom, clone, resources, cache, warnings, ignoreStyleSheetSerializationErrors } = ctx;
+  let { dom, clone, resources, cache, warnings, ignoreStyleSheetSerializationErrors, styleSheetClones } = ctx;
   // in-memory CSSOM into their respective DOM nodes.
   let styleSheets = null;
   // catch error in case styleSheets property is not available (overwritten to throw error)
@@ -81,6 +81,7 @@ export function serializeCSSOM(ctx) {
 
           cloneOwnerNode.parentNode.insertBefore(style, cloneOwnerNode.nextSibling);
           cloneOwnerNode.remove();
+          styleSheetClones?.set(styleSheet.ownerNode, style);
         } catch (err) {
           handleErrors(err, 'Error serializing stylesheet: ', cloneOwnerNode, {
             styleId: styleId
diff --git a/packages/dom/src/serialize-dom.js b/packages/dom/src/serialize-dom.js
index c9cb0bb6c..f287c31f4 100644
--- a/packages/dom/src/serialize-dom.js
+++ b/packages/dom/src/serialize-dom.js
@@ -112,6 +112,7 @@ export function serializeDOM(options) {
     warnings: new Set(),
     hints: new Set(),
     cache: new Map(),
+    styleSheetClones: new WeakMap(),
     shadowRootElements: [],
     enableJavaScript,
     disableShadowDOM,
diff --git a/packages/dom/src/serialize-pseudo-classes.js b/packages/dom/src/serialize-pseudo-classes.js
index 06571965f..877ddb759 100644
--- a/packages/dom/src/serialize-pseudo-classes.js
+++ b/packages/dom/src/serialize-pseudo-classes.js
@@ -510,11 +510,11 @@ function extractPseudoClassRules(ctx) {
     styleElement.textContent = rewrittenRules.join('\n');
 
     if (owner === null) {
-      injectAtSheetPosition(ctx.clone, sheet, styleElement, ctx.clone.head || ctx.clone.querySelector('head'));
+      injectAtSheetPosition(ctx, ctx.clone, sheet, styleElement, ctx.clone.head || ctx.clone.querySelector('head'));
     } else {
       const cloneHost = cloneByPercyId.get(owner.getAttribute('data-percy-element-id'));
       if (cloneHost && cloneHost.shadowRoot) {
-        injectAtSheetPosition(cloneHost.shadowRoot, sheet, styleElement, cloneHost.shadowRoot);
+        injectAtSheetPosition(ctx, cloneHost.shadowRoot, sheet, styleElement, cloneHost.shadowRoot);
       }
     }
   }
@@ -523,13 +523,16 @@ function extractPseudoClassRules(ctx) {
 // Insert an interactive-states <style> immediately AFTER its source sheet's
 // clone element so the copy keeps the sheet's original source-order rank —
 // later stylesheets still win equal-specificity ties, exactly as on the live
-// page (PER-10077). The sheet's ownerNode (<style> / <link rel=stylesheet>) is
-// stamped with a data-percy-element-id, which serialize-cssom preserves on any
-// node it rebuilds in place. Falls back to appending at the scope's end when
-// the sheet has no locatable clone anchor.
-function injectAtSheetPosition(scopeRoot, sheet, styleElement, fallbackTarget) {
-  const anchorId = sheet.ownerNode.getAttribute('data-percy-element-id');
-  const anchor = anchorId ? scopeRoot.querySelector(`[data-percy-element-id="${anchorId}"]`) : null;
+// page (PER-10077).
+function injectAtSheetPosition(ctx, scopeRoot, sheet, styleElement, fallbackTarget) {
+  const ownerNode = sheet.ownerNode;
+  let anchor = ownerNode ? ctx.styleSheetClones?.get(ownerNode) : null;
+
+  if (!anchor?.parentNode && ownerNode) {
+    const anchorId = ownerNode.getAttribute('data-percy-element-id');
+    anchor = anchorId ? scopeRoot.querySelector(`[data-percy-element-id="${anchorId}"]`) : null;
+  }
+
   const anchorParent = anchor ? anchor.parentNode : null;
   if (anchorParent) {
     anchorParent.insertBefore(styleElement, anchor.nextSibling);
diff --git a/packages/dom/test/assets/hover-anchor.css b/packages/dom/test/assets/hover-anchor.css
new file mode 100644
index 000000000..f5ad98e07
--- /dev/null
+++ b/packages/dom/test/assets/hover-anchor.css
@@ -0,0 +1 @@
+.lbtn:hover { color: red }
diff --git a/packages/dom/test/serialize-dom.test.js b/packages/dom/test/serialize-dom.test.js
index 2c322f56e..194c0fafc 100644
--- a/packages/dom/test/serialize-dom.test.js
+++ b/packages/dom/test/serialize-dom.test.js
@@ -883,11 +883,18 @@ describe('serializeDOM', () => {
     });
   });
 
-  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
-      // clone element, found via data-percy-element-id — so stylesheet links
-      // need one. Non-stylesheet links (preload, icon, …) do not.
+  describe('stylesheet <link> handling (PER-10610)', () => {
+    it('leaves a live stylesheet <link> equal to what a head manager rendered', () => {
+      withExample('<link rel="stylesheet" href="data:text/css,.lx{color:red}">', { withShadow: false });
+      let link = document.querySelector('link[rel="stylesheet"][href^="data:text/css,.lx"]');
+      let rendered = link.cloneNode();
+
+      serializeDOM();
+
+      expect(link.isEqualNode(rendered)).toBe(true);
+    });
+
+    it('does not stamp stylesheet <link>s in the serialized output', () => {
       withExample(
         '<link rel="stylesheet" href="data:text/css,.lx{color:red}">' +
         '<link rel="preload" as="style" href="data:text/css,.ly{color:red}">' +
@@ -895,10 +902,48 @@ describe('serializeDOM', () => {
         { withShadow: false }
       );
       let $ = parseDOM(serializeDOM().html, 'plain');
-      expect($('link[rel="stylesheet"]')[0].getAttribute('data-percy-element-id')).toBeTruthy();
+      expect($('link[rel="stylesheet"]')[0].getAttribute('data-percy-element-id')).toBeNull();
       expect($('link[rel="preload"]')[0].getAttribute('data-percy-element-id')).toBeNull();
       expect($('link:not([rel])')[0].getAttribute('data-percy-element-id')).toBeNull();
     });
+
+    it('does not accumulate <link>s when a head manager reconciles between snapshots', () => {
+      withExample('<link rel="stylesheet" href="data:text/css,.lrec{color:red}">', { withShadow: false });
+      let link = document.querySelector('link[rel="stylesheet"][href^="data:text/css,.lrec"]');
+      let rendered = link.cloneNode();
+      let reconcile = () => {
+        if (!link.isEqualNode(rendered)) link.after(rendered.cloneNode());
+      };
+
+      serializeDOM();
+      reconcile();
+      let html = serializeDOM().html;
+
+      expect(html.split('data:text/css,.lrec{').length - 1).toEqual(1);
+    });
+
+    it('still anchors a rewritten copy after its source <link>, not at end of head (PER-10077)', async () => {
+      withExample(
+        '<link rel="stylesheet" href="base/test/assets/hover-anchor.css">' +
+        '<style>.lbtn.later { color: blue }</style>' +
+        '<button class="lbtn later">go</button>',
+        { withShadow: false }
+      );
+      let link = document.querySelector('link[href="base/test/assets/hover-anchor.css"]');
+      await new Promise((resolve, reject) => {
+        if (link.sheet) return resolve();
+        link.addEventListener('load', resolve, { once: true });
+        link.addEventListener('error', () => reject(new Error('hover-anchor.css failed to load')), { once: true });
+      });
+
+      let html = serializeDOM({ enablePseudoClassSerialization: true }).html;
+      let sourceIdx = html.indexOf('hover-anchor.css');
+      let copyIdx = html.indexOf('.lbtn[data-percy-hover]');
+      let laterIdx = html.indexOf('.lbtn.later');
+      expect(copyIdx).toBeGreaterThan(-1);
+      expect(copyIdx).toBeGreaterThan(sourceIdx);
+      expect(copyIdx).toBeLessThan(laterIdx);
+    });
   });
 
   describe(':state() CSS rewriting', () => {