Experimental Soft Navigation support

README.md

@@ -299,6 +299,67 @@ _**Note:** the first time the `callback` function is called, its `value` and `de
 
 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.
+- FID is reset to measure the first interaction after the soft navigation.
+- 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,
+  onFID,
+  onLCP,
+} from 'https://unpkg.com/web-vitals@soft-navs/dist/web-vitals.js?module';
+
+onCLS(console.log, {reportSoftNavs: true});
+onFID(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,
+  onFID,
+  onLCP,
+} from 'https://unpkg.com/web-vitals@soft-navs/dist/web-vitals.js?module';
+
+onCLS(doTraditionalProcessing);
+onFID(doTraditionalProcessing);
+onLCP(doTraditionalProcessing);
+
+onCLS(doSoftNavProcessing, {reportSoftNavs: true});
+onFID(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.
@@ -724,7 +785,14 @@ interface Metric {
     | 'back-forward'
     | 'back-forward-cache'
     | 'prerender'
-    | 'restore';
+    | 'restore'
+    | 'soft-navigation';
+
+  /**
+   * The URL the metric happened for. This is particularly relevent for soft navigations where
+   * the metric may be reported for a previous URL.
+   */
+  pageUrl: string;
 }
 ```
 
@@ -784,6 +852,7 @@ Metric-specific subclasses:
 interface ReportOpts {
   reportAllChanges?: boolean;
   durationThreshold?: number;
+  reportSoftNavs?: boolean;
 }
 ```
 

src/lib/initMetric.ts

@@ -20,11 +20,18 @@ import {getActivationStart} from './getActivationStart.js';
 import {getNavigationEntry} from './getNavigationEntry.js';
 import {Metric} from '../types.js';
 
-export const initMetric = (name: Metric['name'], value?: number): Metric => {
+export const initMetric = (
+  name: Metric['name'],
+  value?: number,
+  navigation?: Metric['navigationType']
+): Metric => {
   const navEntry = getNavigationEntry();
   let navigationType: Metric['navigationType'] = 'navigate';
 
-  if (getBFCacheRestoreTime() >= 0) {
+  if (navigation) {
+    // If it was passed in, then use that
+    navigationType = navigation;
+  } else if (getBFCacheRestoreTime() >= 0) {
     navigationType = 'back-forward-cache';
   } else if (navEntry) {
     if (document.prerendering || getActivationStart() > 0) {
@@ -47,5 +54,6 @@ export const initMetric = (name: Metric['name'], value?: number): Metric => {
     entries: [],
     id: generateUniqueID(),
     navigationType,
+    pageUrl: window.location.href,
   };
 };

src/lib/observe.ts

@@ -27,6 +27,7 @@ interface PerformanceEntryMap {
   'first-input': PerformanceEventTiming[] | FirstInputPolyfillEntry[];
   'navigation': PerformanceNavigationTiming[] | NavigationTimingPolyfillEntry[];
   'resource': PerformanceResourceTiming[];
+  'soft-navigation': SoftNavigationEntry[];
 }
 
 /**

src/lib/polyfills/firstInputPolyfill.ts

@@ -88,7 +88,7 @@ const reportFirstInputDelayIfRecordedAndValid = () => {
       processingStart: firstInputEvent!.timeStamp + firstInputDelay,
     } as FirstInputPolyfillEntry;
     callbacks.forEach(function (callback) {
-      callback(entry);
+      callback([entry]);
     });
     callbacks = [];
   }

src/lib/softNavs.ts

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2023 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {ReportOpts} from '../types.js';
+
+let softNavsEnabled: boolean | undefined;
+
+export const softNavs = (opts?: ReportOpts) => {
+  if (typeof softNavsEnabled !== 'undefined') return softNavsEnabled;
+  return (softNavsEnabled =
+    PerformanceObserver.supportedEntryTypes.includes('soft-navigation') &&
+    opts?.reportSoftNavs);
+};

src/onCLS.ts

@@ -21,8 +21,9 @@ import {bindReporter} from './lib/bindReporter.js';
 import {doubleRAF} from './lib/doubleRAF.js';
 import {onHidden} from './lib/onHidden.js';
 import {runOnce} from './lib/runOnce.js';
+import {softNavs} from './lib/softNavs.js';
 import {onFCP} from './onFCP.js';
-import {CLSMetric, CLSReportCallback, ReportOpts} from './types.js';
+import {CLSMetric, CLSReportCallback, Metric, ReportOpts} from './types.js';
 
 /**
  * Calculates the [CLS](https://web.dev/cls/) value for the current page and
@@ -48,6 +49,8 @@ import {CLSMetric, CLSReportCallback, ReportOpts} from './types.js';
 export const onCLS = (onReport: CLSReportCallback, opts?: ReportOpts) => {
   // Set defaults
   opts = opts || {};
+  let currentNav = 1;
+  const softNavsEnabled = softNavs(opts);
 
   // Start monitoring FCP so we can only report CLS if FCP is also reported.
   // Note: this is done to match the current behavior of CrUX.
@@ -62,9 +65,52 @@ export const onCLS = (onReport: CLSReportCallback, opts?: ReportOpts) => {
       let sessionValue = 0;
       let sessionEntries: PerformanceEntry[] = [];
 
+      const initNewCLSMetric = (navigation?: Metric['navigationType']) => {
+        metric = initMetric('CLS', 0, navigation);
+        report = bindReporter(
+          onReport,
+          metric,
+          thresholds,
+          opts!.reportAllChanges
+        );
+        sessionValue = 0;
+        sessionEntries = [];
+      };
+
       // const handleEntries = (entries: Metric['entries']) => {
       const handleEntries = (entries: LayoutShift[]) => {
+        let pageUrl = '';
         entries.forEach((entry) => {
+          if (
+            softNavsEnabled &&
+            entry.navigationId &&
+            entry.navigationId > currentNav
+          ) {
+            // If we've a pageUrl, then we've already done some updates  to the values.
+            // update the Metric.
+            if (pageUrl != '') {
+              // If the current session value is larger than the current CLS value,
+              // update CLS and the entries contributing to it.
+              if (sessionValue > metric.value) {
+                metric.value = sessionValue;
+                metric.entries = sessionEntries;
+                metric.pageUrl = pageUrl;
+              }
+            }
+            report(true);
+            initNewCLSMetric('soft-navigation');
+            currentNav = entry.navigationId;
+          }
+
+          if (entry.navigationId === 1 || !entry.navigationId) {
+            pageUrl = performance.getEntriesByType('navigation')[0].name;
+          } else {
+            pageUrl =
+              performance.getEntriesByType('soft-navigation')[
+                entry.navigationId - 2
+              ]?.name;
+          }
+
           // Only count layout shifts without recent user input.
           if (!entry.hadRecentInput) {
             const firstSessionEntry = sessionEntries[0];
@@ -93,6 +139,7 @@ export const onCLS = (onReport: CLSReportCallback, opts?: ReportOpts) => {
         if (sessionValue > metric.value) {
           metric.value = sessionValue;
           metric.entries = sessionEntries;
+          metric.pageUrl = pageUrl;
           report();
         }
       };
@@ -126,6 +173,30 @@ export const onCLS = (onReport: CLSReportCallback, opts?: ReportOpts) => {
           doubleRAF(() => report());
         });
 
+        const reportSoftNavCLS = (entries: SoftNavigationEntry[]) => {
+          entries.forEach((entry) => {
+            if (entry.navigationId) {
+              report(true);
+              metric = initMetric('CLS', 0, 'soft-navigation');
+              metric.pageUrl =
+                performance.getEntriesByType('soft-navigation')[
+                  entry.navigationId - 2
+                ]?.name;
+              report = bindReporter(
+                onReport,
+                metric,
+                thresholds,
+                opts!.reportAllChanges
+              );
+              currentNav = entry.navigationId;
+            }
+          });
+        };
+
+        if (softNavs(opts)) {
+          observe('soft-navigation', reportSoftNavCLS);
+        }
+
         // Queue a task to report (if nothing else triggers a report first).
         // This allows CLS to be reported as soon as FCP fires when
         // `reportAllChanges` is true.

src/onFCP.ts

@@ -21,8 +21,9 @@ import {getActivationStart} from './lib/getActivationStart.js';
 import {getVisibilityWatcher} from './lib/getVisibilityWatcher.js';
 import {initMetric} from './lib/initMetric.js';
 import {observe} from './lib/observe.js';
+import {softNavs} from './lib/softNavs.js';
 import {whenActivated} from './lib/whenActivated.js';
-import {FCPMetric, FCPReportCallback, ReportOpts} from './types.js';
+import {FCPMetric, Metric, FCPReportCallback, ReportOpts} from './types.js';
 
 /**
  * Calculates the [FCP](https://web.dev/fcp/) value for the current page and
@@ -33,6 +34,7 @@ import {FCPMetric, FCPReportCallback, ReportOpts} from './types.js';
 export const onFCP = (onReport: FCPReportCallback, opts?: ReportOpts) => {
   // Set defaults
   opts = opts || {};
+  const softNavsEnabled = softNavs(opts);
 
   whenActivated(() => {
     // https://web.dev/fcp/#what-is-a-good-fcp-score
@@ -42,19 +44,54 @@ export const onFCP = (onReport: FCPReportCallback, opts?: ReportOpts) => {
     let metric = initMetric('FCP');
     let report: ReturnType<typeof bindReporter>;
 
+    const initNewFCPMetric = (navigation?: Metric['navigationType']) => {
+      metric = initMetric('FCP', 0, navigation);
+      report = bindReporter(
+        onReport,
+        metric,
+        thresholds,
+        opts!.reportAllChanges
+      );
+    };
+
     const handleEntries = (entries: FCPMetric['entries']) => {
       (entries as PerformancePaintTiming[]).forEach((entry) => {
         if (entry.name === 'first-contentful-paint') {
-          po!.disconnect();
+          if (!softNavsEnabled) {
+            po!.disconnect();
+          } else if (entry.navigationId) {
+            initNewFCPMetric('soft-navigation');
+          }
 
-          // Only report if the page wasn't hidden prior to the first paint.
-          if (entry.startTime < visibilityWatcher.firstHiddenTime) {
+          let value = 0;
+          let pageUrl = '';
+
+          if (entry.navigationId === 1 || !entry.navigationId) {
+            // Only report if the page wasn't hidden prior to the first paint.
             // The activationStart reference is used because FCP should be
             // relative to page activation rather than navigation start if the
             // page was prerendered. But in cases where `activationStart` occurs
             // after the FCP, this time should be clamped at 0.
-            metric.value = Math.max(entry.startTime - getActivationStart(), 0);
+            value = Math.max(entry.startTime - getActivationStart(), 0);
+            pageUrl = performance.getEntriesByType('navigation')[0].name;
+          } else {
+            const navEntry =
+              performance.getEntriesByType('soft-navigation')[
+                entry.navigationId - 2
+              ];
+            const navStartTime = navEntry?.startTime || 0;
+            // As a soft nav needs an interaction, it should never be before
+            // getActivationStart so can just cap to 0
+            value = Math.max(entry.startTime - navStartTime, 0);
+            pageUrl = navEntry?.name;
+          }
+
+          // Only report if the page wasn't hidden prior to FCP.
+          if (entry.startTime < visibilityWatcher.firstHiddenTime) {
+            metric.value = value;
             metric.entries.push(entry);
+            metric.pageUrl = pageUrl;
+            // FCP should only be reported once so can report right
             report(true);
           }
         }