@newrelic/browser-agent 1.312.1 → 1.313.0

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

@@ -19,8 +19,9 @@ import { AggregateBase } from '../../utils/aggregate-base'
 import { now } from '../../../common/timing/now'
 import { applyFnToProps } from '../../../common/util/traverse'
 import { evaluateInternalError } from './internal-errors'
-import { getVersion2Attributes } from '../../../common/util/v2'
+import { getRegisteredTargetsFromFilename, getVersion2Attributes, getVersion2DuplicationAttributes, shouldDuplicate } from '../../../common/v2/utils'
 import { buildCauseString } from './cause-string'
+import { ShortCircuit } from '../../../common/util/short-circuit'
 
 /**
  * @typedef {import('./compute-stack-trace.js').StackInfo} StackInfo
@@ -38,8 +39,8 @@ export class Aggregate extends AggregateBase {
     this.pageviewReported = {}
     this.errorOnPage = false
 
-    register('err', (...args) => this.storeError(...args), this.featureName, this.ee)
-    register('ierr', (...args) => this.storeError(...args), this.featureName, this.ee)
+    register('err', this.processError.bind(this), this.featureName, this.ee)
+    register('ierr', this.processError.bind(this), this.featureName, this.ee)
     register('returnJserror', (jsErrorEvent, softNavAttrs) => this.#storeJserrorForHarvest(jsErrorEvent, softNavAttrs), this.featureName, this.ee)
 
     // 0 == off, 1 == on
@@ -74,43 +75,67 @@ export class Aggregate extends AggregateBase {
   }
 
   /**
-   * Builds a standardized stack trace string from the frames in the given `stackInfo` object, with each frame separated
-   * by a newline character. Lines take the form `<functionName>@<url>:<lineNumber>`.
+   * Main entry point for processing JavaScript errors. This method orchestrates the complete error processing pipeline.
    *
-   * @param {StackInfo} stackInfo - An object specifying a stack string and individual frames.
-   * @returns {string} A canonical stack string built from the URLs and function names in the given `stackInfo` object.
+   * Processing Flow:
+   * 1. Filter the error through the customer's onerror handler (if configured and not internal)
+   * 2. Compute the stack trace from the error object
+   * 3. Evaluate if the error should be swallowed (internal errors, known issues, etc.)
+   * 4. Derive target(s) for the error (MFE detection for v2 endpoints, or default target) - Note: "undefined" indicates the default target will be used
+   * 5. Store the error for each derived target. During storage (#storeJserrorForHarvest), duplication for MFE <-> container will be handled
+   *
+   * Important: "ShortCircuit" Pattern:
+   * Several steps in the pipeline can throw a ShortCircuit error to halt processing without
+   * treating it as a reportable error. This pattern is used when:
+   * - The customer's onerror handler returns a truthy value (excluding fingerprinting objects)
+   * - The error is identified as an internal error that shouldn't be reported
+   *
+   * When a ShortCircuit is thrown, processing stops immediately and the error is not stored.
+   * Any other thrown error is re-thrown as it represents an actual problem in the agent code.
+   *
+   * @param {Error|UncaughtError} err - The error instance to be processed
+   * @param {number} [time] - The relative ms (to origin) timestamp of occurrence. Defaults to now()
+   * @param {boolean} [internal=false] - If the error was "caught" and deemed "internal" before reporting to the jserrors feature
+   * @param {object} [customAttributes] - Any custom attributes to be included in the error payload
+   * @param {boolean} [hasReplay=false] - A flag indicating if the error occurred during a replay session
+   * @param {string} [swallowReason] - A string indicating pre-defined reason if swallowing the error. Mainly used by internal error supportability metrics
+   * @param {object} [target] - The target to buffer and harvest to. If undefined, the default configuration target is used
+   * @returns {void}
    */
