🐛 [RUM] Session Replay: shadow root adoptedStyleSheets replayed with wrong or missing styles (stylesheet ID drift + late adoption not recorded) #5117

Disclaimer:
The following bug was detected by Opus 5.5 when trying to debug why session replays are recorded with broken styles in our application, and the following report was also written with some help from AI.

Describe the bug

Product: rum (Session Replay).

Web components that style their shadow roots only through constructable stylesheets (shadowRoot.adoptedStyleSheets) are replayed with no styles, or with the styles of an unrelated component. Light DOM content styled via <link>/<style> replays correctly. This is the default pattern for Stencil (shadow: true, lazy-load output) and common in Lit, where one constructed CSSStyleSheet is shared by all instances of a component class.

Two independent recorder problems cause this:

1. Stylesheet ID drift. serializeStyleSheet emits an AddStyleSheet change for every occurrence of a sheet, but allocates a recorder-side ID only for sheets not seen before. When one constructed sheet is adopted by several shadow roots, recorder and player IDs go out of sync and later shadow roots get attached to the wrong (or a non-existent) stylesheet.
2. Late adoptedStyleSheets are never recorded. Adopted sheets are only read when the document/shadow root is serialized. Components that adopt their styles after the shadow root exists (lazy hydration, first render after a dynamic import()) stay unstyled in the replay until the next full snapshot.

Environment:

• @datadog/browser-rum: reproduced on 7.10.0 and 7.14.0. The relevant code is unchanged on main. Latest release at time of writing is 7.15.0; its changelog has no related fix, but I have not tested on 7.15.0 directly.
• Browser: Chromium-based (constructable stylesheets support)
• Config: sessionReplaySampleRate: 100; reproduced with defaultPrivacyLevel 'mask' and 'allow'

To Reproduce

Minimal page (no framework). x-a, x-b and x-c each share one constructed sheet across their instances:

<script>
  // load and init @datadog/browser-rum with sessionReplaySampleRate: 100
</script>
<x-a></x-a><x-a></x-a><x-a></x-a>
<x-b></x-b>
<x-c></x-c>
<script>
  const sheetA = new CSSStyleSheet();
  sheetA.replaceSync(':host { display: block; color: red; }');
  const sheetB = new CSSStyleSheet();
  sheetB.replaceSync(':host { display: block; color: blue; }');
  const sheetC = new CSSStyleSheet();
  sheetC.replaceSync(':host { display: block; color: green; }');

  function define(name, sheet, { async = false } = {}) {
    customElements.define(
      name,
      class extends HTMLElement {
        connectedCallback() {
          const root = this.attachShadow({ mode: 'open' });
          root.innerHTML = '<p>' + name + '</p>';
          if (async) {
            // variant 2: adopt after the shadow root was created
            setTimeout(() => (root.adoptedStyleSheets = [sheet]), 500);
          } else {
            root.adoptedStyleSheets = [sheet];
          }
        }
      }
    );
  }
  define('x-a', sheetA);
  define('x-b', sheetB);
  define('x-c', sheetC, { async: true });
</script>

Steps:

