Paint Timing

1. Introduction

This section is non-normative.

Much of the purpose of a web browser is to translate HTML, CSS and image resources into pixels on a screen for users. Measuring the performance of a web page often involves measuring the time it takes to perform these tasks - to render content, whether text or image, to the screen. There are many different ways to use this timing to make statemements about the performance of a page, or about the user experience of loading, but fundamentally all of those ways begin with a common means of measuring time.

This is a foundational document which specifies how to measure paint timing as a general-purpose mechanism. That foundation is then used to define the First Paint and First Contentful Paint metrics. Other specific instances of paint measurement may be specified in other documents.

Specifically, this specification covers:

Measuring the time when images are decoded and ready for painting
Measuring the time when elements are painted
Measuring the size of the painted elements
Determining whether a painted element contains any visible content.

1.1. First Paint and First Contentful Paint

Load is not a single moment in time — it’s an experience that no one metric can fully capture. There are multiple moments during the load experience that can affect whether a user perceives it as "fast" or "slow".

First paint (FP) is the first of these key moments, followed by first contentful paint (FCP). These metrics mark the points in time when the browser renders a given document. This is important to the user because it answers the question: is it happening?

The primary difference between the two metrics is FP marks the first time the browser renders anything for a given document. By contrast, FCP marks the time when the browser renders the first bit of image or text content from the DOM.

1.2. Usage example

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 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 document white space characters.


   An element target is contentful when one or more of the following apply:
   
    
     target has a 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 image.
    

     target has a background-size has non-zero width and height values.
    

     target is a context mode set to any value other than none.

    

     target is a poster frame or the first video frame and the frame is available.

    

     target is an svg element with rendered descendants.
    

     target is an 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 svg element.
    

     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:
   
    
     Let boundingRect be the result of running the getBoundingClientRect() on target.
    

     Clip boundingRect with the scrolling area.
    

     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' 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 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 Paint Timing Mixin
   
    This section is non-normative.
    The PaintTimingMixin interface exposes timestamps related to the rendering cycle.
It is included in PerformanceEntry,
specifically by PerformanceLongAnimationFrameTiming.
    The paintTime attribute represent the timestamp at the end of the update the rendering loop
while the presentationTime represents an implementation-specific timestamp marked when the frame is presented to the user.
The mark paint timing alorithm, called from update the rendering in the HTML standard, populates both attributes.
    Attributes in entries that rely on paint timing, like renderTime (as well as its startTime),
usually return the default paint timestamp rather than one of the specific timestamps, making them agnostic to the implementation-specific nature of presentationTime.
   
   3.1. The PaintTimingMixin interface
[Exposed=Window]
interface mixin PaintTimingMixin {
    readonly attribute DOMHighResTimeStamp paintTime;
    readonly attribute DOMHighResTimeStamp? presentationTime;
};

   Objects including the PaintTimingMixin interface mixin have an associated paint timing info (null or a paint timing info).
   paint timing info is a items:
   
    rendering update end time
    

     A DOMHighResTimeStamp
    
implementation-defined presentation time
    

     Null or a DOMHighResTimeStamp
   
   The paintTime attribute’s getter step is to return this’s paint timing info’s rendering update end time.
   The presentationTime attribute’s getter step, if exists, is to return this’s paint timing info’s implementation-defined presentation time.
   To get the default paint timestamp for a paint timing info paintTimingInfo, return paintTimingInfo’s implementation-defined presentation time if it is non-null, otherwise paintTimingInfo’s rendering update end time.
   4. The PerformancePaintTiming interface
[Exposed=Window]
interface PerformancePaintTiming : PerformanceEntry {
    [object toJSON();
};
PerformancePaintTiming includes PaintTimingMixin;

   PerformancePaintTiming extends the following attributes of PerformanceEntry interface:
   
    
     The 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 DOMHighResTimeStamp of when the paint occured.
    

     The duration attribute’s getter must return 0.
    

     When toJSON is called, run the default toJSON steps for PerformancePaintTiming.
   
   NOTE: A user agent implementing PerformancePaintTiming would need to include "paint" in browsing context is paint-timing eligible.
This allows developers to detect support for paint timing for a particular browsing context.

   5. Processing model
   5.1. Associated Image Requests
   Each image request or null, initially null.

   When the processing model for an Element element of type
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
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 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>

   5.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 Text nodes, initially empty.
   Each strings, initially empty.

   Each list of pending image records, initally empty.

   Each Elements, initially empty.
   5.2.1. Modifications to the CSS specification
   Whenever an image request as inputs.
   5.2.2. Modifications to the HTML specification
   When an completely available, run the algorithm to process an image that finished loading passing in element and its associated image request as inputs.

   
    
When the user agent paints a Text node text for the first time, it should execute the following steps:


    
     
      If text will not be painted due to the font face being in its font block period, then return.
     

      Let element be the containing block of text.

     

      Append text to element’s set of owned text nodes.
    

   

   5.2.3. Process image that finished loading
   
    
To process an image that finished loading given an image request imageRequest:

    
     
      Let root be element’s root.
     

      If root is not a Document, return.
     