-  buildCanonicalStackString (stackInfo) {
-    var canonicalStackString = ''
-
-    for (var i = 0; i < stackInfo.frames.length; i++) {
-      var frame = stackInfo.frames[i]
-      var func = canonicalFunctionName(frame.func)
-
-      if (canonicalStackString) canonicalStackString += '\n'
-      if (func) canonicalStackString += func + '@'
-      if (typeof frame.url === 'string') canonicalStackString += frame.url
-      if (frame.line) canonicalStackString += ':' + frame.line
+  processError (err, time, internal, customAttributes, hasReplay, swallowReason, target) {
+    if (!err) return
+    time = time || now()
+    try {
+      const filterOutput = this.#filterError(err, internal)
+      const stackInfo = computeStackTrace(err)
+      this.#swallowError(stackInfo, internal, swallowReason)
+      this.#deriveTargets(stackInfo, target).forEach(target => {
+        this.#storeError(err, time, stackInfo, filterOutput, customAttributes, hasReplay, target)
+      })
+    } catch (e) {
+      if (!(e instanceof ShortCircuit)) {
+        throw e
+      }
     }
-
-    return canonicalStackString
   }
 
   /**
+   * Filters an error through the customer's configured onerror handler.
    *
-   * @param {Error|UncaughtError} err The error instance to be processed
-   * @param {number} time the relative ms (to origin) timestamp of occurrence
-   * @param {boolean=} internal if the error was "caught" and deemed "internal" before reporting to the jserrors feature
-   * @param {object=} customAttributes  any custom attributes to be included in the error payload
-   * @param {boolean=} hasReplay a flag indicating if the error occurred during a replay session
-   * @param {string=} swallowReason a string indicating pre-defined reason if swallowing the error.  Mainly used by the internal error SMs.
-   * @param {object=} target the target to buffer and harvest to, if undefined the default configuration target is used
-   * @returns
+   * If the customer has configured a custom onerror handler and the error is not internal,
+   * this method invokes that handler. The handler's return value determines whether the error
+   * should be reported:
+   * - Falsey values (false, null, undefined, etc.) → Report the error normally
+   * - Truthy non-object values → Don't report (throws ShortCircuit)
+   * - Object with 'group' property (non-empty string) → Report with fingerprinting label
+   * - Any other truthy value → Don't report (throws ShortCircuit)
+   *
+   * @param {Error|UncaughtError} err - The error to filter
+   * @param {boolean} internal - Whether this is an internal error (internal errors skip filtering)
+   * @returns {undefined|object} The filter output. If an object with 'group' property, contains fingerprinting data
+   * @throws {ShortCircuit} When the error should not be reported based on the filter output
    */
-  storeError (err, time, internal, customAttributes, hasReplay, swallowReason, target) {
-    if (!err) return
-    // are we in an interaction
-    time = time || now()
+  #filterError (err, internal) {
     let filterOutput
 
     if (!internal && this.agentRef.runtime.onerror) {
@@ -118,20 +143,92 @@ export class Aggregate extends AggregateBase {
       if (filterOutput && !(typeof filterOutput.group === 'string' && filterOutput.group.length)) {
         // All truthy values mean don't report (store) the error, per backwards-compatible usage,
         // - EXCEPT if a fingerprinting label is returned, via an object with key of 'group' and value of non-empty string
-        return
+        throw new ShortCircuit()
       }
       // Again as with previous usage, all falsey values would include the error.
     }
+    return filterOutput
+  }
 
-    var stackInfo = computeStackTrace(err)
-
+  /**
+   * Evaluates whether an error should be swallowed (not reported) based on internal error criteria.
+   *
+   * This method uses the evaluateInternalError function to determine if the error matches known
+   * internal error patterns (e.g., errors from the agent itself, known browser issues, etc.).
+   * If the error should be swallowed, a supportability metric is recorded and processing is halted.
+   *
+   * @param {StackInfo} stackInfo - The computed stack trace information
+   * @param {boolean} internal - Whether the error was marked as internal
+   * @param {string} [swallowReason] - Optional pre-determined reason for swallowing
+   * @returns {void}
+   * @throws {ShortCircuit} When the error should be swallowed and not reported
+   */
+  #swallowError (stackInfo, internal, swallowReason) {
     const { shouldSwallow, reason } = evaluateInternalError(stackInfo, internal, swallowReason)
     if (shouldSwallow) {
       this.reportSupportabilityMetric('Internal/Error/' + reason)
-      return
+      throw new ShortCircuit()
+    }
+  }
+
+  /**
+   * Derives the appropriate targets for reporting the given stack information.
+   *
+   * Targets represent the entities that should receive the error data. This is particularly
+   * important for Micro Frontend (MFE) scenarios where errors may need to be reported to
+   * different applications.
+   *
+   * Logic:
+   * - If a target is explicitly provided (e.g., from the register API), use it
+   * - For v2 endpoints without an explicit target, scan stack frames to detect MFE sources
+   * - If no MFE is detected or v2 is not enabled, use undefined (default target)
+   *
+   * @param {StackInfo} stackInfo - The computed stack trace information containing frames
+   * @param {object} [target] - Explicitly provided target, typically from the register API
+   * @returns {Array<object|undefined>} Array of targets to report the error to. Always contains at least one element.
+   */
+  #deriveTargets (stackInfo, target) {
+    const targets = []
+    if (target) {
+      // reported by the register API directly
+      targets.push(target)
+    } else {
+      // we dont know if this is MFE yet, we need to figure it out.
+      if (this.harvestEndpointVersion === 2) {
+        for (const frame of stackInfo.frames) {
+          targets.push(...getRegisteredTargetsFromFilename(frame.url, this.agentRef))
+          if (targets.length) break
+        }
+      }
+      if (!targets.length) targets.push(undefined)
     }
