Improvements to Soft Navigation docs

files/en-us/web/api/interactioncontentfulpaint/index.md

@@ -2,6 +2,8 @@
 title: InteractionContentfulPaint
 slug: Web/API/InteractionContentfulPaint
 page-type: web-api-interface
+status:
+  - experimental
 browser-compat: api.InteractionContentfulPaint
 ---
 
@@ -17,8 +19,6 @@ This interface directly defines the following properties:
   - : The id of the interaction that resulted in the paint.
 - {{domxref("InteractionContentfulPaint.largestContentfulPaint")}} {{ReadOnlyInline}} {{Experimental_Inline}}
   - : Returns details of the largest {{domxref("LargestContentfulPaint")}} for the interaction. This can remain the same between two `InteractionContentfulPaint` entries for the same interaction if a new contentful paint is smaller than the current largest contentful paint for that interaction.
-- {{domxref("InteractionContentfulPaint.navigationId")}} {{ReadOnlyInline}} {{Experimental_Inline}}
-  - : The id of the navigation this paint is attributable to.
 - {{domxref("InteractionContentfulPaint.paintTime")}} {{ReadOnlyInline}} {{Experimental_Inline}}
   - : Returns the {{domxref("DOMHighResTimeStamp","timestamp")}} of when the first rendering phase ended and the paint phase started.
 - {{domxref("InteractionContentfulPaint.presentationTime")}} {{ReadOnlyInline}} {{Experimental_Inline}}
@@ -35,19 +35,28 @@ It also extends the following {{domxref("PerformanceEntry")}} properties, qualif
 - {{domxref("PerformanceEntry.startTime")}} {{ReadOnlyInline}} {{Experimental_Inline}}
   - : Returns the {{domxref("DOMHighResTimeStamp","timestamp")}} of the interaction that resulted in the soft navigation.
 
+## Instance methods
+
+- {{domxref("InteractionContentfulPaint.toJSON()")}}
+  - : Overrides the {{domxref("PerformanceEntry.toJSON()")}} method to return a JSON representation of the `InteractionContentfulPaint` object.
+
 ## Description
 
 The `InteractionContentfulPaint` provides a stream of paint updates attributable to an interaction.
 
-At present this is scoped to increasing paint sizes, so it can be used to measure {{Glossary("Largest Contentful Paint", "Largest Contentful Paint (LCP)")}} for {{glossary("Soft Navigation", "Soft Navigations")}}, but the API has been designed to allow for all paints relevant to an interaction to be emitted.
+At present this is scoped to increasing paint sizes, so it can be used to measure {{Glossary("Largest Contentful Paint", "Largest Contentful Paint (LCP)")}} for {{glossary("Soft Navigation", "Soft Navigations")}}, however the API has been designed to allow for all paints relevant to an interaction to be emitted.
+
+`InteractionContentfulPaint` is needed instead of using the {{domxref("LargestContentfulPaint")}} API, as that is only emitted per full page load and is finalized upon interaction (which is a necessary start to a soft navigation).
+
+### Using `navigationId` and `interactionId`
 
-`InteractionContentfulPaint` is needed instead of using the {{domxref("LargestContentfulPaint")}} API as that is only emitted per full page load and is finalized upon interaction (which is a necessary start to a soft navigation).
+For {{glossary("Soft Navigation", "Soft Navigations")}}, paints happening before the URL is updated may be considered for the {{Glossary("Largest Contentful Paint", "Largest Contentful Paint (LCP)")}} of the soft navigation that is in flight. For the LCP case, {{domxref("PerformanceSoftNavigation.getLargestInteractionContentfulPaint()")}} and {{domxref("InteractionContentfulPaint.interactionId")}} are more effective at considering all relevant paints regardless of the `navigationId`, when calculating that metric.
 
 ### Relationship with Event Timing and INP
 
-The [Event Timing API](/en-US/docs/Web/API/PerformanceEventTiming) provides details about UIEvents — scheduling and processing durations, and total duration to next paint — but does not actually directly track the effects of those events, nor any future paints those effects might cause. It is intended to measure the responsiveness time during which a user receives no feedback, which should be kept to a minimum and forms the basis for metrics such as {{Glossary("Interaction to Next Paint", "Interaction to Next Paint (INP)")}}.
+The [Event Timing API](/en-US/docs/Web/API/PerformanceEventTiming) provides details about UIEvents — scheduling and processing durations, and total duration to next paint — but does not directly track the effects of those events, nor any future paints those effects might cause. It is intended to measure the responsiveness time during which a user receives no feedback, which should be kept to a minimum and forms the basis for metrics such as {{Glossary("Interaction to Next Paint", "Interaction to Next Paint (INP)")}}.
 
