feat: Editorial review: Long animation frames API docs

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

@@ -57,8 +57,10 @@ The following interfaces are present in the Performance API:
   - : 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 first input delay (FID).
+- {{domxref("PerformanceLongAnimationFrameTiming")}}
+  - : 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")}}
-  - : Detects long tasks that occupy rendering and block other tasks from being executed.
+  - : 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.
 - {{domxref("PerformanceMeasure")}}
@@ -73,6 +75,8 @@ 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")}}
+  - : 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")}}
@@ -90,6 +94,7 @@ The following guides help you to understand key concepts of the Performance API
 - [Navigation timing](/en-US/docs/Web/API/Performance_API/Navigation_timing): Measuring navigation timing of a document.
 - [User timing](/en-US/docs/Web/API/Performance_API/User_timing): Measuring and recording performance data custom to your application.
 - [Server timing](/en-US/docs/Web/API/Performance_API/Server_timing): Collecting server-side metrics.
+- [Long animation frame timing](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing): Collecting metrics on long animation frames (LoAFs) and their causes.
 - [Monitoring bfcache blocking reasons](/en-US/docs/Web/API/Performance_API/Monitoring_bfcache_blocking_reasons): Reporting on why the current document was blocked from using the back/forward cache ({{Glossary("bfcache")}}).
 
 ## Specifications

files/en-us/web/api/performanceentry/entrytype/index.md

@@ -46,6 +46,12 @@ A string. The return value depends on the subtype of the `PerformanceEntry` obje
 
     The entry instance will be a {{domxref("LayoutShift")}} object.
 
