@newrelic/browser-agent 1.319.0 → 1.320.0

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.320.0](https://github.com/newrelic/newrelic-browser-agent/compare/v1.319.0...v1.320.0) (2026-08-07)
+
+
+### Features
+
+* Improve ability to apply reasonable caps to MFE vitals ([#1823](https://github.com/newrelic/newrelic-browser-agent/issues/1823)) ([df72604](https://github.com/newrelic/newrelic-browser-agent/commit/df7260404dee51cf3706311235ab9b0d785f8789))
+* MFE iframe support - Beta Access ([#1752](https://github.com/newrelic/newrelic-browser-agent/issues/1752)) ([46e36f7](https://github.com/newrelic/newrelic-browser-agent/commit/46e36f77abbad70155f20755cd4554799125e334))
+
+
+### Bug Fixes
+
+* Deduplicate auto-instrumented MFE events ([#1820](https://github.com/newrelic/newrelic-browser-agent/issues/1820)) ([ba60ac6](https://github.com/newrelic/newrelic-browser-agent/commit/ba60ac6550d93feb466af845a8f3f3fdb03b4970))
+
 ## [1.319.0](https://github.com/newrelic/newrelic-browser-agent/compare/v1.318.0...v1.319.0) (2026-07-28)
 
 

package/dist/cjs/common/config/init.js

@@ -29,7 +29,9 @@ const InitModelFn = () => {
     feature_flags: [],
     experimental: {
       register: false,
-      resources: false
+      resources: false,
+      iframe_bridge: false,
+      iframe_domains: []
     },
     mask_selector: '*',
     block_selector: '[data-nr-block]',
@@ -69,7 +71,20 @@ const InitModelFn = () => {
         set enabled(val) {
           hiddenState.experimental.register = val;
         },
-        duplicate_data_to_container: false
+        duplicate_data_to_container: false,
+        // experimental iframe bridge feature
+        get allow_iframe_bridge() {
+          return hiddenState.feature_flags.includes(_constants.FEATURE_FLAGS.IFRAME_BRIDGE) || hiddenState.experimental.iframe_bridge;
+        },
+        set allow_iframe_bridge(val) {
+          hiddenState.experimental.iframe_bridge = val;
+        },
+        get iframe_domains() {
+          return hiddenState.experimental.iframe_domains;
+        },
+        set iframe_domains(val) {
+          if (Array.isArray(val)) hiddenState.experimental.iframe_domains = val;else (0, _console.warn)(1, val);
+        }
       }
     },
     browser_consent_mode: {

package/dist/cjs/common/config/runtime.js

@@ -63,7 +63,8 @@ const RuntimeModel = {
   },
   get harvestCount() {
     return ++_harvestCount;
-  }
+  },
+  listeningForIframeMessages: false
 };
 const mergeRuntime = runtime => {
   const modeledObject = (0, _configurable.getModeledObject)(runtime, RuntimeModel);

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.319.0";
+const VERSION = exports.VERSION = "1.320.0";
 
 /**
  * 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.319.0";
+const VERSION = exports.VERSION = "1.320.0";
 
 /**
  * Exposes the build type of the agent

package/dist/cjs/common/constants/iframe-constants.js

@@ -0,0 +1,16 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.prefix = exports.IFRAME_VITALS_UPDATE = exports.IFRAME_TIMING_UPDATE = exports.IFRAME_API_RESPONSE = exports.IFRAME_API = exports.IFRAME_AJAX = void 0;
+/**
+ * Copyright 2020-2026 New Relic, Inc. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const prefix = exports.prefix = 'newrelic-iframe-';
+const IFRAME_TIMING_UPDATE = exports.IFRAME_TIMING_UPDATE = prefix + 'timing-update';
+const IFRAME_API = exports.IFRAME_API = prefix + 'api';
+const IFRAME_API_RESPONSE = exports.IFRAME_API_RESPONSE = prefix + 'api-response';
+const IFRAME_VITALS_UPDATE = exports.IFRAME_VITALS_UPDATE = prefix + 'vitals-update';
+const IFRAME_AJAX = exports.IFRAME_AJAX = prefix + 'ajax';

package/dist/cjs/common/url/add-url.js

@@ -0,0 +1,23 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.addUrl = addUrl;
+var _parseUrl = require("./parse-url.js");
+/**
+ * Copyright 2020-2026 New Relic, Inc. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+function addUrl(ctx, url) {
+  var parsed = (0, _parseUrl.parseUrl)(url);
+  var params = ctx.params || ctx;
+  params.hostname = parsed.hostname;
+  params.port = parsed.port;
+  params.protocol = parsed.protocol;
+  params.host = parsed.hostname + ':' + parsed.port;
+  params.pathname = parsed.pathname;
+  ctx.parsedOrigin = parsed;
+  ctx.sameOrigin = parsed.sameOrigin;
+}

package/dist/cjs/common/util/console.js

@@ -21,39 +21,39 @@ var _globalEvent = require("../dispatch/global-event");
  *
  * | Code | Message |
  * |------|---------|
- * | 1 | An error occurred while setting a property of a Configurable |
- * | 2 | An error occurred while setting a Configurable |
- * | 3 | Setting a Configurable requires an object as input |
- * | 4 | Setting a Configurable requires a model to set its initial properties |
+ * | 1 | An error occurred while setting a property of a Configurable. |
+ * | 2 | An error occurred while setting a Configurable. |
+ * | 3 | Setting a Configurable requires an object as input. |
+ * | 4 | Setting a Configurable requires a model to set its initial properties. |
  * | 5 | An invalid session_replay.mask_selector was provided. \* will be used. |
- * | 6 | An invalid session_replay.block_selector was provided and will not be used |
- * | 7 | An invalid session_replay.mask_input_option was provided and will not be used |
- * | 8 | Shared context requires an object as input |
- * | 9 | An error occurred while setting SharedContext |
- * | 10 | Failed to read from storage API |
- * | 11 | Failed to write to the storage API |
+ * | 6 | An invalid session_replay.block_selector was provided and will not be used. |
+ * | 7 | An invalid session_replay.mask_input_option was provided and will not be used. |
+ * | 8 | Shared context requires an object as input. |
+ * | 9 | An error occurred while setting SharedContext. |
+ * | 10 | Failed to read from storage API. |
+ * | 11 | Failed to write to the storage API. |
  * | 12 | An obfuscation replacement rule was detected missing a "regex" value. |
- * | 13 | An obfuscation replacement rule contains a "regex" value with an invalid type (must be a string or RegExp) |
- * | 14 | An obfuscation replacement rule contains a "replacement" value with an invalid type (must be a string) |
- * | 15 | An error occurred while intercepting XHR |
- * | 16 | Could not cast log message to string |
+ * | 13 | An obfuscation replacement rule contains a "regex" value with an invalid type (must be a string or RegExp). |
+ * | 14 | An obfuscation replacement rule contains a "replacement" value with an invalid type (must be a string). |
+ * | 15 | An error occurred while intercepting XHR. |
+ * | 16 | Could not cast log message to string. |
  * | 17 | Could not calculate New Relic server time. Agent shutting down. |
  * | 18 | RUM call failed. Agent shutting down. |
  * | 19 | SPA scheduler is not initialized. Saved interaction is not sent! |
  * | 20 | A problem occurred when starting up session manager. This page will not start or extend any session. |
  * | 21 | Failed to initialize the agent. Could not determine the runtime environment. |
  * | 22 | Failed to initialize all enabled instrument classes (agent aborted) - |
- * | 23 | An unexpected issue occurred |
+ * | 23 | An unexpected issue occurred. |
  * | 24 | Something prevented the agent from instrumenting. |
  * | 25 | Something prevented the agent from being downloaded. |
  * | 26 | Failed to initialize instrument classes. |
  * | 27 | Downloading runtime APIs failed... |
  * | 28 | The Browser Agent is attempting to send a very large payload. This is usually tied to large amounts of custom attributes. Please check your configurations. |
- * | 29 | Failed to wrap logger: invalid argument(s) |
- * | 30 | Invalid log level |
- * | 31 | Ignored log: Log is larger than maximum payload size |
- * | 32 | Ignored log: Invalid message |
- * | 33 | Session Replay Aborted |
+ * | 29 | Failed to wrap logger: invalid argument(s). |
+ * | 30 | Invalid log level. |
+ * | 31 | Ignored log: Log is larger than maximum payload size. |
+ * | 32 | Ignored log: Invalid message. |
+ * | 33 | Session Replay Aborted. |
  * | 34 | Downloading and initializing a feature failed... |
  * | 35 | Call to agent api failed. The API is not currently initialized. |
  * | 36 | A feature is enabled but one or more dependent features have not been initialized. This may cause unintended consequences or missing data... |
@@ -62,7 +62,7 @@ var _globalEvent = require("../dispatch/global-event");
  * | 39 | Failed to execute setCustomAttribute. Name must be a string type. |
  * | 40 | Failed to execute setCustomAttribute. Non-null value must be a string, number or boolean type. |
  * | 41 | Failed to execute setUserId. Non-null value must be a string type. |
- * | 42 | Failed to execute setApplicationVersion. Expected <String \| null> |
+ * | 42 | Failed to execute setApplicationVersion. Expected <String \| null>. |
  * | 43 | Agent not configured properly. |
  * | 44 | Invalid object passed to generic event aggregate. Missing "eventType". |
  * | 45 | An internal agent process failed to execute. |
@@ -71,27 +71,34 @@ var _globalEvent = require("../dispatch/global-event");
  * | 48 | Supplied an invalid API target. Must be an <Object> that contains valid (string) id and name properties. |
  * | 49 | Supplied API target is missing an entityGuid. Some APIs may not behave correctly without a valid entityGuid (ex. logs). |
  * | 50 | Failed to connect. Cannot allow registered API. |
- * | 51 | Container agent is not available to register with. Can not connect |
+ * | 51 | Container agent is not available to register with. Can not connect. |
  * | 52 | Unexpected problem encountered. There should be at least one app for harvest! |
- * | 53 | Did not receive a valid entityGuid from connection response |
- * | 54 | An experimental feature is being used. Support can not be offered for issues |
- * | 55 | Register API has been disabled on the container agent |
- * | 56 | Could not find a matching entity to store data |
+ * | 53 | Did not receive a valid entityGuid from connection response. |
+ * | 54 | An experimental feature is being used. Support can not be offered for issues. |
+ * | 55 | Register API has been disabled on the container agent. |
+ * | 56 | Could not find a matching entity to store data. |
  * | 57 | Failed to execute measure. Arguments must have valid types. |
  * | 58 | Failed to execute measure. Resulting duration must be non-negative. |
- * | 59 | Session replay harvested before a session trace payload could be sent. This could be problematic for replays that rely on a trace |
- * | 60 | Session trace aborted |
+ * | 59 | Session replay harvested before a session trace payload could be sent. This could be problematic for replays that rely on a trace. |
+ * | 60 | Session trace aborted. |
  * | 61 | Timestamps must be non-negative and end time cannot be before start time. |
- * | 62 | Timestamp must be a unix timestamp greater than the page origin time |
- * | 63 | A single event was larger than the maximum allowed payload size |
+ * | 62 | Timestamp must be a unix timestamp greater than the page origin time. |
+ * | 63 | A single event was larger than the maximum allowed payload size. |
  * | 64 | Required globals have been mutated before being accessed by the browser agent. This can cause issues and should be avoided. |
- * | 65 | Consent API argument must be boolean or undefined |
- * | 66 | A new agent session has started |
+ * | 65 | Consent API argument must be boolean or undefined. |
+ * | 66 | A new agent session has started. |
  * | 67 | The "spa" feature has been deprecated and disabled. Please use/import "soft_navigations" instead for tracking of BrowserInteraction data. |
  * | 68 | API has been deregistered and can no longer be used. Call "register" API again with credentials to start over. |
- * | 69 | More than one Browser agent is running on the page |
+ * | 69 | More than one Browser agent is running on the page. |
  * | 70 | A session replay payload failed to send and is being retried. Recording is paused during the retry period, and will resume when a successful harvest is made. Some replay activity may be missed during retry phases. |
  * | 71 | An invalid feature mode was detected and set to "off". |
+ * | 72 | RegisteredIframeEntity failed to transmit API data from an iframe to window context. |
+ * | 73 | RegisteredIframeEntity failed to register with window context. |
+ * | 74 | RegisteredIframeEntity rejected message from unauthorized origin. |
+ * | 75 | RegisteredIframeEntity rejected message with mismatched iframeInterfaceId. |
+ * | 76 | Agent rejected post message, could not match with existing entity. |
+ * | 77 | Agent rejected post message, could not validate origin. |
+ * | 78 | RegisteredIframeEntity could not determine parent origin and will not register, to avoid trusting messages from any origin. |
  *
  * @param {number} code The warning code to emit, which will be used to link to the warning code documentation
  * @param {*} [secondary] Secondary data to include, usually an extra message, error or object

package/dist/cjs/common/v2/mfe-vitals.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.trackMFEVitals = trackMFEVitals;
 var _runtime = require("../constants/runtime");
 var _now = require("../timing/now");
+var _scriptTrackerConstants = require("./script-tracker-constants");
 /**
  * Copyright 2020-2026 New Relic, Inc. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
@@ -139,11 +140,17 @@ function trackMFEVitals(target, timings) {
     fcp: {
       get value() {
         return getTimeRelativeToScriptStart(fcpObservedAt);
+      },
+      set value(v) {
+        fcpObservedAt = v;
       }
     },
     lcp: {
       get value() {
         return getTimeRelativeToScriptStart(lcpObservedAt);
+      },
+      set value(v) {
+        lcpObservedAt = v;
       }
     },
     cls: {
@@ -157,11 +164,11 @@ function trackMFEVitals(target, timings) {
   if (!target || !_runtime.isBrowserScope || !_runtime.globalScope.MutationObserver || !_runtime.globalScope.PerformanceObserver) return vitals;
   const observers = [];
 
-  // If FCP hasn't been observed within 10 seconds, give up and shut down all observers.
+  // If FCP hasn't been observed within this window, give up and shut down all observers.
   // Once FCP is observed, the other vitals are left to record until their natural lifespan ends.
   setTimeout(() => {
     if (!fcpObservedAt) vitals.disconnect();
-  }, 10000);
+  }, _scriptTrackerConstants.CORRELATION_STALE_THRESHOLD_MS);
   const populateVitalMinimums = () => {
     fcpObservedAt ??= (0, _now.now)();
     lcpObservedAt ??= (0, _now.now)();

package/dist/cjs/common/v2/script-correlation.js

@@ -24,6 +24,8 @@ class ScriptCorrelation {
   constructor(url) {
     /** @type {string} The cleaned URL of the script */
     this.url = url;
+    /** @type {Set<string>} MFE target ids that have already claimed this correlation via a completed `findScriptTimings()` call. Keyed per target rather than a single flag so one script that registers multiple distinct MFEs (each with its own id) doesn't have the second MFE's registration mistaken for a stale reuse of the first's. */
+    this.claimedBy = new Set();
   }
 
   /**

package/dist/cjs/common/v2/script-tracker-constants.js

@@ -0,0 +1,13 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.CORRELATION_STALE_THRESHOLD_MS = void 0;
+/**
+ * Copyright 2020-2026 New Relic, Inc. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** @type {number} - Correlations are keyed only by script URL and never cleared per-registration, so a script registered more than once in a session (SPA remount, shared bundle, etc.) can reuse a correlation from a much earlier load. If the correlation's recorded start predates `registeredAt` by more than this, treat it as stale and fall back to `registeredAt`. */
+const CORRELATION_STALE_THRESHOLD_MS = exports.CORRELATION_STALE_THRESHOLD_MS = 10000;

package/dist/cjs/common/v2/script-tracker.js

@@ -12,6 +12,8 @@ var _now = require("../timing/now");
 var _cleanUrl = require("../url/clean-url");
 var _browserStackMatchers = require("../util/browser-stack-matchers");
 var _scriptCorrelation = require("./script-correlation");
+var _scriptTrackerConstants = require("./script-tracker-constants");
+var _timingFactory = require("./timing-factory");
 /**
  * Copyright 2020-2026 New Relic, Inc. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
@@ -19,6 +21,7 @@ var _scriptCorrelation = require("./script-correlation");
 
 /**
  * @typedef {import('./register-api-types').RegisterAPITimings} RegisterAPITimings
+ * @typedef {import('../../loaders/api/register-api-types').RegisterAPITarget} RegisterAPITarget
  */
 
 /** export for testing purposes */
@@ -30,7 +33,7 @@ try {
 }
 
 /** @type {(entry: PerformanceEntry) => boolean} - A shared function to determine if a performance entry is a valid script or link resource for evaluation */
-const validEntryCriteria = entry => entry.initiatorType === 'script' || ['link', 'fetch'].includes(entry.initiatorType) && entry.name.endsWith('.js');
+const validEntryCriteria = entry => entry.initiatorType === 'script' || ['link', 'fetch'].includes(entry.initiatorType) && (0, _cleanUrl.cleanURL)(entry.name).endsWith('.js');
 
 /** @type {Map<string, ScriptCorrelation>} - Central registry for script correlations containing both DOM and Performance data */
 const scriptCorrelations = exports.scriptCorrelations = new Map();
@@ -205,11 +208,32 @@ function applyPerformanceEntry(timings, entry) {
   timings.type = entry.initiatorType;
 }
 
+/**
+ * Subscribes to late resource timing emissions for a script URL.
+ * @param {RegisterAPITimings} timings - The timings object to update
+ * @param {string} mfeScriptUrl - The script URL to match
+ */
+function subscribeToLatePerformanceEntry(timings, mfeScriptUrl) {
+  if (!_runtime.globalScope.PerformanceObserver?.supportedEntryTypes?.includes('resource')) return;
+  poSubscribers.push({
+    addedAt: (0, _now.now)(),
+    test: entry => {
+      if (entryMatchesUrl(entry, mfeScriptUrl)) {
+        applyPerformanceEntry(timings, entry);
+        return true;
+      }
+      return false;
+    }
+  });
+}
+
 /**
  * Uses the stack of the initiator function, returns script timing information if a script can be found with the resource timing API matching the URL found in the stack.
+ * @param {RegisterAPITarget} [target] - The MFE target being registered. Its id is used to scope stale-correlation detection per-MFE rather than per-script-URL, so one script registering multiple distinct MFEs doesn't misclassify a later MFE's registration as a stale reuse of an earlier one's.
  * @returns {RegisterAPITimings} Object containing script fetch start and end times, and the asset URL if found
  */
-function findScriptTimings() {
+function findScriptTimings(target) {
+  const mfeId = target?.id;
   const timings = {
     registeredAt: (0, _now.now)(),
     reportedAt: undefined,
@@ -239,38 +263,39 @@ function findScriptTimings() {
     // Get correlation data
     timings.correlation = findCorrelation(mfeScriptUrl);
 
-    // Use correlation's performance entry if available, otherwise check live performance API
-    const performanceEntry = timings.correlation?.performance.value || performance.getEntriesByType('resource').find(e => entryMatchesUrl(e, mfeScriptUrl));
+    // Use correlation's performance entry if available, otherwise check the live performance API before falling back to the buffered observer.
+    const performanceEntry = timings.correlation?.performance.value || _runtime.globalScope.performance?.getEntriesByType('resource')?.find(e => entryMatchesUrl(e, mfeScriptUrl));
     if (performanceEntry) {
       applyPerformanceEntry(timings, performanceEntry);
-    } else if (wasPreloaded(mfeScriptUrl)) {
-      // Handle preloaded scripts that may report late
-      timings.asset = mfeScriptUrl;
-      timings.type = 'preload';
+    } else {
+      const isPreloaded = wasPreloaded(mfeScriptUrl);
 
-      // Subscribe to late performance observer callbacks
-      poSubscribers.push({
-        addedAt: (0, _now.now)(),
-        test: entry => {
-          if (entryMatchesUrl(entry, mfeScriptUrl)) {
-            applyPerformanceEntry(timings, entry);
-            return true;
-          }
-          return false;
-        }
-      });
+      // Handle preloaded scripts and any late resource emissions through the shared buffered observer.
+      if (isPreloaded) {
+        timings.asset = mfeScriptUrl;
+        timings.type = 'preload';
+      }
+      subscribeToLatePerformanceEntry(timings, mfeScriptUrl);
     }
 
-    /*
-     * Use getters here because the correlation data may arrive after this function returns the timing object, and we want to provide the most up-to-date timing information possible when the getters are accessed at harvest time.
-     * The getters will fall back to fetchEnd if correlation data isn't available yet, which is our best approximation for script execution start when actual script timings can not be determined.
-    */
-    Object.defineProperty(timings, 'scriptStart', {
-      get: () => timings.correlation?.script.start || timings.fetchEnd
-    });
-    Object.defineProperty(timings, 'scriptEnd', {
-      get: () => timings.correlation?.script.end || timings.registeredAt
-    });
+    // A correlation can be reused across multiple `register()` calls for the same script URL (e.g. an SPA
+    // remounting the same MFE without the script actually reloading). When that happens, its dom/performance
+    // timings still describe the *original* load, not this one. Detect that case so scriptStart/scriptEnd
+    // below can ignore the stale data instead of reporting it as if it were fresh.
+    const correlation = timings.correlation;
+    const alreadyClaimedByThisMFE = !!mfeId && !!correlation?.claimedBy.has(mfeId);
+    if (correlation && mfeId) correlation.claimedBy.add(mfeId);
+    const isCorrelationStale = () => {
+      const correlationStart = correlation?.script.start;
+      if (!alreadyClaimedByThisMFE || !correlationStart) return false;
+      const staleness = timings.registeredAt - correlationStart;
+      return staleness > _scriptTrackerConstants.CORRELATION_STALE_THRESHOLD_MS;
+    };
+
+    // Use getters here because the correlation data may arrive after this function returns the timing object, and we want to provide the most up-to-date timing information possible when the getters are accessed at harvest time.
+    // Non-stale: fall back to fetchEnd if correlation data isn't available yet (our best approximation for script execution start). Stale: fall back straight to registeredAt — fetchEnd would be derived from the same stale correlation, so it can't be trusted either.
+    Object.defineProperty(timings, 'scriptStart', (0, _timingFactory.timingFactory)(() => isCorrelationStale() ? timings.registeredAt : correlation?.script.start ?? timings.fetchEnd));
+    Object.defineProperty(timings, 'scriptEnd', (0, _timingFactory.timingFactory)(() => isCorrelationStale() ? timings.registeredAt : correlation?.script.end ?? timings.registeredAt));
   } catch (error) {
     // Don't let stack parsing errors break anything
   }

package/dist/cjs/common/v2/timing-factory.js

@@ -0,0 +1,18 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.timingFactory = timingFactory;
+/**
+ * Copyright 2020-2026 New Relic, Inc. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+function timingFactory(getLazyValue = () => {}, override) {
+  return {
+    get: () => override !== undefined ? override : getLazyValue(),
+    set: newValue => {
+      override = newValue;
+    }
+  };
+}

package/dist/cjs/common/v2/utils.js

@@ -4,7 +4,10 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.V2_TYPES = void 0;
+exports.dedupeRegisteredEntitiesByAsset = dedupeRegisteredEntitiesByAsset;
+exports.dedupeTargetsByInstance = dedupeTargetsByInstance;
 exports.findTargetsFromStackTrace = findTargetsFromStackTrace;
+exports.getRegisteredEntityByIframeInterfaceId = getRegisteredEntityByIframeInterfaceId;
 exports.getRegisteredTargetsFromFilename = getRegisteredTargetsFromFilename;
 exports.getRegisteredTargetsFromId = getRegisteredTargetsFromId;
 exports.getVersion2Attributes = getVersion2Attributes;
@@ -27,6 +30,18 @@ const V2_TYPES = exports.V2_TYPES = {
   BA: 'BA'
 };
 
+/**
+ * Returns a single registered entity associated with a given iframe interface ID. Returns undefined if no entity is found.
+ * @param {string} iframeInterfaceId
+ * @param {*} agentRef the agent reference
+ * @returns {import("../../loaders/api/register-api-types").RegisterAPI|undefined}
+ */
+function getRegisteredEntityByIframeInterfaceId(iframeInterfaceId, agentRef) {
+  if (!isValid(iframeInterfaceId, agentRef)) return undefined;
+  const registeredEntities = agentRef.runtime.registeredEntities;
+  return registeredEntities?.find(entity => entity.metadata.target.iframeInterfaceId === iframeInterfaceId);
+}
+
 /**
  * Returns the registered target associated with a given ID. Returns an empty array if no target is found.
  * @param {string|number} id
@@ -34,21 +49,69 @@ const V2_TYPES = exports.V2_TYPES = {
  * @returns {import("../../interfaces/registered-entity").RegisterAPIMetadataTarget[]}
  */
 function getRegisteredTargetsFromId(id, agentRef) {
-  if (!id || !agentRef?.init.api.register.enabled) return [];
+  if (!isValid(id, agentRef)) return [];
   const registeredEntities = agentRef.runtime.registeredEntities;
   return registeredEntities?.filter(entity => String(entity.metadata.target.id) === String(id)).map(entity => entity.metadata.target) || [];
 }
 
 /**
  * Returns the registered target(s) associated with a given filename if found in the resource timing API during registration. Returns an empty array if no target is found.
+ * Multiple registrations that resolve to the same underlying script asset AND represent the same logical MFE (i.e.
+ * share the same customer-supplied `target.id`) are collapsed to a single target via
+ * {@link dedupeRegisteredEntitiesByAsset}, since auto-instrumented events (AJAX, JS errors, logs, WebSockets) should
+ * only be reported once per real occurrence when the same MFE was registered many times over -- not once per
+ * duplicate registration. Distinct MFEs (different `target.id`) that happen to share a script (e.g. two different
+ * MFEs both registered from the same inline `<script>` block) are intentionally NOT collapsed, since each is a
+ * genuinely different entity that should still receive its own copy of the matched event.
  * @param {string} filename
  * @param {*} agentRef
  * @returns {import("../../interfaces/registered-entity").RegisterAPIMetadataTarget[]}
  */
 function getRegisteredTargetsFromFilename(filename, agentRef) {
-  if (!filename || !agentRef?.init.api.register.enabled) return [];
+  if (!isValid(filename, agentRef)) return [];
   const registeredEntities = agentRef.runtime.registeredEntities;
-  return registeredEntities?.filter(entity => entity.metadata.timings?.asset?.endsWith(filename)).map(entity => entity.metadata.target) || [];
+  const matches = registeredEntities?.filter(entity => entity.metadata.timings?.asset?.endsWith(filename));
+  return dedupeRegisteredEntitiesByAsset(matches).map(entity => entity.metadata.target);
+}
+
+/**
+ * Collapses a list of registered entities down to one canonical entity per unique, defined `metadata.timings.asset` +
+ * `target.id` combination. Entities whose asset could not be resolved (undefined -- e.g. inline scripts or scripts
+ * not found in the resource timing buffer) are never deduped against each other or against resolved entities, since
+ * there is no signal that they represent the same underlying script. Entities that share an asset but have different
+ * `target.id`s are never deduped against each other either, since a differing id means the customer registered
+ * genuinely distinct MFEs (not duplicate registrations of the same one).
+ *
+ * Canonical selection per asset+id: prefer an entity whose target has not been deregistered (`target.blocked ===
+ * false`) over one that has; otherwise the first-encountered entity wins, for determinism.
+ * @param {Array} entities registered entities (each with `metadata.timings.asset` and `metadata.target`)
+ * @returns {Array} deduped list of entities, preserving relative order of first occurrence
+ */
+function dedupeRegisteredEntitiesByAsset(entities) {
+  if (!entities?.length) return entities || [];
+  const byKey = new Map(); // `${asset}::${id}` -> canonical entity
+  const result = [];
+  for (const entity of entities) {
+    const asset = entity.metadata?.timings?.asset;
+    if (!asset) {
+      // can't safely dedupe unresolved-asset entities -- always keep as-is
+      result.push(entity);
+      continue;
+    }
+    const key = "".concat(asset, "::").concat(entity.metadata?.target?.id);
+    const existing = byKey.get(key);
+    if (!existing) {
+      byKey.set(key, entity);
+      result.push(entity);
+    } else if (existing.metadata.target?.blocked && !entity.metadata.target?.blocked) {
+      // swap in a non-deregistered target as the canonical one for this asset+id
+      const idx = result.indexOf(existing);
+      if (idx !== -1) result[idx] = entity;
+      byKey.set(key, entity);
+    }
+    // else: existing canonical entity wins (already non-blocked, or both blocked -- first wins); drop this duplicate
+  }
+  return result;
 }
 
 /**
@@ -107,7 +170,7 @@ function shouldDuplicate(target, aggregateInstance) {
  * @returns {Array} An array of targets found from the stack trace. If no targets are found or allowed, returns an array with undefined.
  */
 function findTargetsFromStackTrace(agentRef) {
-  if (!agentRef?.init.api.register.enabled || !agentRef?.runtime?.registeredEntities?.length) return [undefined];
+  if (!isValid(true, agentRef) || !agentRef?.runtime?.registeredEntities?.length) return [undefined];
   const targets = [];
   try {
     var urls = (0, _scriptTracker.extractUrlsFromStack)((0, _scriptTracker.getDeepStackTrace)());
@@ -118,8 +181,29 @@ function findTargetsFromStackTrace(agentRef) {
   } catch (err) {
     // Silent catch to prevent errors from propagating
   }
-  if (!targets.length) targets.push(undefined); // if we can't find any targets from the stack trace, return an array with undefined to signify the container agent is the target
-  return targets;
+  const deduped = dedupeTargetsByInstance(targets);
+  if (!deduped.length) deduped.push(undefined); // if we can't find any targets from the stack trace, return an array with undefined to signify the container agent is the target
+  return deduped;
+}
+
+/**
+ * Removes duplicate targets from an array, keyed by `target.instance`. This guards against the same canonical
+ * target re-entering the array via multiple matched stack-frame URLs (e.g. a recursive call whose stack contains the
+ * same file at multiple depths). Entries with no `instance` (i.e. `undefined`, meaning "the container agent")
+ * naturally collapse to a single entry too, which is the desired behavior.
+ * @param {Array} targets
+ * @returns {Array} deduped list of targets, preserving relative order of first occurrence
+ */
+function dedupeTargetsByInstance(targets) {
+  const seen = new Set();
+  const result = [];
+  for (const target of targets) {
+    const key = target?.instance;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(target);
+  }
+  return result;
 }
 
 /**
@@ -131,4 +215,14 @@ function findTargetsFromStackTrace(agentRef) {
  */
 function supportsV2(aggregateInstance) {
   return aggregateInstance?.harvestEndpointVersion === 2;
+}
+
+/**
+ * Determines if the given identifier and agent reference are valid for use for entity lookups and other operations in the utils methods. This is a common check that is used across multiple methods in this module to ensure that the necessary data is present and that the register API is enabled before attempting to perform operations that depend on those things.
+ * @param {*} identifier The identifier to check.
+ * @param {*} agentRef The agent reference to check.
+ * @returns {boolean} Returns true if the identifier and agent reference are valid, false otherwise.
+ */
+function isValid(identifier, agentRef) {
+  return !!identifier && !!agentRef?.init.api.register.enabled;
 }