✨ Capture previous and current rects in CLS attribution data (#3269)

packages/rum-core/src/browser/performanceObservable.ts

@@ -116,14 +116,18 @@ export interface RumPerformanceEventTiming {
   name: string
 }
 
+export interface RumLayoutShiftAttribution {
+  node: Node | null
+  previousRect: DOMRectReadOnly
+  currentRect: DOMRectReadOnly
+}
+
 export interface RumLayoutShiftTiming {
   entryType: RumPerformanceEntryType.LAYOUT_SHIFT
   startTime: RelativeTime
   value: number
   hadRecentInput: boolean
-  sources?: Array<{
-    node?: Node
-  }>
+  sources: RumLayoutShiftAttribution[]
 }
 
 // Documentation https://developer.chrome.com/docs/web-platform/long-animation-frames#better-attribution

packages/rum-core/src/domain/view/trackViews.spec.ts

@@ -403,6 +403,8 @@ describe('view metrics', () => {
         value: 0.1,
         targetSelector: undefined,
         time: clock.relative(0),
+        previousRect: undefined,
+        currentRect: undefined,
       })
     })
 

packages/rum-core/src/domain/view/viewCollection.spec.ts

@@ -172,6 +172,8 @@ describe('viewCollection', () => {
             score: 1,
             timestamp: (100 * 1e6) as ServerDuration,
             target_selector: undefined,
+            previous_rect: undefined,
+            current_rect: undefined,
           },
           fcp: {
             timestamp: (10 * 1e6) as ServerDuration,

packages/rum-core/src/domain/view/viewCollection.ts

@@ -150,6 +150,8 @@ function computeViewPerformanceData(
       score: cumulativeLayoutShift.value,
       timestamp: toServerDuration(cumulativeLayoutShift.time),
       target_selector: cumulativeLayoutShift.targetSelector,
+      previous_rect: cumulativeLayoutShift.previousRect,
+      current_rect: cumulativeLayoutShift.currentRect,
     },
     fcp: firstContentfulPaint && { timestamp: toServerDuration(firstContentfulPaint) },
     fid: firstInput && {

packages/rum-core/src/domain/view/viewMetrics/trackCumulativeLayoutShift.spec.ts

@@ -77,6 +77,8 @@ describe('trackCumulativeLayoutShift', () => {
       value: 0.3,
       time: 2 as RelativeTime,
       targetSelector: undefined,
+      previousRect: undefined,
+      currentRect: undefined,
     })
   })
 
@@ -139,6 +141,8 @@ describe('trackCumulativeLayoutShift', () => {
       value: 0.3,
       time: 1 as RelativeTime,
       targetSelector: undefined,
+      previousRect: undefined,
+      currentRect: undefined,
     })
   })
 
@@ -158,6 +162,8 @@ describe('trackCumulativeLayoutShift', () => {
       value: 0.6,
       time: 999 as RelativeTime,
       targetSelector: undefined,
+      previousRect: undefined,
+      currentRect: undefined,
     })
   })
 
@@ -210,6 +216,8 @@ describe('trackCumulativeLayoutShift', () => {
       value: 0.5,
       time: 5002 as RelativeTime,
       targetSelector: undefined,
+      previousRect: undefined,
+      currentRect: undefined,
     })
   })
 