+    return targets
+  }
 
-    var canonicalStackString = this.buildCanonicalStackString(stackInfo)
+  /**
+   * Stores error data for eventual harvesting and transmission to the backend.
+   *
+   * This method processes the error through several stages:
+   * 1. Build canonical stack string for cross-browser error grouping
+   * 2. Build cause chain string if the error has a cause property
+   * 3. Create params object with error metadata (stack hash, class, message, etc.)
+   * 4. Create bucket hash for internal deduplication
+   * 5. Store stack trace on first occurrence of this error
+   * 6. Add custom attributes and send to other features (trace, replay)
+   * 7. Route through soft nav if enabled, or directly to harvest storage
+   * 8. Handle MFE duplication for v2 endpoints if needed
+   *
+   * @param {Error|UncaughtError} err - The error instance to be processed
+   * @param {number} time - The relative ms (to origin) timestamp of occurrence
+   * @param {StackInfo} stackInfo - The computed stack trace information
+   * @param {object} [filterOutput] - Output from the customer's onerror handler, may contain fingerprinting group
+   * @param {object} [customAttributes] - Any custom attributes to be included in the error payload
+   * @param {boolean} [hasReplay=false] - A flag indicating if the error occurred during a replay session
+   * @param {object} [target] - The target to buffer and harvest to. If undefined, the default configuration target is used
+   * @returns {void}
+   */
+  #storeError (err, time, stackInfo, filterOutput, customAttributes, hasReplay, target) {
+    var canonicalStackString = this.#buildCanonicalStackString(stackInfo)
 
     const causeStackString = buildCauseString(err)
 
