index.bs

<pre class=metadata>
Title: Long Animation Frames API
Group: webperf
Status: ED
Shortname: long-animation-frames
Level: 1
URL: https://w3c.github.io/long-animation-frames/
Editor: Noam Rosenthal, Google https://google.com, nrosenthal@google.com, w3cid 121539
Repository: w3c/long-animation-frames
Test Suite: https://wpt.fyi/results/long-animation-frames
Abstract: This document defines an API that web page authors can use to detect presence of "long animation frames" that monopolize the UI thread for extended periods of time and block other critical tasks from being executed - e.g. reacting to user input.
Status Text: If you wish to make comments regarding this document, please create an issue in the <a href="https://github.com/w3c/long-animation-frames">Long Animation Frames</a> repository.
Default Highlight: js
</pre>

<pre class=link-defaults>
spec:hr-time; type:dfn; text:duration
</pre>

<style>
dl {
    margin-left: 2em;
}
</style>

<pre class=anchors>
urlPrefix: https://w3c.github.io/performance-timeline/; spec: PERFORMANCE-TIMELINE-2;
    type: interface; url: #the-performanceentry-interface; text: PerformanceEntry;
    type: attribute; for: PerformanceEntry;
        text: name; url: #dom-performanceentry-name
        text: entryType; url: #dom-performanceentry-entrytype
        text: startTime; url: #dom-performanceentry-starttime
        text: duration; url: #dom-performanceentry-duration
    type: dfn; url: #dfn-queue-a-performanceentry; text: Queue the PerformanceEntry
    type: dfn; url: #dfn-register-a-performance-entry-type; text: register a performance entry type
    type: attribute; for: PerformanceObserver;
        text: supportedEntryTypes; url: #supportedentrytypes-attribute;
urlPrefix: https://w3c.github.io/hr-time/; spec: HR-TIME-2;
    type: typedef; url: #idl-def-domhighrestimestamp; text: DOMHighResTimeStamp;
    type: interface; url: #dfn-performance; text: Performance;
    type: attribute; for: Performance;
        text: now(); url: #dom-performance-now
    type: dfn; text: current high resolution time; url: #dfn-current-high-resolution-time;
urlPrefix: https://w3c.github.io/paint-timing/; spec: PAINT-TIMING;
    type: interface; url: #painttimingmixin; text: PaintTimingMixin;
    type: dfn; url: #paint-timing-info; text: paint timing info;
    type: dfn; for: PaintTimingMixin; url: #painttimingmixin-paint-timing-info; text: paint timing info;
    type: dfn; for: paint timing info; text: rendering update end time;
urlPrefix: https://html.spec.whatwg.org/multipage/; spec: HTML;
    type: dfn; url: #event-loop; text: event loop;
    type: dfn; url: #event-loop-processing-model; text: event loop processing model;
    type: dfn; url: #browsing-context; text: browsing context;
    type: dfn; url: #calling-scripts; text: calling scripts;
    type: dfn; url: #list-of-the-descendant-browsing-contexts; text: list of the descendant browsing contexts;
    type: dfn; url: #ancestor-browsing-context; text: ancestor;
    type: dfn; url: #unit-of-related-browsing-contexts; text: unit of related browsing contexts
    type: dfn; url: #script-evaluation-environment-settings-object-set; text: script evaluation environment settings object set
    type: dfn; url: #integration-with-the-javascript-agent-cluster-formalism; text: agent cluster
    type: dfn; url: #concept-task-document; for: task; text: document;
    type: dfn; url: #running-script; text: running script;
    type: dfn; url: #muted-errors; for: classic script; text: muted errors;
    type: dfn; url: #cors-cross-origin; text: CORS cross-origin;
    type: dfn; url: #implied-document; text: implied document;
    type: dfn: url: #concept-task-document; text: document; for: task;
urlPrefix: https://tc39.github.io/ecma262/; spec: ECMASCRIPT;
    type: dfn; url: #sec-code-realms; text: JavaScript Realms;
urlPrefix: https://dom.spec.whatwg.org/; spec: DOM;
    type: attribute; for: Element;
        text: id; url: #dom-element-id;
urlPrefix: https://webidl.spec.whatwg.org/; spec: WEBIDL;
    type: dfn; text: identifier; url: #dfn-identifier;
    type: dfn; text: attribute; url: #dfn-attribute;
urlPrefix: https://tc39.es/ecma262/multipage/managing-memory.html
    type: dfn; text: weakrefderef; url: #sec-weakrefderef;
</pre>

<pre class=link-defaults>
spec:html; type:dfn; for:/; text:browsing context
</pre>

