@kubesense/kubesense-browser-rum-core 1.0.0

package/src/domain/view/trackViews.ts

@@ -0,0 +1,431 @@
+import type {
+  Duration,
+  ClocksState,
+  TimeStamp,
+  Subscription,
+  RelativeTime,
+  Context,
+  ContextValue,
+} from '@kubesense/kubesense-browser-core'
+import {
+  noop,
+  PageExitReason,
+  shallowClone,
+  elapsed,
+  generateUUID,
+  ONE_MINUTE,
+  throttle,
+  clocksNow,
+  clocksOrigin,
+  relativeToClocks,
+  timeStampNow,
+  display,
+  looksLikeRelativeTime,
+  setInterval,
+  clearInterval,
+  setTimeout,
+  Observable,
+  createContextManager,
+} from '@kubesense/kubesense-browser-core'
+import type { ViewCustomTimings } from '../../rawRumEvent.types'
+import { ViewLoadingType } from '../../rawRumEvent.types'
+import type { LifeCycle } from '../lifeCycle'
+import { LifeCycleEventType } from '../lifeCycle'
+import type { EventCounts } from '../trackEventCounts'
+import type { LocationChange } from '../../browser/locationChangeObservable'
+import type { RumConfiguration, RumInitConfiguration } from '../configuration'
+import type { RumMutationRecord } from '../../browser/domMutationObservable'
+import { trackViewEventCounts } from './trackViewEventCounts'
+import { trackInitialViewMetrics } from './viewMetrics/trackInitialViewMetrics'
+import type { InitialViewMetrics } from './viewMetrics/trackInitialViewMetrics'
+import type { CommonViewMetrics } from './viewMetrics/trackCommonViewMetrics'
+import { trackCommonViewMetrics } from './viewMetrics/trackCommonViewMetrics'
+import { onBFCacheRestore } from './bfCacheSupport'
+import { trackBfcacheMetrics } from './viewMetrics/trackBfcacheMetrics'
+
+export interface ViewEvent {
+  id: string
+  name?: string
+  service?: string
+  version?: string
+  context?: Context
+  location: Readonly<Location>
+  commonViewMetrics: CommonViewMetrics
+  initialViewMetrics: InitialViewMetrics
+  customTimings: ViewCustomTimings
+  eventCounts: EventCounts
+  documentVersion: number
+  startClocks: ClocksState
+  duration: Duration
+  isActive: boolean
+  sessionIsActive: boolean
+  loadingType: ViewLoadingType
+}
+
+export interface ViewCreatedEvent {
+  id: string
+  name?: string
+  service?: string
+  version?: string
+  context?: Context
+  startClocks: ClocksState
+}
+
+export interface BeforeViewUpdateEvent {
+  id: string
+  name?: string
+  context?: Context
+  startClocks: ClocksState
+  sessionIsActive: boolean
+}
+
+export interface ViewEndedEvent {
+  endClocks: ClocksState
+}
+
+export const THROTTLE_VIEW_UPDATE_PERIOD = 3000
+export const SESSION_KEEP_ALIVE_INTERVAL = 5 * ONE_MINUTE
+
+// Some events or metrics can be captured after the end of the view. To avoid missing those;
+// an arbitrary delay is added for stopping their tracking after the view ends.
+//
+// Ideally, we would not stop and keep tracking events or metrics until the end of the session.
+// But this might have a small performance impact if there are many many views.
+// So let's have a fairly short delay improving the situation in most cases and avoid impacting performances too much.
+export const KEEP_TRACKING_AFTER_VIEW_DELAY = 5 * ONE_MINUTE
+
+export interface ViewOptions {
+  name?: string
+  service?: RumInitConfiguration['service']
+  version?: RumInitConfiguration['version']
+  context?: Context
+}
+
+export function trackViews(
+  location: Location,
+  lifeCycle: LifeCycle,
+  domMutationObservable: Observable<RumMutationRecord[]>,
+  windowOpenObservable: Observable<void>,
+  configuration: RumConfiguration,
+  locationChangeObservable: Observable<LocationChange>,
+  areViewsTrackedAutomatically: boolean,
+  initialViewOptions?: ViewOptions
+) {
+  const activeViews: Set<ReturnType<typeof newView>> = new Set()
+  let currentView = startNewView(ViewLoadingType.INITIAL_LOAD, clocksOrigin(), initialViewOptions)
+  let stopOnBFCacheRestore: (() => void) | undefined
+
+  startViewLifeCycle()
+
+  let locationChangeSubscription: Subscription
+  if (areViewsTrackedAutomatically) {
+    locationChangeSubscription = renewViewOnLocationChange(locationChangeObservable)
+    if (configuration.trackBfcacheViews) {
+      stopOnBFCacheRestore = onBFCacheRestore(configuration, (pageshowEvent) => {
+        currentView.end()
+        const startClocks = relativeToClocks(pageshowEvent.timeStamp as RelativeTime)
+        currentView = startNewView(ViewLoadingType.BF_CACHE, startClocks, undefined)
+      })
+    }
+  }
+
+  function startNewView(loadingType: ViewLoadingType, startClocks?: ClocksState, viewOptions?: ViewOptions) {
+    const newlyCreatedView = newView(
+      lifeCycle,
+      domMutationObservable,
+      windowOpenObservable,
+      configuration,
+      location,
+      loadingType,
+      startClocks,
+      viewOptions
+    )
+    activeViews.add(newlyCreatedView)
+    newlyCreatedView.stopObservable.subscribe(() => {
+      activeViews.delete(newlyCreatedView)
+    })
+    return newlyCreatedView
+  }
+
+  function startViewLifeCycle() {
+    lifeCycle.subscribe(LifeCycleEventType.SESSION_RENEWED, () => {
+      // Renew view on session renewal
+      currentView = startNewView(ViewLoadingType.ROUTE_CHANGE, undefined, {
+        name: currentView.name,
+        service: currentView.service,
+        version: currentView.version,
+        context: currentView.contextManager.getContext(),
+      })
+    })
+
+    lifeCycle.subscribe(LifeCycleEventType.SESSION_EXPIRED, () => {
+      currentView.end({ sessionIsActive: false })
+    })
+  }
+
+  function renewViewOnLocationChange(locationChangeObservable: Observable<LocationChange>) {
+    return locationChangeObservable.subscribe(({ oldLocation, newLocation }) => {
+      if (areDifferentLocation(oldLocation, newLocation)) {
+        currentView.end()
+        currentView = startNewView(ViewLoadingType.ROUTE_CHANGE)
+      }
+    })
+  }
+
+  return {
+    addTiming: (name: string, time: RelativeTime | TimeStamp = timeStampNow()) => {
+      currentView.addTiming(name, time)
+    },
+    startView: (options?: ViewOptions, startClocks?: ClocksState) => {
+      currentView.end({ endClocks: startClocks })
+      currentView = startNewView(ViewLoadingType.ROUTE_CHANGE, startClocks, options)
+    },
+    setViewContext: (context: Context) => {
+      currentView.contextManager.setContext(context)
+    },
+    setViewContextProperty: (key: string, value: ContextValue) => {
+      currentView.contextManager.setContextProperty(key, value)
+    },
+    setViewName: (name: string) => {
+      currentView.setViewName(name)
+    },
+    getViewContext: () => currentView.contextManager.getContext(),
+
+    stop: () => {
+      if (locationChangeSubscription) {
+        locationChangeSubscription.unsubscribe()
+      }
+      if (stopOnBFCacheRestore) {
+        stopOnBFCacheRestore()
+      }
+      currentView.end()
+      activeViews.forEach((view) => view.stop())
+    },
+  }
+}
+
+function newView(
+  lifeCycle: LifeCycle,
+  domMutationObservable: Observable<RumMutationRecord[]>,
+  windowOpenObservable: Observable<void>,
+  configuration: RumConfiguration,
+  initialLocation: Location,
+  loadingType: ViewLoadingType,
+  startClocks: ClocksState = clocksNow(),
+  viewOptions?: ViewOptions
+) {
+  // Setup initial values
+  const id = generateUUID()
+  const stopObservable = new Observable<void>()
+  const customTimings: ViewCustomTimings = {}
+  let documentVersion = 0
+  let endClocks: ClocksState | undefined
+  const location = shallowClone(initialLocation)
+  const contextManager = createContextManager()
+
+  let sessionIsActive = true
+  let name = viewOptions?.name
+  const service = viewOptions?.service || configuration.service
+  const version = viewOptions?.version || configuration.version
+  const context = viewOptions?.context
+
+  if (context) {
+    contextManager.setContext(context)
+  }
+
+  const viewCreatedEvent = {
+    id,
+    name,
+    startClocks,
+    service,
+    version,
+    context,
+  }
+  lifeCycle.notify(LifeCycleEventType.BEFORE_VIEW_CREATED, viewCreatedEvent)
+  lifeCycle.notify(LifeCycleEventType.VIEW_CREATED, viewCreatedEvent)
+
+  // Update the view every time the measures are changing
+  const { throttled, cancel: cancelScheduleViewUpdate } = throttle(triggerViewUpdate, THROTTLE_VIEW_UPDATE_PERIOD, {
+    leading: false,
+  })
+
+  const {
+    setLoadEvent,
+    setViewEnd,
+    stop: stopCommonViewMetricsTracking,
+    stopINPTracking,
+    getCommonViewMetrics,
+  } = trackCommonViewMetrics(
+    lifeCycle,
+    domMutationObservable,
+    windowOpenObservable,
+    configuration,
+    scheduleViewUpdate,
+    loadingType,
+    startClocks
+  )
+
+  const { stop: stopInitialViewMetricsTracking, initialViewMetrics } =
+    loadingType === ViewLoadingType.INITIAL_LOAD
+      ? trackInitialViewMetrics(configuration, startClocks, setLoadEvent, scheduleViewUpdate)
+      : { stop: noop, initialViewMetrics: {} as InitialViewMetrics }
+
+  // Start BFCache-specific metrics when restoring from BFCache
+  if (loadingType === ViewLoadingType.BF_CACHE) {
+    trackBfcacheMetrics(startClocks, initialViewMetrics, scheduleViewUpdate)
+  }
+
+  const { stop: stopEventCountsTracking, eventCounts } = trackViewEventCounts(lifeCycle, id, scheduleViewUpdate)
+
+  // Session keep alive
+  const keepAliveIntervalId = setInterval(triggerViewUpdate, SESSION_KEEP_ALIVE_INTERVAL)
+
+  const pageMayExitSubscription = lifeCycle.subscribe(LifeCycleEventType.PAGE_MAY_EXIT, (pageMayExitEvent) => {
+    if (pageMayExitEvent.reason === PageExitReason.UNLOADING) {
+      // Force the final emission's isActive=false without mutating endClocks.
+      // Why this matters: the regular triggerViewUpdate computes
+      // `isActive: endClocks === undefined`, which is `true` here because we
+      // haven't called end(). If we leave the final pre-unload event with
+      // isActive=true the view sits in rum_view_raw permanently active —
+      // the backend cron only aggregates inactive views, so the view stays
+      // invisible to rum_view (and session aggregations) until a 10-minute
+      // stale-view fallback force-finalizes it.
+      // Why not just set endClocks here: beforeunload is not guaranteed to
+      // be followed by an actual unload (the user can cancel navigation in
+      // some flows). If we permanently set endClocks, setViewEnd() would
+      // also fire — which calls stopViewInteractionCount() and stops INP /
+      // interaction tracking for the rest of the page's life, and any later
+      // addTiming() calls are silently dropped (see the endClocks guard in
+      // addTiming). Forcing the override only on this one emission keeps
+      // the view fully recoverable if the page survives.
+      triggerViewUpdate(true)
+    }
+  })
+
+  // Initial view update
+  triggerViewUpdate()
+
+  // View context update should always be throttled
+  contextManager.changeObservable.subscribe(scheduleViewUpdate)
+
+  function triggerBeforeViewUpdate() {
+    lifeCycle.notify(LifeCycleEventType.BEFORE_VIEW_UPDATED, {
+      id,
+      name,
+      context: contextManager.getContext(),
+      startClocks,
+      sessionIsActive,
+    })
+  }
+
+  function scheduleViewUpdate() {
+    triggerBeforeViewUpdate()
+    throttled()
+  }
+
+  function triggerViewUpdate(forceInactive = false) {
+    cancelScheduleViewUpdate()
+    triggerBeforeViewUpdate()
+
+    documentVersion += 1
+    const currentEnd = endClocks === undefined ? timeStampNow() : endClocks.timeStamp
+    lifeCycle.notify(LifeCycleEventType.VIEW_UPDATED, {
+      customTimings,
+      documentVersion,
+      id,
+      name,
+      service,
+      version,
+      context: contextManager.getContext(),
+      loadingType,
+      location,
+      startClocks,
+      commonViewMetrics: getCommonViewMetrics(),
+      initialViewMetrics,
+      duration: elapsed(startClocks.timeStamp, currentEnd),
+      // forceInactive is set by the page-unload handler so the final emission
+      // is marked inactive without permanently ending the view (see comment
+      // there). All other call sites use the natural endClocks-based check.
+      isActive: !forceInactive && endClocks === undefined,
+      sessionIsActive,
+      eventCounts,
+    })
+  }
+
+  return {
+    get name() {
+      return name
+    },
+    service,
+    version,
+    contextManager,
+    stopObservable,
+    end(options: { endClocks?: ClocksState; sessionIsActive?: boolean } = {}) {
+      if (endClocks) {
+        // view already ended
+        return
+      }
+      endClocks = options.endClocks ?? clocksNow()
+      sessionIsActive = options.sessionIsActive ?? true
+
+      lifeCycle.notify(LifeCycleEventType.VIEW_ENDED, { endClocks })
+      lifeCycle.notify(LifeCycleEventType.AFTER_VIEW_ENDED, { endClocks })
+      clearInterval(keepAliveIntervalId)
+      setViewEnd(endClocks.relative)
+      stopCommonViewMetricsTracking()
+      pageMayExitSubscription.unsubscribe()
+      triggerViewUpdate()
+      setTimeout(() => {
+        this.stop()
+      }, KEEP_TRACKING_AFTER_VIEW_DELAY)
+    },
+    stop() {
+      stopInitialViewMetricsTracking()
+      stopEventCountsTracking()
+      stopINPTracking()
+      stopObservable.notify()
+    },
+    addTiming(name: string, time: RelativeTime | TimeStamp) {
+      if (endClocks) {
+        return
+      }
+      const relativeTime = looksLikeRelativeTime(time) ? time : elapsed(startClocks.timeStamp, time)
+      customTimings[sanitizeTiming(name)] = relativeTime
+      scheduleViewUpdate()
+    },
+    setViewName(updatedName: string) {
+      name = updatedName
+      triggerViewUpdate()
+    },
+  }
+}
+
+/**
+ * Timing name is used as facet path that must contain only letters, digits, or the characters - _ . @ $
+ */
+function sanitizeTiming(name: string) {
+  const sanitized = name.replace(/[^a-zA-Z0-9-_.@$]/g, '_')
+  if (sanitized !== name) {
+    display.warn(`Invalid timing name: ${name}, sanitized to: ${sanitized}`)
+  }
+  return sanitized
+}
+
+function areDifferentLocation(currentLocation: Location, otherLocation: Location) {
+  return (
+    currentLocation.pathname !== otherLocation.pathname ||
+    (!isHashAnAnchor(otherLocation.hash) &&
+      getPathFromHash(otherLocation.hash) !== getPathFromHash(currentLocation.hash))
+  )
+}
+
+function isHashAnAnchor(hash: string) {
+  const correspondingId = hash.substring(1)
+  // check if the correspondingId is empty because on Firefox an empty string passed to getElementById() prints a consol warning
+  return correspondingId !== '' && !!document.getElementById(correspondingId)
+}
+
+function getPathFromHash(hash: string) {
+  const index = hash.indexOf('?')
+  return index < 0 ? hash : hash.slice(0, index)
+}

