fix(browser): Reduce number of visibilitystate and pagehide listeners (#18581)

Previously, we called `onHidden` in our slightly modified version of the
vendored in `whenIdleOrHidden` API from web-vitals. This caused 2
additional event listeners to be registered with each `whenIdleOrHidden`
invocation, which also didn't get cleaned up properly.

To fix this, and prevent similar situations, this PR:
- inlines the `pagehide` event listener registration in
`whenIdleOrHidden` so that we can remove the `onHidden` call
- adds `once: true` to the listener registration so that the callback is
only invoked once
- deprecates `onHidden` because IMHO we should remove it in v11 and
replace the one remaining use of it with a direct `visibilityChange`
subscription.

Closes #18584 (added automatically)

closes
https://linear.app/getsentry/issue/JS-1339/investigate-multiple-event-listeners-in-nextjs-sdk

Author: Lms24

packages/browser-utils/src/metrics/utils.ts

@@ -218,6 +218,7 @@ export function listenForWebVitalReportEvents(
     collected = true;
   }
 
+  // eslint-disable-next-line deprecation/deprecation
   onHidden(() => {
     _runCollectorCallbackOnce('pagehide');
   });

packages/browser-utils/src/metrics/web-vitals/lib/onHidden.ts

@@ -21,25 +21,37 @@ export interface OnHiddenCallback {
   (event: Event): void;
 }
 
-// Sentry-specific change:
-// This function's logic was NOT updated to web-vitals 4.2.4 or 5.x but we continue
-// to use the web-vitals 3.5.2 versiondue to us having stricter browser support.
-// PR with context that made the changes: https://github.com/GoogleChrome/web-vitals/pull/442/files#r1530492402
-// The PR removed listening to the `pagehide` event, in favour of only listening to `visibilitychange` event.
-// This is "more correct" but some browsers we still support (Safari <14.4) don't fully support `visibilitychange`
-// or have known bugs w.r.t the `visibilitychange` event.
-// TODO (v11): If we decide to drop support for Safari 14.4, we can use the logic from web-vitals 4.2.4
-// In this case, we also need to update the integration tests that currently trigger the `pagehide` event to
-// simulate the page being hidden.
+/**
+ * Sentry-specific change:
+ *
+ * This function's logic was NOT updated to web-vitals 4.2.4 or 5.x but we continue
+ * to use the web-vitals 3.5.2 version due to having stricter browser support.
+ *
+ * PR with context that made the changes:
+ * https://github.com/GoogleChrome/web-vitals/pull/442/files#r1530492402
+ *
+ * The PR removed listening to the `pagehide` event, in favour of only listening to
+ * the `visibilitychange` event. This is "more correct" but some browsers we still
+ * support (Safari <14.4) don't fully support `visibilitychange` or have known bugs
+ * with respect to the `visibilitychange` event.
+ *
+ * TODO (v11): If we decide to drop support for Safari 14.4, we can use the logic
+ * from web-vitals 4.2.4. In this case, we also need to update the integration tests
+ * that currently trigger the `pagehide` event to simulate the page being hidden.
+ *
+ * @param {OnHiddenCallback} cb - Callback to be executed when the page is hidden or unloaded.
+ *
+ * @deprecated use `whenIdleOrHidden` or `addPageListener('visibilitychange')` instead
+ */
 export const onHidden = (cb: OnHiddenCallback) => {
   const onHiddenOrPageHide = (event: Event) => {
     if (event.type === 'pagehide' || WINDOW.document?.visibilityState === 'hidden') {
       cb(event);
     }
   };
 
-  addPageListener('visibilitychange', onHiddenOrPageHide, true);
+  addPageListener('visibilitychange', onHiddenOrPageHide, { capture: true, once: true });
   // Some browsers have buggy implementations of visibilitychange,
   // so we use pagehide in addition, just to be safe.
-  addPageListener('pagehide', onHiddenOrPageHide, true);
+  addPageListener('pagehide', onHiddenOrPageHide, { capture: true, once: true });
 };

packages/browser-utils/src/metrics/web-vitals/lib/whenIdleOrHidden.ts

@@ -16,7 +16,6 @@
 
 import { WINDOW } from '../../../types.js';
 import { addPageListener, removePageListener } from './globalListeners.js';
-import { onHidden } from './onHidden.js';
 import { runOnce } from './runOnce.js';
 
 /**
@@ -34,15 +33,18 @@ export const whenIdleOrHidden = (cb: () => void) => {
     // eslint-disable-next-line no-param-reassign
     cb = runOnce(cb);
     addPageListener('visibilitychange', cb, { once: true, capture: true });
+    // sentry: we use pagehide instead of directly listening to visibilitychange
+    // because some browsers we still support (Safari <14.4) don't fully support
+    // `visibilitychange` or have known bugs w.r.t the `visibilitychange` event.
+    // TODO(v11): remove this once we drop support for Safari <14.4
+    addPageListener('pagehide', cb, { once: true, capture: true });
     rIC(() => {
       cb();
       // Remove the above event listener since no longer required.
       // See: https://github.com/GoogleChrome/web-vitals/issues/622
       removePageListener('visibilitychange', cb, { capture: true });
+      // TODO(v11): remove this once we drop support for Safari <14.4
+      removePageListener('pagehide', cb, { capture: true });
     });
-    // sentry: we use onHidden instead of directly listening to visibilitychange
-    // because some browsers we still support (Safari <14.4) don't fully support
-    // `visibilitychange` or have known bugs w.r.t the `visibilitychange` event.
-    onHidden(cb);
   }
 };