docs: Modify Browser SPA docs for soft nav 2.1 feature GA

src/content/docs/browser/new-relic-browser/browser-apis/createtracer.mdx

@@ -17,7 +17,7 @@ freshnessValidatedDate: never
 ---
 
 <Callout variant="important">
-  The `createTracer` method in the SPA API has been deprecated. The recommended way to trace the duration of a task is to capture a performance [mark](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark) and/or [measure](https://developer.mozilla.org/en-US/docs/Web/API/Performance/measure). Future browser agent versions will capture marks and measures automatically, at which point support for `createTracer` will cease.     
+  The `createTracer` method in the SPA API has been deprecated. The recommended way to trace the duration of a task is now to use performance [marks](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark) and/or [measures](https://developer.mozilla.org/en-US/docs/Web/API/Performance/measure) for measuring callback execution time. This method is now inactive and no longer functions to link JavaScript execution with interactions or keep them open.
 </Callout>
 
 ## Syntax

src/content/docs/browser/new-relic-browser/browser-apis/end.mdx

@@ -45,7 +45,7 @@ Ends the SPA interaction at the current time.
 
 ## Description
 
-This SPA method will end the browser interaction at the current time. Any subsequent callbacks or requests will not be included as part of the SPA interaction.
+This SPA method will end the browser interaction at the current time. Any subsequent network requests that begin after this method is called will not be included as part of the current SPA interaction. In SPA v2.1 and later, this method can also be used to terminate an interaction in a pending state that monitors for any long task in a 5-second window.
 
 ## Return values
 

src/content/docs/browser/new-relic-browser/browser-apis/ignore.mdx

@@ -57,7 +57,7 @@ This method returns the same API object created by `interaction()`.
 ```js
 router.addRoute('/uninteresting-route', () => {
   newrelic.interaction() // Get handle to current interaction.
-    .ignore(); // Ignore this interaction to ensure it will not be saved.
+    .ignore(); // Ignore this interaction to ensure it will not be saved, even if it has fulfilled the default heuristic that makes it valid.
   renderUninterestingRoute(); // Render route.
 });
 ```

src/content/docs/browser/new-relic-browser/browser-apis/interaction.mdx

@@ -19,14 +19,15 @@ freshnessValidatedDate: never
 ## Syntax
 
 ```js
-newrelic.interaction()
+newrelic.interaction([JSON object $options])
 ```
 
-Returns a new API object that is bound to the current SPA interaction.
+Returns a new handle object that is bound to the current SPA interaction, or a new interaction if one does not exist.
 
 ## Requirements
 
 * Browser Pro+SPA agent (v963 or higher)
+* The `$options` parameter requires v1.285.0+
 * If you're using npm to install the browser agent, you must enable the `spa` feature when instantiating the `BrowserAgent` class. In the `features` array, add the following:
 
   ```js
@@ -46,26 +47,68 @@ Returns a new API object that is bound to the current SPA interaction.
 
 ## Description
 
-The [SPA monitoring](/docs/browser/single-page-app-monitoring/get-started/introduction-single-page-app-monitoring) `interaction()` call returns a new API object that is bound to the current interaction.
+The [SPA monitoring](/docs/browser/single-page-app-monitoring/get-started/introduction-single-page-app-monitoring) `interaction()` call returns a new handle that is bound to the current interaction.
 
-* <DNT>**New interaction:**</DNT> If the API calls it when New Relic is not currently monitoring an interaction, a new interaction is created.
-* <DNT>**New object:**</DNT> If the API calls it again within the same interaction, a new object referencing the current interaction is created.
+* <DNT>**New interaction:**</DNT> If this function is called and no interaction is open or in-progress, then a new [custom](/docs/browser/single-page-app-monitoring/use-spa-data/spa-data-collection#api-custom-events) interaction is created.
+  * A custom interaction will still follow the default heuristic and close automatically on the next complete soft navigation, _unless_ `waitForEnd` is specified.
+* <DNT>**New object:**</DNT> If this function is called while an interaction is ongoing, a new handle referencing the current interaction is created.
+  * Multiple handles can point to the same interaction. Each `.interaction` call creates a new handle.
+  * The handle will point to the open interaction, whether it began from an user event like a `click` or from a previous api-triggered `.interaction` call.
+  * This function cannot replace its own effect or that of an user event. That is, it cannot overwrite any existing open interaction with a new api-driven interaction.
 
 ## Parameters
 
-The parameters depend on the specific SPA interaction API call.
+<table>
+  <thead>
+    <tr>
+      <th width="25%">
+        Parameter
+      </th>
+      <th>
+        Description
+      </th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        `$options`
+
+        _JSON object_
+      </td>
+      <td>
+        Optional: Specifies options that affect the behavior of the interaction.
+
+        * `waitForEnd` - Default is `false`. To forcibly keep the interaction open until the `.end` method is called on its handle, set it to `true`. After an interaction is earmarked with this, it cannot be undone.
+      </td>
+    </tr>
+  </tbody>
+</table>
 
 ## Return values
 
-This method returns an API object that is bound to a specific [`BrowserInteraction` event](/docs/insights/explore-data/attributes/browser-default-attributes-insights#browserinteraction-attributes). Each time this method is called for the same `BrowserInteraction`, a new object is created, but it still references the same interaction.
+This method returns an native JS object that points to a potential [`BrowserInteraction` event](/docs/insights/explore-data/attributes/browser-default-attributes-insights#browserinteraction-attributes). Each time this method is called for the same `BrowserInteraction` while it has not yet ended, a new object is created, but it still references the same interaction.
 
 ## Examples
 
-SPA API methods can be used on `newrelic.interaction()`. The methods can also be used on a handle you assign with a variable. For example:
+SPA API methods must be used on `newrelic.interaction()`. You can assign the returned value or handle to another variable for later use. For example:
 
 ```js
-myInteraction = newrelic.interaction();
+let myInteraction = newrelic.interaction();
+...
 myInteraction.save();
 ```
 
-The named handle can be saved and used from outside an interaction, but methods will have no effect after the interaction has ended.
+While the named handle can be saved and used from outside an interaction, note that SPA methods will have no effect after the interaction has ended.
+
+Interaction duration can also be customized using the following method:
+
+```js
+// Say an interaction is already open from a user click.
+const userInteraction = newrelic.interaction({ waitForEnd: true }); // grabs the current interaction in-progress & keep it open
+// URL changes & DOM is modified. Because of those condition being met, interaction will be saved but is kept open.
+fetch('myurl.com/endpoint').then(() => userInteraction.end()) // associate this request to the interaction before completing this BrowserInteraction
+
+const myCustomIxn = newrelic.interaction({ waitForEnd: true }) // create a new api-triggered interaction
+// This interaction will be kept open indefinitely until `.end` is called, and no new interaction will start, custom or otherwise. AjaxRequest will continue to buffer under this interaction until it is closed.
+```

src/content/docs/browser/new-relic-browser/browser-apis/save.mdx

@@ -46,7 +46,7 @@ Ensures a SPA browser interaction will be saved when it ends.
 
 ## Description
 
-This SPA method ensures a browser interaction will be saved when it ends. Normally an interaction is only saved and sent to New Relic if it is an initial page load or if it results in a URL or hash change. You must call this method to override this behavior and guarantee the interaction will be recorded.
+This SPA method ensures a browser interaction will be saved when it ends. Normally an interaction is only saved and sent to New Relic if it is the initial page load or if it is a route change subject to the [default heuristic](/docs/browser/single-page-app-monitoring/use-spa-data/spa-data-collection#browser-interaction). You must call this method to override this behavior and guarantee the interaction will be recorded.
 
 ## Return values
 
@@ -59,7 +59,7 @@ window.addEventListener('scroll', () => {
   if (atBottomOfPage()) {
     newrelic.interaction() // Start monitoring this interaction.
       .setName('loadNextPage') // Set name of interaction.
-      .save(); // Ensure that this interaction will be saved as a BrowserInteraction event when it ends.
+      .save(); // Ensure that this interaction will be saved as a BrowserInteraction event when it ends, even if URL change and DOM modification did not occur.
     loadNextPage(); // Start loading the next page.
   }
 });

src/content/docs/browser/single-page-app-monitoring/get-started/browser-spa-v2.mdx

@@ -1,13 +1,24 @@
 ---
-title: Browser SPA monitoring 2.0
+title: Browser SPA monitoring 2.1
 metaDescription: "The new browser SPA monitoring capability is a streamlined way to monitor your users' experience and app performance."
 freshnessValidatedDate: 2024-09-04
 ---
 
 <Callout variant="important">
-    This feature is in public preview. It will eventually replace the existing browser SPA experience.
+    We’re rolling out this feature in phases using a feature flag to replace the existing browser SPA experience by default. There won’t be an option to choose which new SPA version you receive; you’ll always get the latest version automatically.
+
     </Callout> 
 
+## SPA 2.1
+
+Long task consideration has been introduced to replace the extensive callback tracking used in older Single Page Applications (SPA). It also serves to backfill `jsDuration`, `timeToSettle` and `timeToLastCallbackEnd` attributes of AjaxRequest event(s) associated with a BrowserInteraction.
+
+For _select_ native browser objects wrapped by the agent's `nrWrapper`, their callbacks will be timed. Those over 50ms in duration (long task) can extend a BrowserInteraction. In 2.0, the feature followed a soft navigation heuristic to determine when an interaction occurred naturally. Now, the interaction will additionally wait and extend its duration until a period of no long task for 5 seconds, and its end time will be re-adjusted accordingly.
+
+Previously, in version 2.0, AjaxRequest associated with interactions did not report or track callback timing, resulting in nullified values for the three attributes mentioned above. With the current update, `XMLHttpRequest` (but not `fetch`) that is part of an interaction and includes event listeners causing long tasks will have `jsDuration`, `timeToSettle`, and `timeToLastCallbackEnd` attributes updated to reflect the timing of long callbacks.
+
+## SPA 2.0
+
 For customers monitoring browser single page applications (SPA), we're excited to announce an overhaul of our SPA monitoring functionality, meant to address numerous pain points:
 
 * Unusable latest versions: Frequent conflicts with third-party libraries and unreliable interaction capture plagued the existing agent, often rendering the latest version unusable.

src/content/docs/browser/single-page-app-monitoring/get-started/introduction-single-page-app-monitoring.mdx

@@ -13,11 +13,11 @@ redirects:
 freshnessValidatedDate: never
 ---
 
-New Relic <InlinePopover type="browser"/> offers single-page application (SPA) monitoring to give you deeper visibility and actionable insights into real user interactions with single-page apps or any app that uses AJAX requests.
+New Relic <InlinePopover type="browser"/> offers single-page application (SPA) monitoring to give you deeper visibility and actionable insights into real user interactions with single-page apps.
 
-In addition to monitoring route changes automatically, our SPA API allows you to monitor virtually anything that executes inside the browser. Developers and their teams can use the API to:
+The SPA feature monitors [soft navigations](https://developer.chrome.com/docs/web-platform/soft-navigations-experiment#what_is_a_soft_navigation) automatically, and our SPA API allows you to modify the interactions. Developers and their teams can use the API to:
 
-* Create faster, more responsive, highly interactive apps.
+* Track user journeys through URL paths on their SPA.
 * Monitor the throughput and performance that real users are experiencing.
 * Troubleshoot and resolve problems within the context of the page load.
 * [Query your data](/docs/using-new-relic/data/understand-data/query-new-relic-data) to assist with business decisions.
@@ -33,7 +33,7 @@ For compatibility information about SPA-related features, see [SPA requirements]
 
 ## Analyze throughput and performance data [#spa-data]
 
-Improving on traditional industry standards for measuring page load timing, we give you a complete picture of the activity, both synchronous and asynchronous, associated with page loads and route changes.
+`BrowserInteraction` events drives the UI page views tab whenever SPA is enabled. Both the initial page load (hard nav) and route changes (soft navs) are shown.
 
 <img
   title="browser_SPA.png"
@@ -49,7 +49,6 @@ SPA data monitored by browser monitoring includes:
 
 * Performance data and throughput for page loads and route changes
 * AJAX request data
-* JavaScript activity, both synchronous and asynchronous
 * Dynamic page updates, monitored using the [SPA API](/docs/browser/new-relic-browser/browser-agent-spa-api)
 
 With this data, you will gain a clear understanding of how your users experience your app's page loads and route changes, and be able to solve bottlenecks and troubleshoot errors. For more about how New Relic handles SPA data, see [Understand SPA data collection](/docs/browser/single-page-app-monitoring/use-spa-data/understand-spa-data-collection).
@@ -82,7 +81,7 @@ Here is a summary of SPA monitoring features:
       </td>
 
       <td>
-        When a user initiates a page load or route change, New Relic begins to monitor all subsequent JavaScript, and ends the timing once all AJAX events are complete. This provides a more accurate view of when a page is actually ready for a user compared to the traditional method of ending the timing when the window load event is fired.
+        When a user initiates an interaction event, New Relic tracks the time until the url path changes and the next frame is repainted.
 
         When SPA monitoring is enabled, the [<DNT>**Page views**</DNT> page](/docs/browser/single-page-app-monitoring/browser-ui/view-spa-data-new-relic-browser) in browser shows event-driven data about application usage levels (throughput) and user experience (performance), including:
 
@@ -100,7 +99,9 @@ Here is a summary of SPA monitoring features:
       </td>
 
       <td>
-        [Metrics and events](/docs/query-your-data/explore-query-data/data-explorer/introduction-data-explorer) supports three SPA-specific event types: [`BrowserInteraction`](/docs/insights/new-relic-insights/decorating-events/browser-default-attributes-insights#browserinteraction-attributes), [`AjaxRequest`](/docs/insights/new-relic-insights/decorating-events/browser-default-attributes-insights#ajaxrequest-attributes), and [`BrowserTiming`](/docs/insights/insights-data-sources/default-events-attributes/browser-default-events-attributes-insights#browsertiming-attributes). You can query these events in the [query builder](/docs/query-your-data/explore-query-data/query-builder/use-advanced-nrql-mode-specify-data) to analyze your app's performance and make business decisions.
+        [Metrics and events](/docs/query-your-data/explore-query-data/data-explorer/introduction-data-explorer) supports two SPA-specific event types: [`BrowserInteraction`](/docs/insights/new-relic-insights/decorating-events/browser-default-attributes-insights#browserinteraction-attributes) and [`AjaxRequest`](/docs/insights/new-relic-insights/decorating-events/browser-default-attributes-insights#ajaxrequest-attributes), which may be associated with the former when using the SPA agent. You can query these events in the [query builder](/docs/query-your-data/explore-query-data/query-builder/use-advanced-nrql-mode-specify-data) to analyze your app's performance and make business decisions.
+
+        Previously, [`BrowserTiming`](/docs/insights/insights-data-sources/default-events-attributes/browser-default-events-attributes-insights#browsertiming-attributes) also existed but is now deprecated.
       </td>
     </tr>
 
@@ -110,7 +111,7 @@ Here is a summary of SPA monitoring features:
       </td>
 
       <td>
-        Use [SPA API](/docs/browser/new-relic-browser/browser-agent-spa-api) to obtain the specific data you need, such as custom naming, custom timing, `finishline` API, or other custom attributes.
+        Use [SPA API](/docs/browser/new-relic-browser/browser-agent-spa-api) to obtain the specific data you need, such as custom naming, custom timing, or other custom attributes.
       </td>
     </tr>
   </tbody>