Introduction {#intro}
=====================

As the page is loading and while the user is interacting with the page afterwards, both the application and browser queue various events that are then executed by the browser -- e.g. user agent schedules input events based on user’s activity, the application schedules callbacks for requestAnimationFrame and other callbacks, etc. Once in the queue, the browser dequeues these events one-by-one and executes them.

However, some tasks can take a long time (multiple frames) and if/when that happens, the UI thread may become blocked and block all other tasks as well. To the user, this is commonly visible as a "locked up" page where the browser is unable to respond to user input; this is a major source of bad user experience on the web today:

: Delayed "time to Interactive":
:: while the page is loading, or even completely visually rendered, long tasks often tie up the main thread and prevent the user from interacting with the page. Poorly designed third-party content is frequently the culprit.

: High/variable input latency:
:: critical user-interaction events (e.g. tap, click, scroll, wheel, etc.) are queued behind long tasks which yields janky and unpredictable user experience.

: High/variable event handling latency:
:: like input, processing event callbacks (e.g. onload events, etc.) delay application updates.

: Janky animations and scrolling:
:: some animation and scrolling interactions require coordination between compositor and main threads; if a long task is blocking the main thread it can affect responsiveness of animations and scrolling.

Some applications (and <a href="https://en.wikipedia.org/wiki/Real_user_monitoring">RUM</a> vendors) are already attempting to identify and track cases where "long tasks" happen. For example, one known pattern is to install a ~short periodic timer and inspect the elapsed time between the successive expirations: if the elapsed time is greater than the timer period, then there is high likelihood that one or more long tasks have delayed execution of the event loop. This approach mostly works but has several bad performance implications: by polling to detect long tasks, the application prevents quiescence and long idle blocks (see requestIdleCallback); it’s bad for battery life; there is no way to know what is causing the delay (e.g. first party or third party code).

The <a href="https://developers.google.com/web/fundamentals/performance/rail">RAIL</a> performance model suggests that applications should respond to user input in less than 100ms (for touch move and scrolling, the threshold is 16ms). The goal of this API is to surface notifications about tasks that may prevent the application from hitting these targets. This API surfaces tasks that take 50ms or more. A website without these tasks should respond to user input in under 100ms: it will take less than 50ms to finish the task that is being executed when the user input is received and less than 50ms to execute the task to react to such user input.

Usage Example {#example}
------------------------

<pre class="example highlight">
    const observer = new PerformanceObserver(function(list) {
        for (const entry of list.getEntries()) {
            // Process long task notifications:
            // report back for analytics and monitoring
            // ...
        }
    });
    // Register observer for previous and future long task notifications.
    observer.observe({type: "long-animation-frame", buffered: true});
    // Long script execution after this will result in queueing
    // and receiving "long-animation-frame" entries in the observer.

    // Register observer for previous and future long animation frame notifications.
    // After this, long periods where the main thread is busy will result in queueing
    // and receiving "long-animation-frame" entries in the observer.
    observer.observe({type: "long-animation-frame", buffered: true});
</pre>

Long Animation Frames vs. Long Tasks {#loaf-vs-longtasks}
---------------------------------------------------------

While both [=long tasks=] and long animation frames measure congestion and jank, long animation frames
provide information that has a better correlation with how users perceive this type of congestion.
That's because long animation frames measure a sequence that begins when the main thread is idle,
and end when the frame either renders or the user agents decides there is nothing to render.

The [=task=] term is somewhat of an implementation detail, and the long animation frame addition
attempts to remedy that by introducing a more user-centric metric of the same phenomenon of main
thread congestion/jank.

Because long animation frames are guaranteed to have a maximum of one rendering phase, we can also
use them to expose additional information about the rendering phase itself, such as
{{PerformanceLongAnimationFrameTiming/renderStart}} and {{PerformanceLongAnimationFrameTiming/styleAndLayoutStart}}.

Long Animation Frame Timing {#sec-loaf-timing}
=======================================

A <dfn export>long animation frame</dfn> refers to any of the following occurrences whose duration exceeds 50ms:

* A [=task=], after which updating the rendering is not necessary.

* A [=task=] after which updating the rendering is necessary, up until rendering is updated.

Long Animation Frame timing involves the following new interfaces:

{{PerformanceLongAnimationFrameTiming}} interface {#sec-PerformanceLongAnimationFrameTiming}
------------------------------------------------------------------------

<pre class="idl">
    [Exposed=Window]
    interface PerformanceLongAnimationFrameTiming : PerformanceEntry {
        /* Overloading PerformanceEntry */
        readonly attribute DOMHighResTimeStamp startTime;
        readonly attribute DOMHighResTimeStamp duration;
        readonly attribute DOMString name;
        readonly attribute DOMString entryType;

        readonly attribute DOMHighResTimeStamp renderStart;
        readonly attribute DOMHighResTimeStamp styleAndLayoutStart;
        readonly attribute DOMHighResTimeStamp blockingDuration;
        readonly attribute DOMHighResTimeStamp firstUIEventTimestamp;
        [SameObject] readonly attribute FrozenArray&lt;PerformanceScriptTiming&gt; scripts;
        [Default] object toJSON();
    };

    PerformanceLongAnimationFrameTiming includes PaintTimingMixin;
</pre>

A {{PerformanceLongAnimationFrameTiming}} has a [=frame timing info=] <dfn for=PerformanceLongAnimationFrameTiming>timing info</dfn>.

The {{PerformanceLongAnimationFrameTiming/entryType}} attribute's getter step is to return <code>"long-animation-frame"</code>.

The {{PerformanceLongAnimationFrameTiming/name}} attribute's getter step is to return <code>"long-animation-frame"</code>.

The {{PerformanceLongAnimationFrameTiming/startTime}} attribute's getter step is to return the [=relative high resolution time=] given [=this=]'s [=PerformanceLongAnimationFrameTiming/timing info=]'s [=frame timing info/start time=] and [=this=]'s [=relevant global object=].

The {{PerformanceLongAnimationFrameTiming/duration}} attribute's getter step is to return the [=duration=] between [=this=]'s {{PerformanceEntry/startTime}} and the [=relative high resolution time=] given [=this=]'s [=PerformanceLongAnimationFrameTiming/timing info=]'s [=frame timing info/end time=] and [=this=]'s [=relevant global object=].

The {{PerformanceLongAnimationFrameTiming/renderStart}} attribute's getter step is to return the [=relative high resolution time=] given [=this=]'s [=PerformanceLongAnimationFrameTiming/timing info=]'s [=frame timing info/update the rendering start time=] and [=this=]'s [=relevant global object=].

The {{PerformanceLongAnimationFrameTiming/styleAndLayoutStart}} attribute's getter step is to return the [=relative high resolution time=] given [=this=]'s [=PerformanceLongAnimationFrameTiming/timing info=]'s [=frame timing info/style and layout start time=] and [=this=]'s [=relevant global object=].

The {{PerformanceLongAnimationFrameTiming/firstUIEventTimestamp}} attribute's getter step is to return the [=relative high resolution time=] given [=this=]'s [=PerformanceLongAnimationFrameTiming/timing info=]'s [=frame timing info/first ui event timestamp=] and [=this=]'s [=relevant global object=].

The {{PerformanceLongAnimationFrameTiming/blockingDuration}} attribute's getter steps are:
    1. Let |sortedTaskDurations| be [=PerformanceLongAnimationFrameTiming/timing info=]'s [=frame timing info/task durations=], [=list/sort in descending order|sorted in descending order=].
    1. If [=this=]'s [=PerformanceLongAnimationFrameTiming/timing info=]'s [=frame timing info/update the rendering  start time=] is not zero, then:
        1. Let |renderDuration| be the [=duration=] between [=this=]'s {{PerformanceLongAnimationFrameTiming/renderStart}} and
            the [=relative high resolution time=] given [=this=]'s [=PerformanceLongAnimationFrameTiming/timing info=]'s [=frame timing info/end time=].
        1. Increment |sortedTaskDurations|[0] by |renderDuration|.

            Note: This makes it so that the longest task duration + render duration would be considered blocking if their total
            duration is >50ms.

    1. Let |totalBlockingDuration| be 0.
    1. [=list/iterate|For each=] |duration| in |sortedTaskDurations|, if |duration| is greater than 50 then increment |totalBlockingDuration| by |duration| - 50.
    1. Return |totalBlockingDuration|.

The {{PerformanceLongAnimationFrameTiming/scripts}} attribute's getter steps are:
    1. Let |scripts| be a [=/list=] « ».
    1. Let |entryWindow| be |this|'s [=relevant global object=].
    1. [=list/For each=] |scriptInfo| in [=this=]'s [=frame timing info=]'s [=frame timing info/scripts=]:
        1. Let |scriptWindow| be |scriptInfo|'s [=script timing info/window=].
        1. Let |scriptEntry| be a new {{PerformanceScriptTiming}} in [=this=]'s [=relevant realm=],
            whose [=PerformanceScriptTiming/timing info=] is |scriptInfo| and whose [=PerformanceScriptTiming/window attribution=] is the value corresponding to the first matching statement:

            :  |scriptWindow| is undefined
            :: {{ScriptWindowAttribution/other}}

            :  |scriptWindow| is |entryWindow|
            :: {{ScriptWindowAttribution/self}}

            : |entryWindow|'s associated {{Document}}'s [=node navigable=]'s [=ancestor navigables=] [=list/contains=] |scriptWindow|'s associated {{Document}}'s [=node navigable=]
            :: {{ScriptWindowAttribution/ancestor}}

            : |scriptWindow|'s associated {{Document}}'s [=node navigable=]'s [=ancestor navigables=] [=list/contains=] |entryWindow|'s associated {{Document}}'s [=node navigable=]
            :: {{ScriptWindowAttribution/descendant}}

            : |entryWindow|'s associated {{Document}}'s [=node navigable=]'s [=navigable/top-level traversable=] is |scriptWindow|'s associated {{Document}}'s [=node navigable=]'s [=navigable/top-level traversable=]
            :: {{ScriptWindowAttribution/same-page}}

            : Otherwise
            :: {{ScriptWindowAttribution/other}}.

        1. [=list/Append=] |scriptEntry| to |scripts|.
    1. Return |scripts|.

{{PerformanceScriptTiming}} interface {#sec-PerformanceScriptTiming}
------------------------------------------------------------------------

<pre class="idl">
    enum ScriptInvokerType {
        "classic-script",
        "module-script",
        "event-listener",
        "user-callback",
        "resolve-promise",
        "reject-promise"
    };

    enum ScriptWindowAttribution {
        "self", "descendant", "ancestor", "same-page", "other"
    };

    [Exposed=Window]
    interface PerformanceScriptTiming : PerformanceEntry {
        /* Overloading PerformanceEntry */
        readonly attribute DOMHighResTimeStamp startTime;
        readonly attribute DOMHighResTimeStamp duration;
        readonly attribute DOMString name;
        readonly attribute DOMString entryType;

        readonly attribute ScriptInvokerType invokerType;
        readonly attribute DOMString invoker;
        readonly attribute DOMHighResTimeStamp executionStart;
        readonly attribute DOMString sourceURL;
        readonly attribute DOMString sourceFunctionName;
        readonly attribute long long sourceCharPosition;
        readonly attribute DOMHighResTimeStamp pauseDuration;
        readonly attribute DOMHighResTimeStamp forcedStyleAndLayoutDuration;
        readonly attribute Window? window;
        readonly attribute ScriptWindowAttribution windowAttribution;
        [Default] object toJSON();
    };
</pre>

A {{PerformanceScriptTiming}} has an associated [=script timing info=] <dfn for=PerformanceScriptTiming>timing info</dfn>.

A {{PerformanceScriptTiming}} has an associated {{ScriptWindowAttribution}} <dfn for=PerformanceScriptTiming>window attribution</dfn>.

The {{PerformanceScriptTiming/entryType}} attribute's getter step is to return <code>"script"</code>.

The {{PerformanceScriptTiming/name}} attribute's getter step is to return <code>"script"</code>.

The {{PerformanceScriptTiming/invokerType}} attribute's getter step is to return [=this=]'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/invoker type=].

The {{PerformanceScriptTiming/invoker}} attribute's getter steps are:
    1.  Switch on |this|'s {{PerformanceScriptTiming/invokerType}}:

        : "`classic-script`"
        : "`module-script`"
        :: Return |this|'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/source url=].

        : "`event-listener`"
        ::
            1. Let |targetName| be |this|'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/invoker name=].
            1. If |this|'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/event target element id=] is not the empty string, then:
                Set |targetName| to the [=concatenate|concatenation=] of « |targetName|, "#", |this|'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/event target element id=] ».
            1. Otherwise, If |this|'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/event target element src attribute=] is not the empty string, then:
                Set |targetName| to the [=concatenate|concatenation=] of « |targetName|, "[src=", |this|'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/event target element src attribute=], "]" ».
            1. Return the [=concatenate|concatenation=] of « |targetName|, ".on", [=this=]'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/event type=] ».

            Issue: this feels a bit custom, need to discuss name generation.

        : "`user-callback`"
        :: Return |this|'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/invoker name=].

        : "`resolve-promise`"
        : "`reject-promise`"
        ::
            1. If |this|'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/invoker name=] is the empty string,
                then:
                    1. If |this|'s {{PerformanceScriptTiming/invokerType}} is "`resolve-promise`", then return "`Promise.resolve`".
                    1. Otherwise, return "`Promise.reject`".
            1. Let |thenOrCatch| be "`then`" if {{PerformanceScriptTiming/invokerType}} is "`resolve-promise`"; otherwise "`reject-promise`".
            1. Return the [=concatenate|concatenation=] of « [=script timing info/invoker name=], ".", |thenOrCatch| ».

The {{PerformanceScriptTiming/startTime}} attribute's getter step is to return the [=relative high resolution time=] given [=this=]'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/start time=] and [=this=]'s [=relevant global object=].

The {{PerformanceScriptTiming/duration}} attribute's getter step is to return the [=duration=] between [=this=]'s {{PerformanceScriptTiming/startTime}} and the [=relative high resolution time=] given [=this=]'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/end time=] and [=this=]'s [=relevant global object=].

The {{PerformanceScriptTiming/executionStart}} attribute's getter step is to return 0 if [=this=]'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/execution start time=] is 0; Otherwise the [=relative high resolution time=] given [=this=]'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/execution start time=] and [=this=]'s [=relevant global object=].

The {{PerformanceScriptTiming/forcedStyleAndLayoutDuration}} attribute's getter step is to return an [=implementation-defined=] value that represents time spent performing style and layout synchronously, e.g. by calling {{Window/getComputedStyle()}} or {{Element/getBoundingClientRect()}}.

    Issue: Find a way to make this interoperable/normative. Perhaps mark those functions in WebIDL as requiring synchronous style/layout? Also move to [=PerformanceScriptTiming/timing info=] once that's resolved.

The {{PerformanceScriptTiming/pauseDuration}} attribute's getter step is to return [=this=]'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/pause duration=].

The {{PerformanceScriptTiming/sourceURL}} attribute's getter step is to return [=this=]'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/source url=].
The {{PerformanceScriptTiming/sourceFunctionName}} attribute's getter step is to return [=this=]'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/source function name=].
The {{PerformanceScriptTiming/sourceCharPosition}} attribute's getter step is to return [=this=]'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/source character position=].