@@ -237,7 +245,23 @@ describe('trackCumulativeLayoutShift', () => {
 
       notifyPerformanceEntries([
         createPerformanceEntry(RumPerformanceEntryType.LAYOUT_SHIFT, {
-          sources: [{ node: textNode }, { node: divElement }, { node: textNode }],
+          sources: [
+            {
+              node: textNode,
+              previousRect: DOMRectReadOnly.fromRect({ x: 0, y: 0, width: 10, height: 10 }),
+              currentRect: DOMRectReadOnly.fromRect({ x: 0, y: 0, width: 10, height: 10 }),
+            },
+            {
+              node: divElement,
+              previousRect: DOMRectReadOnly.fromRect({ x: 0, y: 0, width: 10, height: 10 }),
+              currentRect: DOMRectReadOnly.fromRect({ x: 0, y: 0, width: 10, height: 10 }),
+            },
+            {
+              node: textNode,
+              previousRect: DOMRectReadOnly.fromRect({ x: 0, y: 0, width: 10, height: 10 }),
+              currentRect: DOMRectReadOnly.fromRect({ x: 0, y: 0, width: 10, height: 10 }),
+            },
+          ],
         }),
       ])
 
@@ -265,15 +289,21 @@ describe('trackCumulativeLayoutShift', () => {
         createPerformanceEntry(RumPerformanceEntryType.LAYOUT_SHIFT, {
           value: 0.2,
           startTime: 1001 as RelativeTime,
-          sources: [{ node: divElement }],
+          sources: [
+            {
+              node: divElement,
+              previousRect: DOMRectReadOnly.fromRect({ x: 0, y: 0, width: 10, height: 10 }),
+              currentRect: DOMRectReadOnly.fromRect({ x: 0, y: 0, width: 10, height: 10 }),
+            },
+          ],
         }),
       ])
 
       expect(clsCallback.calls.mostRecent().args[0].value).toEqual(0.2)
       expect(clsCallback.calls.mostRecent().args[0].targetSelector).toEqual(undefined)
     })
 