      Let now be the relevant global object.
     

      Let record be a pending image record with element element, request imageRequest and loadTime now.
     

      Add record to root’s images pending rendering.
    
   

   5.3. Reporting paint timing
   5.3.1. First Contentful Paint
   
    
    To know whether Document document should report first contentful paint, perform the following steps:

    
     
      If document’s set of previously reported paints contains "first-contentful-paint", then return false.
     

      If document contains at least one element that is both paintable and contentful, then return true.
     

      Otherwise, return false.
    
   
   5.3.2. Mark paint timing
   
    
    When asked to mark paint timing given a Document document as input, perform the following steps:

    
     
      If the browsing context is not paint-timing eligible, return.
     

      Let paintTimingInfo be a new paint timing info, whose rendering update end time is the relevant global object.
     

      Let paintedImages be a new ordered set
     

      Let paintedTextNodes be a new ordered set
     

      For each record in doc’s images pending rendering list:
      
       
        If record’s request is available and ready to be painted, then run the following steps:
        
         
          Append record to paintedImages.
         

          Remove record from doc’s images pending rendering list.
        
      
     

      For each descendants:

      
       
        If element is contained in doc’s set of elements with rendered text, continue.
       

        If element’s set of owned text nodes is empty, continue.
       

        Append element to doc’s set of elements with rendered text.
       

        Append element to paintedTextNodes.
      
     

      Let reportedPaints be the document’s set of previously reported paints.
     

      Let frameTimingInfo be document’s current frame timing info.
     

      Set document’s current frame timing info to null.
     

      Let flushPaintTimings be the following steps:
      
       
        If reportedPaints does not contain "first-paint", and the user agent is configured to mark first paint, then report paint timing given document, "first-paint", and paintTimingInfo.
        NOTE: First paint excludes the default background paint, but includes non-default background paint.
         This should be turned into a normative note.
       

        If document should report first contentful paint, then:
        
         
          Report paint timing given document, "first-contentful-paint", and paintTimingInfo.
        
        NOTE: A parent frame should not be aware of the paint events from its child iframes, and vice versa. This means that a frame that contains just iframes will have first paint (due to the enclosing boxes of the iframes) but no first contentful paint.
        NOTE: A document containing only elements that are not contentful may never mark first contentful paint.
        NOTE: The marking of first paint is optional. User-agents implementing paint timing should at the very least mark first contentful paint.
       

        Report largest contentful paint given document, paintTimingInfo,
paintedImages and paintedTextNodes.
       

        Report element timing given document, paintTimingInfo,
paintedImages and paintedTextNodes.
       

        If frameTimingInfo is not null, then queue a long animation frame entry given document, frameTimingInfo, and paintTimingInfo.
      
     

      If the user-agent does not support implementation-defined presentation times, call flushPaintTimings and return.
     

      Run the following steps In parallel:
      
       
        Wait until an implementation-defined time when the current frame has been presented to the user.
       

        Set paintTimingInfo’s implementation-defined presentation time to the relevant global object.
       

        If document’s cross-origin isolated capability is false, then:
        
         
          Coarsen paintTimingInfo’s implementation-defined presentation time to the next multiple of 4 milliseconds, or coarser.
         

          Wait until the current high resolution time is paintTimingInfo’s implementation-defined presentation time.
        
       

        relevant global object to run flushPaintTimings.
      
    

   

   5.3.3. Report paint timing
   
    
    To report paint timing given document, paintType, and a paint timing info paintTimingInfo as arguments, perform the following steps:

    
     
      Create a relevant realm and set its attributes as follows:
      
       
        Set newEntry’s name attribute to paintType.
       

        Set newEntry’s entryType attribute to "paint".
       

        Set newEntry’s startTime attribute to the default paint timestamp given paintTimingInfo.
       

        Set newEntry’s duration attribute to 0.
      
     

      Set newEntry’s paint timing info to paintTimingInfo.
     

      relevant realm.
     

      Append paintType to document’s set of previously reported paints.
    
   
   5.4. Common algorithms
   5.4.1. Exposed for paint timing
   
    To determine whether an Document or null document, perform the following steps:
    
     
      If element is not connected, return false.
     

      If document is null, let document be element’s associated document.
     

      If document is not fully active, return false.
     

      If element’s root is not equal to document, return false.
     

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

Paint Timing

Abstract

Status of this document

1. Introduction

1.1. First Paint and First Contentful Paint

1.2. Usage example

2. Terminology

3. The Paint Timing Mixin

3.1. The `PaintTimingMixin` interface

4. The `PerformancePaintTiming` interface

5. Processing model

5.1. Associated Image Requests

5.2. Recording paint timing

5.2.1. Modifications to the CSS specification

5.2.2. Modifications to the HTML specification

5.2.3. Process image that finished loading

5.3. Reporting paint timing

5.3.1. First Contentful Paint

5.3.2. Mark paint timing

5.3.3. Report paint timing

5.4. Common algorithms

5.4.1. Exposed for paint timing

6. Acknowledgements

Conformance

Document conventions

Conformant Algorithms

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

Informative References

IDL Index

Issues Index