From f2839722e1b3dc56368c32fd5808f172f3ea3289 Mon Sep 17 00:00:00 2001
From: Domenic Denicola <d@domenic.me>
Date: Thu, 6 Aug 2020 14:50:55 -0400
Subject: [PATCH] Improve "completely loaded" specification

Closes #5796. This also makes <meta http-equiv="refresh">'s discussion
of "seconds elapsed since document's has completed loaded" more
rigorous, by explicitly saving the timestamp in a new field.

Additionally, this fixes what is either a spec bug or a serious
ambiguity. Previously, <iframe> and friends, when loading the initial
about:blank, would fire two load events: one from explicit prose doing
so in their sections, and one implicitly because one always gets fired
when you set the "completely loaded" flag.

It's possible that the spec meant to distinguish "mark the document as
completely loaded" from the initial about:blank's "the document is
completely loaded immediately", and have only the former trigger the
reaction-at-a-distance that fired load events. In that case this change
is an editorial clarification only, albeit quite a nice one as by
moving the load firing into the initial about:blank creation, we
deduplicate spec prose from the iframe/frame, embed, and object
sections.
---
 source | 121 +++++++++++++++++++++++++++++----------------------------
 1 file changed, 62 insertions(+), 59 deletions(-)

diff --git a/source b/source
index 1f4439d93a2..50b6a4f4f75 100644
--- a/source
+++ b/source
@@ -9009,8 +9009,7 @@ o.myself = o;</code></pre>
   <p>When a <code>Document</code> is created by a <span data-x="concept-script">script</span> using
   the <code data-x="dom-DOMImplementation-createDocument">createDocument()</code> or <code
   data-x="dom-DOMImplementation-createHTMLDocument">createHTMLDocument()</code> the
-  <code>Document</code> is both <span>ready for post-load tasks</span> and <span>completely
-  loaded</span> immediately.</p>
+  <code>Document</code> is <span>ready for post-load tasks</span> immediately.</p>
 
   <p><dfn data-export="">The document's referrer</dfn> is a string (representing a <span>URL</span>)
   that can be set when the <code>Document</code> is created. If it is not explicitly set, then its
@@ -14595,8 +14594,8 @@ people expect to have work and what is necessary.
         the <em>later</em> of the following two conditions occurs:</p>
 
         <ul>
-         <li>At least <var>time</var> seconds have elapsed since <var>document</var> has
-         <span>completely loaded</span>, adjusted to take into account user or user agent
+         <li>At least <var>time</var> seconds have elapsed since <var>document</var>'s
+         <span>completely loaded time</span>, adjusted to take into account user or user agent
          preferences.</li>
          <!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=774 -->
 
