Add an explanation of active vs. fully active documents

Author: domenic

source

@@ -77042,6 +77042,60 @@ dictionary <dfn>DragEventInit</dfn> : <span>MouseEventInit</span> {
   browsing context">child browsing contexts</span> of elements that are in <code>Document</code>s
   that are not themselves <span>fully active</span>.</p>
 
+  <div class="example">
+   <p>The following example illustrates the differences between <span data-x="active
+   document">active</span> and <span>fully active</span> <code>Document</code> objects. Here <code
+   data-x="">a.html</code> is loaded into a browser window, <code data-x="">b-1.html</code> starts
+   out loaded into an <code>iframe</code> as shown, and <code data-x="">b-2.html</code> and <code
+   data-x="">c.html</code> are omitted (they can simply be an empty document).</p>
+
+   <pre>&lt;!-- a.html -->
+&lt;!DOCTYPE html>
+&lt;html lang="en">
+&lt;title>Browsing context A&lt;/title>
+
+&lt;iframe src="b-1.html">&lt;/iframe>
+&lt;button onclick="frames[0].location.href = 'b-2.html'">Click me&lt;/button>
+
+&lt;!-- b-1.html -->
+&lt;!DOCTYPE html>
+&lt;html lang="en">
+&lt;title>Browsing context B&lt;/title>
+
+&lt;iframe src="c.html">&lt;/iframe></pre>
+
+   <p>At this point, the documents given by <code data-x="">a.html</code>, <code
+   data-x="">b-1.html</code>, and <code data-x="">c.html</code> are all the <span data-x="active
+   document">active documents</span> of their respective <span data-x="concept-document-bc">browsing
+   contexts</span>. They are also all <span>fully active</span>.</p>
+
+   <p>After clicking on the <code>button</code>, and thus loading a new <code>Document</code> from
+   <code data-x="">b-2.html</code> into browsing context B, we have the following results:</p>
+
+   <ul>
+    <li><p>The <code data-x="">a.html</code> <code>Document</code> remains both the <span>active
+    document</span> of browsing context A, and <span>fully active</span>.</p></li>
+
+    <li><p>The <code data-x="">b-1.html</code> <code>Document</code> is now <em>not</em> the
+    <span>active document</span> of browsing context B. As such it is also not <span>fully
+    active</span>.</p></li>
+
+    <li><p>The new <code data-x="">b-2.html</code> <code>Document</code> is now the <span>active
+    document</span> of browsing context B, and is also <span>fully active</span>.</p></li>
+
+    <li><p>The <code data-x="">c.html</code> <code>Document</code> is still the <span>active
+    document</span> of browsing context C. However, since it is <span data-x="browsing context
+    nested through">nested through</span> the <code data-x="">b-1.html</code> <code>Document</code>,
+    which is itself not <span>fully active</span>, this means the <code data-x="">c.html</code>
+    <code>Document</code> is now not <span>fully active</span> (even though it is <span
+    data-x="active document">active</span>).</p></li>
+   </ul>
+
+   <p>For more explorations of the complexities involved here, especially as it impacts <a
+   href="#history">the session history</a>, see <cite>A Model of Navigation History</cite>. <ref
+   spec=NAVMODEL></p>
+  </div>
+
   <p>A <span>browsing context</span> that is a <span>nested browsing context</span> can be put into
   a <dfn>delaying <code data-x="event-load">load</code> events mode</dfn>. This is used when it is
   <span data-x="navigate">navigated</span>, to <span>delay the load event</span> of its
@@ -120275,6 +120329,9 @@ INSERT INTERFACES HERE
    <dt id="refsMQ">[MQ]</dt>
    <dd><cite><a href="https://drafts.csswg.org/mediaqueries/">Media Queries</a></cite>, H. Lie, T. &Ccedil;elik, D. Glazman, A. van Kesteren. W3C.</dd>
 
+   <dt id="refsNAVMODEL">[NAVMODEL]</dt>
+   <dd><cite><a href="https://arxiv.org/abs/1608.05444">A Model of Navigation History</a></cite>. C. Brewster, A. Jeffrey.</dd>
+
    <dt id="refsNPAPI">[NPAPI]</dt>
    <dd>(Non-normative) <cite><a href="https://developer.mozilla.org/en-US/docs/Plugins/Guide">Gecko Plugin API Reference</a></cite>. Mozilla.</dd>