-`InteractionContentfulPaint`, despite being similarly named to Interaction to Next Paint, serves a different purpose. `InteractionContentfulPaint` excludes non-contentful paints which do count for Event Timing and INP but also measures additional paints beyond the first paint. It allows enables measurement of a more complete understanding of the effects and content updates directly attributable to an interaction.
+`InteractionContentfulPaint`, despite being similarly named to Interaction to Next Paint, serves a different purpose. `InteractionContentfulPaint` excludes non-contentful paints, which do count for Event Timing and INP but also measures additional paints beyond the first paint. It enables measuring the effects and content updates directly attributable to an interaction, resulting in a better understanding of the associated performance implications.
 
 ## Examples
 
@@ -68,7 +77,7 @@ observer.observe({ type: "interaction-contentful-paints", buffered: true });
 
 One of the key uses of the `InteractionContentfulPaint` interface is to measure all contentful paints related to a [soft navigation](/en-US/docs/Web/API/PerformanceSoftNavigation) to calculate the {{Glossary("Largest Contentful Paint", "Largest Contentful Paint (LCP)")}} for that soft navigation.
 
-To do this, it is recommended to use the {{domxref("PerformanceSoftNavigation.interactionId")}} rather than the {{domxref("PerformanceSoftNavigation.navigationId")}}, since some LCP candidates can happen before the soft navigation is defined (for paints, before the URL is updated) and will therefore have the old `navigationId`.
+To do this, it is recommended to use the {{domxref("PerformanceSoftNavigation.interactionId")}} rather than the {{domxref("PerformanceEntry.navigationId")}}, since some LCP candidates can happen before the soft navigation is defined (for paints, before the URL is updated) and will therefore have the old `navigationId`.
 
 ```js
 let currentNavigationInteractionId = 1045; // hardcoded in this example

files/en-us/web/api/interactioncontentfulpaint/interactionid/index.md

@@ -3,6 +3,8 @@ title: "InteractionContentfulPaint: interactionId property"
 short-title: interactionId
 slug: Web/API/InteractionContentfulPaint/interactionId
 page-type: web-api-instance-property
+status:
+  - experimental
 browser-compat: api.InteractionContentfulPaint.interactionId
 ---
 

files/en-us/web/api/interactioncontentfulpaint/largestcontentfulpaint/index.md

@@ -3,6 +3,8 @@ title: "InteractionContentfulPaint: largestContentfulPaint property"
 short-title: largestContentfulPaint
 slug: Web/API/InteractionContentfulPaint/largestContentfulPaint
 page-type: web-api-instance-property
+status:
+  - experimental
 browser-compat: api.InteractionContentfulPaint.largestContentfulPaint
 ---
 

files/en-us/web/api/interactioncontentfulpaint/painttime/index.md

@@ -3,6 +3,8 @@ title: "InteractionContentfulPaint: paintTime property"
 short-title: paintTime
 slug: Web/API/InteractionContentfulPaint/paintTime
 page-type: web-api-instance-property
+status:
+  - experimental
 browser-compat: api.InteractionContentfulPaint.paintTime
 ---
 

files/en-us/web/api/interactioncontentfulpaint/presentationtime/index.md

@@ -3,6 +3,8 @@ title: "InteractionContentfulPaint: presentationTime property"
 short-title: presentationTime
 slug: Web/API/InteractionContentfulPaint/presentationTime
 page-type: web-api-instance-property
+status:
+  - experimental
 browser-compat: api.InteractionContentfulPaint.presentationTime
 ---
 
@@ -14,7 +16,7 @@ The `presentationTime` is optional — some browsers may always return `0` or no
 
 ## Value
 
-A {{domxref("DOMHighResTimeStamp")}} or {{jsxref("operators/null", "null")}} if the value is not exposed.
+A {{domxref("DOMHighResTimeStamp")}} or {{jsxref("Operators/null", "null")}} if the value is not exposed.
 
 ## Examples
 

files/en-us/web/api/interactioncontentfulpaint/tojson/index.md

@@ -0,0 +1,72 @@
+---
+title: "InteractionContentfulPaint: toJSON() method"
+short-title: toJSON()
+slug: Web/API/InteractionContentfulPaint/toJSON
+page-type: web-api-instance-method
+status:
+  - experimental
+browser-compat: api.InteractionContentfulPaint.toJSON
+---
+
+{{APIRef("Performance API")}}
+
+The **`toJSON()`** method of the {{domxref("InteractionContentfulPaint")}} interface is a {{Glossary("Serialization","serializer")}}; it returns a JSON representation of the {{domxref("InteractionContentfulPaint")}} object.
+
+## Syntax
+
+```js-nolint
+toJSON()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+A {{jsxref("JSON")}} object that is the serialization of the {{domxref("InteractionContentfulPaint")}} object.
+
+## Examples
+
+### Using the toJSON method
+
+In this example, calling `entry.toJSON()` returns a JSON representation of the `InteractionContentfulPaint` object.
+
+```js
+const observer = new PerformanceObserver((list) => {
+  list.getEntries().forEach((entry) => {
+    console.log(entry.toJSON());
+  });
+});
+
+observer.observe({ type: "interaction-contentful-paint", buffered: true });
+```
+
+This would log a JSON object like so:
+
+```json
+{
+  "entryType": "interaction-contentful-paint",
+  "interactionId": 1704,
+  "largestContentfulPaint": <not shown>,
+  "name": "",
+  "navigationId": 2463,
+  "paintTime": 2589.3,
+  "presentationTime": 2616,
+  "startTime": 2226.6,
+}
+```
+
+To get a JSON string, you can use [`JSON.stringify(entry)`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) directly; it will call `toJSON()` automatically.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{jsxref("JSON")}}

