+spec:dom; type:dfn; text:descendant spec:dom; type:dfn; text:element spec:css22; type:dfn; text:visibility@@ -26,9 +27,11 @@ urlPrefix: https://www.w3.org/TR/SVG2/render.html; spec: CR-SVG2 urlPrefix: https://www.w3.org/TR/css-backgrounds-3/; spec: CSS-BACKGROUNDS-3; type: dfn; text: background-image; url: #propdef-background-image; type: dfn; text: background-size; url: #background-size; -urlPrefix: https://html.spec.whatwg.org/multipage/canvas.html +urlPrefix: https://html.spec.whatwg.org/multipage/canvas.html; spec: HTML; type: dfn; text: context mode; url: #concept-canvas-context-mode; -urlPrefix: https://html.spec.whatwg.org/multipage/rendering.html +urlPrefix: https://html.spec.whatwg.org/multipage/images.html; spec: HTML; + type: dfn; text: completely available; url: #img-all; +urlPrefix: https://html.spec.whatwg.org/multipage/rendering.html; spec: HTML; type: dfn; text: being rendered; url: #being-rendered; urlPrefix: https://w3c.github.io/IntersectionObserver/ type: dfn; text: Intersection rect algorithm; url: #calculate-intersection-rect-algo @@ -37,6 +40,8 @@ urlPrefix: https://html.spec.whatwg.org/multipage/dom.html urlPrefix: https://drafts.csswg.org/css-pseudo-4 type: dfn; text: generated content pseudo-element; url: #generated-content; type: dfn; text: typographical pseudo-element; url: #typographic-pseudos; +urlPrefix: https://drafts.csswg.org/css2/zindex.html; spec: CSS; + type: dfn; url:#painting-order; text: painting order; urlPrefix: https://www.w3.org/TR/cssom-view type: dfn; text: scrolling area; url: #scrolling-area; urlPrefix: https://www.w3.org/TR/css3-values/ @@ -50,6 +55,12 @@ urlPrefix: https://html.spec.whatwg.org/multipage/media.html urlPrefix: https://html.spec.whatwg.org/multipage/browsers.html type: dfn; text: browsing context; url: #browsing-context; type: dfn; text: nested browsing context; url: #nested-browsing-context; +urlPrefix: https://fetch.spec.whatwg.org/; spec: FETCH; + type: dfn; url:#concept-tao-check; text: timing allow check; +urlPrefix: https://wicg.github.io/largest-contentful-paint/; spec: ELEMENT-TIMING + type: dfn; url:#report-largest-contentful-paint; text: Report largest contentful paint +urlPrefix: https://wicg.github.io/element-timing/; spec: ELEMENT-TIMING + type: dfn; url:#report-element-timing; text: Report element timing Introduction {#intro} @@ -59,6 +70,28 @@ Introduction {#intro} 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. + +First Paint and First Contentful Paint {#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? @@ -116,6 +149,14 @@ An [=/element=] |target| is contentful when one or more of the * |target| is an <{input}> element with a [=non-empty=] <{input/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 image|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 {{Element/getBoundingClientRect()}} on |target|. 1. Clip |boundingRect| with the [=document=]'s [=scrolling area=]. @@ -169,15 +210,106 @@ This allows developers to detect support for paint timing for a particular [=bro Processing model {#sec-processing-model} ======================================== -Reporting paint timing {#sec-reporting-paint-timing} +Associated Image Requests {#sec-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. + +```html + + + + +``` + +Recording paint timing {#sec-recording-paint-timing} -------------------------------------------------------- -Every [=Document=] has an associated [=ordered set=] of previously reported paints, initiallized to an empty [=ordered set=]. +A pending image record is a [=struct=] with the following +[=struct/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 {{Element}}s, initially empty. + +
"first-contentful-paint", then return false.
+ 1. If |document|'s [=set of previously reported paints=] contains "first-contentful-paint", then return false.
1. If |document| contains at least one [=/element=] that is both [=paintable=] and [=contentful=], then return true.
1. Otherwise, return false.
"first-paint", and the user agent is configured to mark [=first paint=], then invoke the [[#report-paint-timing]] algorithm with |document|, "first-paint", and |paintTimestamp|.
NOTE: [=First paint=] excludes the default background paint, but includes non-default background paint.
@@ -200,9 +343,14 @@ Every [=Document=] has an associated [=ordered set=] of previously reported
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=] is not guaranteed to mark "first-paint" or "first-contentful-paint". A completely blank [=document=] may never mark [=first paint=], and a [=document=] containing only elements that are not [=contentful=], may never mark [=first contentful paint=].
+ NOTE: A [=document=] is not guaranteed to mark "first-paint" or "first-contentful-paint". A completely blank [=document=] may never mark [=first paint=], and 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=] .
+ NOTE: The marking of [=first paint=] is optional. User-agents implementing paint timing should at the very least mark [=first contentful paint=].
+
+ 1. [=Report largest contentful paint=] given |document|, |paintTimestamp|,
+ |paintedImages| and |paintedTextNodes|.
+ 1. [=Report element timing=] given |document|, |paintTimestamp|,
+ |paintedImages| and |paintedTextNodes|.