[pull] main from mdn:main

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

@@ -32,38 +32,40 @@ Additional key paint moments are provided by the {{domxref("PerformancePaintTimi
 
 To get an accurate measurement of render time for cross-origin resources, set the {{httpheader("Timing-Allow-Origin")}} header.
 
-Developers should use `startTime` instead of `renderTime` as the LCP value, as the `renderTime` may not be set in some browsers.
-
 See [Cross-origin image render time](/en-US/docs/Web/API/LargestContentfulPaint/renderTime#cross-origin_image_render_time) and [Use startTime over renderTime](/en-US/docs/Web/API/LargestContentfulPaint/renderTime#use_starttime_over_rendertime) for more details.
 
 ## Instance properties
 
-This interface extends the following {{domxref("PerformanceEntry")}} properties by qualifying and constraining the properties as follows:
-
-- {{domxref("PerformanceEntry.entryType")}} {{ReadOnlyInline}} {{Experimental_Inline}}
-  - : Returns `"largest-contentful-paint"`.
-- {{domxref("PerformanceEntry.name")}} {{ReadOnlyInline}} {{Experimental_Inline}}
-  - : Always returns an empty string.
-- {{domxref("PerformanceEntry.startTime")}} {{ReadOnlyInline}} {{Experimental_Inline}}
-  - : Returns the value of this entry's {{domxref("LargestContentfulPaint.renderTime", "renderTime")}} if it is not `0`, otherwise the value of this entry's {{domxref("LargestContentfulPaint.loadTime", "loadTime")}}.
-- {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} {{Experimental_Inline}}
-  - : Returns `0`, as `duration` is not applicable to this interface.
-
-It also supports the following properties:
+This interface directly defines the following properties:
 
 - {{domxref("LargestContentfulPaint.element")}} {{ReadOnlyInline}}
   - : The element that is the current largest contentful paint.
 - {{domxref("LargestContentfulPaint.renderTime")}} {{ReadOnlyInline}}
-  - : The time the element was rendered to the screen. May be a coarsened value or `0` if the element is a cross-origin image loaded without the `Timing-Allow-Origin` header.
+  - : The time the element was rendered to the screen. May be a coarsened value if the element is a cross-origin image loaded without the `Timing-Allow-Origin` header.
 - {{domxref("LargestContentfulPaint.loadTime")}} {{ReadOnlyInline}}
   - : The time the element was loaded.
 - {{domxref("LargestContentfulPaint.size")}} {{ReadOnlyInline}}
   - : The intrinsic size of the element returned as the area (width \* height).
 - {{domxref("LargestContentfulPaint.id")}} {{ReadOnlyInline}}
   - : The id of the element. This property returns an empty string when there is no id.
+- {{domxref("LargestContentfulPaint.paintTime")}}
+  - : Returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the rendering phase ended and the paint phase started.
+- {{domxref("LargestContentfulPaint.presentationTime")}}
+  - : Returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the painted pixels were actually drawn on the screen.
 - {{domxref("LargestContentfulPaint.url")}} {{ReadOnlyInline}}
   - : If the element is an image, the request url of the image.
 
+It also extends the following {{domxref("PerformanceEntry")}} properties, qualifying and constraining them as described:
+
+- {{domxref("PerformanceEntry.entryType")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns `"largest-contentful-paint"`.
+- {{domxref("PerformanceEntry.name")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Always returns an empty string.
+- {{domxref("PerformanceEntry.startTime")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns the value of this entry's {{domxref("LargestContentfulPaint.renderTime", "renderTime")}}.
+- {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns `0`, as `duration` is not applicable to this interface.
+
 ## Instance methods
 
 _This interface also inherits methods from {{domxref("PerformanceEntry")}}._
@@ -75,7 +77,7 @@ _This interface also inherits methods from {{domxref("PerformanceEntry")}}._
 
 ### Observing the largest contentful paint
 
-In the following example, an observer is registered to get the largest contentful paint while the page is loading. The `buffered` flag is used to access data from before observer creation.
+In the following example, a {{domxref("PerformanceObserver")}} is registered to get the largest contentful paint while the page is loading. The `buffered` flag is used to access data from before observer creation.
 
 The LCP API analyzes all content it finds (including content that is removed from the DOM). When new largest content is found, it creates a new entry. It stops searching for larger content when scroll or input events occur, since these events likely introduce new content on the website. Thus the LCP is the last performance entry reported by the observer.
 
@@ -89,6 +91,34 @@ const observer = new PerformanceObserver((list) => {
 observer.observe({ type: "largest-contentful-paint", buffered: true });
 ```
 
+### Observing separate paint and presentation timings
+
+The `paintTime` and `presentationTime` properties enable you to retrieve specific timings for the paint phase starting and the painted pixels being drawn on the screen. The `paintTime` is broadly interoperable, whereas the `presentationTime` is implementation-dependent.
+
+This example builds on the earlier observer example, showing how to check for `paintTime` and `presentationTime` support and retrieve those values if they are available. In non-supporting browsers, the code retrieves the `renderTime` or `loadTime`, depending on what is supported.
+
+```js
+const observer = new PerformanceObserver((list) => {
+  const entries = list.getEntries();
+  const lastEntry = entries[entries.length - 1]; // Use the latest LCP candidate
+  if (lastEntry.presentationTime) {
+    console.log(
+      "LCP paintTime:",
+      lastEntry.paintTime,
+      "LCP presentationTime:",
+      lastEntry.presentationTime,
+    );
+  } else if (lastEntry.paintTime) {
+    console.log("LCP paintTime:", lastEntry.paintTime);
+  } else if (lastEntry.renderTime) {
+    console.log("LCP renderTime:", lastEntry.renderTime);
+  } else {
+    console.log("LCP loadTime:", lastEntry.loadTime);
+  }
+});
+observer.observe({ type: "largest-contentful-paint", buffered: true });
+```
+
 ## Specifications
 
 {{Specifications}}

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

@@ -0,0 +1,33 @@
+---
+title: "LargestContentfulPaint: paintTime property"
+short-title: paintTime
+slug: Web/API/LargestContentfulPaint/paintTime
+page-type: web-api-instance-property
+browser-compat: api.LargestContentfulPaint.paintTime
+---
+
+{{APIRef("Performance API")}}
+
+The **`paintTime`** read-only property of the {{domxref("LargestContentfulPaint")}} interface returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the rendering phase ended and the paint phase started.
+
+The `paintTime` is broadly interoperable: The value should be the same across different implementations.
+
+## Value
+
+A {{domxref("DOMHighResTimeStamp")}}.
+
+## Examples
+
+See [Observing separate paint and presentation timings](/en-US/docs/Web/API/LargestContentfulPaint#observing_separate_paint_and_presentation_timings).
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("LargestContentfulPaint.presentationTime")}}

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

@@ -0,0 +1,33 @@
+---
+title: "LargestContentfulPaint: presentationTime property"
+short-title: presentationTime
+slug: Web/API/LargestContentfulPaint/presentationTime
+page-type: web-api-instance-property
+browser-compat: api.LargestContentfulPaint.presentationTime
+---
+
+{{APIRef("Performance API")}}
+
+The **`presentationTime`** read-only property of the {{domxref("LargestContentfulPaint")}} interface returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the painted pixels were actually drawn on the screen.
+
+The `presentationTime` is optional — some browsers may choose always to return `0` or not to expose the value at all. The value is also implementation-dependent — it may differ across browsers that choose to expose it.
+
+## Value
+
+A {{domxref("DOMHighResTimeStamp")}} or {{jsxref("Operators/null", "null")}} if the value is not exposed.
+
+## Examples
+
+See [Observing separate paint and presentation timings](/en-US/docs/Web/API/LargestContentfulPaint#observing_separate_paint_and_presentation_timings).
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("LargestContentfulPaint.paintTime")}}

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

@@ -49,6 +49,8 @@ The following is a complete `"long-animation-frame"` performance entry example,
   entryType: "long-animation-frame",
   firstUIEventTimestamp: 11801.099999999627,
   name: "long-animation-frame",
+  paintTime: 11862.400000000373,
+  presentationTime: 11863.199999999255,
   renderStart: 11858.800000000745,
   scripts: [
     {
@@ -81,6 +83,10 @@ Beyond the standard data returned by a {{domxref("PerformanceEntry")}} entry, th
   - : A {{domxref("DOMHighResTimeStamp")}} indicating the total time in milliseconds for which the main thread was blocked from responding to high priority tasks, such as user input. This is calculated by taking all the [long tasks](/en-US/docs/Web/API/PerformanceLongTaskTiming#description) within the LoAF that have a `duration` of more than `50ms`, subtracting `50ms` from each, adding the rendering time to the longest task time, and summing the results.
 - {{domxref("PerformanceLongAnimationFrameTiming.firstUIEventTimestamp", "firstUIEventTimestamp")}}
   - : A {{domxref("DOMHighResTimeStamp")}} indicating the time of the first UI event — such as a mouse or keyboard event — to be processed during the current animation frame. Note this timestamp can be before the start of this animation frame if there was a delay between the event happening and it being processed.
+- {{domxref("PerformanceLongAnimationFrameTiming.paintTime", "paintTime")}}
+  - : Returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the rendering phase ended and the animation frame started.
+- {{domxref("PerformanceLongAnimationFrameTiming.presentationTime", "presentationTime")}}
+  - : Returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the UI update was actually drawn on the screen.
 - {{domxref("PerformanceLongAnimationFrameTiming.renderStart", "renderStart")}}
   - : A {{domxref("DOMHighResTimeStamp")}} indicating the start time of the rendering cycle, which includes {{domxref("Window.requestAnimationFrame()")}} callbacks, style and layout calculation, {{domxref("ResizeObserver")}} callbacks, and {{domxref("IntersectionObserver")}} callbacks.
 - {{domxref("PerformanceLongAnimationFrameTiming.styleAndLayoutStart", "styleAndLayoutStart")}}
@@ -113,7 +119,7 @@ The timestamps provided in the {{domxref("PerformanceLongAnimationFrameTiming")}
 | Timing                            | Calculation                                                              |
 | --------------------------------- | ------------------------------------------------------------------------ |
 | Start time                        | `startTime`                                                              |
-| End time                          | `startTime + duration`                                                   |
+| End time                          | `startTime + duration` (or `paintTime`/`presentationTime`)               |
 | Work duration                     | `renderStart ? renderStart - startTime : duration`                       |
 | Render duration                   | `renderStart ? (startTime + duration) - renderStart : 0`                 |
 | Render: Pre-layout duration       | `styleAndLayoutStart ? styleAndLayoutStart - renderStart : 0`            |
@@ -142,7 +148,8 @@ const observer = new PerformanceObserver((list) => {
   for (const entry of list.getEntries()) {
     if (entry.duration > REPORTING_THRESHOLD_MS) {
       // Example here logs to console; real code could send to analytics endpoint
-      console.log(entry);
+      console.log(entry.paintTime);
+      console.log(entry.presentationTime);
     }
   }
 });

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

@@ -31,18 +31,7 @@ The author flags an element for observation by adding the [`elementtiming`](/en-
 
 ## Instance properties
 
-This interface extends the following {{domxref("PerformanceEntry")}} properties for event timing performance entry types by qualifying them as follows:
-
-- {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} {{Experimental_Inline}}
-  - : Always returns `0` as `duration` does not apply to this interface.
-- {{domxref("PerformanceEntry.entryType")}} {{ReadOnlyInline}} {{Experimental_Inline}}
-  - : Always returns `"element"`.
-- {{domxref("PerformanceEntry.name")}} {{ReadOnlyInline}} {{Experimental_Inline}}
-  - : Returns `"image-paint"` for images and `"text-paint"` for text.
-- {{domxref("PerformanceEntry.startTime")}} {{ReadOnlyInline}} {{Experimental_Inline}}
-  - : Returns the value of this entry's {{domxref("PerformanceElementTiming.renderTime", "renderTime")}} if it is not `0`, otherwise the value of this entry's {{domxref("PerformanceElementTiming.loadTime", "loadTime")}}.
-
-This interface also supports the following properties:
+This interface directly defines the following properties:
 
 - {{domxref("PerformanceElementTiming.element")}} {{ReadOnlyInline}} {{Experimental_Inline}}
   - : An {{domxref("Element")}} representing the element we are returning information about.
@@ -58,11 +47,26 @@ This interface also supports the following properties:
   - : An unsigned 32-bit integer (unsigned long) which is the intrinsic height of the image if this is applied to an image, 0 for text.
 - {{domxref("PerformanceElementTiming.naturalWidth")}} {{ReadOnlyInline}} {{Experimental_Inline}}
   - : An unsigned 32-bit integer (unsigned long) which is the intrinsic width of the image if this is applied to an image, 0 for text.
+- {{domxref("PerformanceElementTiming.paintTime")}}
+  - : Returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the rendering phase ended and the paint phase started.
+- {{domxref("PerformanceElementTiming.presentationTime")}}
+  - : Returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the element was actually drawn on the screen.
 - {{domxref("PerformanceElementTiming.renderTime")}} {{ReadOnlyInline}} {{Experimental_Inline}}
   - : A {{domxref("DOMHighResTimeStamp")}} with the renderTime of the element.
 - {{domxref("PerformanceElementTiming.url")}} {{ReadOnlyInline}} {{Experimental_Inline}}
   - : A string which is the initial URL of the resources request for images, 0 for text.
 
+It also extends the following {{domxref("PerformanceEntry")}} properties, qualifying and constraining them as described:
+
+- {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Always returns `0` as `duration` does not apply to this interface.
+- {{domxref("PerformanceEntry.entryType")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Always returns `"element"`.
+- {{domxref("PerformanceEntry.name")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns `"image-paint"` for images and `"text-paint"` for text.
+- {{domxref("PerformanceEntry.startTime")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns the value of this entry's {{domxref("PerformanceElementTiming.renderTime", "renderTime")}} if it is not `0`, otherwise the value of this entry's {{domxref("PerformanceElementTiming.loadTime", "loadTime")}}.
+
 ## Instance methods
 
 - {{domxref("PerformanceElementTiming.toJSON()")}} {{Experimental_Inline}}
@@ -90,6 +94,35 @@ observer.observe({ type: "element", buffered: true });
 
 Two entries will be output to the console. The first containing details of the image, the second with details of the text node.
 
+### Observing separate paint and presentation timings
+
+The `paintTime` and `presentationTime` properties enable you to retrieve specific timings for the paint phase starting and the element being drawn on the screen. The `paintTime` is broadly interoperable, whereas the `presentationTime` is implementation-dependent.
+
+This example uses a `PerformanceObserver` to observe all performance entries of type `"element"` (remember that, to be observed, elements need to have `elementtiming` attributes set on them). We check for `paintTime` and `presentationTime` support and retrieve those values if they are available. In non-supporting browsers, the code retrieves the `renderTime` or `loadTime`, depending on what is supported.
+
+```js
+const observer = new PerformanceObserver((list) => {
+  const entries = list.getEntries();
+  entries.forEach((entry) => {
+    if (entry.presentationTime) {
+      console.log(
+        "Element paintTime:",
+        entry.paintTime,
+        "Element presentationTime:",
+        entry.presentationTime,
+      );
+    } else if (entry.paintTime) {
+      console.log("Element paintTime:", entry.paintTime);
+    } else if (entry.renderTime) {
+      console.log("Element renderTime:", entry.renderTime);
+    } else {
+      console.log("Element loadTime", entry.loadTime);
+    }
+  });
+});
+observer.observe({ type: "element", buffered: true });
+```
+
 ## Specifications
 
 {{Specifications}}

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

@@ -0,0 +1,33 @@
+---
+title: "PerformanceElementTiming: paintTime property"
+short-title: paintTime
+slug: Web/API/PerformanceElementTiming/paintTime
+page-type: web-api-instance-property
+browser-compat: api.PerformanceElementTiming.paintTime
+---
+
+{{APIRef("Performance API")}}
+
+The **`paintTime`** read-only property of the {{domxref("PerformanceElementTiming")}} interface returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the rendering phase ended and the paint phase started.
+
+The `paintTime` is broadly interoperable: The value should be the same across different implementations.
+
+## Value
+
+A {{domxref("DOMHighResTimeStamp")}}.
+
+## Examples
+
+See [Observing separate paint and presentation timings](/en-US/docs/Web/API/PerformanceElementTiming#observing_separate_paint_and_presentation_timings).
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("PerformanceElementTiming.presentationTime")}}

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

@@ -0,0 +1,33 @@
+---
+title: "PerformanceElementTiming: presentationTime property"
+short-title: presentationTime
+slug: Web/API/PerformanceElementTiming/presentationTime
+page-type: web-api-instance-property
+browser-compat: api.PerformanceElementTiming.presentationTime
+---
+
+{{APIRef("Performance API")}}
+
+The **`presentationTime`** read-only property of the {{domxref("PerformanceElementTiming")}} interface returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the element was actually drawn on the screen.
+
+The `presentationTime` is optional — some browsers may choose always to return `0` or not to expose the value at all. The value is also implementation-dependent — it may differ across browsers that choose to expose it.
+
+## Value
+
+A {{domxref("DOMHighResTimeStamp")}} or {{jsxref("Operators/null", "null")}} if the value is not exposed.
+
+## Examples
+
+See [Observing separate paint and presentation timings](/en-US/docs/Web/API/PerformanceElementTiming#observing_separate_paint_and_presentation_timings).
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("PerformanceElementTiming.paintTime")}}