@@ -154,7 +251,7 @@ export class Aggregate extends AggregateBase {
      * the canonical stack trace excludes items like the column number increasing the hit-rate of different errors potentially
      * bucketing and ultimately resulting in the loss of data in NR1.
      */
-    var bucketHash = stringHashCode(`${stackInfo.name}_${stackInfo.message}_${stackInfo.stackString}_${params.hasReplay ? 1 : 0}_${target?.id || 'container'}`)
+    var bucketHash = stringHashCode(`${stackInfo.name}_${stackInfo.message}_${stackInfo.stackString}_${params.hasReplay ? 1 : 0}_${target?.id || 'container'}_${target?.instance || ''}`)
 
     if (!this.stackReported[bucketHash]) {
       this.stackReported[bucketHash] = true
@@ -196,23 +293,78 @@ export class Aggregate extends AggregateBase {
       if (softNavInUse) { // pass the error to soft nav for evaluation - it will return it via 'returnJserror' when interaction is resolved
         handle('jserror', [jsErrorEvent], undefined, FEATURE_NAMES.softNav, this.ee)
       } else {
-        this.#storeJserrorForHarvest(jsErrorEvent, false)
+        this.#storeJserrorForHarvest(jsErrorEvent)
       }
     }
 
     // always add directly if scoped to a sub-entity, the other pathways above will be deterministic if the main agent should procede
-    if (target) this.#storeJserrorForHarvest([...jsErrorEvent, target], false, params._softNavAttributes)
+    if (target) this.#storeJserrorForHarvest(jsErrorEvent, {}, target)
   }
 
-  #storeJserrorForHarvest (errorInfoArr, softNavCustomAttrs = {}) {
-    let [type, bucketHash, params, newMetrics, localAttrs, target] = errorInfoArr
+  /**
+   * Builds a standardized (canonical) stack trace string from the frames in the given `stackInfo` object.
+   *
+   * The canonical format is used for cross-browser error grouping in NR1, as different browsers
+   * format stack traces differently. Each frame is separated by a newline character and takes
+   * the form: `<functionName>@<url>:<lineNumber>`
+   *
+   * Note: Column numbers are intentionally excluded from the canonical format to improve
+   * grouping accuracy, as the same error across different minified builds might have different
+   * column numbers but should still be grouped together.
+   *
+   * Example output:
+   * ```
+   * handleClick@https://example.com/app.js:42
+   * EventEmitter.emit@https://example.com/vendor.js:1337
+   * ```
+   *
+   * @param {StackInfo} stackInfo - An object containing parsed stack frames from computeStackTrace
+   * @returns {string} A canonical stack string built from the URLs and function names in the given `stackInfo` object
+   */
+  #buildCanonicalStackString (stackInfo) {
+    var canonicalStackString = ''
+
+    for (var i = 0; i < stackInfo.frames.length; i++) {
+      var frame = stackInfo.frames[i]
+      var func = canonicalFunctionName(frame.func)
+
+      if (canonicalStackString) canonicalStackString += '\n'
+      if (func) canonicalStackString += func + '@'
+      if (typeof frame.url === 'string') canonicalStackString += frame.url
+      if (frame.line) canonicalStackString += ':' + frame.line
+    }
+
+    return canonicalStackString
+  }
+
+  /**
+   * Adds a processed error to the harvest buffer with all custom attributes merged.
+   *
+   * This is the final step before an error is stored to be sent to the backend. It handles:
+   * - Merging all custom attributes (global, soft nav, MFE, and local)
+   * - Creating a unique aggregate hash for deduplication
+   * - Adding the error to the events buffer for harvest
+   * - Duplicating the error for MFE scenarios when needed (v2 endpoints)
+   *
+   * Custom Attribute Precedence (lowest to highest):
+   * 1. Global jsAttributes from agent config
+   * 2. Soft navigation attributes (if from a soft nav interaction)
+   * 3. MFE v2 attributes (source/parent metadata)
+   * 4. Local custom attributes passed with the specific error
+   *
+   * @param {Array} errorInfoArr - Array containing [type, bucketHash, params, metrics, customAttributes, target]
+   * @param {object} [attrs={}] - Additional attributes to merge (e.g., from soft nav interactions)
+   * @returns {void}
+   */
+  #storeJserrorForHarvest (errorInfoArr, attrs = {}, target) {
+    let [type, bucketHash, params, newMetrics, localAttrs] = errorInfoArr
     const allCustomAttrs = {
       /** MFE specific attributes if in "multiple" mode (ie consumer version 2) */
       ...getVersion2Attributes(target, this)
     }
 
     Object.entries(this.agentRef.info.jsAttributes).forEach(([k, v]) => setCustom(k, v))
-    Object.entries(softNavCustomAttrs).forEach(([k, v]) => setCustom(k, v)) // when an ixn finishes, it'll pass attrs specific to the ixn; if no associated ixn, this defaults to empty
+    Object.entries(attrs).forEach(([k, v]) => setCustom(k, v)) // when an ixn finishes, it'll pass attrs specific to the ixn; if no associated ixn, this defaults to empty
     if (params.browserInteractionId) bucketHash += params.browserInteractionId
     if (localAttrs) Object.entries(localAttrs).forEach(([k, v]) => setCustom(k, v)) // local custom attrs are applied in either case with the highest precedence
 