files/en-us/web/api/largestcontentfulpaint/index.md

@@ -43,10 +43,8 @@ It also extends the following {{domxref("PerformanceEntry")}} properties, qualif
 
 ## Instance methods
 
-_This interface also inherits methods from {{domxref("PerformanceEntry")}}._
-
 - {{domxref("LargestContentfulPaint.toJSON()")}}
-  - : Returns a JSON representation of the `LargestContentfulPaint` object.
+  - : Overrides the {{domxref("PerformanceEntry.toJSON()")}} method to return a JSON representation of the `LargestContentfulPaint` object.
 
 ## Description
 

files/en-us/web/api/performance_api/index.md

@@ -14,6 +14,7 @@ spec-urls:
   - https://w3c.github.io/performance-timeline/
   - https://w3c.github.io/resource-timing/
   - https://w3c.github.io/server-timing/
+  - https://wicg.github.io/soft-navigations/
   - https://w3c.github.io/user-timing/
   - https://w3c.github.io/long-animation-frames/
   - https://wicg.github.io/performance-measure-memory/
@@ -47,27 +48,31 @@ The following interfaces are present in the Performance API:
 
 - {{domxref("EventCounts")}}
   - : A read-only map returned by {{domxref("performance.eventCounts")}} containing the number of events which have been dispatched per event type.
+- {{domxref("InteractionContentfulPaint")}} {{Experimental_Inline}}
+  - : Measures the render time of {{glossary("contentful paint", "contentful paints")}} attributed to an interaction.
 - {{domxref("LargestContentfulPaint")}}
   - : Measures the render time of the largest image or text block visible within the viewport, recorded from when the page first begins to load.
-- {{domxref("LayoutShift")}}
+- {{domxref("LayoutShift")}} {{Experimental_Inline}}
   - : Provides insights into the layout stability of web pages based on movements of the elements on the page.
-- {{domxref("LayoutShiftAttribution")}}
-  - : Provides debugging information about elements which have shifted.
-- {{domxref("NotRestoredReasonDetails")}}
-  - : Represents a single reason why a navigated page was blocked from using the back/forward cache ({{Glossary("bfcache")}}).
-- {{domxref("NotRestoredReasons")}}
-  - : Provides report data containing reasons why the current document was blocked from using the back/forward cache ({{Glossary("bfcache")}}) on navigation.
+- {{domxref("LayoutShiftAttribution")}} {{Experimental_Inline}}
+  - : Provides debugging information about elements which have shifted. This is available through {{domxref("LayoutShift")}} entries.
+- {{domxref("NotRestoredReasonDetails")}} {{Experimental_Inline}}
+  - : Represents a single reason why a navigated page was blocked from using the back/forward cache ({{Glossary("bfcache")}}). This is available through {{domxref("NotRestoredReasons")}} entries.
+- {{domxref("NotRestoredReasons")}} {{Experimental_Inline}}
+  - : Provides report data containing reasons why the current document was blocked from using the back/forward cache ({{Glossary("bfcache")}}) on navigation. This is available through {{domxref("PerformanceNavigationTiming")}} entries.
 - {{domxref("Performance")}}
   - : Main interface to access performance measurements. Available to window and worker contexts using {{domxref("Window.performance")}} or {{domxref("WorkerGlobalScope.performance")}}.
