Skip to content

Commit

Permalink
Editorial: introduce browsing context's "active window"
Browse files Browse the repository at this point in the history 
This abstracts away having to say "browsing context's WindowProxy
object's [[Window]] internal slot value", and replaces a few imprecise
instances of "browsing context's Window object".
  • Loading branch information
@domenic
domenic authored Jun 24, 2020
1 parent b4fbe04 commit 244d97e
Showing 1 changed file with 58 additions and 60 deletions.
118 changes: 58 additions & 60 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29971,9 +29971,9 @@ interface <dfn>HTMLIFrameElement</dfn> : <span>HTMLElement</span> {
the <code
data-x="attr-iframe-sandbox-allow-top-navigation-by-user-activation">allow-top-navigation-by-user-activation</code>
keyword behaves similarly but allows such <span data-x="navigate">navigation</span> only when the
browsing context's <code>WindowProxy</code>'s [[Window]] value has <span>transient
activation</span>; and the <code data-x="attr-iframe-sandbox-allow-forms">allow-forms</code>,
<code data-x="attr-iframe-sandbox-allow-modals">allow-modals</code>, <code
browsing context's <span>active window</span> has <span>transient activation</span>; and the <code
data-x="attr-iframe-sandbox-allow-forms">allow-forms</code>, <code
data-x="attr-iframe-sandbox-allow-modals">allow-modals</code>, <code
data-x="attr-iframe-sandbox-allow-orientation-lock">allow-orientation-lock</code>, <code
data-x="attr-iframe-sandbox-allow-pointer-lock">allow-pointer-lock</code>, <code
data-x="attr-iframe-sandbox-allow-popups">allow-popups</code>, <code
Expand Down Expand Up @@ -71651,8 +71651,7 @@ END:VCARD</pre>
</li>

<li><p>Let <var>windows</var> be the list of <code>Window</code> objects constructed by taking
the [[Window]] internal slot value of <var>browsingContext</var>'s <code>WindowProxy</code>
object for each <var>browsingContext</var> in <var>browsingContexts</var>.</p></li>
the <span>active window</span> of each item in <var>browsingContexts</var>.</p></li>

<li><p><span data-x="list iterate">For each</span> <var>window</var> in <var>windows</var>, set
<var>window</var>'s <span>last activation timestamp</span> to the <span>current high resolution
Expand Down Expand Up @@ -71696,8 +71695,7 @@ END:VCARD</pre>
<var>browsingContexts</var>.</p></li>

<li><p>Let <var>windows</var> be the list of <code>Window</code> objects constructed by taking
the [[Window]] internal slot value of <var>browsingContext</var>'s <code>WindowProxy</code>
object for each <var>browsingContext</var> of <var>browsingContexts</var>.</p></li>
the <span>active window</span> of each item in <var>browsingContexts</var>.</p></li>

<li><p><span data-x="list iterate">For each</span> <var>window</var> in <var>windows</var>, if
<var>window</var>'s <span>last activation timestamp</span> is not positive infinity, then set
Expand Down Expand Up @@ -76437,34 +76435,6 @@ dictionary <dfn>DragEventInit</dfn> : <span>MouseEventInit</span> {
<p>A <span>browsing context</span> has an <dfn>is closing</dfn> boolean. It is initially
false.</p>

<p>A <span>browsing context</span> has a <span>session history</span>, which lists the
<code>Document</code> objects that the <span>browsing context</span> has presented, is presenting,
or will present. A <span>browsing context</span>'s <dfn data-export="">active document</dfn> is
its <code>WindowProxy</code> object's <span data-x="concept-windowproxy-window">[[Window]]</span>
internal slot value's <span data-x="concept-document-window">associated
<code>Document</code></span>. A <dfn data-x="concept-document-bc" data-lt="browsing context"
data-dfn-for="Document" data-export=""><code>Document</code>'s browsing context</dfn> is the
<span>browsing context</span> whose <span>session history</span> contains the
<code>Document</code>, if any such browsing context exists and has not been <span data-x="a
browsing context is discarded">discarded</span>, and null otherwise.</p>

<p class="note">In general, there is a 1-to-1 mapping from the <code>Window</code> object to the
<code>Document</code> object, as long as the <code>Document</code> object has a non-null <span
data-x="concept-document-bc">browsing context</span>. There is one exception. A
<code>Window</code> can be reused for the presentation of a second <code>Document</code> in the
same <span>browsing context</span>, such that the mapping is then 1-to-2. This occurs when a
<span>browsing context</span> is <span data-x="navigate">navigated</span> from the initial
<code>about:blank</code> <code>Document</code> to another, with <span>replacement enabled</span>.

<p class="note">A <code>Document</code> does not necessarily have a non-null <span
data-x="concept-document-bc">browsing context</span>. In particular, data mining tools are likely
to never instantiate browsing contexts. A <code>Document</code> created using an API such as <code
data-x="dom-DOMImplementation-createDocument">createDocument()</code> never has a non-null <span
data-x="concept-document-bc">browsing context</span>. And the <code>Document</code> originally
created for an <code>iframe</code> element, which has since been <span data-x="node is removed
from a document">removed from the document</span>, has no associated browsing context, since that
browsing context was <span data-x="a browsing context is discarded">discarded</span>.</p>

<div class="example">
<p>The following example illustrates the various possibilities of a <span>browsing context</span>.
It can be <span>disowned</span>, <span>is closing</span>, neither, or both.</p>
Expand All @@ -76485,6 +76455,37 @@ const popup4 = window.open();
popup4.opener = null;
popup4.close();</code></pre></div>

<p>A <span>browsing context</span> has a <span>session history</span>, which lists the
<code>Document</code> objects that the <span>browsing context</span> has presented, is presenting,
or will present. A <dfn data-x="concept-document-bc" data-lt="browsing context"
data-dfn-for="Document" data-export=""><code>Document</code>'s browsing context</dfn> is the
<span>browsing context</span> whose <span>session history</span> contains the
<code>Document</code>, if any such browsing context exists and has not been <span data-x="a
browsing context is discarded">discarded</span>, and null otherwise.</p>

<p class="note">A <code>Document</code> does not necessarily have a non-null <span
data-x="concept-document-bc">browsing context</span>. In particular, data mining tools are likely
to never instantiate browsing contexts. A <code>Document</code> created using an API such as <code
data-x="dom-DOMImplementation-createDocument">createDocument()</code> never has a non-null <span
data-x="concept-document-bc">browsing context</span>. And the <code>Document</code> originally
created for an <code>iframe</code> element, which has since been <span data-x="node is removed
from a document">removed from the document</span>, has no associated browsing context, since that
browsing context was <span data-x="a browsing context is discarded">discarded</span>.</p>

<p>A <span>browsing context</span>'s <dfn data-export="" data-dfn-for="browsing context">active
window</dfn> is its <code>WindowProxy</code> object's <span
data-x="concept-windowproxy-window">[[Window]]</span> internal slot value. A <span>browsing
context</span>'s <dfn data-export="">active document</dfn> is its <span>active window</span>'s
<span data-x="concept-document-window">associated <code>Document</code></span>.

<p class="note">In general, there is a 1-to-1 mapping from the <code>Window</code> object to the
<code>Document</code> object, as long as the <code>Document</code> object has a non-null <span
data-x="concept-document-bc">browsing context</span>. There is one exception. A
<code>Window</code> can be reused for the presentation of a second <code>Document</code> in the
same <span>browsing context</span>, such that the mapping is then 1-to-2. This occurs when a
<span>browsing context</span> is <span data-x="navigate">navigated</span> from the initial
<code>about:blank</code> <code>Document</code> to another, with <span>replacement enabled</span>.


<h4>Creating browsing contexts</h4>

Expand All @@ -76501,9 +76502,7 @@ popup4.close();</code></pre></div>
#2688</a>.</p>
</li>

<li><p>Set <var>browsingContext</var>'s <code>WindowProxy</code> object's <span
data-x="concept-windowproxy-window">[[Window]]</span> internal slot value to
<var>window</var>.</p></li>
<li><p>Set <var>browsingContext</var>'s <span>active window</span> to <var>window</var>.</p></li>

<li><p>Set <var>window</var>'s <span data-x="concept-document-window">associated
<code>Document</code></span> to <var>document</var>.</p></li>
Expand Down Expand Up @@ -77116,15 +77115,15 @@ console.assert(iframeWindow.frameElement === null);
then:</p>

<ol>
<li><p>If <var>A</var>'s <code>WindowProxy</code>'s [[Window]] value has <span>transient
<li><p>If <var>A</var>'s <span>active window</span> has <span>transient activation</span> and
<var>A</var>'s <span>active document</span>'s <span>active sandboxing flag set</span> has its
<span>sandboxed top-level navigation with user activation browsing context flag</span> set,
then return false.</p></li>

<li><p>Otherwise, if <var>A</var>'s <span>active window</span> does not have <span>transient
activation</span> and <var>A</var>'s <span>active document</span>'s <span>active sandboxing
flag set</span> has its <span>sandboxed top-level navigation with user activation browsing
flag set</span> has its <span>sandboxed top-level navigation without user activation browsing
context flag</span> set, then return false.</p></li>

<li><p>Otherwise, if <var>A</var>'s <code>WindowProxy</code>'s [[Window]] value does not have
<span>transient activation</span> and <var>A</var>'s <span>active document</span>'s
<span>active sandboxing flag set</span> has its <span>sandboxed top-level navigation without
user activation browsing context flag</span> set, then return false.</p></li>
</ol>
</li>

Expand Down Expand Up @@ -77436,9 +77435,9 @@ console.assert(iframeWindow.frameElement === null);
applicable option from the following list:</p>

<dl class="switch">
<dt id="popup-blocker">If <var>current</var>'s <code>WindowProxy</code>'s [[Window]] value does
not have <span>transient activation</span> and the user agent has been configured to not show
popups (i.e. the user agent has a "popup blocker" enabled)</dt>
<dt id="popup-blocker">If <var>current</var>'s <span>active window</span> does not have
<span>transient activation</span> and the user agent has been configured to not show popups
(i.e., the user agent has a "popup blocker" enabled)</dt>

<dd><p>The user agent may inform the user that a popup has been blocked.</p></dd>

Expand Down Expand Up @@ -78077,8 +78076,8 @@ dictionary <dfn>WindowPostMessageOptions</dfn> : <span>PostMessageOptions</span>

<li><p>If <var>urlRecord</var> is "<code>about:blank</code>" and <var>new</var> is true, then
<span>queue a task</span> to <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-load">load</code> at <var>target browsing context</var>'s <code>Window</code>
object, with the <var>legacy target override flag</var> set.</p>
data-x="event-load">load</code> at <var>target browsing context</var>'s <span>active
window</span>, with the <var>legacy target override flag</var> set.</p>

<li><p>Otherwise, <span>navigate</span><!--DONAV window.open()--> <var>target browsing
context</var> to <var>request</var>, with the <var><span>exceptions enabled flag</span></var>
Expand Down Expand Up @@ -79617,8 +79616,7 @@ interface <dfn>BarProp</dfn> {
<p>This flag <a href="#sandboxLinks">prevents content from navigating their <span>top-level
browsing context</span></a> and <a href="#sandboxClose">prevents content from closing their
<span>top-level browsing context</span></a>. It is consulted only when the sandboxed browsing
context's <code>WindowProxy</code>'s [[Window]] value does not have <span>transient
activation</span>.</p>
context's <span>active window</span> does not have <span>transient activation</span>.</p>

<p>When the <span>sandboxed top-level navigation without user activation browsing context
flag</span> is <em>not</em> set, content can navigate its <span>top-level browsing
Expand All @@ -79635,7 +79633,7 @@ interface <dfn>BarProp</dfn> {
<p>This flag <a href="#sandboxLinks">prevents content from navigating their <span>top-level
browsing context</span></a> and <a href="#sandboxClose">prevents content from closing their
<span>top-level browsing context</span></a>. It is consulted only when the sandboxed browsing
context's <code>WindowProxy</code>'s [[Window]] value has <span>transient activation</span>.</p>
context's <span>active window</span> has <span>transient activation</span>.</p>

<p>As with the <span>sandboxed top-level navigation without user activation browsing context
flag</span>, this flag only affects the <span>top-level browsing context</span>; if it is not
Expand Down Expand Up @@ -82178,9 +82176,9 @@ interface <dfn>Location</dfn> { // but see also <a href="#the-location-interface
target software, e.g. by prompting the user to confirm that the <span>source browsing
context</span>'s <span>active document</span>'s <span>origin</span> is to be allowed to invoke the
specified software. In particular, if the <span>navigate</span> algorithm was invoked when
<span>source browsing context</span>'s <code>WindowProxy</code>'s [[Window]] value does not have
<span>transient activation</span>, the user agent should not invoke the external software package
without prior user confirmation.</p>
<span>source browsing context</span>'s <span>active window</span> does not have <span>transient
activation</span>, the user agent should not invoke the external software package without prior
user confirmation.</p>

<p class="example">For example, there could be a vulnerability in the target software's URL
handler which a hostile page would attempt to exploit by tricking a user into clicking a link.</p>
Expand Down Expand Up @@ -83264,10 +83262,10 @@ new PaymentRequest(&hellip;); // Allowed to use

<li><p>If <var>hash changed</var> is true, then <span data-x="concept-event-fire">fire an
event</span> named <code data-x="event-hashchange">hashchange</code> at the <span>browsing
context</span>'s <code>Window</code> object, using <code>HashChangeEvent</code>, with the
<code data-x="dom-HashChangeEvent-oldURL">oldURL</code> attribute initialized to <var>old
URL</var> and the <code data-x="dom-HashChangeEvent-newURL">newURL</code> attribute
initialized to <var>new URL</var>.</p></li>
context</span>'s <span>active window</span>, using <code>HashChangeEvent</code>, with the <code
data-x="dom-HashChangeEvent-oldURL">oldURL</code> attribute initialized to <var>old URL</var>
and the <code data-x="dom-HashChangeEvent-newURL">newURL</code> attribute initialized to
<var>new URL</var>.</p></li>
</ol>
</li>
</ol>
Expand Down

0 comments on commit 244d97e

Please sign in to comment.