Paint Timing

1. Introduction

const observer = new PerformanceObserver(function(list) {
    const perfEntries = list.getEntries();
    for (const perfEntry of perfEntries) {
        // Process entries
        // report back for analytics and monitoring
        // ...
    }
});

// register observer for paint timing notifications
observer.observe({entryTypes: ["paint"]});

2. Terminology

Paint: the user agent has performed a "paint" (or "render") when it has converted the render tree to pixels on the screen. Formally, we consider the user agent to have "rendered" a document when it has performed the update the rendering steps of the event loop.

NOTE: The rendering pipeline is very complex, and the timestamp should be the latest timestamp the user agent is able to note in this pipeline (best effort). Typically the time at which the frame is submitted to the OS for display is recommended for this API.

A generated content pseudo-element is a paintable pseudo-element when all of the following apply:

• The pseudo-element’s used visibility is visible.

• The pseudo-element’s used opacity is greater than zero.

• The pseudo-element generates a non-empty box.

A CSS image img is a contentful image when all of the following apply:

• img is url valued.

• img is available.

A DOMString is non-empty if it contains at least one character excluding document white space characters.

An element target is contentful when one or more of the following apply:

• target has a text node child, representing non-empty text, and the node’s used opacity is greater than zero.

  NOTE: this covers the case where a typographical pseudo-element would override the opacity of the text node.

• target is a replaced element representing an available image.

• target has a background-image which is a contentful image, and its used background-size has non-zero width and height values.

• target is a canvas with its context mode set to any value other than none.

• target is a video element that represents its poster frame or the first video frame and the frame is available.

• target is an svg element with rendered descendants.

• target is an input element with a non-empty value attribute.

• target is an originating element for a paintable pseudo-element that represents a contentful image or non-empty text.

An element is timing-eligible if it is one of the following:

• an img element.

• an image element inside an svg element.

• a video element with a poster frame.

• an element with a contentful background-image.

• a text node.

To compute the paintable bounding rect of element target, run the following steps:

1. Let boundingRect be the result of running the getBoundingClientRect() on target.

2. Clip boundingRect with the document's scrolling area.

3. Return boundingRect.

NOTE: elements contained by boxes with overflow: scroll or overflow: hidden don’t have their paintable bounding rect clipped, as in both cases the element can become visible by scrolling.

An element el is paintable when all of the following apply:

• el is being rendered.

• el’s used visibility is visible.

• el and all of its ancestors' used opacity is greater than zero.

  NOTE: there could be cases where a paintable element would not be visible to the user, for example in the case of text that has the same color as its background. Those elements would still considered as paintable for the purpose of computing first contentful paint.

• el’s paintable bounding rect intersects with the scrolling area of the document.

  NOTE: This covers the cases where the element is scaled to zero size, has display: none, or display: contents where the contents resolve to an empty rect.

  NOTE: As a general rule, an element is paintable if it is within the viewport, or can potentially be in the viewport as a result of scrolling or zooming.

First paint entry contains a DOMHighResTimeStamp reporting the time when the user agent first rendered after navigation. This excludes the default background paint, but includes non-default background paint and the enclosing box of an iframe. This is the first key moment developers care about in page load – when the user agent has started to render the page.

A browsing context ctx is paint-timing eligible when one of the following apply:

• ctx is a top-level browsing context.

• ctx is a nested browsing context, and the user agent has configured ctx to report paint timing.

  NOTE: this allows user agents to enable paint-timing only for some of the frames, in addition to the main frame, if they so choose. For example, a user agent may decide to disable paint-timing for cross-origin iframes, as in some scenarios their paint-timing might reveal information about the main frame.

3. The PerformancePaintTiming interface

[Exposed=Window]
interface PerformancePaintTiming : PerformanceEntry {};

PerformancePaintTiming extends the following attributes of PerformanceEntry interface:

• The name attribute’s getter must return a DOMString for minimal frame attribution. Possible values of name are:

  • "first-paint": for first paint

  • "first-contentful-paint": for first contentful paint

• The entryType attribute’s getter must return "paint".

• The startTime attribute’s getter must return a DOMHighResTimeStamp of when the paint occured.

• The duration attribute’s getter must return 0.

NOTE: A user agent implementing PerformancePaintTiming would need to include "paint" in supportedEntryTypes of a global object whose browsing context is paint-timing eligible. This allows developers to detect support for paint timing for a particular browsing context.

4. Processing model

4.1. Associated Image Requests

Each Element has an associated image request which is an image request or null, initially null.

When the processing model for an Element element of type HTMLImageElement, SVGImageElement, or HTMLVideoElement creates a new image resource (e.g., to be displayed as an image or poster image), element’s associated image request is set to the image request of the created image resource.

Note: Every image resource that is obtained from a URL whose scheme is equal to "data" has an associated image request which is not fetched but still needs to be loaded. This request can be the associated image request of an Element.

Note: The current language is vague since it does not point to specific algorithms. This can be made more rigorous when the corresponding processing models have a more unified processing model.

Every Element has a list of associated background image requests which is initially an empty array. When the processing model for the Element element’s style requires a new image resource (to be displayed as background image), the image request created by the new resource is appended to element’s associated background image requests.

NOTE: An Element can have several image requests, e.g. if its background-image property has multiple values. For instance, in the following example, a single background-image property produces four image requests, each of which will be recorded and reported by the algorithms below.

<!DOCTYPE html>
<style>
div {
  background-image: url(https://images.example/background1.png),
                    url(https://images.example/background2.png);
}
</style>
<div></div>
<div></div>

4.2. Recording paint timing

A pending image record is a struct with the following items:

• element, an Element

• request, an image request

• loadTime, a DOMHighResTimeStamp

Each Element has a set of owned text nodes, which is an ordered set of Text nodes, initially empty.

Each Document has a set of previously reported paints, which is an ordered set of strings, initially empty.

Each Document has an images pending rendering, which is a list of pending image records, initally empty.

Each Document has a set of elements with rendered text, which is an ordered set of Elements, initially empty.

4.2.1. Modifications to the CSS specification

Whenever an image request in an Element element’s associated background image requests becomes completely available, run the algorithm to process an image that finished loading with element and image request as inputs.

4.2.2. Modifications to the HTML specification

When an Element element’s associated image request has become completely available, run the algorithm to process an image that finished loading passing in element and its associated image request as inputs.

4.2.3. Process image that finished loading

4.3. Reporting paint timing

4.3.1. First Contentful Paint

4.3.2. Mark paint timing

4.3.3. Report paint timing

4.4. Common algorithms

4.4.1. Exposed for paint timing

5. Acknowledgements

Special thanks to all the contributors for their technical input and suggestions that led to improvements to this specification.