From a16851f834daf05677a28174fc9197efed364c81 Mon Sep 17 00:00:00 2001 From: Ian Clelland Date: Tue, 16 Jan 2024 10:34:00 -0500 Subject: [PATCH] Refactor Element Timing on top of Paint Timing (#78) This updates Element Timing to use the common timing algorithms exposed in Paint Timing, so that it is more closely aligned with that spec. At the same time, Element Timing no longer drives Largest Contentful Paint, as that API now relies on Paint TIming directly instead (with the PR in w3c/largest-contentful-paint#121) This also moves npm@chromium.org to "Former Editor" --- index.bs | 155 +++++++++++++++---------------------------------------- 1 file changed, 41 insertions(+), 114 deletions(-) diff --git a/index.bs b/index.bs index c9b781e..206641d 100644 --- a/index.bs +++ b/index.bs @@ -4,8 +4,9 @@ Status: CG-DRAFT Shortname: element-timing Group: WICG Level: 1 -Editor: Nicolás Peña Moreno, Google https://google.com, npm@chromium.org +Editor: Ian Clelland, Google https://google.com, iclelland@chromium.org, w3cid 76841 Tim Dresser, Google https://google.com, tdresser@chromium.org +Former Editor: Nicolás Peña Moreno, Google https://google.com, npm@chromium.org URL: https://wicg.github.io/element-timing Repository: https://github.com/WICG/element-timing Test Suite: https://github.com/web-platform-tests/wpt/tree/master/element-timing @@ -28,16 +29,23 @@ urlPrefix: https://w3c.github.io/performance-timeline/; spec: PERFORMANCE-TIMELI urlPrefix: https://w3c.github.io/IntersectionObserver; spec: INTERSECTION-OBSERVER; type: dfn; url: #calculate-intersection-rect-algo; text: intersection rect algorithm; urlPrefix: https://html.spec.whatwg.org/multipage; spec: HTML; - type: dfn; url: /images.html#img-all; text: completely available; type: dfn; url: //webappapis.html#event-loop-processing-model; text: event loop processing model; urlPrefix: https://drafts.csswg.org/css-backgrounds-3; spec: CSS-BACKGROUNDS-3; type: dfn; url: #propdef-background-image; text: background-image; -urlPrefix: https://drafts.csswg.org/css2/zindex.html; spec: CSS; - type: dfn; url:#painting-order; text: painting order; urlPrefix: https://wicg.github.io/largest-contentful-paint/; spec: LARGEST-CONTENTFUL-PAINT; type: dfn; url:#potentially-add-a-largestcontentfulpaint-entry; text: potentially add a LargestContentfulPaint entry; urlPrefix: https://fetch.spec.whatwg.org/; spec: FETCH; type: dfn; url:#concept-tao-check; text: timing allow check; +urlPrefix: https://w3c.github.io/paint-timing/; spec: PAINT-TIMING; + type: dfn; url:#set-of-owned-text-nodes; text: set of owned text nodes; + type: dfn; url:#process-image-that-finished-loading; text: process image that finished loading; + type: dfn; url:#timing-eligible; text: timing-eligible + type: dfn; url:#the-paint-timing-steps; text: the paint timing steps + type: dfn; url:#exposed-for-paint-timing; text: exposed for paint timing + type: dfn; url:#pending-image-record; text: pending image record + type: dfn; for:pending image record; url:#pending-image-record-element; text: element + type: dfn; for:pending image record; url:#pending-image-record-loadtime; text: loadTime + type: dfn; for:pending image record; url:#pending-image-record-request; text: request 
 spec:dom; type:dfn; text:descendant
@@ -63,12 +71,8 @@ Thus, this API exposes rendering timing information about web-developer-annotate
 Elements exposed {#sec-elements-exposed}
 ------------------------
 
-The Element Timing API supports timing information about the following elements:
-* <{img}> elements.
-* <{image}> elements inside an <{svg}>.
-* The poster images of <{video}> elements.
-* Elements with a background-image.
-* Groups of text nodes, which are aggregated as described in [[#sec-modifications-CSS]].
+The Element Timing API supports timing information about timing-eligible
+elements, as defined by [[PAINT-TIMING]].
 
 Elements that have a "elementtiming" content attribute are reported in the report image element timing and the report text element timing algorithms.
 
@@ -153,7 +157,11 @@ The {{PerformanceElementTiming/naturalHeight}} attribute must return the value i
 
 The {{PerformanceElementTiming/id}} attribute's getter must return the value it was initialized to.
 
-The {{PerformanceElementTiming/element}} attribute's getter must run the [=get an element=] algorithm this's element and null as inputs.
+The {{PerformanceElementTiming/element}} attribute's getter must perform the following steps:
+

+    1. If this's element is not [=exposed for paint timing=] given null, return null.
+    1. Return this's element.
+

 
 Note: This means that an element that is no longer descendant of the {{Document}} will no longer be returned by {{PerformanceElementTiming/element}}'s attribute getter.
 
@@ -189,101 +197,50 @@ partial interface Element {
 
 The {{Element/elementTiming}} attribute must reflect the element's "elementtiming" content attribute.
 
-Each {{Element}} has an associated image request which is 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.
-
-Each {{Element}} has a set of owned text nodes, which is initially an empty ordered set.
-
-Each {{Document}} has images pending rendering, a list of triples ({{Element}}, image request, DOMHighResTimeStamp) which are considered loaded but not yet rendered.
-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.
-
-Each {{Document}} also has a set of elements with rendered text, which is initially an empty, ordered set.
-
-Modifications to the CSS specification {#sec-modifications-CSS}
---------------------------------------------------------
-
-When the user agent is executing the painting order, it must populate the set of owned text nodes of the painted {{Element|Elements}} so that the following is true:
-
-

-    * If a {{Text}} object |text| will not be painted due to the font face being in its font block period, then it is not appended to the set of owned text nodes of any {{Element}}.
-    * Otherwise, |text| is appended to the set of owned text nodes of the {{Element}} which determines the containing block of |text|.
-

-
-NOTE: A user agent might want to use a stack to efficiently compute the set of owned text nodes while implementing the painting order.
-
-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.
-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.
-
-NOTE: we assume that there is one image request for each {{Element}} that a background-image property affects and for each URL that the background-image property specifies.
-So, for example, if there is a style with two URLs affecting all <{div}>s, and there are two <{div}>s, then there will be four image requests.
-This means that a single background-image property could produce multiple {{PerformanceElementTiming}} entries because it can affect multiple elements and because it can specify multiple URLs.
-
-Modifications to the HTML specification {#sec-modifications-HTML}
---------------------------------------------------------
-
-This section will be removed once the [[HTML]] specification has been modified.
-
-In the update the rendering step of the event loop processing model, add the following substep at the end:
+Report Element Timing {#sec-report-element-timing}
+--------------------------------------------------
 
-1. For each fully active {{Document}} in docs, run the element timing processing algorithm passing in the {{Document}} and now.
+

+    When asked to report element timing given a {{Document}} |doc|, a timestamp |now|, an [=ordered set=] of [=pending image records=] |paintedImages|, and an [=ordered set=] of [=/elements=] |paintedTextNodes|, perform the following steps:
 
-Process image that finished loading {#sec-process-loaded-image}
---------------------------------------------------------
-
-

-To process an image that finished loading given |element| and |imageRequest| as inputs:
-    1. Let |element| be the input {{Element}}.
-    1. Let |imageRequest| be |element|'s associated image request.
-    1. Let |root| be |element|'s root.
-    1. If |root| is not a {{Document}}, return.
-    1. Let |now| be the current high resolution time given |element|'s relevant global object.
-    1. If |imageRequest| is not a data URL [[RFC2397]] and if the timing allow check fails for |imageRequest|'s resource, run the report image element timing algorithm, passing in the triple (|element|, |imageRequest|, |now|), 0, and |root| as inputs.
-    1. Otherwise, add the triple (|element|, |imageRequest|, |now|) to |root|'s images pending rendering.
+    1. For each |record| in |paintedImages|:
+        1. Run the report image element timing algorithm passing in |record|, |now|, and |doc|.
+    1. For each {{Element}} |element| in |paintedTextNodes|:
+        1. Run the report text element timing given |element|, |now|, and |doc|.
 

 
-Report image Element Timing {#sec-report-image-element}
+Report Image Element Timing {#sec-report-image-element}
 --------------------------------------------------------
 
 

-    When asked to report image element timing given a triple (|element|, |imageRequest|, |loadTime|), a DOMHighResTimestamp |renderTime| and a {{Document}} |document|, perform the following steps:
+    When asked to report image element timing given a [=pending image record=] |record|, a DOMHighResTimestamp |renderTime| and a {{Document}} |document|, perform the following steps:
 
-    1. Let |intersectionRect| be the value returned by the intersection rect algorithm using |element| as the target and viewport as the root.
-    1. Let |exposedElement| be the result of running [=get an element=] with |element| and |document| as input.
-    1. If |exposedElement| is not null, call the potentially add a LargestContentfulPaint entry algorithm with |intersectionRect|, |imageRequest|, |renderTime|, |loadTime|, |element|, and |document|.
-    1. If |element|'s "elementtiming" content attribute is absent, then abort these steps.
-    1. Create and initialize a {{PerformanceElementTiming}} object |entry|.
-        1. Initialize |entry|'s request to |imageRequest|.
-        1. Initialize |entry|'s element to |element|.
+    1. If |record|'s [=pending image record/element=]'s "elementtiming" content attribute is absent, then abort these steps.
+    1. Let |intersectionRect| be the value returned by the intersection rect algorithm using |record|'s [=pending image record/element=] as the target and viewport as the root.
+    1. Create and initialize a {{PerformanceElementTiming}} object |entry| with |document|'s [=relevant realm=].
+        1. Initialize |entry|'s request to |record|'s [=pending image record/request=].
+        1. Initialize |entry|'s element to |record|'s [=pending image record/element=].
         1. Initialize |entry|'s {{PerformanceEntry/name}} to the {{DOMString}} "image-paint".
         1. Initialize |entry|'s {{renderTime}} to |renderTime|.
-        1. Initialize |entry|'s {{loadTime}} to |loadTime|.
+        1. Initialize |entry|'s {{loadTime}} to |record|'s [=pending image record/loadTime=].
         1. Initialize |entry|'s {{intersectionRect}} to |intersectionRect|.
-        1. Initialize |entry|'s {{identifier}} to |element|'s "elementtiming" content attribute.
-        1. Initialize |entry|'s {{PerformanceElementTiming/naturalWidth}} and {{PerformanceElementTiming/naturalHeight}} by running the same steps for an <{img}>'s {{HTMLImageElement/naturalWidth}} and {{HTMLImageElement/naturalHeight}} attribute getters, but using |imageRequest| as the image.
-        1. Initialize |entry|'s {{id}} to |element|'s "id" content attribute.
+        1. Initialize |entry|'s {{identifier}} to |record|'s [=pending image record/element=]'s "elementtiming" content attribute.
+        1. Initialize |entry|'s {{PerformanceElementTiming/naturalWidth}} and {{PerformanceElementTiming/naturalHeight}} by running the same steps for an <{img}>'s {{HTMLImageElement/naturalWidth}} and {{HTMLImageElement/naturalHeight}} attribute getters, but using |record|'s [=pending image record/request=] as the image.
+        1. Initialize |entry|'s {{id}} to |record|'s [=pending image record/element=]'s "id" content attribute.
     1. Queue the PerformanceEntry |entry|.
 

 
-Report text Element Timing {#sec-report-text}
+Report Text Element Timing {#sec-report-text}
 --------------------------------------------------------
 
 

     When asked to report text element timing given an {{Element}} |element|, a DOMHighResTimestamp |renderTime| and a {{Document}} |document|, perform the following steps:
 
+    1. If |element|'s "elementtiming" content attribute is absent, then abort these steps.
     1. Let |intersectionRect| be an empty rectangle.
     1. For each {{Text}} node |text| in |element|'s set of owned text nodes:
         1. Augment |intersectionRect| to be smallest rectangle containing the border box of |text| and |intersectionRect|.
     1. Intersect |intersectionRect| with the visual viewport.
-    1. Let |exposedElement| be the result of running [=get an element=] with |element| and |document| as input.
-    1. If |exposedElement| is not null, call the potentially add a LargestContentfulPaint entry algorithm with |intersectionRect|, null, |renderTime|, 0, |exposedElement|, and |document|.
-    1. If |element|'s "elementtiming" content attribute is absent, then abort these steps.
     1. Create and initialize a {{PerformanceElementTiming}} object |entry| with |document|'s [=relevant realm=].
         1. Initialize |entry|'s element to |element|.
         1. Initialize |entry|'s {{PerformanceEntry/name}} to the {{DOMString}} "text-paint".
@@ -296,36 +253,6 @@ Report text Element Timing {#sec-report-text}
     1. Queue the PerformanceEntry |entry|.
 

 
-Element Timing processing {#sec-element-processing}
---------------------------------------------------------
-
-

-    The element timing processing algorithm receives a {{Document}} |doc| and a timestamp |now| and performs the following steps:
-
-    1. For each |imagePendingRenderingTriple| in |doc|'s images pending rendering list:
-        1. Let |imageRequest| be the image request of |imagePendingRenderingTriple|.
-        1. If |imageRequest| is fully decoded, then run the following steps:
-            1. Run the report image element timing algorithm passing in |imagePendingRenderingTriple|, |now|, and |doc|.
-            1. Remove |imagePendingRenderingTriple| from |doc|'s images pending rendering list.
-    1. For each {{Element}} |element| in |doc|'s descendants:
-        1. If |element| is contained in |doc|'s set of elements with rendered text, continue.
-        1. If |element|'s set of owned text nodes is empty, continue.
-        1. Append |element| to |doc|'s set of elements with rendered text.
-        1. Run the report text element timing given |element|, |now|, and |doc|.
-

-
-Get an element algorithm {#sec-get-an-element}
----------------------------------
-
-

-When asked to run the get an element algorithm with {{Element}} |element| and {{Document}} |document| as inputs, run these steps:
-    1. If |element| is not connected, return null.
-    1. Let |settings| be this's relevant settings object.
-    1. if |document| is null, let |document| be |settings|'s relevant global object's associated Document.
-    1. If |element|'s root is not equal to |document| or if |document| is not [=fully active=], return null.
-    1. Return |element|.
-

-
 Security & privacy considerations {#sec-security}
 ===============================================
 
@@ -375,7 +302,7 @@ Computing it at this point in time allows exposing the entry at that time.
 If we were to compute the rect only until the image is fully displayed, we'd only be able to expose the entry after that time.
 
 If we do not want to expose the rendering timetamp of an image, it's preferable to dispatch the entry to the {{PerformanceObserver}} right away.
-Suppose we waited and exposed all the entries during the element timing processing algorithm.
+Suppose we waited and exposed all the entries during the report element timing algorithm.
 An attacker could infer nontrivial information about the rendering timestamp of an image.
 It would do so by only observing the timing for that image.
 Even though the timestamp is not exposed as a member of the {{PerformanceElementTiming}} entry received,