The {{PerformanceScriptTiming/window}} attribute's getter steps are:
    1. Let |window| be the result of calling [=weakrefderef|deref=] on [=this=]'s [=PerformanceScriptTiming/timing info=]'s [=script timing info/window=].
    1. If |window| is undefined, then return null; Otherwise return |window|.

The {{PerformanceScriptTiming/windowAttribution}} attribute's getter step is to return [=this=]'s [=PerformanceScriptTiming/window attribution=].

Processing model {#sec-processing-model}
========================================

Note: A user agent implementing the Long Animation Frame API would need to include <code>"long-animation-frame"</code>
    in {{PerformanceObserver/supportedEntryTypes}} for {{Window}} contexts, respectively.

Frame Timing Info {#sec-frame-timing-info}
------------------------------------------
<dfn export>frame timing info</dfn> is a [=struct=] used as a bookkeeping detail by the long animation frame algorithms.
It has the following [=struct/items=]:

<dl dfn-for="frame timing info">
    : <dfn>start time</dfn>
    : <dfn>current task start time</dfn>
    : <dfn>update the rendering start time</dfn>
    : <dfn>style and layout start time</dfn>
    : <dfn>first ui event timestamp</dfn>
    : <dfn>end time</dfn>
    :: A {{DOMHighResTimeStamp}}, initially 0.
        Note: all the above are [=monotonic clock/unsafe current time|unsafe=],
        and should be [=coarsen time|coarsened=] when exposed via an API.

    : <dfn>task durations</dfn>
    :: A [=/list=] of {{DOMHighResTimeStamp}}, initially empty.

    : <dfn>scripts</dfn>
    :: A [=/list=] of [=script timing info=], initially empty.

    : <dfn>pending script</dfn>
    :: Null or a [=script timing info=], initially null.

    : <dfn>script initiated</dfn>
    :: A boolean, initially false.
</dl>

<dfn export>script timing info</dfn> is a [=struct=]. It has the following [=struct/items=]:

<dl dfn-for="script timing info">
    : <dfn>invoker type</dfn>
    :: A {{ScriptInvokerType}}.

    : <dfn>start time</dfn>
    : <dfn>end time</dfn>
    : <dfn>execution start time</dfn>
    :: An unsafe {{DOMHighResTimeStamp}}, initially 0.

    : <dfn>pause duration</dfn>
    :: A {{DOMHighResTimeStamp}} representing a number of milliseconds, initially 0.

    : <dfn>invoker name</dfn>
    : <dfn>source url</dfn>
    : <dfn>source function name</dfn>
    : <dfn>event type</dfn>
    : <dfn>event target element id</dfn>
    : <dfn>event target element src attribute</dfn>
    :: A string, initially the empty string.

    : <dfn>source character position</dfn>
    :: A number, initially -1.

    : <dfn>window</dfn>
    :: A {{WeakRef}} to a {{Window}}.
</dl>

A {{Document}} has a null or [=frame timing info=] <dfn export>current frame timing info</dfn>, initially null.


Report Long Animation Frames {#loaf-processing-model}
------------------------------------------

### Long Animation Frame Monitoring {#loaf-monitoring}

<div algorithm="Accessing the frame timing info">
    To get the <dfn>nearest same-origin root</dfn> for a {{Document}} |document|:
    1. Let |ancestors| be the [=ancestor navigables=] of |document|.

    1. [=list/For each=] |ancestorNavigable| in |ancestors|:
        If |ancestorNavigable|'s [=navigable/active document=]'s [=Document/origin=] is [=same origin=] with |document|'s [=Document/origin=],
            and |ancestorNavigable|'s [=navigable/active document=]'s [=relevant agent=] is |document|'s [=relevant agent=],
            then return |ancestorNavigable|'s [=navigable/active document=].

    1. Return |document|.

    The <dfn>relevant frame timing info</dfn> for a {{Document}} |document| is its [=nearest same-origin root=]'s [=current frame timing info=].
</div>

<div algorithm="Record if needed">
    To <dfn export>start recording task time if needed</dfn> given an [=environment settings object=] |settingsObject|:

    Note: this is called from the [=fire an event=] algorithm and the [=create script entry point=] algorithm.
    It starts recording frame timing info for the duration of the [=fire an event|event firing=] or [=create script entry point|script=], as if it was a task.
    This accounts for script and event durations that are not associated with tasks, which would otherwise require an [=implied document=].

    1. If |settingsObject| is not a {{Document}} or its [=relevant frame timing info=] is non-null, then return false.
    1. [=Record task start time=] given the [=unsafe shared current time=] and |settingsObject|.
    1. Return true.
</div>


<div algorithm="Record task start time">
    To <dfn export>record task start time</dfn> given a {{DOMHighResTimeStamp}} |unsafeTaskStartTime|, and a {{Document}} |document|:

    1. Let |root| be |document|'s [=nearest same-origin root=].

    1. If |root|'s [=current frame timing info=] is null,
        then set |root|'s [=current frame timing info=] to a new [=frame timing info=] whose [=frame timing info/start time=] is |unsafeTaskStartTime|.

    1. Set |root|'s [=current frame timing info=]'s [=frame timing info/current task start time=] to |unsafeTaskStartTime|.

    1. If |root|'s [=current frame timing info=]'s 's [=frame timing info/start time=] is 0, then set |root|'s [=current frame timing info=]'s [=frame timing info/start time=] to |unsafeTaskStartTime|.
</div>

<div algorithm="Report task end time">
    To <dfn export>record task end time</dfn> given an {{DOMHighResTimeStamp}} |unsafeTaskEndTime|, and a {{Document}} |document|:

    1. Let |timingInfo| be |document|'s [=relevant frame timing info=].

    1. If |timingInfo| is null, then return.

        Note: This can occur if the browser becomes hidden during the sequence.

    1. Let |safeTaskEndTime| be the [=relative high resolution time=] given |unsafeTaskEndTime| and |document|'s [=relevant global object=].

    1. Let |safeTaskStartTime| be the [=relative high resolution time=] given |timingInfo|'s [=frame timing info/current task start time=] and |document|'s [=relevant global object=].

    1. [=list/Append=] the [=duration=] between |safeTaskStartTime| and |safeTaskEndTime| to |timingInfo|'s [=task durations=].

    1. If the user agent believes that updating the rendering of |document|'s [=node navigable=] would have no visible effect, then:
        1. set |document|'s [=nearest same-origin root=]'s [=current frame timing info=] to null.

        1. Let |frameDuration| be the [=duration=] between the [=relative high resolution time=] given |timingInfo|'s [=frame timing info/start time=] and |global|,
            and the [=relative high resolution time=] given |unsafeTaskEndTime| and |global|.

        1. If |frameDuration| is equal or greater than 50 milliseconds, then [=queue a long animation frame entry=] given |document|, |timingInfo|, and a new [/=paint timing info=].

        Note: even though there was no actual visual update, we mark a [=long animation frame=] here because it would be blocking in a scenario where it coincided with an unrelated visual update.
</div>

<div algorithm="Record rendering time">
    To <dfn export>record rendering time</dfn> given a {{Document}} |document|, and a {{DOMHighResTimeStamp}} |unsafeStyleAndLayoutStart|:

    1. Let |timingInfo| be |document|'s [=relevant frame timing info=].

    1. If |timingInfo| is null, then return.

        Note: This can occur if the browser becomes hidden during the sequence.

    1. Let |frameDuration| be the [=duration=] between the [=relative high resolution time=] given |timingInfo|'s [=frame timing info/start time=] and |global|,
        and the [=current high resolution time=] given |global|.

    1. If |frameDuration| is less than 50 milliseconds, then set |document|'s [=nearest same-origin root=]'s [=current frame timing info=] to null and return.

    1. Set |timingInfo|'s [=frame timing info/update the rendering start time=] to |timingInfo|'s [=frame timing info/current task start time=].

    1. Set |timingInfo|'s [=frame timing info/style and layout start time=] to |unsafeStyleAndLayoutStart|.
</div>

<div algorithm="Queue frame timing">
    To <dfn export>queue a long animation frame entry</dfn> given a {{Document}} |document|, a [=frame timing info=] |timingInfo|, and a [=/paint timing info=] |paintTimingInfo|,
        [=queue a PerformanceEntry|queue=] a new {{PerformanceLongAnimationFrameTiming}} in |document|'s [=relevant realm=],
        whose [=PerformanceLongAnimationFrameTiming/timing info=] is |timingInfo| and whose [=PaintTimingMixin/paint timing info=] is |paintTimingInfo|.
</div>

### Long Script Monitoring ### {#long-script-monitoring}

<div algorithm="Report pending user callback">
    To <dfn export>record timing info for user callback</dfn> given a [=callback function=] |callback| and an [=environment settings object=] |settings|:
    [=Create script entry point=] given |settings|, "`user-callback`", and the following steps given a [=script timing info=] |scriptTimingInfo|:

        1. Set |scriptTimingInfo|'s [=script timing info/invoker name=] to |callback|'s [=identifier=].
        1. [=Apply source location=] for |scriptTimingInfo| given |callback|.
</div>

<div algorithm="Report pending timer">
    To <dfn export>record timing info for timer handler</dfn> given a string or {{Function}} |handler|, an [=environment settings object=] |settings|, and a boolean |repeat|:
        [=Create script entry point=] given |settings|, "`user-callback`",
            and the following steps given a [=script timing info=] |scriptTimingInfo|:

            1. Let |setTimeoutOrInterval| be "setInterval" if |repeat| is true, "setTimeout" otherwise.
            1. Set |scriptTimingInfo|'s [=script timing info/invoker name=] to [=concatenate|concatenation=] of
                « TimerHandler:", |setTimeoutOrInterval| ».
            1. If |handler| is a {{Function}}, then [=apply source location=] for |scriptTimingInfo| given |handler|.
</div>

<div algorithm="Report event listener">
    To <dfn export>record timing info for event listener</dfn> given an {{Event}} |event| and an {{EventListener}} |listener|:
        [=Create script entry point=] given |listener|'s [=relevant settings object=], "`event-listener`",
        and the following steps given a [=script timing info=] |scriptTimingInfo| and a [=frame timing info=] |frameTimingInfo|:

        1. Set |scriptTimingInfo|'s [=script timing info/event type=] to |event|'s {{Event/type}}.
        1. Let |target| be |event|'s {{Event/currentTarget}}.
        1. If |target| is a {{Node}}, then:
            1. Set |scriptTimingInfo|'s [=script timing info/invoker name=] to |target|'s {{Node/nodeName}}.
            1. If |target| is an {{Element}}, then:
                1. Set |scriptTimingInfo|'s [=script timing info/event target element id=] to |target|'s [=Element/id=].
                1. Set |scriptTimingInfo|'s [=script timing info/event target element src attribute=] to the result of [=get an attribute by name|getting an attribute value by name=] "`src`" and |target|.
        1. Else, set |scriptTimingInfo|'s [=script timing info/invoker name=] to |target|'s interface name.
        1. [=Apply source location=] for |scriptTimingInfo| given |listener|'s [=event listener/callback=].
        1. If |event| is a {{UIEvent}}, and |frameTimingInfo|'s [=frame timing info/first ui event timestamp=] is 0,
            then set |frameTimingInfo|'s [=frame timing info/first ui event timestamp=] to |event|'s {{Event/timeStamp}}.
</div>

<div algorithm="Report promise resolver">
    To <dfn export>record timing info for promise resolver</dfn> given a {{Promise}} |promise| and a "`resolve-promise`" or "`reject-promise`" |type|:
    1. [=Create script entry point=] given |promise|'s [=relevant realm=]'s [=realm/settings object=], |type|,
        and the following steps given a [=script timing info=] |scriptTimingInfo|:

        1. Set |scriptTimingInfo|'s [=script timing info/invoker name=] to |promise|'s [=Promise/invoker name when created=].
        1. Set |scriptTimingInfo|'s [=script timing info/source url=] to |promise|'s [=Promise/script url when created=].
</div>

<div algorithm="Set source URL for script block">
    To <dfn>set source url for script block</dfn> given a [=script timing info=] |scriptTimingInfo|, a [=/script=] |script|, and a [=/URL=]-or-null |url|:
        1. If |url| is null, then return.
        1. If |url|'s [=url/scheme=] is "`http`" or "`https`", then set |scriptTimingInfo|'s [=script timing info/source url=] to |script|'s [=script/base URL=].
        1. Otherwise, if |url|'s [=url/scheme=] is "`blob`" or "`data`" then set |scriptTimingInfo|'s [=script timing info/source url=] to the [=concatenate|concatenation=] of  « |url|'s [=url/scheme=], ":"" ».
</div>

<div algorithm="Report classic script execution">
    To <dfn export>record classic script creation time</dfn> given a [=/script=] |script| and a [=/URL=]-or-null |originalSourceURL|:
        1. [=Create script entry point=] with |script|'s [=script/settings object=], "`classic-script`",
            and the following step given a [=script timing info=] |scriptTimingInfo|:
            [=Set source url for script block=] given |scriptTimingInfo|, |script|, and |originalSourceURL|.
</div>

<div algorithm="Report classic script execution start">
    To <dfn export>record classic script execution start time</dfn> given a [=classic script=] |script|:
        1. Let |settings| be |script|'s [=script/settings object=].
        1. If |script|'s [=classic script/muted errors=] is true, then return.
        1. If |settings| is not a {{Window}}, then return.
        1. Let |document| be |settings|'s {{Window/document}}.
        1. Let |frameTimingInfo| be |document|'s [=relevant frame timing info=].
        1. [=Assert=]: |frameTimingInfo| is non-null.
        1. If |frameTimingInfo|'s [=frame timing info/pending script=] is not null, then return.
        1. Set |frameTimingInfo|'s [=frame timing info/pending script=]'s [=script timing info/execution start time=] to the [=unsafe shared current time=].
</div>

<div algorithm="Report module script execution start">
    To <dfn export>record module script execution start time</dfn> given a [=module script=] |script|:
        [=Create script entry point=] with |script|'s [=script/settings object=], "`module-script`",
            and the following step given a [=script timing info=] |scriptTimingInfo|:
            1. Set |scriptTimingInfo|'s [=script timing info/execution start time=] to |script|'s |scriptTimingInfo|'s [=script timing info/start time=].
            1. [=Set source url for script block=] given |scriptTimingInfo|, |script|, and |script|'s [=script/base URL=].
</div>

<div algorithm="Create script entry point">
    To <dfn>create script entry point</dfn> given an [=environment settings object=] |settings|,
        a {{ScriptInvokerType}} |invokerType|, and |steps|,
        which is an algorithm that takes a [=script timing info=] and an optional [=frame timing info=]:

        1. If |settings| is not a {{Window}}, then return.
        1. Let |document| be |settings|'s {{Window/document}}.
        1. If |document| is not [=fully active=] or	{{Document/hidden}}, then return.
        1. Let |didStartRecording| be the result of calling [=start recording task time if needed=] given |document|.
        1. Let |frameTimingInfo| be |document|'s [=relevant frame timing info=].
        1. [=Assert=]: |frameTimingInfo| is non-null.
        1. Set |frameTimingInfo|'s [=script initiated=] to |didStartRecording|.
        1. If |frameTimingInfo|'s [=frame timing info/pending script=] is not null, then return.
        1. Let |scriptTimingInfo| be a new [=script timing info=]
            whose [=script timing info/start time=] is the [=unsafe shared current time=],
            and whose [=script timing info/invoker type=] is |invokerType|.
        1. Run |steps| given |scriptTimingInfo| and |frameTimingInfo|.
        1. Set |scriptTimingInfo|'s [=script timing info/window=] to |settings|.
        1. Set |frameTimingInfo|'s [=frame timing info/pending script=] to |scriptTimingInfo|.
</div>

<div algorithm="Record timing info for microtask checkpoint">
    To <dfn export>record timing info for microtask checkpoint</dfn>:

    1. Let |script| be the [=running script=].
    1. Let |settings| be |script|'s [=script/settings object=].
    1. Let |document| be |settings|'s {{Window/document}}.
    1. If |document| is not [=fully active=] or	{{Document/hidden}}, then return.
    1. Let |frameTimingInfo| be |document|'s [=relevant frame timing info=].
    1. [=Assert=]: |frameTimingInfo| is not null.
    1. Let |scriptTimingInfo| be |frameTimingInfo|'s [=frame timing info/pending script=].
    1. Let |endTime| be the [=unsafe shared current time=].
    1. Set |frameTimingInfo|'s [=frame timing info/pending script=] to null.
    1. If |scriptTimingInfo| is null, then return.
    1. Set |scriptTimingInfo|'s [=script timing info/end time=] to |endTime|.
    1. If |script| is a [=classic script=] whose [=classic script/muted errors=] is true, then:
        1. set |scriptTimingInfo|'s [=script timing info/source url=] to the empty string.
        1. set |scriptTimingInfo|'s [=script timing info/source character position=] to -1.
        1. set |scriptTimingInfo|'s [=script timing info/source function name=] to the empty string.
    1. If the [=duration=] between |scriptTimingInfo|'s [=script timing info/start time=] and |scriptTimingInfo|'s [=script timing info/end time=] is greater than 5 milliseconds, then
        [=list/append=] |scriptTimingInfo| to |frameTimingInfo|'s [=frame timing info/scripts=].
    1. If |frameTimingInfo| is [=frame timing info/script initiated=], then [=record task end time=] given |endTime| and |document|.

        Note: For event listeners, the task lifetime is managed by the [=fire an event=] algorithm, which may invoke multiple listeners to the same event, rather than at the end of a single listener's execution.
</div>

<div algorithm="Applying source location">
    To <dfn>apply source location</dfn> to a [=script timing info=] |scriptTimingInfo| given a [=callback function=] or {{Function}} |callback|:
    1. The user agent may set |scriptTimingInfo|'s [=script timing info/source url=] to the source URL of the script where |callback| was defined.
    1. The user agent may set |scriptTimingInfo|'s [=script timing info/source function name=] to the function name of |callback|.
    1. The user agent may set |scriptTimingInfo|'s [=script timing info/source character position=] to the character position where |callback| was defined.
</div>

<div algorithm="Report pause duration">
    To <dfn export>record pause duration</dfn> given a [=duration=] |duration|:
    1. Let |script| be the [=running script=].
    1. Let |settings| be |script|'s [=script/settings object=].
    1. If |settings| is not a {{Window}}, then return.
    1. Let |document| be |settings|'s {{Window/document}}.
    1. If |document| is not [=fully active=] or	{{Document/hidden}}, then return.
    1. Let |frameTimingInfo| be the [=relevant frame timing info=] given |document|.
    1. Assert: |frameTimingInfo| is not null.
    1. If |frameTimingInfo|'s [=frame timing info/pending script=] is null, then return.
    1. Increment |frameTimingInfo|'s [=frame timing info/pending script=]'s [=script timing info/pause duration=] by the milliseconds value of |duration|.
</div>

Additions to existing standards {#other-standards}
==================================================

Monkey-patches to the WebIDL standard {#webidl-monkey-patches}
----------------------------------------------------------
<div algorithm="Monkey patches to promise handling">
The {{Promise}} interface has an associated string <dfn for=Promise>invoker name when created</dfn>, initially "`Promise`".
The {{Promise}} interface has an associated string <dfn for=Promise>script url when created</dfn>, initially the empty string.

Append the following steps to <a href="https://webidl.spec.whatwg.org/#a-new-promise">creating a new promise</a>, before returning the {{Promise}}:
    1. Let |interfaceName| be a string representing the [=interface=] responsible for creating this promise.
    1. Let |attributeName| be a string representing the [=attribute=] in the interface responsible for creating this promise.
    1. Set the created {{Promise}}'s [=Promise/script url when created=] to the [=running script=]'s [=script/base URL=].
    1. The user-agent may set the created {{Promise}}'s [=Promise/invoker name when created=] to the last known [=concatenate|concatenation=] of
        « |interfaceName|, ".", |attributeName| »

        Issue: this is quite handwavy, because this is difficult to do in a normative way. Need to see if
        that can be improved, or if the source location for promise handlers would remain a bit implementation-defined.

Prepend the following step to <a href="https://webidl.spec.whatwg.org/#resolve">resolve a promise</a> given {{Promise}} |p|:
    [=Record timing info for promise resolver=] given |p| and "`resolve-promise`".

Prepend the following step to <a href="https://webidl.spec.whatwg.org/#reject">reject a promise</a> given {{Promise}} |p|:
    [=Record timing info for promise resolver=] given |p| and "`reject-promise`".
</div>

<div algorithm="Monkey patch to callback invocation">
Insert the following steps to <a href="https://webidl.spec.whatwg.org/#invoke-a-callback-function">invoke a callback function</a>,
    once we have an [=environment settings object=] |relevant settings| and a [=callback function=] |F|:
        [=Record timing info for user callback=] given |F| and |relevant settings|.
</div>


Security & privacy considerations {#priv-sec}
===============================================

The Long Animation Frames API adheres to the same-origin policy by including origin-safe attribution information about
the source of the long task. There is a 50ms threshold for long tasks. Durations are only provided in 1 ms
granularity. Together this provides adequate protection against cross-origin leaks.

The Long Animation Frames API provides timing information about the duration and type of tasks executed by the user,
as well as attribution such as the browsing context causing the function calls. This could enable an attacker
to perform side-channel timing attacks to guess the user’s action, or identify the user. For example, a pattern of
long script followed by a long render could be put together to guess user’s interaction with a social
widget. Detailed function call attribution would be used to determine the user’s action.

What is Exposed to Observers? {#what-is-exposed}
--------------------------------------------------------

All observers within the top level page (i.e. all iframes in the page and the main frame) will receive
notifications about presence of long animation frames. We expose the start time of the task, its duration (with 1 ms
granularity), and a pointer to the culprit frame. This information can already be observed today, and with
higher resolution, using setTimeout. An attacker can do this by clearing everything else on the page and adding
the vulnerable cross-origin resource to ensure that delays from the setTimeout are caused by that resource.
Observers in other different pages (tabs or windows) should not receive notifications, regardless of the
architecture of the user agent.

Attack Scenarios Considered {#attack-scenarios}
-----------------------------------------------

The following are the timing attacks considered:

1. <b>Traditional timing attacks</b>: using external resource load time to reveal the size of
    private data. For instance the number of hidden pictures in a gallery, whether username is
    valid, etc. See an <a href="http://crypto.stanford.edu/~dabo/papers/webtiming.pdf">example</a>.

1. <b>Side-channel timing attacks</b>: using time for video parsing, script parsing, App Cache reads
    or Cache API (service workers) usage to uniquely identify a user, or to create a profile of the
    user’s age, gender, location, and interests etc. For
    <a href="https://tom.vg/papers/timing-attacks_ccs2015.pdf">instance</a>, status updates from
    a social network can be limited to certain demographic (eg. females of age 20-30) the file size of
    the permalink page can be used to determine whether the user is in the target demographic.

These scenarios are addressed by the 50ms threshold AND respecting cross-origin boundary i.e. not
showing task type or additional attribution to untrusted cross origin observers.

Additional information exposed by the Long Animation Frames API {#loaf-sec-priv}
--------------------------------------------------------------------------------
Since several cross-origin documents can share the same event loop, they can also render as part of
the same frame sequence and influence each other's rendering time. This makes it so that these timings
are already somewhat observable cross-origin, e.g. by requesting an animation frame and observing if it is delayed,
though long animation frames exposes them at a higher fidelity.

To mitigate this, long animation frames are only reported to "participating local roots": only documents
that are associated with a work task that contributed to the sequence, or that were rendered as part of the frame,
are eligible to observe the long animation frame, and that long animation frame would be available only in
their nearest ancestor that is either topmost or has a cross-origin parent.

{{PerformanceScriptTiming}} and opaque scripts {#loaf-opaque-scripts-sec}
-----------------------------------------------
Since {{PerformanceScriptTiming}} exposes information about script execution, we need to make sure it
doesn't expose too much information about [=CORS cross-origin=] scripts that cannot be easily deduced otherwise.
To do that, we use the existing [=classic script/muted errors=] boolean, and report an empty {{PerformanceScriptTiming/sourceURL}}
in such cases.