package/src/domain/view/viewCollection.ts

@@ -0,0 +1,203 @@
+import type { Duration, ServerDuration, Observable } from '@kubesense/kubesense-browser-core'
+import { getTimeZone, DISCARDED, HookNames, isEmptyObject, mapValues, toServerDuration } from '@kubesense/kubesense-browser-core'
+import { discardNegativeDuration } from '../discardNegativeDuration'
+import type { RecorderApi } from '../../boot/rumPublicApi'
+import type { RawRumViewEvent, ViewPerformanceData } from '../../rawRumEvent.types'
+import { RumEventType } from '../../rawRumEvent.types'
+import type { LifeCycle, RawRumEventCollectedData } from '../lifeCycle'
+import { LifeCycleEventType } from '../lifeCycle'
+import type { LocationChange } from '../../browser/locationChangeObservable'
+import type { RumConfiguration } from '../configuration'
+import type { ViewHistory } from '../contexts/viewHistory'
+import type { DefaultRumEventAttributes, DefaultTelemetryEventAttributes, Hooks } from '../hooks'
+import type { RumMutationRecord } from '../../browser/domMutationObservable'
+import { trackViews } from './trackViews'
+import type { ViewEvent, ViewOptions } from './trackViews'
+import type { CommonViewMetrics } from './viewMetrics/trackCommonViewMetrics'
+import type { InitialViewMetrics } from './viewMetrics/trackInitialViewMetrics'
+
+export function startViewCollection(
+  lifeCycle: LifeCycle,
+  hooks: Hooks,
+  configuration: RumConfiguration,
+  location: Location,
+  domMutationObservable: Observable<RumMutationRecord[]>,
+  pageOpenObservable: Observable<void>,
+  locationChangeObservable: Observable<LocationChange>,
+  recorderApi: RecorderApi,
+  viewHistory: ViewHistory,
+  initialViewOptions?: ViewOptions
+) {
+  lifeCycle.subscribe(LifeCycleEventType.VIEW_UPDATED, (view) =>
+    lifeCycle.notify(LifeCycleEventType.RAW_RUM_EVENT_COLLECTED, processViewUpdate(view, configuration, recorderApi))
+  )
+
+  hooks.register(HookNames.Assemble, ({ startTime, eventType }): DefaultRumEventAttributes | DISCARDED => {
+    const view = viewHistory.findView(startTime)
+
+    if (!view) {
+      return DISCARDED
+    }
+
+    return {
+      type: eventType,
+      service: view.service,
+      version: view.version,
+      context: view.context,
+      view: {
+        id: view.id,
+        name: view.name,
+      },
+    }
+  })
+
+  hooks.register(
+    HookNames.AssembleTelemetry,
+    ({ startTime }): DefaultTelemetryEventAttributes => ({
+      view: {
+        id: viewHistory.findView(startTime)?.id,
+      },
+    })
+  )
+
+  return trackViews(
+    location,
+    lifeCycle,
+    domMutationObservable,
+    pageOpenObservable,
+    configuration,
+    locationChangeObservable,
+    !configuration.trackViewsManually,
+    initialViewOptions
+  )
+}
+
+function processViewUpdate(
+  view: ViewEvent,
+  configuration: RumConfiguration,
+  recorderApi: RecorderApi
+): RawRumEventCollectedData<RawRumViewEvent> {
+  const replayStats = recorderApi.getReplayStats(view.id)
+  const clsDevicePixelRatio = view.commonViewMetrics?.cumulativeLayoutShift?.devicePixelRatio
+  const viewEvent: RawRumViewEvent = {
+    _kubesense: {
+      document_version: view.documentVersion,
+      replay_stats: replayStats,
+      cls: clsDevicePixelRatio
+        ? {
+            device_pixel_ratio: clsDevicePixelRatio,
+          }
+        : undefined,
+      configuration: {
+        start_session_replay_recording_manually: configuration.startSessionReplayRecordingManually,
+      },
+    },
+    date: view.startClocks.timeStamp,
+    type: RumEventType.VIEW,
+    view: {
+      action: {
+        count: view.eventCounts.actionCount,
+      },
+      frustration: {
+        count: view.eventCounts.frustrationCount,
+      },
+      cumulative_layout_shift: view.commonViewMetrics.cumulativeLayoutShift?.value,
+      cumulative_layout_shift_time: toServerDuration(view.commonViewMetrics.cumulativeLayoutShift?.time),
+      cumulative_layout_shift_target_selector: view.commonViewMetrics.cumulativeLayoutShift?.targetSelector,
+      first_byte: toServerDuration(view.initialViewMetrics.navigationTimings?.firstByte),
+      dom_complete: toServerDuration(view.initialViewMetrics.navigationTimings?.domComplete),
+      dom_content_loaded: toServerDuration(view.initialViewMetrics.navigationTimings?.domContentLoaded),
+      dom_interactive: toServerDuration(view.initialViewMetrics.navigationTimings?.domInteractive),
+      error: {
+        count: view.eventCounts.errorCount,
+      },
+      first_contentful_paint: toServerDuration(view.initialViewMetrics.firstContentfulPaint),
+      first_input_delay: toServerDuration(view.initialViewMetrics.firstInput?.delay),
+      first_input_time: toServerDuration(view.initialViewMetrics.firstInput?.time),
+      first_input_target_selector: view.initialViewMetrics.firstInput?.targetSelector,
+      interaction_to_next_paint: toServerDuration(view.commonViewMetrics.interactionToNextPaint?.value),
+      interaction_to_next_paint_time: toServerDuration(view.commonViewMetrics.interactionToNextPaint?.time),
+      interaction_to_next_paint_target_selector: view.commonViewMetrics.interactionToNextPaint?.targetSelector,
+      is_active: view.isActive,
+      name: view.name,
+      largest_contentful_paint: toServerDuration(view.initialViewMetrics.largestContentfulPaint?.value),
+      largest_contentful_paint_target_selector: view.initialViewMetrics.largestContentfulPaint?.targetSelector,
+      load_event: toServerDuration(view.initialViewMetrics.navigationTimings?.loadEvent),
+      loading_time: discardNegativeDuration(toServerDuration(view.commonViewMetrics.loadingTime)),
+      loading_type: view.loadingType,
+      long_task: {
+        count: view.eventCounts.longTaskCount,
+      },
+      performance: computeViewPerformanceData(view.commonViewMetrics, view.initialViewMetrics),
+      resource: {
+        count: view.eventCounts.resourceCount,
+      },
+      time_spent: toServerDuration(view.duration),
+    },
+    display: view.commonViewMetrics.scroll
+      ? {
+          scroll: {
+            max_depth: view.commonViewMetrics.scroll.maxDepth,
+            max_depth_scroll_top: view.commonViewMetrics.scroll.maxDepthScrollTop,
+            max_scroll_height: view.commonViewMetrics.scroll.maxScrollHeight,
+            max_scroll_height_time: toServerDuration(view.commonViewMetrics.scroll.maxScrollHeightTime),
+          },
+        }
+      : undefined,
+    privacy: {
+      replay_level: configuration.defaultPrivacyLevel,
+    },
+    device: {
+      locale: navigator.language,
+      locales: navigator.languages,
+      time_zone: getTimeZone(),
+    },
+  }
+
+  if (!isEmptyObject(view.customTimings)) {
+    viewEvent.view.custom_timings = mapValues(
+      view.customTimings,
+      toServerDuration as (duration: Duration) => ServerDuration
+    )
+  }
+
+  return {
+    rawRumEvent: viewEvent,
+    startTime: view.startClocks.relative,
+    duration: view.duration,
+    domainContext: {
+      location: view.location,
+    },
+  }
+}
+
+function computeViewPerformanceData(
+  { cumulativeLayoutShift, interactionToNextPaint }: CommonViewMetrics,
+  { firstContentfulPaint, firstInput, largestContentfulPaint }: InitialViewMetrics
+): ViewPerformanceData {
+  return {
+    cls: cumulativeLayoutShift && {
+      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 && {
+      duration: toServerDuration(firstInput.delay),
+      timestamp: toServerDuration(firstInput.time),
+      target_selector: firstInput.targetSelector,
+    },
+    inp: interactionToNextPaint && {
+      duration: toServerDuration(interactionToNextPaint.value),
+      timestamp: toServerDuration(interactionToNextPaint.time),
+      target_selector: interactionToNextPaint.targetSelector,
+    },
+    lcp: largestContentfulPaint && {
+      timestamp: toServerDuration(largestContentfulPaint.value),
+      target_selector: largestContentfulPaint.targetSelector,
+      resource_url: largestContentfulPaint.resourceUrl,
+    },
+  }
+}

package/src/domain/view/viewMetrics/getClsAttributionImpactedArea.ts

@@ -0,0 +1,34 @@
+import type { RumLayoutShiftAttribution } from '../../../browser/performanceObservable'
+
+/**
+ * Calculates the area of a rectangle given its width and height
+ */
+const calculateArea = (width: number, height: number): number => width * height
+
+/**
+ * Calculates the intersection area between two rectangles
+ */
+const calculateIntersectionArea = (rect1: DOMRectReadOnly, rect2: DOMRectReadOnly): number => {
+  const left = Math.max(rect1.left, rect2.left)
+  const top = Math.max(rect1.top, rect2.top)
+  const right = Math.min(rect1.right, rect2.right)
+  const bottom = Math.min(rect1.bottom, rect2.bottom)
+
+  if (left >= right || top >= bottom) {
+    return 0
+  }
+
+  return calculateArea(right - left, bottom - top)
+}
+
+/**
+ * Calculates the total impacted area of a layout shift source
+ * This is the sum of the previous and current areas minus their intersection
+ */
+export const getClsAttributionImpactedArea = (source: RumLayoutShiftAttribution): number => {
+  const previousArea = calculateArea(source.previousRect.width, source.previousRect.height)
+  const currentArea = calculateArea(source.currentRect.width, source.currentRect.height)
+  const intersectionArea = calculateIntersectionArea(source.previousRect, source.currentRect)
+
+  return previousArea + currentArea - intersectionArea
+}