1. Serve the page above with RUM and Session Replay enabled.
2. Let it load for a few seconds, then end the session / open the replay.
3. Problem 1: x-b is expected to be replayed red (x-a's style) instead of blue. sheetA is sent once per x-a shadow root, so it takes player IDs 0, 1 and 2, and sheetB gets player ID 3. The recorder, however, attaches x-b to ID 1, a copy of sheetA (see the walk-through under Root cause). In real components, the wrongly attached sheet's selectors usually don't match the shadow DOM, so the component looks unstyled rather than mis-styled.
4. Problem 2: x-c is replayed unstyled, because its sheet is adopted after its shadow root was serialized. Calling datadogRum.startView() after the page settles forces a full snapshot and fixes x-c (once problem 1 is fixed), confirming that the recorded DOM is correct and only the stylesheet attachment is missing.

Expected behavior

Each shadow root is replayed with the same adoptedStyleSheets as on the recorded page, including sheets shared between shadow roots and sheets adopted after the shadow root was first serialized.

Root cause

Problem 1: packages/browser-rum/src/domain/record/serialization/serializeNode.ts

function serializeStyleSheet(sheet: CSSStyleSheet, transaction: SerializationTransaction): StyleSheetId {
  const rules = Array.from(sheet.cssRules || sheet.rules, (rule) => createString(StringRole.Css, rule.cssText));
  // ...
  transaction.addStyleSheet(rules, mediaList, sheet.disabled); // always emitted
  return transaction.scope.styleSheetIds.getOrInsert(sheet); // ID allocated only for unseen sheets
}

AddStyleSheet carries no explicit ID, so the player must number sheets in the order they are received. The recorder numbers distinct sheet objects instead, so every duplicate puts the player's numbering one step ahead. Walk-through for the repro above:

The x-a roots are unaffected because they all reference ID 0, the original. x-b references ID 1, which the player assigned to the second copy of sheetA, while sheetB's rules sit unreferenced at ID 3. The gap grows by one for every duplicate, so with N instances of the first component the next new sheet is offset by N − 1. Since the recorder never allocates more IDs than the player, the referenced sheet always exists but belongs to another component. Its selectors typically don't match, so the component appears unstyled.

The player's numbering is inferred from the recorder code (the player source is not public). It is consistent with the observation that skipping already-emitted sheets fixes the replay.

The <link>/<style> path is unaffected in practice because those sheets are not shared.

Problem 2: adoptedStyleSheets are only read in serializeDocumentNode / serializeDocumentFragmentNode (same serializeNode.ts). After that:

• trackers/trackStyleSheet.ts only instruments insertRule/deleteRule for sheets with an ownerNode; constructed sheets have none;
• nothing observes assignment to adoptedStyleSheets, in-place push on its ObservableArray, or replace/replaceSync;
• serializeMutations.ts does not re-check the stylesheets of already serialized shadow roots.

All paths are under packages/browser-rum/src/domain/record/.

Suggested fix

1. Emit each sheet once per recording scope; return the existing ID when known:

   const existingSheetId = transaction.scope.styleSheetIds.get(sheet);
   if (existingSheetId !== undefined) {
     return existingSheetId;
   }
   // ...build rules, then:
   transaction.addStyleSheet(rules, mediaList, sheet.disabled);
   return transaction.scope.styleSheetIds.getOrInsert(sheet);

   Why: player and recorder counters must advance together. It also avoids re-sending identical CSS for every component instance. Validated locally: shared component styles replay correctly.

2. Detect changes to the adopted sheets of already serialized documents/shadow roots and emit AttachedStyleSheets with the current list (new sheets go through serializeStyleSheet, so fix 1 applies). A low-risk approach is to remember the adopted sheets per serialized shadow root and compare them at the end of each mutation batch. A complete fix should also cover document.adoptedStyleSheets, reset tracked state on full snapshot, avoid retaining disconnected shadow roots, and ideally record insertRule/deleteRule/replace/replaceSync on constructed sheets. Patching the adoptedStyleSheets setter alone is insufficient since in-place push bypasses it.

   Why: component runtimes commonly adopt styles after the shadow root is in the DOM. Status: a comparison-based patch exists locally, but replay verification of fix 2 is still pending.

Additional context

• [REPLAY] Add support for adoptedStyleSheets #1916 added adoptedStyleSheets support (serialization at node-serialization time only).
• 🎨 [PANA-5260] Consolidate recorder object id tracking code #4049 consolidated recorder object ID tracking and is likely where styleSheetIds.getOrInsert came from (inferred, diff not confirmed).
• Session Replay doesn't capture elements rendered in a Shadow DOM #1518 was the original shadow DOM replay report (unrelated to stylesheets).
• I found no existing issue or PR for either problem. I'm happy to open a PR for fix 1 if that is welcome.