-    it('should get the target element and time of the largest layout shift', () => {
+    it('should get the target element, time, and rects of the largest layout shift', () => {
       startCLSTracking()
       const divElement = appendElement('<div id="div-element"></div>')
 
@@ -285,7 +315,13 @@ describe('trackCumulativeLayoutShift', () => {
         createPerformanceEntry(RumPerformanceEntryType.LAYOUT_SHIFT, {
           value: 0.2,
           startTime: 1 as RelativeTime,
-          sources: [{ node: divElement }],
+          sources: [
+            {
+              node: divElement,
+              previousRect: DOMRectReadOnly.fromRect({ x: 0, y: 0, width: 10, height: 10 }),
+              currentRect: DOMRectReadOnly.fromRect({ x: 50, y: 50, width: 10, height: 10 }),
+            },
+          ],
         }),
       ])
       notifyPerformanceEntries([
@@ -311,6 +347,8 @@ describe('trackCumulativeLayoutShift', () => {
         value: 0.5,
         time: 1 as RelativeTime,
         targetSelector: '#div-element',
+        previousRect: { x: 0, y: 0, width: 10, height: 10 },
+        currentRect: { x: 50, y: 50, width: 10, height: 10 },
       })
     })
   })

packages/rum-core/src/domain/view/viewMetrics/trackCumulativeLayoutShift.ts

@@ -1,22 +1,32 @@
 import { round, ONE_SECOND, noop, elapsed } from '@datadog/browser-core'
 import type { Duration, RelativeTime, WeakRef, WeakRefConstructor } from '@datadog/browser-core'
 import { isElementNode } from '../../../browser/htmlDomUtils'
-import type { RumLayoutShiftTiming } from '../../../browser/performanceObservable'
+import type { RumLayoutShiftAttribution, RumLayoutShiftTiming } from '../../../browser/performanceObservable'
 import {
   supportPerformanceTimingEvent,
   RumPerformanceEntryType,
   createPerformanceObservable,
 } from '../../../browser/performanceObservable'
 import { getSelectorFromElement } from '../../getSelectorFromElement'
 import type { RumConfiguration } from '../../configuration'
+import type { RumRect } from '../../../rumEvent.types'
+
+declare const WeakRef: WeakRefConstructor
 
 export interface CumulativeLayoutShift {
   value: number
   targetSelector?: string
   time?: Duration
+  previousRect?: RumRect
+  currentRect?: RumRect
 }
 
-declare const WeakRef: WeakRefConstructor
+interface LayoutShiftInstance {
+  target: WeakRef<Element> | undefined
+  time: Duration
+  previousRect: DOMRectReadOnly | undefined
+  currentRect: DOMRectReadOnly | undefined
+}
 
 /**
  * Track the cumulative layout shifts (CLS).
@@ -47,8 +57,7 @@ export function trackCumulativeLayoutShift(
   }
 
   let maxClsValue = 0
-  let maxClsTarget: WeakRef<HTMLElement> | undefined
-  let maxClsStartTime: Duration | undefined
+  let biggestShift: LayoutShiftInstance | undefined
 
   // if no layout shift happen the value should be reported as 0
   callback({
@@ -68,19 +77,25 @@ export function trackCumulativeLayoutShift(
       const { cumulatedValue, isMaxValue } = window.update(entry)
 
       if (isMaxValue) {
-        const target = getTargetFromSource(entry.sources)
-        maxClsTarget = target ? new WeakRef(target) : undefined
-        maxClsStartTime = elapsed(viewStart, entry.startTime)
+        const attribution = getFirstElementAttribution(entry.sources)
+        biggestShift = {
+          target: attribution?.node ? new WeakRef(attribution.node) : undefined,
+          time: elapsed(viewStart, entry.startTime),
+          previousRect: attribution?.previousRect,
+          currentRect: attribution?.currentRect,
+        }
       }
 
       if (cumulatedValue > maxClsValue) {
         maxClsValue = cumulatedValue
-        const target = maxClsTarget?.deref()
+        const target = biggestShift?.target?.deref()
 
         callback({
           value: round(maxClsValue, 4),
           targetSelector: target && getSelectorFromElement(target, configuration.actionNameAttribute),
-          time: maxClsStartTime,
+          time: biggestShift?.time,
+          previousRect: biggestShift?.previousRect ? asRumRect(biggestShift.previousRect) : undefined,
+          currentRect: biggestShift?.currentRect ? asRumRect(biggestShift.currentRect) : undefined,
         })
       }
     }
@@ -93,12 +108,16 @@ export function trackCumulativeLayoutShift(
   }
 }
 
-function getTargetFromSource(sources?: Array<{ node?: Node }>) {
-  if (!sources) {
-    return
-  }
+function getFirstElementAttribution(
+  sources: RumLayoutShiftAttribution[]
+): (RumLayoutShiftAttribution & { node: Element }) | undefined {
+  return sources.find(
+    (source): source is RumLayoutShiftAttribution & { node: Element } => !!source.node && isElementNode(source.node)
+  )
+}
 
-  return sources.find((source): source is { node: HTMLElement } => !!source.node && isElementNode(source.node))?.node
+function asRumRect({ x, y, width, height }: DOMRectReadOnly): RumRect {
+  return { x, y, width, height }
 }
 
 export const MAX_WINDOW_DURATION = 5 * ONE_SECOND

packages/rum-core/src/rawRumEvent.types.ts

@@ -158,6 +158,8 @@ export interface ViewPerformanceData {
     score: number
     timestamp?: ServerDuration
     target_selector?: string
+    previous_rect?: RumRect
+    current_rect?: RumRect
   }
   fcp?: {
     timestamp: number
@@ -178,6 +180,13 @@ export interface ViewPerformanceData {
   }
 }
 
+export interface RumRect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
 export type PageStateServerEntry = { state: PageState; start: ServerDuration }
 
 export const enum ViewLoadingType {

packages/rum-core/test/fixtures.ts

@@ -1,6 +1,10 @@
 import type { Context, Duration, RelativeTime, ServerDuration, TimeStamp } from '@datadog/browser-core'
 import { combine, ErrorHandling, ErrorSource, generateUUID, relativeNow, ResourceType } from '@datadog/browser-core'
-import { RumPerformanceEntryType, type EntryTypeToReturnType } from '../src/browser/performanceObservable'
+import {
+  type RumLayoutShiftAttribution,
+  RumPerformanceEntryType,
+  type EntryTypeToReturnType,
+} from '../src/browser/performanceObservable'
 import type { RawRumEvent } from '../src/rawRumEvent.types'
 import { VitalType, ActionType, RumEventType, ViewLoadingType, RumLongTaskEntryType } from '../src/rawRumEvent.types'
 
@@ -152,6 +156,7 @@ export function createPerformanceEntry<T extends RumPerformanceEntryType>(
         startTime: relativeNow(),
         hadRecentInput: false,
         value: 0.1,
+        sources: [] as RumLayoutShiftAttribution[],
         ...overrides,
       } as EntryTypeToReturnType[T]
     case RumPerformanceEntryType.PAINT: