Add a performance entry type for visibility state changes

See w3c/page-visibility#29 and w3c/performance-timeline#105
noamr · Apr 9, 2023 · 668373c · 668373c
1 parent 1279623
commit 668373c
Showing 1 changed file with 81 additions and 0 deletions.
diff --git a/source b/source
@@ -2717,6 +2717,21 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
     <ul class="brief">
      <li><dfn data-x-href="https://w3c.github.io/resource-timing/#dfn-mark-resource-timing">Mark resource timing</dfn></li>
     </ul>
+
+   <dt>Performance Timeline</dt>
+
+   <dd>
+    <p>The following terms are defined in <cite>Performance Timeline</cite>: <ref spec=PERFORMANCETIMELINE></p>
+
+    <ul class="brief">
+     <li><dfn data-x-href="https://w3c.github.io/performance-timeline/#dom-performanceentry"><code>PerformanceEntry</code></dfn> and its
+         <dfn data-x="PerformanceEntry-name" data-x-href="https://w3c.github.io/performance-timeline/#dom-performanceentry-name"><code>name</code></dfn>,
+         <dfn data-x="PerformanceEntry-entryType" data-x-href="https://w3c.github.io/performance-timeline/#dom-performanceentry-entrytype"><code>entryType</code></dfn>,
+         <dfn data-x="PerformanceEntry-startTime" data-x-href="https://w3c.github.io/performance-timeline/#dom-performanceentry-starttime"><code>startTime</code></dfn>, and
+         <dfn data-x="PerformanceEntry-duration" data-x-href="https://w3c.github.io/performance-timeline/#dom-performanceentry-duration"><code>duration</code></dfn> attributes.</li>
+
+     <li><dfn data-x-href="https://w3c.github.io/performance-timeline/#queue-a-performanceentry">Queue a performance entry</dfn></li>
+     </ul>
    </dd>
 
    <dt>Long Tasks</dt>
@@ -76621,6 +76636,14 @@ END:VCARD</pre>
    <li><p>Set <var>document</var>'s <span>visibility state</span> to
    <var>visibilityState</var>.</p></li>
 
+   <li><p><span data-x="queue a performance entry">Queue</span> a new
+   <code>VisibilityStateEntry</code> whose
+   <span data-x="VisibilityStateEntry-state">visibility state</span> is
+   <var>visibilityState</var> and whose <span
+   data-x="VisibilityStateEntry-timestamp">timestamp</span> is
+   the <span>current high resolution time</span> given <var>document</var>'s
+   <span>relevant global object</span>.</p>
+
    <li><p>Run the <span>screen orientation change steps</span> with <var>document</var>. <ref
    spec=SCREENORIENTATION></p></li>
 
@@ -76641,6 +76664,56 @@ END:VCARD</pre>
    initialized to true.</p></li>
   </ol>
 
+  <h4>The <code>VisibilityStateEntry</code> interface</h4>
+
+  <p>The <code>VisibilityStateEntry</code> interface exposes visibility changes to the document,
+  from the moment the document becomes active.</p>
+
+  <div class="example">For example, this allows JavaScript code in the page to examine correlation
+  between visibility changes and paint timing:
+
+  <pre><code class="js">function wasHiddenBeforeFirstContentfulPaint() {
+    const fcpEntry = performance.getEntriesByName("first-contentful-paint")[0];
+    const visibilityStateEntries = performance.getEntriesByType("visibility-state");
+    return visibilityStateEntries.some(e =>
+                                            e.startTime &lt; fcpEntry.startTime &&
+                                            e.name === "hidden");
+}</code></pre>
+  </div>
+
+  <p class="note">Since hiding a page can cause throttling of rendering and other user-agent
+  operations, it is common to use visibility changes as an indication that such throttling has
+  occurred. However, other things could also cause throttling in different browsers, such as
+  long periods of inactivity.</p>
+
+  <pre><code class="idl">[Exposed=(Window)]
+interface <dfn interface>VisibilityStateEntry</dfn> : <span>PerformanceEntry</span> {
+  readonly attribute DOMString <span data-x="VisibilityStateEntry-name">name</span>;                 // shadows inherited <span data-x="PerformanceEntry-name">name</span>
+  readonly attribute DOMString <span data-x="VisibilityStateEntry-entryType">entryType</span>;            // shadows inherited <span data-x="PerformanceEntry-entryType">entryType</span>
+  readonly attribute DOMHighResTimeStamp <span data-x="VisibilityStateEntry-startTime">startTime</span>;  // shadows inherited <span data-x="PerformanceEntry-startTime">startTime</span>
+  readonly attribute unsigned long <span data-x="VisibilityStateEntry-duration">duration</span>;         // shadows inherited <span data-x="PerformanceEntry-duration">duration</span>
+};</code></pre>
+
+  <p>The <code>VisibilityStateEntry</code> has an associated
+  <span><code>DOMHighResTimeStamp</code></span>
+  <dfn data-x="VisibilityStateEntry-timestamp">timestamp</dfn>.</p>
+
+  <p>The <code>VisibilityStateEntry</code> has an associated "<code data-x="">visible</code>" or
+  "<code data-x="">hidden</code>" <dfn
+  data-x="VisibilityStateEntry-state">visibility state</dfn>.</p>
+
+  <p>The <dfn data-x="VisibilityStateEntry-name"><code>name</code></dfn> getter steps are to return
+  <span>this</span>'s <span data-x="VisibilityStateEntry-state">visibility state</span>.</p>
+
+  <p>The <dfn data-x="VisibilityStateEntry-entryType"><code>entryType</code></dfn> getter steps are to return
+  "<code data-x="">visibility-state</code>".</p>
+
+  <p>The <dfn data-x="VisibilityStateEntry-startTime"><code>startTime</code></dfn> getter steps are to return
+  <span>this</span>'s <span data-x="VisibilityStateEntry-timestamp">timestamp</span>.</p>
+
+  <p>The <dfn data-x="VisibilityStateEntry-duration"><code>duration</code></dfn> getter steps are to return
+  zero.</p>
+
 
   <h3>Inert subtrees</h3>
 
@@ -94920,6 +94993,11 @@ location.href = '#foo';</code></pre>
    <span>node navigable</span>'s <span data-x="nav-traversable">traversable navigable</span>'s
    <span>system visibility state</span>.</p></li>
 
+   <li><p><span data-x="queue a performance entry">Queue</span> a new
+   <code>VisibilityStateEntry</code> whose <span data-x="VisibilityStateEntry-state">visibility
+   state</span> is <var>document</var>'s <span>visibility state</span> and whose <span
+   data-x="VisibilityStateEntry-timestamp">timestamp</span> is zero.</p></li>
+
    <li><p>Set <var>window</var>'s <span>relevant settings object</span>'s <span
    data-x="concept-environment-execution-ready-flag">execution ready flag</span>.</p></li>
   </ol>
@@ -133499,6 +133577,9 @@ INSERT INTERFACES HERE
    <dt id="refsPDF">[PDF]</dt>
    <dd>(Non-normative) <cite><a href="https://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/PDF32000_2008.pdf">Document management &mdash; Portable document format &mdash; Part 1: PDF</a></cite>. ISO.</dd>
 
+   <dt id="refsPERFORMANCETIMELINE">[PERFORMANCETIMELINE]</dt>
+   <dd><cite><a href="https://w3c.github.io/performance-timeline/">Performance Timeline</a></cite>, N. Peña Moreno, W3C.</dd>
+
    <dt id="refsPERMISSIONSPOLICY">[PERMISSIONSPOLICY]</dt>
    <dd><cite><a href="https://w3c.github.io/webappsec-feature-policy/">Permissions Policy</a></cite>, I. Clelland, W3C.</dd>