+- `long-animation-frame`
+
+  - : Reports instances of [long animation frames (LoAFs)](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing#what_is_a_long_animation_frame).
+
+    The entry instance will be a {{domxref("PerformanceLongAnimationFrameTiming")}} object.
+
 - `longtask`
 
   - : Reports instances of long tasks.

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

@@ -18,12 +18,14 @@ The `PerformanceEntry` instances will always be one of the following subclasses:
 - {{domxref("LargestContentfulPaint")}}
 - {{domxref("LayoutShift")}}
 - {{domxref("PerformanceEventTiming")}}
+- {{domxref("PerformanceLongAnimationFrameTiming")}}
 - {{domxref("PerformanceLongTaskTiming")}}
 - {{domxref("PerformanceMark")}}
 - {{domxref("PerformanceMeasure")}}
 - {{domxref("PerformanceNavigationTiming")}}
 - {{domxref("PerformancePaintTiming")}}
 - {{domxref("PerformanceResourceTiming")}}
+- {{domxref("PerformanceScriptTiming")}}
 - {{domxref("PerformanceServerTiming")}}
 - {{domxref("TaskAttributionTiming")}}
 - {{domxref("VisibilityStateEntry")}}

files/en-us/web/api/performancelonganimationframetiming/blockingduration/index.md

@@ -0,0 +1,70 @@
+---
+title: "PerformanceLongAnimationFrameTiming: blockingDuration property"
+short-title: blockingDuration
+slug: Web/API/PerformanceLongAnimationFrameTiming/blockingDuration
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.PerformanceLongAnimationFrameTiming.blockingDuration
+---
+
+{{SeeCompatTable}}{{APIRef("Performance API")}}
+
+The **`blockingDuration`** read-only property of the {{domxref("PerformanceLongAnimationFrameTiming")}} interface returns a {{domxref("DOMHighResTimeStamp")}} indicating the total time in milliseconds that the main thread was blocked from responding to high priority tasks, such as user input.
+
+## Description
+
+`blockingDuration` 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. Let's look at an example to clarify what this means.
+
+Consider a JavaScript file that takes a total of 145ms to process. After the first major chunk of the script is processed in 65ms, we could consider breaking the execution of the remaining script into a second task, with this second one taking 80ms to execute. Splitting the processing in this way is preferable to the complete script execution as one task because it gives the browser a chance to handle user interactions between tasks. This approach is known as **yielding**. As an example, you can yield by inserting a {{domxref("setTimeout()")}} after the first major chunk of the script is executed.
+
+There are three options to consider here in how the script might end up being processed:
+
+1. If we yield after the first 65ms, the browser can decide to render a frame before running the rest of the script.
+2. Alternatively, the browser could run the rest of the script first, and then render the frame.
+3. We could also decide **not** to yield and let the browser process the entire script as a single task.
+
+> **Note:** The browser generally tries to prioritize important tasks, such as user interactions and rendering new frames, over less important tasks it might have queued. The browser _tries_ to render a new frame every 16ms.
+
+We mentioned earlier that the total processing time for the script is 145ms. Assuming the time for rendering the UI update is 10ms, the timings for the LoAFs in each of the three options are as follows:
+
+| Option | `duration` (LoAF 1) | `blockingDuration` (LoAF1)        | `duration` (LoAF2) | `blockingDuration` (LoAF2) |
+| ------ | ------------------- | --------------------------------- | ------------------ | -------------------------- |
+| 1      | 65ms                | 15ms (65 - 50)                    | 80ms               | 40ms (80 + 10 - 50)        |
+| 2      | 145ms (65 + 80)     | 55ms ((65 - 50) + (80 + 10 - 50)) | n/a\*              | n/a\*                      |
+| 3      | 145ms (65 + 80)     | 105ms ((65 + 80) + 10 - 50)       | n/a\*              | n/a\*                      |
+
+`*` In options 2 and 3, there is only a single LoAF.
+
+Note that the total `blockingDuration` in the first two options is the same (55ms) — in each case the browser has decided to split the work in different ways.
+
+Option 3, however, has a much longer `blockingDuration` because the browser is completely blocked and unable to interrupt the long task at all. This highlights the importance of optimizing long tasks by yielding — regardless of how the browser decides to handle the tasks, the blocking duration will still be less than if you don't yield at all.
+
+The difference between `duration` and `blockingDuration` of LoAFs can be summarised as follows:
+
+- `duration` is a measure of the LoAF's total response time, which is useful for understanding whether the frame's layout, painting, etc. took a long time.
+- `blockingDuration` is a measure of the total time the LoAF blocked the main thread from responding to high priority tasks, such as user interactions, which can cause the UI to feel [janky](/en-US/docs/Glossary/Jank). To put it another way, it is a measure of the effect the LoAF will have on responsiveness.
+
+The reason why the `blockingDuration` of each task is calculated as `duration - 50ms` is that response delays of above 50ms start to be perceptible by users. This threshold is when users start noticing sluggishness; therefore, the time above the 50ms mark is important to measure for determining the severity of jank. See [Total Blocking Time (TBT)](https://web.dev/articles/tbt) for more details.
+
+## Value
+
+A {{domxref("DOMHighResTimeStamp")}}.
+
+## Examples
+
+See [Long animation frame timing](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing#examples) for examples related to the Long Animation Frames API.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Long animation frame timing](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing)
+- {{domxref("PerformanceScriptTiming")}}
+- [Optimize long tasks](https://web.dev/articles/optimize-long-tasks) on web.dev (2024)

files/en-us/web/api/performancelonganimationframetiming/firstuieventtimestamp/index.md

@@ -0,0 +1,34 @@
+---
+title: "PerformanceLongAnimationFrameTiming: firstUIEventTimestamp property"
+short-title: firstUIEventTimestamp
+slug: Web/API/PerformanceLongAnimationFrameTiming/firstUIEventTimestamp
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.PerformanceLongAnimationFrameTiming.firstUIEventTimestamp
+---
+
+{{SeeCompatTable}}{{APIRef("Performance API")}}
+
+The **`firstUIEventTimestamp`** read-only property of the {{domxref("PerformanceLongAnimationFrameTiming")}} interface returns a {{domxref("DOMHighResTimeStamp")}} indicating the time of the first UI event — such as a mouse or keyboard event — to be queued during the current animation frame.
+
+## Value
+
+A {{domxref("DOMHighResTimeStamp")}}.
+
+## Examples
+
+See [Long animation frame timing](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing#examples) for examples related to the Long Animation Frames API.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Long animation frame timing](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing)
+- {{domxref("PerformanceScriptTiming")}}

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

@@ -0,0 +1,75 @@
+---
+title: PerformanceLongAnimationFrameTiming
+slug: Web/API/PerformanceLongAnimationFrameTiming
+page-type: web-api-interface
+status:
+  - experimental
+browser-compat: api.PerformanceLongAnimationFrameTiming
+---
+
+{{SeeCompatTable}}{{APIRef("Performance API")}}
+
+The **`PerformanceLongAnimationFrameTiming`** interface is specified in the Long Animation Frames API and provides metrics on long animation frames (LoAFs) that occupy rendering and block other tasks from being executed.
+
+## Description
+
+Long animation frames (LoAFs) are rendering updates that are delayed beyond 50ms. LoAFs can result in slow user interface (UI) updates, making controls appear unresponsive and causing [janky](/en-US/docs/Glossary/Jank) (non-smooth) animated effects and scrolling. This often leads to user frustration.
+
+The `PerformanceLongAnimationFrameTiming` interface provides the following granular set of information on LoAFs, allowing developers to narrow down their root causes:
+
+- A detailed set of timestamps for each LoAF.
+- Detailed information on each script that contributed to creating the LoAF, via the {{domxref("PerformanceLongAnimationFrameTiming.scripts")}} property. This returns an array of {{domxref("PerformanceScriptTiming")}} objects, one for each script.
+
+## Inheritance
+
+`PerformanceLongAnimationFrameTiming` inherits from {{domxref("PerformanceEntry")}}.
+
+{{InheritanceDiagram}}
+
+## Instance properties
+
+This interface extends the following {{domxref("PerformanceEntry")}} properties for long animation frame performance entries:
+
+- {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns a {{domxref("DOMHighResTimeStamp")}} representing the time taken in milliseconds to process the LoAF in its entirety.
+- {{domxref("PerformanceEntry.entryType")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns the entry type, which is always `"long-animation-frame"`.
+- {{domxref("PerformanceEntry.name")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns the entry name, which is always `"long-animation-frame"`.
+- {{domxref("PerformanceEntry.startTime")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns a {{domxref("DOMHighResTimeStamp")}} representing the time in milliseconds when the animation frame started.
+
+This interface also supports the following properties:
+
+- {{domxref("PerformanceLongAnimationFrameTiming.blockingDuration")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns a {{domxref("DOMHighResTimeStamp")}} indicating the total time in milliseconds that 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")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns a {{domxref("DOMHighResTimeStamp")}} indicating the time of the first UI event — such as a mouse or keyboard event — to be queued during the current animation frame.
+- {{domxref("PerformanceLongAnimationFrameTiming.renderStart")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns 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.scripts")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns an array of {{domxref("PerformanceScriptTiming")}} instances.
+- {{domxref("PerformanceLongAnimationFrameTiming.styleAndLayoutStart")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns a {{domxref("DOMHighResTimeStamp")}} indicating the beginning of the time period spent in style and layout calculations for the current animation frame, in milliseconds.
+
+## Instance methods
+
+- {{domxref("PerformanceLongAnimationFrameTiming.toJSON()")}} {{Experimental_Inline}}
+  - : Returns a JSON representation of the `PerformanceLongAnimationFrameTiming` object.
+
+## Examples
+
+See [Long animation frame timing](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing#examples) for examples related to the Long Animation Frames API.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Long animation frame timing](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing)
+- {{domxref("PerformanceScriptTiming")}}

files/en-us/web/api/performancelonganimationframetiming/renderstart/index.md

@@ -0,0 +1,34 @@
+---
+title: "PerformanceLongAnimationFrameTiming: renderStart property"
+short-title: renderStart
+slug: Web/API/PerformanceLongAnimationFrameTiming/renderStart
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.PerformanceLongAnimationFrameTiming.renderStart
+---
+
+{{SeeCompatTable}}{{APIRef("Performance API")}}
+
+The **`renderStart`** read-only property of the {{domxref("PerformanceLongAnimationFrameTiming")}} interface returns 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.
+
+## Value
+
+A {{domxref("DOMHighResTimeStamp")}}.
+
+## Examples
+
+See [Long animation frame timing](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing#examples) for examples related to the Long Animation Frames API.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Long animation frame timing](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing)
+- {{domxref("PerformanceScriptTiming")}}

files/en-us/web/api/performancelonganimationframetiming/scripts/index.md

@@ -0,0 +1,36 @@
+---
+title: "PerformanceLongAnimationFrameTiming: scripts property"
+short-title: scripts
+slug: Web/API/PerformanceLongAnimationFrameTiming/scripts
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.PerformanceLongAnimationFrameTiming.scripts
+---
+
+{{SeeCompatTable}}{{APIRef("Performance API")}}
+
+The **`scripts`** read-only property of the {{domxref("PerformanceLongAnimationFrameTiming")}} interface returns an array of {{domxref("PerformanceScriptTiming")}} objects.
+
+Script attribution is provided only for scripts running in the main thread of a page, including same-origin `<iframe>`s. However, cross-origin `<iframe>`s, [web workers](/en-US/docs/Web/API/Web_Workers_API), [service workers](/en-US/docs/Web/API/Service_Worker_API), and [extension](/en-US/docs/Mozilla/Add-ons/WebExtensions) code will not have script attribution in long animation frames, even if they impact the duration of one.
+
+## Value
+
+An array of {{domxref("PerformanceScriptTiming")}} objects.
+
+## Examples
+
+See [Long animation frame timing](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing#examples) for examples related to the Long Animation Frames API.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Long animation frame timing](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing)
+- {{domxref("PerformanceScriptTiming")}}

files/en-us/web/api/performancelonganimationframetiming/styleandlayoutstart/index.md

@@ -0,0 +1,34 @@
+---
+title: "PerformanceLongAnimationFrameTiming: styleAndLayoutStart property"
+short-title: styleAndLayoutStart
+slug: Web/API/PerformanceLongAnimationFrameTiming/styleAndLayoutStart
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.PerformanceLongAnimationFrameTiming.styleAndLayoutStart
+---
+
+{{SeeCompatTable}}{{APIRef("Performance API")}}
+
+The **`styleAndLayoutStart`** read-only property of the {{domxref("PerformanceLongAnimationFrameTiming")}} interface returns a {{domxref("DOMHighResTimeStamp")}} indicating the beginning of the time period spent in style and layout calculations for the current animation frame, in milliseconds.
+
+## Value
+
+A {{domxref("DOMHighResTimeStamp")}}.
+
+## Examples
+
+See [Long animation frame timing](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing#examples) for examples related to the Long Animation Frames API.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Long animation frame timing](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing)
+- {{domxref("PerformanceScriptTiming")}}