This specification defines an interface for web applications to access
runtime performance information of the browser event loop, enabling them to
identify and fix issues that cause delayed rendering, processing of input,
and other critical work necessary to deliver a smooth and responsive user
experience.

If all of the work within each execution of the event loop (i.e. _within
a "frame"_) is completed in allotted time budget (e.g. 16.6ms
for 60Hz refresh rate), the browser can guarantee a smooth and responsive
experience. However, if the work within the frame exceeds this time budget,
for whatever reason, then one or more frames is skipped, resulting in
inconsistent response, processing, and rendering times, which hurts the
user experience.

The Frame Timing API enables web developers to monitor the performance
of their applications, as experienced by their users, by observing when the
browser is unable to deliver the desired refresh rate due to long-running
frames that exceed the allotted time budget. By identifying such cases, and
their cause, web developers can adapt or fix their logic to stay within the
allotted budget and help the browser deliver an improved user
experience.

Requirements phrased in the imperative as part of algorithms (such as
"strip any leading space characters" or "return false and abort these steps")
are to be interpreted with the meaning of the key word ("MUST", "SHOULD",
"MAY", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps MAY be
implemented in any manner, so long as the end result is equivalent. (In
particular, the algorithms defined in this specification are intended to be
easy to follow, and not intended to be performant.)

The IDL fragments in this specification must be interpreted as
required for conforming IDL fragments, as described in the Web IDL
specification. [[!WebIDL]]

Frame Timing

PerformanceFrameTiming interface

interface PerformanceFrameTiming : PerformanceEntry {
};

Attributes

`name`

This attribute MUST return the [current document's
address][].

entryType

This attribute MUST return the [DOMString][] "`frame`".

`startTime`

This attribute MUST return a [DOMHighResTimeStamp][] [[!HR-Time-2]] indicating
the frame start time.

duration

This attribute MUST return a [DOMHighResTimeStamp][] indicating
the difference between the startTime's of two successive frames.

Processing

The PerformanceFrameTiming interface participates in the
[[!Performance-Timeline-2]] and extends the browser processing model.

TODO: define proper hook in the HTML spec...

Run the following steps prior to running [step 1 of the browser
processing
model](https://html.spec.whatwg.org/multipage/webappapis.html#processing-model-8) [[!HTML5]]:

Let frame startTime be the value that would be returned
by the `Performance` object's `now()` method.

Run the following steps after running [step 8.10 of the browser
processing
model](https://html.spec.whatwg.org/multipage/webappapis.html#processing-model-8):

Let frame endTime be the value that would be returned by
the `Performance` object's `now()` method.

Let frame duration be the difference between the values
of frame endTime and frame startTime.

For each [fully active][] [Document][] in docs,
[queue][Queue a PerformanceEntry entry] entry.

This specification does not mandate any particular
value for time budget for the frame that results in delivery
of a PerformanceFrameTiming entry. This value is subject to user
agent configuration and runtime factors. For example, the user agent may
set different target update frequencies (60Hz, 30Hz, etc) and adjust this
target at runtime based on device performance, power consumption,
responsiveness, and other requirements.

The user agent SHOULD adjust its duration thresholds to match the
expected frame duration and update frequency to avoid reporting
false-positives to the developer. For example, if the user agent is idle,
it may interleave long idle callbacks (e.g. 50ms idle callback via
[requestIdleCallback][]) and the duration threshold for slow frames
should be adjusted accordingly to account for such frames.

Explain _why_ frame is slow (in v2, probably): current
definition reports slow frames, but there is no simple mechanism to
determine what was the culprit (e.g. slow input handler vs. rAF vs.
expensive paint). We may want to extend the PerformanceFrameTiming
interface with additional attributes that capture this.

Privacy and Security

The PerformanceFrameTiming interface exposes timing information
about the processing costs of the browser event loop. To limit the exposed
information the interface is restricted to reporting slow frames only,
which are already observable through other means (e.g.
`requestAnimationFrame`), and the user agent is allowed to set and exercise
own thresholds for delivery of slow frame events.

Acknowledgments

Thanks to Enne Walker, Rick Byers, Chris Harrelson, Timothy Robert
Ansell, Vladimir Levin, and Nat Duca for their helpful comments and
contributions to this work.