-- {{domxref("PerformanceElementTiming")}}
+- `PerformanceContainerTiming` {{ experimental_inline }}
+  - : Measures rendering timestamps of specific containers of multiple elements.
+- {{domxref("PerformanceElementTiming")}} {{Experimental_Inline}}
   - : Measures rendering timestamps of specific elements.
 - {{domxref("PerformanceEntry")}}
   - : An entry on the performance timeline encapsulating a single performance metric. All performance metrics inherit from this interface.
 - {{domxref("PerformanceEventTiming")}}
   - : Measures latency of events and {{Glossary("Interaction to Next Paint")}} (INP).
-- {{domxref("PerformanceLongAnimationFrameTiming")}}
+- {{domxref("PerformanceLongAnimationFrameTiming")}} {{Experimental_Inline}}
   - : Provides metrics on [long animation frames (LoAFs)](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing#what_is_a_long_animation_frame) that occupy rendering and block other tasks from being executed.
-- {{domxref("PerformanceLongTaskTiming")}}
+- {{domxref("PerformanceLongTaskTiming")}} {{Experimental_Inline}}
   - : Provides metrics on [long tasks](/en-US/docs/Glossary/Long_task) that occupy rendering and block other tasks from being executed.
 - {{domxref("PerformanceMark")}}
   - : Custom marker for your own entry on the performance timeline.
@@ -83,12 +88,14 @@ The following interfaces are present in the Performance API:
   - : Measures render operations during web page construction.
 - {{domxref("PerformanceResourceTiming")}}
   - : Measures network loading metrics such as redirect start and end times, fetch start, DNS lookup start and end times, response start and end times for resources such as images, scripts, fetch calls, etc.
-- {{domxref("PerformanceScriptTiming")}}
+- {{domxref("PerformanceScriptTiming")}} {{Experimental_Inline}}
   - : Provides metrics on individual scripts causing [long animation frames (LoAFs)](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing#what_is_a_long_animation_frame).
 - {{domxref("PerformanceServerTiming")}}
-  - : Surfaces server metrics that are sent with the response in the {{HTTPHeader("Server-Timing")}} HTTP header.
-- {{domxref("TaskAttributionTiming")}}
-  - : Identifies the type of task and the container that is responsible for the long task.
+  - : Surfaces server metrics sent with the response in the {{HTTPHeader("Server-Timing")}} HTTP header. This is available through {{domxref("PerformanceNavigationTiming")}} and {{domxref("PerformanceResourceTiming")}} entries.
+- {{domxref("PerformanceSoftNavigation")}} {{Experimental_Inline}}
+  - : Measures when {{glossary("Soft Navigation", "Soft Navigations")}} occur.
+- {{domxref("TaskAttributionTiming")}} {{Experimental_Inline}}
+  - : Identifies the type of task and the container that is responsible for a {{glossary("long task")}}. This is available through {{domxref("PerformanceLongTaskTiming")}} entries.
 - {{domxref("VisibilityStateEntry")}}
   - : Measures the timing of page visibility state changes, i.e., when a tab changes from the foreground to the background or vice versa.
 

files/en-us/web/api/performanceelementtiming/index.md

@@ -70,7 +70,7 @@ It also extends the following {{domxref("PerformanceEntry")}} properties, qualif
 ## Instance methods
 
 - {{domxref("PerformanceElementTiming.toJSON()")}} {{Experimental_Inline}}
-  - : Returns a JSON representation of the `PerformanceElementTiming` object.
+  - : Overrides the {{domxref("PerformanceEntry.toJSON()")}} method to return a JSON representation of the `PerformanceElementTiming` object.
 
 ## Examples