@@ -30043,13 +30042,8 @@ interface <dfn>HTMLIFrameElement</dfn> : <span>HTMLElement</span> {
     </ol>
    </li>
 
-   <li><p>Otherwise, if <var>element</var> has no <code data-x="attr-iframe-src">src</code>
-   attribute specified, and <var>initialInsertion</var> is true, then <span>queue an element
-   task</span> on the <span>DOM manipulation task source</span> given <var>element</var> and the
-   <span>iframe load event steps</span>.</p></li>
-
-   <li><p>Otherwise, run the <span>otherwise steps for <code>iframe</code> or <code>frame</code>
-   elements</span> given <var>element</var>.</p></li>
+   <li><p>Otherwise, if <var>initialInsertion</var> is false, run the <span>otherwise steps for
+   <code>iframe</code> or <code>frame</code> elements</span> given <var>element</var>.</p></li>
   </ol>
 
   <p>The <dfn>otherwise steps for <code>iframe</code> or <code>frame</code> elements</dfn>, given an
@@ -30135,9 +30129,6 @@ interface <dfn>HTMLIFrameElement</dfn> : <span>HTMLElement</span> {
 
   <!-- see also the note near similar text for the location.assign() method -->
 
-  <p>When a <code>Document</code> in an <code>iframe</code> is marked as <span>completely
-  loaded</span>, the user agent must run the <span>iframe load event steps</span>.</p>
-
   <p class="note">A <code data-x="event-load">load</code> event is also fired at the
   <code>iframe</code> element when it is created if no other data is loaded in it.</p>
 
@@ -30145,24 +30136,24 @@ interface <dfn>HTMLIFrameElement</dfn> : <span>HTMLElement</span> {
   iframe load</dfn> flag. When a <code>Document</code> is created, these flags must be unset for
   that <code>Document</code>.</p>
 
-  <p>The <dfn>iframe load event steps</dfn> are as follows:</p>
+  <p>To run the <dfn>iframe load event steps</dfn>, given an <code>iframe</code> element
+  <var>element</var>:</p>
 
   <ol>
-   <li><p>Let <var>child document</var> be the <span>active document</span> of the
-   <code>iframe</code> element's <span>nested browsing context</span> (which cannot be null at this
-   point).</p></li>
+   <li><p>Assert: <var>element</var>'s <span>nested browsing context</span> is not null.</p></li>
 
-   <li><p>If <var>child document</var> has its <span>mute iframe load</span> flag set,
+   <li><p>Let <var>childDocument</var> be the <span>active document</span> of <var>element</var>'s
+   <span>nested browsing context</span>.</p></li>
+
+   <li><p>If <var>childDocument</var> has its <span>mute iframe load</span> flag set, then
    return.</p></li>
 
-   <li><p>Set <var>child document</var>'s <span>iframe load in progress</span>
-   flag.</p></li>
+   <li><p>Set <var>childDocument</var>'s <span>iframe load in progress</span> flag.</p></li>
 
    <li><p><span data-x="concept-event-fire">Fire an event</span> named <code
-   data-x="event-load">load</code> at the <code>iframe</code> element.</p></li>
+   data-x="event-load">load</code> at <var>element</var>.</p></li>
 
-   <li><p>Unset <var>child document</var>'s <span>iframe load in progress</span>
-   flag.</p></li>
+   <li><p>Unset <var>childDocument</var>'s <span>iframe load in progress</span> flag.</p></li>
   </ol>
 
   <p class="warning">This, in conjunction with scripting, can be used to probe the URL space of the
@@ -30799,12 +30790,6 @@ interface <dfn>HTMLEmbedElement</dfn> : <span>HTMLElement</span> {
 
            <li><p><var>element</var> now <span>represents</span> its <span>nested browsing
            context</span>.</p></li>
-
-           <li><p>When the <code>Document</code> of <var>element</var>'s <span>nested browsing
-           context</span> is marked as <span>completely loaded</span>, <span>queue an element
-           task</span> on the <span>DOM manipulation task source</span> given <var>element</var> to
-           <span data-x="concept-event-fire">fire an event</span> named <code
-           data-x="event-load">load</code> at <var>element</var>.</p></li>
           </ol>
          </dd>
 
@@ -31485,14 +31470,6 @@ interface <dfn>HTMLObjectElement</dfn> : <span>HTMLElement</span> {
         data-x="attr-object-data">data</code> attribute of the <code>object</code> element doesn't
         get updated if the browsing context gets further navigated to other locations.)</p>
 
-        <p>If the <span>URL</span> of the given resource <em>is</em> <code>about:blank</code>, then,
-        instead, the user agent must <span>queue an element task</span> on the <span>DOM
-        manipulation task source</span> given the <code>object</code> element to <span
-        data-x="concept-event-fire">fire an event</span> named <code data-x="event-load">load</code>
-        at the <code>object</code> element. <span class="note">No <code
-        data-x="event-load">load</code> event is fired at the <code>about:blank</code> document
-        itself.</span></p>
-
         <p>The <code>object</code> element <span>represents</span> its <span>nested browsing
         context</span>.</p>
 
@@ -31544,11 +31521,18 @@ interface <dfn>HTMLObjectElement</dfn> : <span>HTMLElement</span> {
      represents.</p>
 
      <li>
-      <p>Return. Once the resource is completely loaded, <span>queue an element task</span> on the
-      <span>DOM manipulation task source</span> given the <code>object</code> element to <span
-      data-x="concept-event-fire">fire an event</span> named <code data-x="event-load">load</code>
-      at the element.</p>
+      <p>If the <code>object</code> element does not represent its <span>nested browsing
+      context</span>, then once the resource is completely loaded, <span>queue an element
+      task</span> on the <span>DOM manipulation task source</span> given the <code>object</code>
+      element to <span data-x="concept-event-fire">fire an event</span> named <code
+      data-x="event-load">load</code> at the element.</p>
+
+      <p class="note">If the element <em>does</em> represent its <span>nested browsing
+      context</span>, then an analogous task will be queued when the created <code>Document</code>
+      is <span data-x="completely finish loading">completely finished loading</span>.</p>
      </li>
+
+     <li><p>Return.</p></li>
     </ol>
    </li>
 
@@ -76935,8 +76919,8 @@ popup4.close();</code></pre></div>
    <span>origin</span> is <var>origin</var>, <span>active sandboxing flag set</span> is
    <var>sandboxFlags</var>, <span data-x="concept-document-permissions-policy">permissions
    policy</span> is <var>permissionsPolicy</var>, <span data-x="concept-document-coop">cross-origin
-   opener policy</span> is <var>coop</var>, and which is both <span>ready for post-load tasks</span>
-   and <span>completely loaded</span> immediately.</p></li>
+   opener policy</span> is <var>coop</var>, and which is <span>ready for post-load
+   tasks</span>.</p></li>
 
    <li><p>Ensure that <var>document</var> has a single child <code>html</code> node, which itself
    has two empty child nodes: a <code>head</code> element, and a <code>body</code> element.</p></li>
@@ -76959,6 +76943,8 @@ popup4.close();</code></pre></div>
    <li><p>Add <var>document</var> to <var>browsingContext</var>'s <span>session
    history</span>.</p></li>
 
+   <li><p><span>Completely finish loading</span> <var>document</var>.</p></li>
+
    <li><p>Return <var>browsingContext</var>.</p></li>
   </ol>
 
@@ -84512,9 +84498,38 @@ dictionary <dfn>PageTransitionEventInit</dfn> : <span>EventInit</span> {
   <p>The <dfn><code data-x="dom-PageTransitionEvent-persisted">persisted</code></dfn> attribute must
   return the value it was initialized to. It represents the context information for the event.</p>
 
-  </div>
+  <h4>Loading documents</h4>
 
+  <p>A <code>Document</code> has a <dfn>completely loaded time</dfn> (a time or null), which is
+  initially null.</p>
 
+  <p>A <code>Document</code> is considered <dfn>completely loaded</dfn> if its <span>completely
+  loaded time</span> is non-null.
+
+  <p>To <dfn>completely finish loading</dfn> a <code>Document</code> <var>document</var>:</p>
+
+  <ol>
+   <li><p>Assert: <var>document</var>'s <span data-x="concept-document-bc">browsing context</span>
+   is non-null.</p></li>
+
+   <li><p>Set <var>document</var>'s <span>completely loaded time</span> to the current
+   time.</p></li>
+
+   <li><p>Let <var>container</var> be <var>document</var>'s <span
+   data-x="concept-document-bc">browsing context</span>'s <span
+   data-x="bc-container">container</span>.</p></li>
+
+   <li><p>If <var>container</var> is an <code>iframe</code> element, then <span>queue an element
+   task</span> on the <span>DOM manipulation task source</span> given <var>container</var> to run
+   the <span>iframe load event steps</span> given <var>container</var>.</p></li>
+
+   <li><p>Otherwise, if <var>container</var> is non-null, then <span>queue an element task</span> on
+   the <span>DOM manipulation task source</span> given <var>container</var> to <span
+   data-x="concept-event-fire">fire an event</span> named <code data-x="event-load">load</code> at
+   <var>container</var>.</p>
+  </ol>
+
+  </div>
 
   <h4>Unloading documents</h4>
 
@@ -110790,9 +110805,7 @@ document.body.appendChild(text);
 
    <li><p>The <code>Document</code> is now <dfn>ready for post-load tasks</dfn>.</p></li>
 
-   <li><p><span>Queue a global task</span> on the <span>DOM manipulation task source</span> given
-   the <code>Document</code>'s <span>relevant global object</span> to mark the <code>Document</code>
-   as <dfn>completely loaded</dfn>.</p></li>
+   <li><p><span>Completely finish loading</span> the <code>Document</code>.</p></li>
   </ol>
 
   <p>When the user agent is to <dfn>abort a parser</dfn>, it must run the following steps:</p>
@@ -115733,22 +115746,12 @@ interface <dfn>HTMLFrameSetElement</dfn> : <span>HTMLElement</span> {
   data-x="process-frame-initial-insertion"><var>initialInsertion</var></dfn>:</p>
 
   <ol>
-   <li><p>If <var>element</var> has no <code undefined data-x="attr-frame-src">src</code> attribute
-   specified, and <var>initialInsertion</var> is true, then <span>queue an element task</span> on
-   the <span>DOM manipulation task source</span> given <var>element</var> to <span
-   data-x="concept-event-fire">fire an event</span> named <code data-x="event-load">load</code> at
-   <var>element</var>.</p></li>
+   <li><p>If <var>initialInsertion</var> is true, then do nothing.</p></li>
 
    <li><p>Otherwise, run the <span>otherwise steps for <code>iframe</code> or <code>frame</code>
    elements</span> given <var>element</var>.</p></li>
   </ol>
 
-  <!-- next few paragraphs are also from <iframe> but less detailed -->
-
-  <p>When a <code>Document</code> in a <code>frame</code> is marked as <span>completely
-  loaded</span>, the user agent must <span data-x="concept-event-fire">fire an event</span> named
-  <code data-x="event-load">load</code> at the <code>frame</code> element.</p>
-
   <p>The <code>frame</code> element <span>potentially delays the load event</span>.</p>
 
   <!-- END of section that's very similar to <iframe> -->