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,73 @@
+---
+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 the main thread was blocked from responding to high priority tasks, such as user input, in milliseconds.
+
+## 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.
+
+Take the case of a JavaScript file that takes a total of 145ms to process. After the first major chunk of script, which is processed after 65ms, we could consider breaking the execution of the script into two tasks, the second one taking 80ms to execute. This is preferable to having it all executed in one task, as it gives the browser a chance to handle user interactions in between. This is also known as **yielding**, and could be done for example by inserting a {{domxref("setTimeout()")}} after the first major chunk of script.
+
+> **Note:** See [Optimize long tasks](https://web.dev/articles/optimize-long-tasks) for more information on long tasks and yielding.
+
+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, then run the rest of the script
+2. Alternatively, the browser could run the rest of the script first, then render the frame.
+3. We could also decide **not** to yield and let the browser deal with the entire script in one task.
+
+> **Note:** The browser will generally try to prioritize important tasks (such as user interactions) and rendering new frames over less important tasks it might have queued. The browser will _try_ to render a new frame every 16ms.
+
+Assuming the rendering time is 10ms, 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 `duration` in all three instances is 145ms. The total `blockingDuration` in the first two is the same (55ms) — the browser just decides to split the work in different ways in each.
+
+The third option 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, it is the time above the 50ms that is important to measure for determining the severity of jank.
+
+> **Note:** 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) for Long Animation Frames API examples.
+
+## 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/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 (for example mouse or keyboard) to be queued during the course of 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) for Long Animation Frames API examples.
+
+## 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 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.
+
+## Description
+
+Long animation frames (LoAFs) are rendering updates that are delayed beyond 50ms. LoAFs can cause slow user interface (UI) updates, resulting in seemingly unresponsive controls and [janky](/en-US/docs/Glossary/Jank) (or non-smooth) animated effects and scrolling, leading to user frustration.
+
+The `PerformanceLongAnimationFrameTiming` interface provides a granular set of information on LoAFs allowing developers to narrow down their root causes:
+
+- It provides a detailed set of timestamps for each LoAF.
+- It provides 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 timing performance entry types by qualifying them as follows:
+
+- {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns a {{domxref("DOMHighResTimeStamp")}} representing the time taken to process the LoAF in it's entirety, in milliseconds.
+- {{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 when the animation frame started, in milliseconds.
+
+This interface also supports the following properties:
+
+- {{domxref("PerformanceLongAnimationFrameTiming.blockingDuration")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : A {{domxref("DOMHighResTimeStamp")}} indicating the total time the main thread was blocked from responding to high priority tasks, such as user input, in milliseconds. 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 (for example mouse or keyboard) to be queued during the course of the current animation frame, in milliseconds.
+- {{domxref("PerformanceLongAnimationFrameTiming.renderStart")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns a {{domxref("DOMHighResTimeStamp")}} indicating the start time of the rendering cycle in milliseconds, 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) for Long Animation Frames API examples.
+
+## 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 in milliseconds, 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) for Long Animation Frames API examples.
+
+## 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: attribution
+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 only provided for scripts running in the main thread of a page, including same-origin `<iframe>`s. 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 {{jsxref("Array")}} of {{domxref("PerformanceScriptTiming")}} objects.
+
+## Examples
+
+See [Long animation frame timing](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing) for Long Animation Frames API examples.
+
+## 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) for Long Animation Frames API examples.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Long animation frame timing](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing)
+- {{domxref("PerformanceScriptTiming")}}