@newrelic/browser-agent 1.324.1-rc.2 → 1.324.1-rc.3

package/dist/cjs/common/constants/env.cdn.js

@@ -17,7 +17,7 @@ exports.VERSION = exports.RRWEB_VERSION = exports.RRWEB_PACKAGE_NAME = exports.D
 /**
  * Exposes the version of the agent
  */
-const VERSION = exports.VERSION = "1.324.1-rc.2";
+const VERSION = exports.VERSION = "1.324.1-rc.3";
 
 /**
  * Exposes the build type of the agent

package/dist/cjs/common/constants/env.npm.js

@@ -17,7 +17,7 @@ exports.VERSION = exports.RRWEB_VERSION = exports.RRWEB_PACKAGE_NAME = exports.D
 /**
  * Exposes the version of the agent
  */
-const VERSION = exports.VERSION = "1.324.1-rc.2";
+const VERSION = exports.VERSION = "1.324.1-rc.3";
 
 /**
  * Exposes the build type of the agent

package/dist/cjs/common/vitals/vital-metric.js

@@ -4,10 +4,12 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.VitalMetric = void 0;
+var _now = require("../timing/now");
 /**
  * Copyright 2020-2026 New Relic, Inc. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
+
 class VitalMetric {
   #subscribers = new Set();
   history = [];
@@ -16,16 +18,29 @@ class VitalMetric {
     this.attrs = {};
     this.roundingMethod = typeof roundingMethod === 'function' ? roundingMethod : Math.floor;
   }
+
+  /**
+   * Records a new value for this metric and notifies subscribers.
+   * @param {object} params
+   * @param {number} params.value The metric's value. For most metrics this is itself a ms offset from page origin
+   * (i.e. the metric's own real time of occurrence); for score-based metrics like CLS it isn't a time at all.
+   * @param {object} [params.attrs] Metric-specific attribution attrs.
+   */
   update({
     value,
     attrs = {}
   }) {
     if (value === undefined || value === null || value < 0) return;
+    const metricTimestamps = {
+      inp: attrs.interactionTime ?? (0, _now.now)(),
+      cls: attrs.largestShiftTime ?? (0, _now.now)()
+    };
     const state = {
       value: this.roundingMethod(value),
       name: this.name,
       // optional web-vitals attribution fields are omitted rather than being serialized as null attributes
-      attrs: Object.fromEntries(Object.entries(attrs).filter(([, attrValue]) => attrValue !== undefined))
+      attrs: Object.fromEntries(Object.entries(attrs).filter(([, attrValue]) => attrValue !== undefined)),
+      relativeTimestamp: metricTimestamps[this.name] ?? value
     };
     this.history.push(state);
     this.#subscribers.forEach(cb => {

package/dist/cjs/features/page_view_timing/aggregate/index.js

@@ -35,9 +35,10 @@ class Aggregate extends _aggregateBase.AggregateBase {
   #handleVitalMetric = ({
     name,
     value,
-    attrs
+    attrs,
+    relativeTimestamp
   }) => {
-    this.addTiming(name, value, attrs);
+    this.addTiming(name, value, attrs, relativeTimestamp);
   };
   constructor(agentRef) {
     super(agentRef, _constants.FEATURE_NAME);
@@ -49,7 +50,7 @@ class Aggregate extends _aggregateBase.AggregateBase {
     this.obfuscator = new _obfuscate.Obfuscator(agentRef, _events.EVENT_TYPES.PVT);
     (0, _registerHandler.registerHandler)('docHidden', msTimestamp => this.endCurrentSession(msTimestamp), this.featureName, this.ee);
     // Add the time of _window pagehide event_ firing to the next PVT harvest == NRDB windowUnload attr:
-    (0, _registerHandler.registerHandler)('winPagehide', msTimestamp => this.addTiming('unload', msTimestamp, null), this.featureName, this.ee);
+    (0, _registerHandler.registerHandler)('winPagehide', msTimestamp => this.addTiming('unload', msTimestamp), this.featureName, this.ee);
     this.waitForFlags([]).then(() => {
       _firstPaint.firstPaint.subscribe(this.#handleVitalMetric);
       _firstContentfulPaint.firstContentfulPaint.subscribe(this.#handleVitalMetric);
@@ -68,10 +69,11 @@ class Aggregate extends _aggregateBase.AggregateBase {
         const {
           name,
           value,
-          attrs
+          attrs,
+          relativeTimestamp
         } = _cumulativeLayoutShift.cumulativeLayoutShift.current;
         if (value === undefined) return;
-        this.addTiming(name, value * 1000, attrs);
+        this.addTiming(name, value * 1000, attrs, relativeTimestamp);
       }, true, true); // CLS node should only report on vis change rather than on every change.
       /* NOTE: the capture=true is required -- empirically verified against a real browser (Chrome) for CLS
       timing node to reliably be in the same final harvest as the rest, alongside Harvester#startTimer's
@@ -89,12 +91,25 @@ class Aggregate extends _aggregateBase.AggregateBase {
   endCurrentSession(timestamp) {
     if (!this.curSessEndRecorded) {
       // TO DO: stage 2 - we don't want to capture this timing twice on page navigating away, but it should run again if we return to page and away *again*
-      this.addTiming('pageHide', timestamp, null);
+      this.addTiming('pageHide', timestamp);
       this.curSessEndRecorded = true;
     }
   }
-  addTiming(name, value, attrs) {
-    attrs = attrs || {};
+
+  /**
+   * Records a page view timing node, decorating it with system attributes (page URL, connection info,
+   * CLS-so-far, webdriver detection, and a server-corrected absolute timestamp) before buffering it for harvest.
+   * @param {string} name The timing node's name (e.g. 'fp', 'fcp', 'lcp', 'cls', 'fi', 'pageHide', 'unload').
+   * @param {number} value The timing node's value; a ms offset from page origin for most nodes, a duration for
+   * 'inp', and a unitless score for 'cls'.
+   * @param {object} [attrs] Additional custom attributes to attach to the node.
+   * @param {number} [relativeTimestamp] The ms offset from page origin at which the underlying event occurred. It is
+   * server-corrected into the node's absolute `timestamp` attribute, which is omitted if the time keeper isn't ready
+   * or this isn't a finite number. Supplied by VitalMetric for nodes whose `value` isn't itself the event's time
+   * (e.g. 'inp' uses the interaction time, 'cls' uses the largest shift time). Defaults to `value`.
+   * @returns {{name: string, value: number, attrs: object}} The recorded timing node.
+   */
+  addTiming(name, value, attrs = {}, relativeTimestamp = value) {
     attrs.pageUrl = (0, _cleanUrl.cleanURL)((0, _runtime.getNavigationEntry)()?.name || _runtime.initialLocation);
     addConnectionAttributes(attrs); // network conditions may differ from the actual for VitalMetrics when they were captured
 
@@ -110,6 +125,10 @@ class Aggregate extends _aggregateBase.AggregateBase {
       attrs.cls = _cumulativeLayoutShift.cumulativeLayoutShift.current.value;
     }
     attrs.webdriverDetected = _webdriverDetection.webdriverDetected;
+    const timeKeeper = this.agentRef.runtime.timeKeeper;
+    if (timeKeeper?.ready && Number.isFinite(relativeTimestamp)) {
+      attrs.timestamp = Math.floor(timeKeeper.correctRelativeTimestamp(relativeTimestamp));
+    }
     const timing = {
       name,
       value,
@@ -140,7 +159,7 @@ class Aggregate extends _aggregateBase.AggregateBase {
     });
   }
   #getGlobalCustomAttributes() {
-    const reservedAttributes = ['size', 'eid', 'cls', 'type', 'fid', 'elTag', 'elUrl', 'net-type', 'net-etype', 'net-rtt', 'net-dlink', 'webdriverDetected'];
+    const reservedAttributes = ['size', 'eid', 'cls', 'type', 'fid', 'elTag', 'elUrl', 'net-type', 'net-etype', 'net-rtt', 'net-dlink', 'webdriverDetected', 'timestamp'];
     return Object.fromEntries(Object.entries(this.agentRef.info.jsAttributes || {}).filter(([key]) => !reservedAttributes.includes(key)));
   }
   preHarvestChecks() {

package/dist/esm/common/constants/env.cdn.js

@@ -11,7 +11,7 @@
 /**
  * Exposes the version of the agent
  */
-export const VERSION = "1.324.1-rc.2";
+export const VERSION = "1.324.1-rc.3";
 
 /**
  * Exposes the build type of the agent

package/dist/esm/common/constants/env.npm.js

@@ -11,7 +11,7 @@
 /**
  * Exposes the version of the agent
  */
-export const VERSION = "1.324.1-rc.2";
+export const VERSION = "1.324.1-rc.3";
 
 /**
  * Exposes the build type of the agent

package/dist/esm/common/vitals/vital-metric.js

@@ -2,6 +2,7 @@
  * Copyright 2020-2026 New Relic, Inc. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
+import { now } from '../timing/now';
 export class VitalMetric {
   #subscribers = new Set();
   history = [];
@@ -10,16 +11,29 @@ export class VitalMetric {
     this.attrs = {};
     this.roundingMethod = typeof roundingMethod === 'function' ? roundingMethod : Math.floor;
   }
+
+  /**
+   * Records a new value for this metric and notifies subscribers.
+   * @param {object} params
+   * @param {number} params.value The metric's value. For most metrics this is itself a ms offset from page origin
+   * (i.e. the metric's own real time of occurrence); for score-based metrics like CLS it isn't a time at all.
+   * @param {object} [params.attrs] Metric-specific attribution attrs.
+   */
   update({
     value,
     attrs = {}
   }) {
     if (value === undefined || value === null || value < 0) return;
+    const metricTimestamps = {
+      inp: attrs.interactionTime ?? now(),
+      cls: attrs.largestShiftTime ?? now()
+    };
     const state = {
       value: this.roundingMethod(value),
       name: this.name,
       // optional web-vitals attribution fields are omitted rather than being serialized as null attributes
-      attrs: Object.fromEntries(Object.entries(attrs).filter(([, attrValue]) => attrValue !== undefined))
+      attrs: Object.fromEntries(Object.entries(attrs).filter(([, attrValue]) => attrValue !== undefined)),
+      relativeTimestamp: metricTimestamps[this.name] ?? value
     };
     this.history.push(state);
     this.#subscribers.forEach(cb => {

package/dist/esm/features/page_view_timing/aggregate/index.js

@@ -29,9 +29,10 @@ export class Aggregate extends AggregateBase {
   #handleVitalMetric = ({
     name,
     value,
-    attrs
+    attrs,
+    relativeTimestamp
   }) => {
-    this.addTiming(name, value, attrs);
+    this.addTiming(name, value, attrs, relativeTimestamp);
   };
   constructor(agentRef) {
     super(agentRef, FEATURE_NAME);
@@ -43,7 +44,7 @@ export class Aggregate extends AggregateBase {
     this.obfuscator = new Obfuscator(agentRef, EVENT_TYPES.PVT);
     registerHandler('docHidden', msTimestamp => this.endCurrentSession(msTimestamp), this.featureName, this.ee);
     // Add the time of _window pagehide event_ firing to the next PVT harvest == NRDB windowUnload attr:
-    registerHandler('winPagehide', msTimestamp => this.addTiming('unload', msTimestamp, null), this.featureName, this.ee);
+    registerHandler('winPagehide', msTimestamp => this.addTiming('unload', msTimestamp), this.featureName, this.ee);
     this.waitForFlags([]).then(() => {
       firstPaint.subscribe(this.#handleVitalMetric);
       firstContentfulPaint.subscribe(this.#handleVitalMetric);
@@ -62,10 +63,11 @@ export class Aggregate extends AggregateBase {
         const {
           name,
           value,
-          attrs
+          attrs,
+          relativeTimestamp
         } = cumulativeLayoutShift.current;
         if (value === undefined) return;
-        this.addTiming(name, value * 1000, attrs);
+        this.addTiming(name, value * 1000, attrs, relativeTimestamp);
       }, true, true); // CLS node should only report on vis change rather than on every change.
       /* NOTE: the capture=true is required -- empirically verified against a real browser (Chrome) for CLS
       timing node to reliably be in the same final harvest as the rest, alongside Harvester#startTimer's
@@ -83,12 +85,25 @@ export class Aggregate extends AggregateBase {
   endCurrentSession(timestamp) {
     if (!this.curSessEndRecorded) {
       // TO DO: stage 2 - we don't want to capture this timing twice on page navigating away, but it should run again if we return to page and away *again*
-      this.addTiming('pageHide', timestamp, null);
+      this.addTiming('pageHide', timestamp);
       this.curSessEndRecorded = true;
     }
   }
-  addTiming(name, value, attrs) {
-    attrs = attrs || {};
+
+  /**
+   * Records a page view timing node, decorating it with system attributes (page URL, connection info,
+   * CLS-so-far, webdriver detection, and a server-corrected absolute timestamp) before buffering it for harvest.
+   * @param {string} name The timing node's name (e.g. 'fp', 'fcp', 'lcp', 'cls', 'fi', 'pageHide', 'unload').
+   * @param {number} value The timing node's value; a ms offset from page origin for most nodes, a duration for
+   * 'inp', and a unitless score for 'cls'.
+   * @param {object} [attrs] Additional custom attributes to attach to the node.
+   * @param {number} [relativeTimestamp] The ms offset from page origin at which the underlying event occurred. It is
+   * server-corrected into the node's absolute `timestamp` attribute, which is omitted if the time keeper isn't ready
+   * or this isn't a finite number. Supplied by VitalMetric for nodes whose `value` isn't itself the event's time
+   * (e.g. 'inp' uses the interaction time, 'cls' uses the largest shift time). Defaults to `value`.
+   * @returns {{name: string, value: number, attrs: object}} The recorded timing node.
+   */
+  addTiming(name, value, attrs = {}, relativeTimestamp = value) {
     attrs.pageUrl = cleanURL(getNavigationEntry()?.name || initialLocation);
     addConnectionAttributes(attrs); // network conditions may differ from the actual for VitalMetrics when they were captured
 
@@ -104,6 +119,10 @@ export class Aggregate extends AggregateBase {
       attrs.cls = cumulativeLayoutShift.current.value;
     }
     attrs.webdriverDetected = webdriverDetected;
+    const timeKeeper = this.agentRef.runtime.timeKeeper;
+    if (timeKeeper?.ready && Number.isFinite(relativeTimestamp)) {
+      attrs.timestamp = Math.floor(timeKeeper.correctRelativeTimestamp(relativeTimestamp));
+    }
     const timing = {
       name,
       value,
@@ -134,7 +153,7 @@ export class Aggregate extends AggregateBase {
     });
   }
   #getGlobalCustomAttributes() {
-    const reservedAttributes = ['size', 'eid', 'cls', 'type', 'fid', 'elTag', 'elUrl', 'net-type', 'net-etype', 'net-rtt', 'net-dlink', 'webdriverDetected'];
+    const reservedAttributes = ['size', 'eid', 'cls', 'type', 'fid', 'elTag', 'elUrl', 'net-type', 'net-etype', 'net-rtt', 'net-dlink', 'webdriverDetected', 'timestamp'];
     return Object.fromEntries(Object.entries(this.agentRef.info.jsAttributes || {}).filter(([key]) => !reservedAttributes.includes(key)));
   }
   preHarvestChecks() {

package/dist/types/common/vitals/vital-metric.d.ts

@@ -1,16 +1,19 @@
-/**
- * Copyright 2020-2026 New Relic, Inc. All rights reserved.
- * SPDX-License-Identifier: Apache-2.0
- */
 export class VitalMetric {
     constructor(name: any, roundingMethod: any);
     history: any[];
     name: any;
     attrs: {};
     roundingMethod: any;
+    /**
+     * Records a new value for this metric and notifies subscribers.
+     * @param {object} params
+     * @param {number} params.value The metric's value. For most metrics this is itself a ms offset from page origin
+     * (i.e. the metric's own real time of occurrence); for score-based metrics like CLS it isn't a time at all.
+     * @param {object} [params.attrs] Metric-specific attribution attrs.
+     */
     update({ value, attrs }: {
-        value: any;
-        attrs?: {} | undefined;
+        value: number;
+        attrs?: object | undefined;
     }): void;
     get current(): any;
     get isValid(): boolean;

package/dist/types/common/vitals/vital-metric.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vital-metric.d.ts","sourceRoot":"","sources":["../../../../src/common/vitals/vital-metric.js"],"names":[],"mappings":"AAAA;;;GAGG;AACH;IAIE,4CAIC;IAND,eAAY;IAGV,UAAgB;IAChB,UAAe;IACf,oBAAwF;IAG1F;;;aAiBC;IAED,mBAMC;IAED,uBAEC;IAED,uEAMC;;CACF"}
+{"version":3,"file":"vital-metric.d.ts","sourceRoot":"","sources":["../../../../src/common/vitals/vital-metric.js"],"names":[],"mappings":"AAMA;IAIE,4CAIC;IAND,eAAY;IAGV,UAAgB;IAChB,UAAe;IACf,oBAAwF;IAG1F;;;;;;OAMG;IACH,yBAJG;QAAuB,KAAK,EAApB,MAAM;QAEU,KAAK;KAC/B,QAoBA;IAED,mBAMC;IAED,uBAEC;IAED,uEAMC;;CACF"}

package/dist/types/features/page_view_timing/aggregate/index.d.ts

@@ -9,10 +9,23 @@ export class Aggregate extends AggregateBase {
      * @param {number} timestamp
      */
     endCurrentSession(timestamp: number): void;
-    addTiming(name: any, value: any, attrs: any): {
-        name: any;
-        value: any;
-        attrs: any;
+    /**
+     * Records a page view timing node, decorating it with system attributes (page URL, connection info,
+     * CLS-so-far, webdriver detection, and a server-corrected absolute timestamp) before buffering it for harvest.
+     * @param {string} name The timing node's name (e.g. 'fp', 'fcp', 'lcp', 'cls', 'fi', 'pageHide', 'unload').
+     * @param {number} value The timing node's value; a ms offset from page origin for most nodes, a duration for
+     * 'inp', and a unitless score for 'cls'.
+     * @param {object} [attrs] Additional custom attributes to attach to the node.
+     * @param {number} [relativeTimestamp] The ms offset from page origin at which the underlying event occurred. It is
+     * server-corrected into the node's absolute `timestamp` attribute, which is omitted if the time keeper isn't ready
+     * or this isn't a finite number. Supplied by VitalMetric for nodes whose `value` isn't itself the event's time
+     * (e.g. 'inp' uses the interaction time, 'cls' uses the largest shift time). Defaults to `value`.
+     * @returns {{name: string, value: number, attrs: object}} The recorded timing node.
+     */
+    addTiming(name: string, value: number, attrs?: object, relativeTimestamp?: number): {
+        name: string;
+        value: number;
+        attrs: object;
     };
     /**
      * Checks the performance API to see if the agent can set a first interaction event value

package/dist/types/features/page_view_timing/aggregate/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/features/page_view_timing/aggregate/index.js"],"names":[],"mappings":"AA2BA;IACE,2BAAiC;IAMjC,2BAmCC;IAjCC,4BAA+B;IAC/B,0BAA6B;IAK7B,uBAA2D;IA6B7D;;;OAGG;IACH,6BAFW,MAAM,QAOhB;IAED;;;;MAiCC;IAED;;;OAGG;IACH,4BAFa,IAAI,CAahB;IAWD,4BAGC;IAGD,qCA8BC;;CACF;8BA1K6B,4BAA4B;2BAC/B,gCAAgC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/features/page_view_timing/aggregate/index.js"],"names":[],"mappings":"AA2BA;IACE,2BAAiC;IAMjC,2BAmCC;IAjCC,4BAA+B;IAC/B,0BAA6B;IAK7B,uBAA2D;IA6B7D;;;OAGG;IACH,6BAFW,MAAM,QAOhB;IAED;;;;;;;;;;;;OAYG;IACH,gBAVW,MAAM,SACN,MAAM,UAEN,MAAM,sBACN,MAAM,GAIJ;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAuCxD;IAED;;;OAGG;IACH,4BAFa,IAAI,CAahB;IAWD,4BAGC;IAGD,qCA8BC;;CACF;8BA3L6B,4BAA4B;2BAC/B,gCAAgC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newrelic/browser-agent",
-  "version": "1.324.1-rc.2",
+  "version": "1.324.1-rc.3",
   "private": false,
   "author": "New Relic Browser Agent Team <browser-agent@newrelic.com>",
   "description": "New Relic Browser Agent",

package/src/common/vitals/vital-metric.js

@@ -2,6 +2,8 @@
  * Copyright 2020-2026 New Relic, Inc. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
+import { now } from '../timing/now'
+
 export class VitalMetric {
   #subscribers = new Set()
   history = []
@@ -12,13 +14,22 @@ export class VitalMetric {
     this.roundingMethod = typeof roundingMethod === 'function' ? roundingMethod : Math.floor
   }
 
+  /**
+   * Records a new value for this metric and notifies subscribers.
+   * @param {object} params
+   * @param {number} params.value The metric's value. For most metrics this is itself a ms offset from page origin
+   * (i.e. the metric's own real time of occurrence); for score-based metrics like CLS it isn't a time at all.
+   * @param {object} [params.attrs] Metric-specific attribution attrs.
+   */
   update ({ value, attrs = {} }) {
     if (value === undefined || value === null || value < 0) return
+    const metricTimestamps = { inp: attrs.interactionTime ?? now(), cls: attrs.largestShiftTime ?? now() }
     const state = {
       value: this.roundingMethod(value),
       name: this.name,
       // optional web-vitals attribution fields are omitted rather than being serialized as null attributes
-      attrs: Object.fromEntries(Object.entries(attrs).filter(([, attrValue]) => attrValue !== undefined))
+      attrs: Object.fromEntries(Object.entries(attrs).filter(([, attrValue]) => attrValue !== undefined)),
+      relativeTimestamp: metricTimestamps[this.name] ?? value
     }
 
     this.history.push(state)

package/src/features/page_view_timing/aggregate/index.js

@@ -28,8 +28,8 @@ import { createStringAdders } from '../../../common/payloads/payloads'
 export class Aggregate extends AggregateBase {
   static featureName = FEATURE_NAME
 
-  #handleVitalMetric = ({ name, value, attrs }) => {
-    this.addTiming(name, value, attrs)
+  #handleVitalMetric = ({ name, value, attrs, relativeTimestamp }) => {
+    this.addTiming(name, value, attrs, relativeTimestamp)
   }
 
   constructor (agentRef) {
@@ -44,7 +44,7 @@ export class Aggregate extends AggregateBase {
 
     registerHandler('docHidden', msTimestamp => this.endCurrentSession(msTimestamp), this.featureName, this.ee)
     // Add the time of _window pagehide event_ firing to the next PVT harvest == NRDB windowUnload attr:
-    registerHandler('winPagehide', msTimestamp => this.addTiming('unload', msTimestamp, null), this.featureName, this.ee)
+    registerHandler('winPagehide', msTimestamp => this.addTiming('unload', msTimestamp), this.featureName, this.ee)
 
     this.waitForFlags(([])).then(() => {
       firstPaint.subscribe(this.#handleVitalMetric)
@@ -56,9 +56,9 @@ export class Aggregate extends AggregateBase {
         /* Downstream, the event consumer interprets all timing node value as ms-unit and converts it to seconds via division by 1000. CLS is unitless so this normally is a problem.
           bel.6 schema also doesn't support decimal values, of which cls within [0,1). However, the two nicely cancels out, and we can multiply cls by 1000 to both negate the division
           and send an integer > 1. We effectively lose some precision down to 3 decimal places for this workaround. E.g. (real) 0.749132... -> 749.132...-> 749 -> 0.749 (final) */
-        const { name, value, attrs } = cumulativeLayoutShift.current
+        const { name, value, attrs, relativeTimestamp } = cumulativeLayoutShift.current
         if (value === undefined) return
-        this.addTiming(name, value * 1000, attrs)
+        this.addTiming(name, value * 1000, attrs, relativeTimestamp)
       }, true, true) // CLS node should only report on vis change rather than on every change.
       /* NOTE: the capture=true is required -- empirically verified against a real browser (Chrome) for CLS
       timing node to reliably be in the same final harvest as the rest, alongside Harvester#startTimer's
@@ -75,13 +75,25 @@ export class Aggregate extends AggregateBase {
    */
   endCurrentSession (timestamp) {
     if (!this.curSessEndRecorded) { // TO DO: stage 2 - we don't want to capture this timing twice on page navigating away, but it should run again if we return to page and away *again*
-      this.addTiming('pageHide', timestamp, null)
+      this.addTiming('pageHide', timestamp)
       this.curSessEndRecorded = true
     }
   }
 
-  addTiming (name, value, attrs) {
-    attrs = attrs || {}
+  /**
+   * Records a page view timing node, decorating it with system attributes (page URL, connection info,
+   * CLS-so-far, webdriver detection, and a server-corrected absolute timestamp) before buffering it for harvest.
+   * @param {string} name The timing node's name (e.g. 'fp', 'fcp', 'lcp', 'cls', 'fi', 'pageHide', 'unload').
+   * @param {number} value The timing node's value; a ms offset from page origin for most nodes, a duration for
+   * 'inp', and a unitless score for 'cls'.
+   * @param {object} [attrs] Additional custom attributes to attach to the node.
+   * @param {number} [relativeTimestamp] The ms offset from page origin at which the underlying event occurred. It is
+   * server-corrected into the node's absolute `timestamp` attribute, which is omitted if the time keeper isn't ready
+   * or this isn't a finite number. Supplied by VitalMetric for nodes whose `value` isn't itself the event's time
+   * (e.g. 'inp' uses the interaction time, 'cls' uses the largest shift time). Defaults to `value`.
+   * @returns {{name: string, value: number, attrs: object}} The recorded timing node.
+   */
+  addTiming (name, value, attrs = {}, relativeTimestamp = value) {
     attrs.pageUrl = cleanURL(getNavigationEntry()?.name || initialLocation)
 
     addConnectionAttributes(attrs) // network conditions may differ from the actual for VitalMetrics when they were captured
@@ -100,6 +112,11 @@ export class Aggregate extends AggregateBase {
 
     attrs.webdriverDetected = webdriverDetected
 
+    const timeKeeper = this.agentRef.runtime.timeKeeper
+    if (timeKeeper?.ready && Number.isFinite(relativeTimestamp)) {
+      attrs.timestamp = Math.floor(timeKeeper.correctRelativeTimestamp(relativeTimestamp))
+    }
+
     const timing = {
       name,
       value,
@@ -134,7 +151,7 @@ export class Aggregate extends AggregateBase {
 
   #getGlobalCustomAttributes () {
     const reservedAttributes = ['size', 'eid', 'cls', 'type', 'fid', 'elTag', 'elUrl', 'net-type',
-      'net-etype', 'net-rtt', 'net-dlink', 'webdriverDetected']
+      'net-etype', 'net-rtt', 'net-dlink', 'webdriverDetected', 'timestamp']
 
     return Object.fromEntries(
       Object.entries(this.agentRef.info.jsAttributes || {}).filter(([key]) => !reservedAttributes.includes(key))