Experimental Soft Navigation support

README.md

@@ -252,6 +252,66 @@ onLCP(logDelta);
 
 In addition to using the `id` field to group multiple deltas for the same metric, it can also be used to differentiate different metrics reported on the same page. For example, after a back/forward cache restore, a new metric object is created with a new `id` (since back/forward cache restores are considered separate page visits).
 
+### Report metrics for soft navigations (experimental)
+
+_**Note:** this is experimental and subject to change._
+
+Currently Core Web Vitals are only tracked for full page navigations, which can affect how [Single Page Applications](https://web.dev/vitals-spa-faq/) that use so called "soft navigations" to update the browser URL and history outside of the normal browser's handling of this. The Chrome team are experimenting with being able to [measure these soft navigations](https://github.com/WICG/soft-navigations) separately and report on Core Web Vitals separately for them.
+
+This experimental support allows sites to measure how their Core Web Vitals might be measured differently should this happen.
+
+At present a "soft navigation" is defined as happening after the following three things happen:
+
+- A user interaction occurs
+- The URL changes
+- Content is added to the DOM
+- Something is painted to screen.
+
+For some sites, these heuristics may lead to false positives (that users would not really consider a "navigation"), or false negatives (where the user does consider a navigation to have happened despite not missing the above criteria). We welcome feedback at https://github.com/WICG/soft-navigations/issues on the heuristics, at https://crbug.com for bugs in the Chrome implementation, and on [https://github.com/GoogleChrome/web-vitals/pull/308](this pull request) for implementation issues with web-vitals.js.
+
+_**Note:** At this time it is not known if this experiment will be something we want to move forward with. Until such time, this support will likely remain in a separate branch of this project, rather than be included in any production builds. If we decide not to move forward with this, the support of this will likely be removed from this project since this library is intended to mirror the Core Web Vitals as much as possible._
+
+Some important points to note:
+
+- TTFB is reported as 0, and not the time of the first network call (if any) after the soft navigation.
+- FCP and LCP are the first and largest contentful paints after the soft navigation. Prior reported paint times will not be counted for these metrics, even though these elements may remain between soft navigations, and may be the first or largest contentful item.
+- INP is reset to measure only interactions after the the soft navigation.
+- CLS is reset to measure again separate to the first page.
+
+_**Note:** It is not known at this time whether soft navigations will be weighted the same as full navigations. No weighting is included in this library at present and metrics are reported in the same way as full page load metrics._
+
+The metrics can be reported for Soft Navigations using the `reportSoftNavs: true` reporting option:
+
+```js
+import {
+  onCLS,
+  onINP,
+  onLCP,
+} from 'https://unpkg.com/web-vitals@soft-navs/dist/web-vitals.js?module';
+
+onCLS(console.log, {reportSoftNavs: true});
+onINP(console.log, {reportSoftNavs: true});
+onLCP(console.log, {reportSoftNavs: true});
+```
+
+Note that this will change the way the first page loads are measured as the metrics for the inital URL will be finalized once the first soft nav occurs. To measure both you need to register two callbacks:
+
+```js
+import {
+  onCLS,
+  onINP,
+  onLCP,
+} from 'https://unpkg.com/web-vitals@soft-navs/dist/web-vitals.js?module';
+
+onCLS(doTraditionalProcessing);
+onINP(doTraditionalProcessing);
+onLCP(doTraditionalProcessing);
+
+onCLS(doSoftNavProcessing, {reportSoftNavs: true});
+onINP(doSoftNavProcessing, {reportSoftNavs: true});
+onLCP(doSoftNavProcessing, {reportSoftNavs: true});
+```
+
 ### Send the results to an analytics endpoint
 
 The following example measures each of the Core Web Vitals metrics and reports them to a hypothetical `/analytics` endpoint, as soon as each is ready to be sent.
@@ -546,14 +606,28 @@ interface Metric {
    * - 'prerender': for pages that were prerendered.
    * - 'restore': for pages that were discarded by the browser and then
    * restored by the user.
+   * - 'soft-navigation': for soft navigations.
    */
   navigationType:
     | 'navigate'
     | 'reload'
     | 'back-forward'
     | 'back-forward-cache'
     | 'prerender'
-    | 'restore';
+    | 'restore'
+    | 'soft-navigation';
+
+  /**
+   * The navigationId the metric happened for. This is particularly relevant for soft navigations where
+   * the metric may be reported for a previous URL.
+   */
+  navigationId: number;
+
+  /**
+   * The navigation URL the metric happened for. This is particularly relevant for soft navigations where
+   * the metric may be reported for a previous URL.
+   */
+  navigationURL?: string;
 }
 ```
 
@@ -591,7 +665,7 @@ interface INPMetric extends Metric {
 ```ts
 interface LCPMetric extends Metric {
   name: 'LCP';
-  entries: LargestContentfulPaint[];
+  entries: (LargestContentfulPaint | InteractionContentfulPaint)[];
 }
 ```
 
@@ -660,6 +734,7 @@ Metric-specific subclasses:
 interface INPAttributionReportOpts extends AttributionReportOpts {
   durationThreshold?: number;
   includeProcessedEventEntries?: boolean;
+  reportSoftNavs?: boolean;
 }
 ```
 
@@ -1091,9 +1166,10 @@ interface LCPAttribution {
    */
   lcpResourceEntry?: PerformanceResourceTiming;
   /**
-   * The `LargestContentfulPaint` entry corresponding to LCP.
+   * The `LargestContentfulPaint` entry corresponding to LCP
+   * (or `InteractionContentfulPaint` for soft navigations).
    */
-  lcpEntry?: LargestContentfulPaint;
+  lcpEntry?: LargestContentfulPaint | InteractionContentfulPaint;
 }
 ```
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-vitals",
-  "version": "5.2.0",
+  "version": "5.2.0-soft-navs-2",
   "description": "Easily measure performance metrics in JavaScript",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"

src/attribution/onFCP.ts

@@ -17,6 +17,7 @@
 import {getBFCacheRestoreTime} from '../lib/bfcache.js';
 import {getLoadState} from '../lib/getLoadState.js';
 import {getNavigationEntry} from '../lib/getNavigationEntry.js';
+import {getSoftNavigationEntry} from '../lib/softNavs.js';
 import {onFCP as unattributedOnFCP} from '../onFCP.js';
 import {
   FCPAttribution,
@@ -26,6 +27,7 @@ import {
 } from '../types.js';
 
 const attributeFCP = (metric: FCPMetric): FCPMetricWithAttribution => {
+  const hardNavId = getNavigationEntry()?.navigationId || 0;
   // Use a default object if no other attribution has been set.
   let attribution: FCPAttribution = {
     timeToFirstByte: 0,
@@ -34,13 +36,26 @@ const attributeFCP = (metric: FCPMetric): FCPMetricWithAttribution => {
   };
 
   if (metric.entries.length) {
-    const navigationEntry = getNavigationEntry();
+    let navigationEntry;
     const fcpEntry = metric.entries.at(-1);
 
-    if (navigationEntry) {
-      const activationStart = navigationEntry.activationStart || 0;
-      const ttfb = Math.max(0, navigationEntry.responseStart - activationStart);
+    let ttfb = 0;
+    let softNavStart = 0;
+    if (!metric.navigationId || metric.navigationId === hardNavId) {
+      navigationEntry = getNavigationEntry();
+      if (navigationEntry) {
+        const responseStart = navigationEntry.responseStart;
+        const activationStart = navigationEntry.activationStart || 0;
+        ttfb = Math.max(0, responseStart - activationStart);
+      }
+    } else {
+      navigationEntry = getSoftNavigationEntry(metric.navigationId);
+      // Set ttfb to the SoftNav start time
+      softNavStart = navigationEntry ? navigationEntry.startTime : 0;
+      ttfb = softNavStart;
+    }
 
+    if (navigationEntry) {
       attribution = {
         timeToFirstByte: ttfb,
         firstByteToFCP: metric.value - ttfb,

src/attribution/onINP.ts

@@ -436,7 +436,7 @@ export const onINP = (
   };
 
   // Start observing LoAF entries for attribution.
-  observe('long-animation-frame', handleLoAFEntries);
+  observe('long-animation-frame', handleLoAFEntries, opts);
 
   unattributedOnINP((metric: INPMetric) => {
     onReport(attributeINP(metric));

src/attribution/onLCP.ts

@@ -15,6 +15,7 @@
  */
 
 import {getNavigationEntry} from '../lib/getNavigationEntry.js';
+import {getSoftNavigationEntry} from '../lib/softNavs.js';
 import {getSelector} from '../lib/getSelector.js';
 import {initUnique} from '../lib/initUnique.js';
 import {LCPEntryManager} from '../lib/LCPEntryManager.js';
@@ -48,10 +49,13 @@ export const onLCP = (
   opts = Object.assign({}, opts);
 
   const lcpEntryManager = initUnique(opts, LCPEntryManager);
-  const lcpTargetMap: WeakMap<LargestContentfulPaint, string> = new WeakMap();
+  const lcpTargetMap: WeakMap<
+    LargestContentfulPaint | InteractionContentfulPaint,
+    string
+  > = new WeakMap();
 
   lcpEntryManager._onBeforeProcessingEntry = (
-    entry: LargestContentfulPaint,
+    entry: LargestContentfulPaint | InteractionContentfulPaint,
   ) => {
     const node = entry.element;
     if (node) {
@@ -65,6 +69,7 @@ export const onLCP = (
   };
 
   const attributeLCP = (metric: LCPMetric): LCPMetricWithAttribution => {
+    const hardNavId = getNavigationEntry()?.navigationId || 0;
     // Use a default object if no other attribution has been set.
     let attribution: LCPAttribution = {
       timeToFirstByte: 0,
@@ -94,14 +99,30 @@ export const onLCP = (
 
       // Get subparts from navigation entry. Do this last as occasionally
       // Safari seems to fail to find a navigation entry.
-      const navigationEntry = getNavigationEntry();
-      if (navigationEntry) {
-        const activationStart = navigationEntry.activationStart || 0;
+      let navigationEntry;
+      let activationStart = 0;
+      let responseStart = 0;
+      let softNavStart = 0;
 
-        const ttfb = Math.max(
-          0,
-          navigationEntry.responseStart - activationStart,
-        );
+      if (!metric.navigationId || metric.navigationId === hardNavId) {
+        navigationEntry = getNavigationEntry();
+        activationStart =
+          navigationEntry && navigationEntry.activationStart
+            ? navigationEntry.activationStart
+            : 0;
+        responseStart =
+          navigationEntry && navigationEntry.responseStart
+            ? navigationEntry.responseStart
+            : 0;
+      } else {
+        navigationEntry = getSoftNavigationEntry(metric.navigationId);
+        // Set activationStart to the SoftNav start time
+        softNavStart = navigationEntry ? navigationEntry.startTime : 0;
+        activationStart = softNavStart;
+      }
+
+      if (navigationEntry) {
+        const ttfb = Math.max(0, responseStart - activationStart);
 
         const lcpRequestStart = Math.max(
           ttfb,
@@ -115,10 +136,11 @@ export const onLCP = (
           // Cap at LCP time (videos continue downloading after LCP for example)
           metric.value,
           Math.max(
-            lcpRequestStart,
+            lcpRequestStart - softNavStart,
             lcpResourceEntry
               ? lcpResourceEntry.responseEnd - activationStart
               : 0,
+            0,
           ),
         );
 

src/attribution/onTTFB.ts

@@ -33,27 +33,30 @@ const attributeTTFB = (metric: TTFBMetric): TTFBMetricWithAttribution => {
   };
 
   if (metric.entries.length) {
-    const navigationEntry = metric.entries[0];
+    // Is there a better way to check if this is a soft nav entry or not?
+    // Refuses to build without this as soft navs don't have activationStart
+    const navigationEntry = <PerformanceNavigationTiming>metric.entries[0];
+
     const activationStart = navigationEntry.activationStart || 0;
 
     // Measure from workerStart or fetchStart so any service worker startup
     // time is included in cacheDuration (which also includes other sw time
     // anyway, that cannot be accurately split out cross-browser).
     const waitEnd = Math.max(
-      (navigationEntry.workerStart || navigationEntry.fetchStart) -
+      (navigationEntry.workerStart || navigationEntry.fetchStart || 0) -
         activationStart,
       0,
     );
     const dnsStart = Math.max(
-      navigationEntry.domainLookupStart - activationStart,
+      navigationEntry.domainLookupStart - activationStart || 0,
       0,
     );
     const connectStart = Math.max(
-      navigationEntry.connectStart - activationStart,
+      navigationEntry.connectStart - activationStart || 0,
       0,
     );
     const connectEnd = Math.max(
-      navigationEntry.connectEnd - activationStart,
+      navigationEntry.connectEnd - activationStart || 0,
       0,
     );
 

src/lib/LCPEntryManager.ts

@@ -15,9 +15,11 @@
  */
 
 export class LCPEntryManager {
-  _onBeforeProcessingEntry?: (entry: LargestContentfulPaint) => void;
+  _onBeforeProcessingEntry?: (
+    entry: LargestContentfulPaint | InteractionContentfulPaint,
+  ) => void;
 
-  _processEntry(entry: LargestContentfulPaint) {
+  _processEntry(entry: LargestContentfulPaint | InteractionContentfulPaint) {
     this._onBeforeProcessingEntry?.(entry);
   }
 }

src/lib/getLoadState.ts

@@ -23,22 +23,21 @@ export const getLoadState = (timestamp: number): LoadState => {
     // since the timestamp has to be the current time or earlier.
     return 'loading';
   }
-  const navigationEntry = getNavigationEntry();
-  if (navigationEntry) {
-    if (timestamp < navigationEntry.domInteractive) {
+
+  const hardNavEntry = getNavigationEntry();
+  if (hardNavEntry) {
+    if (timestamp < hardNavEntry.domInteractive) {
       return 'loading';
-    }
-    if (
-      navigationEntry.domContentLoadedEventStart === 0 ||
-      timestamp < navigationEntry.domContentLoadedEventStart
+    } else if (
+      hardNavEntry.domContentLoadedEventStart === 0 ||
+      timestamp < hardNavEntry.domContentLoadedEventStart
     ) {
       // If the `domContentLoadedEventStart` timestamp has not yet been
       // set, or if the given timestamp is less than that value.
       return 'dom-interactive';
-    }
-    if (
-      navigationEntry.domComplete === 0 ||
-      timestamp < navigationEntry.domComplete
+    } else if (
+      hardNavEntry.domComplete === 0 ||
+      timestamp < hardNavEntry.domComplete
     ) {
       // If the `domComplete` timestamp has not yet been
       // set, or if the given timestamp is less than that value.

src/lib/getVisibilityWatcher.ts

@@ -60,7 +60,10 @@ const onVisibilityUpdate = (event: Event) => {
   }
 };
 
-export const getVisibilityWatcher = () => {
+export const getVisibilityWatcher = (reset = false) => {
+  if (reset) {
+    firstHiddenTime = Infinity;
+  }
   if (firstHiddenTime < 0) {
     // Check if we have a previous hidden `visibility-state` performance entry.
     const activationStart = getActivationStart();