@@ -221,6 +373,11 @@ export class Aggregate extends AggregateBase {
 
     this.events.add([type, aggregateHash, params, newMetrics, allCustomAttrs])
 
+    if (shouldDuplicate(target, this)) {
+      // Clone the array with new object references to prevent deduplication in the shared aggregator
+      this.#storeJserrorForHarvest([type, bucketHash, { ...params }, { ...newMetrics }, localAttrs && { ...localAttrs }], getVersion2DuplicationAttributes(target, this))
+    }
+
     function setCustom (key, val) {
       allCustomAttrs[key] = (val && typeof val === 'object' ? stringify(val) : val)
     }

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

@@ -13,7 +13,7 @@ import { applyFnToProps } from '../../../common/util/traverse'
 import { SESSION_EVENT_TYPES, SESSION_EVENTS } from '../../../common/session/constants'
 import { ABORT_REASONS } from '../../session_replay/constants'
 import { canEnableSessionTracking } from '../../utils/feature-gates'
-import { getVersion2Attributes, getVersion2DuplicationAttributes, shouldDuplicate } from '../../../common/util/v2'
+import { getVersion2Attributes, getVersion2DuplicationAttributes, shouldDuplicate } from '../../../common/v2/utils'
 
 const LOGGING_EVENT = 'Logging/Event/'
 

package/src/features/metrics/instrument/index.js

@@ -1,27 +1,16 @@
 /**
- * Copyright 2020-2025 New Relic, Inc. All rights reserved.
+ * Copyright 2020-2026 New Relic, Inc. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { isBrowserScope } from '../../../common/constants/runtime'
-import { handle } from '../../../common/event-emitter/handle'
 import { InstrumentBase } from '../../utils/instrument-base'
-import {
-  FEATURE_NAME,
-  SUPPORTABILITY_METRIC_CHANNEL
-} from '../constants'
+import { FEATURE_NAME } from '../constants'
 
 export class Instrument extends InstrumentBase {
   static featureName = FEATURE_NAME
   constructor (agentRef) {
     super(agentRef, FEATURE_NAME)
 
-    if (isBrowserScope) {
-      document.addEventListener('securitypolicyviolation', (e) => {
-        handle(SUPPORTABILITY_METRIC_CHANNEL, ['Generic/CSPViolation/Detected'], undefined, this.featureName, this.ee)
-      })
-    }
-
     this.importAggregator(agentRef, () => import(/* webpackChunkName: "metrics-aggregate" */ '../aggregate'))
   }
 }

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

@@ -7,7 +7,7 @@ import { FEATURE_NAME } from '../constants'
 import { AggregateBase } from '../../utils/aggregate-base'
 import { TraceStorage } from './trace/storage'
 import { obj as encodeObj } from '../../../common/url/encode'
-import { globalScope, getNavigationEntry } from '../../../common/constants/runtime'
+import { globalScope } from '../../../common/constants/runtime'
 import { MODE, SESSION_EVENTS } from '../../../common/session/constants'
 import { applyFnToProps } from '../../../common/util/traverse'
 import { cleanURL } from '../../../common/url/clean-url'
