From 87b45fe1a427adede808389087f5fcc3e175d2ac Mon Sep 17 00:00:00 2001 From: Shubham Gupta Date: Sat, 21 Mar 2026 01:11:44 +0800 Subject: [PATCH] Add First Paint Definition Signed-off-by: Shubham Gupta --- index.bs | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/index.bs b/index.bs index f4b83e9..5578bed 100644 --- a/index.bs +++ b/index.bs @@ -11,7 +11,7 @@ Editor: Ian Clelland, Google https://google.com, iclelland@chromium.org, w3cid 7 Former Editor: Shubhie Panicker, Google https://google.com, panicker@google.com, w3cid 92587 Nicolás Peña Moreno, Google https://google.com, npm@chromium.org, w3cid 103755 Repository: w3c/paint-timing -Abstract: This document defines an API that can be used to capture a series of key moments (first paint, first contentful paint) during pageload which developers care about. +Abstract: This document defines an API that can be used to capture a series of key moments (first paint, first contentful paint) during page load which developers care about. Default Highlight: js 
@@ -100,7 +100,7 @@ Load is not a single moment in time — it's an experience that no one metric ca
 
 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.
+The primary difference between the two metrics is FP marks the first time the browser renders anything for a given document - This is the first key moment developers care about in page load. By contrast, FCP marks the time when the browser renders the first bit of image or text content from the DOM.
 
 Usage example {#example}
 ------------------------
@@ -182,8 +182,6 @@ An [=/element=] |el| is paintable when all of the following apply:
 
     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.
@@ -361,6 +359,18 @@ To process an image that finished loading given an {{Element}} |eleme
 
 Reporting paint timing {#sec-reporting-paint-timing}
 --------------------------------------------------------
+
First Paint

+

+    To know whether [=Document=] |document| should report first paint, perform the following steps:
+    1. If |document|'s [=set of previously reported paints=] contains "first-paint", then return false.
+    1. If |document| contains at least one [=/element=] that is [=paintable=], then return true.
+    1. Otherwise, return false.
+
+    NOTE: [=First paint=] excludes the default background paint, but includes non-default background paint with [=used value|used=] [=opacity=] greater than zero.
+    
+    NOTE: [=First paint=] includes the enclosing box of an iframe considering it is [=paintable=].
+
+

 
 
First Contentful Paint

 

@@ -391,11 +401,8 @@ Reporting paint timing {#sec-reporting-paint-timing}
     1. Let |frameTimingInfo| be |document|'s [=current frame timing info=].
     1. Set |document|'s [=current frame timing info=] to null.
     1. Let |flushPaintTimings| be the following steps:
-        1. 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.
-
-                ISSUE: This should be turned into a normative note.
+        1. If |document| [=should report first paint=], then:
+            1. [=Report paint timing=] given |document|, "first-paint", and |paintTimingInfo|.
 
         1. If |document| [=should report first contentful paint=], then:
             1. [=Report paint timing=] given |document|, "first-contentful-paint", and |paintTimingInfo|.