Clarify what 'contentful' means (#66)

* Clarify what 'contentful' means

* Define 'paintable', to cover the cases of zero size and out-of-viewport

* Remove some unneeded links, clarify some terminology

* Fix broken link

* Fix typo

* Address review comments

* Paintable rects need to have positive right/bottom

* Clarify clipping and pseudo-elements

* Another review iteration

* Apply wording suggestion from npm

* Apply wording suggestion from npm

* Reorder definitions

* Reorder definitions

* Gradient note

* Revise background and rect

* Change wording for backgrounds and use algorithm for paintable bounding rect

* Make loaded/decode image definitions more precise

* Move contentful CSS image to own def

* Use 'available' image

* Add .

* Update painttiming.bs

Co-Authored-By: npm1 <npm@chromium.org>

* Remove clipping for now

Co-authored-by: Noam Rosenthal <noam@webkit.org>
Co-authored-by: npm1 <npm@chromium.org>

painttiming.bs

@@ -27,6 +27,40 @@ urlPrefix: https://www.w3.org/TR/hr-time-2/#idl-def-domhighrestimestamp; spec: H
     type: typedef; text: DOMHighResTimeStamp
 urlPrefix: https://www.w3.org/TR/CSS2/visuren.html; spec: CSS-2;
     type: dfn; url: #viewport; text: viewport
+urlPrefix: https://www.w3.org/TR/CSS22/visufx.html; spec: CSS-2;
+    type: dfn; url: #propdef-visibility; text: visibility;
+urlPrefix: https://www.w3.org/TR/css-color-3; spec: CSS-COLOR-3;
+    type: dfn; url: #opacity; text: opacity;
+urlPrefix: https://html.spec.whatwg.org/multipage/images.html
+    type: dfn; text: available; url: #img-available;
+    type: dfn; text: image; url: #images;
+urlPrefix: https://www.w3.org/TR/SVG2/render.html; spec: CR-SVG2
+    type: dfn; url: #Rendered-vs-NonRendered; text: svg element with rendered descendants;
+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
+    type: dfn; text: canvas;
+    type: dfn; text: context mode; url: #concept-canvas-context-mode;
+urlPrefix: https://html.spec.whatwg.org/multipage/rendering.html
+    type: dfn; text: replaced element; url: #replaced-elements;
+urlPrefix: https://w3c.github.io/IntersectionObserver/
+    type: dfn; text: Intersection rect algorithm; url: #calculate-intersection-rect-algo
+urlPrefix: https://drafts.csswg.org/css-cascade-4/
+    type: dfn; text: used; url: #used;
+urlPrefix: https://html.spec.whatwg.org/multipage/dom.html
+    type: dfn; text: element; url: #element;
+urlPrefix: https://drafts.csswg.org/css-pseudo-4
+    type: dfn; text: generated content pseudo-element; url: #generated-content;
+urlPrefix: https://www.w3.org/TR/cssom-view
+    type: dfn; text: getBoundingClientRect; url: #dom-element-getboundingclientrect;
+    type: dfn; text: scrolling area; url: #scrolling-area;
+urlPrefix: https://www.w3.org/TR/css3-values/
+    type: dfn; text: url valued; url: #url-value;
+urlPrefix: https://drafts.fxtf.org/css-masking-1/
+    type: dfn; text: clip-path; url: #the-clip-path;
+urlPrefix: https://www.w3.org/TR/css-images-3/
+    type: dfn; text: CSS image; url: #typedef-image;
 </pre>
 
 Introduction {#intro}
@@ -69,9 +103,46 @@ Formally, we consider the user agent to have "rendered" a document when it has p
 
     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 <dfn>paintable pseudo-element</dfn> when all of the following apply:
+* The pseudo-element's [=used=] [=visibility=] is <code>visible</code>.
+* The pseudo-element's [=used=] [=opacity=] is greater than zero.
+* The pseudo-element generates a non-empty [=box=].
+
+A [=CSS image=] |img| is a <dfn>contentful image</dfn> when all of the following apply:
+* |img| is [=url valued=].
+* |img| is [=available=].
+
+An [=element=] |target| is <dfn export>contentful</dfn> when one or more of the following apply:
+* |target| has a [=text node=] child, with at least one character, excluding [=document white space characters=].
+* |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 <code>none</code>.
+* |target| is an [=svg element with rendered descendants=].
+* |target| is an [=originating element=] for a [=paintable pseudo-element=] that represents a [=contentful image=] or text with at least one character excluding [=document white space characters=].
+
+To compute the <dfn>paintable bounding rect</dfn> of [=element=] |target|, run the following steps:
+    1. Let |boundingRect| be the result of running the [=getBoundingClientRect=] on |target|.
+    1. Clip |boundingRect| with the [=document=]'s [=scrolling area=].
+    1. Return |boundingRect|.
+
+    NOTE: elements contained by boxes with <code>overflow: scroll</code> or <code>overflow: hidden</code> don't have their [=paintable bounding rect=] clipped, as in both cases the [=element=] can become visible by scrolling.
+
+An [=element=] |el| is <dfn>paintable</dfn> when all of the following apply:
+* |el|'s [=used=] [=visibility=] is <code>visible</code>.
+* |el| and all of its ancestors' [=used=] [=opacity=] is greater than zero.
+
+    NOTE: there could be cases where a <code>paintable</code> [=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 <code>display: none</code>, or <code>display: contents</code> 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.
+
 <dfn export>First paint</dfn> 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.
 
-<dfn export>First contentful paint</dfn> entry contains a {{DOMHighResTimeStamp}} reporting the time when the user agent first rendered any text, image (including background images), non-white canvas or SVG. This excludes any content of iframes, but includes text with pending webfonts. This is the first time users could start consuming page content.
+<dfn export>First contentful paint</dfn> entry contains a {{DOMHighResTimeStamp}} reporting the time when the user agent first rendered a [=document=] which includes at least one [=element=] that is both [=contentful=] and [=paintable=].
 
 Whenever a user agent preemptively paints content outside of the [=viewport=], those paints must be considered for [=first paint=] and [=first contentful paint=].
 
@@ -115,8 +186,6 @@ Reporting paint timing {#sec-reporting-paint-timing}
 
     1. If this instance of [=update the rendering=] is the [=first contentful paint=] of |document|, then invoke the [[#report-paint-timing]] algorithm with |document|, <code>"first-contentful-paint"</code>, and |paintTimestamp| as arguments.
 
-        NOTE: This paint must include text, image (including background images), non-white canvas or SVG.
-
         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=].
 </div>