@@ -41,6 +41,7 @@ export class Aggregate extends AggregateBase {
     this.entitled ??= stEntitled
     if (!this.entitled) this.blocked = true
     if (this.blocked) return this.deregisterDrain()
+    this.timeKeeper ??= this.agentRef.runtime.timeKeeper
 
     if (!this.initialized) {
       this.initialized = true
@@ -62,9 +63,8 @@ export class Aggregate extends AggregateBase {
         if (this.sessionId !== sessionState.value || (eventType === 'cross-tab' && sessionState.sessionTraceMode === MODE.OFF)) this.abort(2)
       })
 
-      const navEntry = getNavigationEntry()
-      if (navEntry) {
-        this.traceStorage.storeTiming(navEntry)
+      if (typeof PerformanceNavigationTiming !== 'undefined' && globalScope.performance?.getEntriesByType('navigation')?.length > 0) {
+        this.traceStorage.storeTiming(globalScope.performance.getEntriesByType('navigation')[0])
       } else {
         this.traceStorage.storeTiming(globalScope.performance?.timing, true)
       }
@@ -79,8 +79,6 @@ export class Aggregate extends AggregateBase {
      * If it drains later (due to a mode change), data and handlers will instantly drain instead of waiting for the registry. */
     if (this.mode === MODE.OFF) return this.deregisterDrain()
 
-    this.timeKeeper ??= this.agentRef.runtime.timeKeeper
-
     /** The handlers set up by the Inst file */
     registerHandler('bst', (...args) => this.traceStorage.storeEvent(...args), this.featureName, this.ee)
     registerHandler('bstResource', (...args) => this.traceStorage.storeResources(...args), this.featureName, this.ee)

package/src/features/session_trace/aggregate/trace/storage.js

@@ -1,5 +1,5 @@
 /**
- * Copyright 2020-2025 New Relic, Inc. All rights reserved.
+ * Copyright 2020-2026 New Relic, Inc. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
 import { MODE } from '../../../../common/session/constants'
@@ -168,7 +168,7 @@ export class TraceStorage {
       if (!(typeof val === 'number' && val >= 0)) continue
 
       val = Math.round(val)
-      if (this.parent.timeKeeper && this.parent.timeKeeper.ready && isAbsoluteTimestamp) {
+      if (isAbsoluteTimestamp && this.parent.timeKeeper?.ready) {
         val = this.parent.timeKeeper.convertAbsoluteTimestamp(
           Math.floor(this.parent.timeKeeper.correctAbsoluteTimestamp(val))
         )

package/src/interfaces/registered-entity.js

@@ -18,18 +18,19 @@ import { warn } from '../common/util/console'
  * An interface for registering an external caller to report through the base agent to a different target than the base agent.
  */
 export class RegisteredEntity {
-  /** @type {RegisterAPIMetadata} */
-  metadata = {
-    target: {},
-    timings: {},
-    customAttributes: {}
-  }
-
   /**
    *
    * @param {RegisterAPIConstructor} opts The options for setting up the registered entity.
    */
   constructor (opts) {
+    // Initialize metadata as an own property to ensure it exists even when agent is missing
+    /** @type {RegisterAPIMetadata} */
+    this.metadata = {
+      target: /** @type {import('../loaders/api/register-api-types').RegisterAPITarget} */ ({}),
+      timings: /** @type {import('../loaders/api/register-api-types').RegisterAPITimings} */ ({}),
+      customAttributes: {}
+    }
+
     try {
       if (!window?.newrelic) return warn(51)
       Object.assign(this, window?.newrelic?.register(opts) || {})
@@ -49,19 +50,6 @@ export class RegisteredEntity {
     warn(35, 'addPageAction')
   }
 
-  /**
-   * @experimental
-   * IMPORTANT: This feature is being developed for use internally and is not in a public-facing production-ready state.
-   * It is not recommended for use in production environments and will not receive support for issues.
-   *
-   * Registers an external caller to report through the base agent to a different target than the base agent. Will be related to this registered entity when called through this access point.
-   * @param {import('../loaders/api/register-api-types').RegisterAPIConstructor} target the target object to report data to
-    @returns {import('../loaders/api/register-api-types').RegisterAPI} Returns an object that contains the available API methods and configurations to use with the external caller. See loaders/api/api.js for more information.
-   */
-  register (target) {
-    warn(35, 'register')
-  }
-
   /**
    * @experimental
    * IMPORTANT: This feature is being developed for use internally and is not in a public-facing production-ready state.

package/src/loaders/api/register-api-types.js

@@ -8,7 +8,6 @@
  * @property {(name: string, attributes?: object) => void} addPageAction - Add a page action for the registered entity.
  * @property {(message: string, options?: { customAttributes?: object, level?: 'ERROR' | 'TRACE' | 'DEBUG' | 'INFO' | 'WARN'}) => void} log - Capture a log for the registered entity.
  * @property {(error: Error | string, customAttributes?: object) => void} noticeError - Notice an error for the registered entity.
- * @property {(target: RegisterAPIConstructor) => RegisterAPI} register - Record a custom event for the registered entity.
  * @property {() => void} deregister - Deregister the registered entity, which blocks its use and captures end of life timings.
  * @property {(eventType: string, attributes?: Object) => void} recordCustomEvent - Record a custom event for the registered entity.
  * @property {(eventType: string, options?: {start?: number|PerformanceMark, end?: number|PerformanceMark, customAttributes?: object}) => ({start: number, end: number, duration: number, customAttributes: object})} measure - Measures a task that is recorded as a BrowserPerformance event.
@@ -23,15 +22,15 @@
  * @property {string} id - The unique id for the registered entity. This will be assigned to any synthesized entities.
  * @property {string} name - The readable name for the registered entity. This will be assigned to any synthesized entities.
  * @property {{[key: string]: any}} [tags] - The tags for the registered entity as key-value pairs. This will be assigned to any synthesized entities. Tags are converted to source.* attributes (e.g., {environment: 'production'} becomes source.environment: 'production').
- * @property {boolean} [isolated] - When true, each registration creates an isolated instance. When false, multiple registrations with the same id and isolated: false will share a single instance, including all custom attributes, ids, names, and metadata. Calling deregister on a shared instance will deregister it for all entities using the instance. Defaults to true.
+ * @property {RegisterAPITarget} [parent] - The parent target for the registered entity. If none was supplied, it will assume the entity guid from the main agent.
  * @property {string} [parentId] - The parentId for the registered entity. If none was supplied, it will assume the entity guid from the main agent.
  */
 
 /**
  * @typedef {Object} RegisterAPIMetadata
  * @property {Object} customAttributes - The custom attributes for the registered entity.
- * @property {RegisterAPITimings} timings - The timing metrics for the registered entity.
- * @property {RegisterAPITarget} target - The options for the registered entity.
+ * @property {Partial<RegisterAPITimings>} timings - The timing metrics for the registered entity.
+ * @property {Partial<RegisterAPITarget>} target - The options for the registered entity.
  */
 
 /**
@@ -40,17 +39,18 @@
  * @property {string} name - The name returned for the registered entity.
  * @property {{[key: string]: any}} [tags] - The tags for the registered entity as key-value pairs.
  * @property {string} [parentId] - The parentId for the registered entity. If none was supplied, it will assume the entity guid from the main agent.
- * @property {boolean} [isolated] - When true, each registration creates an isolated instance. When false, multiple registrations with the same id and isolated: false will share a single instance, including all custom attributes, ids, names, and metadata. Calling deregister on a shared instance will deregister it for all entities using the instance. Defaults to true.
  */
 
 /**
  * @typedef {Object} RegisterAPITimings
  * @property {number} registeredAt - The timestamp when the registered entity was created.
  * @property {number} [reportedAt] - The timestamp when the registered entity was deregistered.
- * @property {number} fetchStart - The timestamp when the registered entity began fetching.
- * @property {number} fetchEnd - The timestamp when the registered entity finished fetching.
+ * @property {number} fetchStart - The timestamp when the registered entity began fetching (performance.start).
+ * @property {number} fetchEnd - The timestamp when the registered entity finished fetching (performance.end).
+ * @property {number} scriptStart - The timestamp when script initialization began (max of dom.start or performance.end, or performance.end if no dom.start).
+ * @property {number} scriptEnd - The timestamp when script loading completed (dom.end or registeredAt if no dom.end).
  * @property {Object} [asset] - The asset path (if found) for the registered entity.
- * @property {string} type - The type of timing associated with the registered entity, 'script' or 'link' if found with the performance resource API, 'inline' if found to be associated with the root document URL, or 'unknown' if no associated resource could be found.
+ * @property {string} type - The type of timing associated with the registered entity, 'script' or 'link' if found with the performance resource API, 'fetch' for dynamic imports, 'inline' if found to be associated with the root document URL, or 'unknown' if no associated resource could be found.
  */
 
 export default {}