From 141439c578680c10efa3043fb7431d00db45fa10 Mon Sep 17 00:00:00 2001
From: Noam Rosenthal <noamr@users.noreply.github.com>
Date: Mon, 15 Sep 2025 10:09:24 +0100
Subject: [PATCH 1/3] Add informative note about how PaintTimingMixin works

Closes #115
See also w3c/largest-contentful-paint/145
---
 index.bs | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/index.bs b/index.bs
index 6d98ece..c28eae7 100644
--- a/index.bs
+++ b/index.bs
@@ -194,6 +194,23 @@ A [=browsing context=] |ctx| is <dfn>paint-timing eligible</dfn> when one of the
 The {{PaintTimingMixin}} interface {#sec-PaintTimingMixin}
 =======================================
 
+<div class=non-normative>
+
+<em>This section is non-normative.</em>
+
+The {{PaintTimingMixin}} interface exposes timestamps related to the rendering cycle.
+It is included in [=platform objects=] that extend {{PerformanceEntry}},
+specifically by {{PefrormanceElementTiming}}, {{LargestContentfulPaint}}, {{PerformanceEventTiming}}, {{PerformancePaintTiming}}, and {{PerformanceLongAnimationFrameTiming}}.
+
+The {{PaintTimingMixin/paintTime}} attribute represent the timestamp at the end of the [=update the rendering=] loop
+while the {{PaintTimingMixin/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 {{LargestContentfulPaint}}'s {{LargestContentfulPaint/renderTime}} (as well as its {{LargestContentfulPaint/startTime}}),
+usually return the [=default paint timestamp=] rather than one of the specific timestamps, making them agnostic to the implementation-specific nature of {{PaintTimingMixin/presentationTime}}.
+
+</div>
+
 <pre class="idl">
     [Exposed=Window]
     interface mixin PaintTimingMixin {

From cb41bef58c22d3bfe68e66412f29a069396191f3 Mon Sep 17 00:00:00 2001
From: Noam Rosenthal <noamr@users.noreply.github.com>
Date: Mon, 15 Sep 2025 14:03:44 +0100
Subject: [PATCH 2/3] fix headings

---
 index.bs | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/index.bs b/index.bs
index c28eae7..ead7863 100644
--- a/index.bs
+++ b/index.bs
@@ -191,7 +191,7 @@ A [=browsing context=] |ctx| is <dfn>paint-timing eligible</dfn> when one of the
     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.
 
-The {{PaintTimingMixin}} interface {#sec-PaintTimingMixin}
+The Paint Timing Mixin
 =======================================
 
 <div class=non-normative>
@@ -211,6 +211,9 @@ usually return the [=default paint timestamp=] rather than one of the specific t
 
 </div>
 
+The {{PaintTimingMixin}} interface {#sec-PaintTimingMixin}
+----------------------------------------------------------
+
 <pre class="idl">
     [Exposed=Window]
     interface mixin PaintTimingMixin {

From 9c5c61d53e6587d9cf6690a58d70325b956496e2 Mon Sep 17 00:00:00 2001
From: Noam Rosenthal <noamr@users.noreply.github.com>
Date: Mon, 15 Sep 2025 15:01:46 +0100
Subject: [PATCH 3/3] typo

---
 index.bs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.bs b/index.bs
index ead7863..a07392f 100644
--- a/index.bs
+++ b/index.bs
@@ -200,7 +200,7 @@ The Paint Timing Mixin
 
 The {{PaintTimingMixin}} interface exposes timestamps related to the rendering cycle.
 It is included in [=platform objects=] that extend {{PerformanceEntry}},
-specifically by {{PefrormanceElementTiming}}, {{LargestContentfulPaint}}, {{PerformanceEventTiming}}, {{PerformancePaintTiming}}, and {{PerformanceLongAnimationFrameTiming}}.
+specifically by {{PerformanceElementTiming}}, {{LargestContentfulPaint}}, {{PerformanceEventTiming}}, {{PerformancePaintTiming}}, and {{PerformanceLongAnimationFrameTiming}}.
 
 The {{PaintTimingMixin/paintTime}} attribute represent the timestamp at the end of the [=update the rendering=] loop
 while the {{PaintTimingMixin/presentationTime}} represents an implementation-specific timestamp marked when the frame is presented to the user.