To avoid exposing web authors to the complexities of multithreading, the HTML and DOM APIs are designed such that no script can ever detect the simultaneous execution of other scripts. Even with workers, the intent is that the behavior of implementations can - be thought of as completely serializing the execution of all scripts in all browsing contexts.
+ be thought of as completely serializing the execution of all scripts in all globals.The exception to this general design principle is the JavaScript SharedArrayBuffer
class. Using SharedArrayBuffer objects, it can in fact be observed that scripts in
@@ -1872,9 +1871,9 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
The term plugin refers to an implementation-defined set of content
handlers used by the user agent that can take part in the user agent's rendering of a
- Document object, but that neither act as child
- browsing contexts of the Document nor introduce any Node objects
- to the Document's DOM.
Document object, but that neither act as child
+ navigables of the Document nor introduce any Node objects to the
+ Document's DOM.
Typically such content handlers are provided by third parties, though a user agent can also designate built-in content handlers as plugins.
@@ -1889,7 +1888,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attributeOne example of a plugin would be a PDF viewer that is instantiated in a - browsing context when the user navigates to a PDF file. This would count as a plugin + navigable when the user navigates to a PDF file. This would count as a plugin regardless of whether the party that implemented the PDF viewer component was the same as that which implemented the user agent itself. However, a PDF viewer application that launches separate from the user agent (as opposed to using the same interface) is not a plugin by this @@ -2205,7 +2204,6 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
Origin` headerCross-Origin-Resource-Policy` headerRequestCredentials enumerationRequestDestination enumerationfetch() methodThe following terms are defined in uuid:
+The following terms are defined in Web Cryptography API:
A unique internal value is a value that is serializable, comparable by value, and + never exposed to script.
+ +To create a new unique internal value, return a unique internal value + that has never previously been returned by this algorithm.
If document is an iframe srcdoc document, then return the document base
- URL of document's browsing context's
- container document.
Document object is created, and can change during the lifetime of the
- Document only upon setting document.domain.
- A Document's origin may differ from the
- origin of its URL; for example when a nested browsing context
- is created, its active
- Document's origin is set to the
- nested browsing context's container
- document's origin, even though its
- active Document's URL is
+ Document only upon setting document.domain. A Document's origin can differ from the origin of its URL;
+ for example when a nested navigable is created, its active document's origin is inherited from its parent's active document's origin, even though its active document's URL is
about:blank.
When a Document is created by a script using
@@ -10007,18 +10024,14 @@ partial interface Document {
which is a module map, initially empty.
Each Document has a cross-origin opener
- policy, which is a cross-origin opener policy.
Each Document has an is initial about:blank, which is a
- boolean, initially false. A browsing context browsingContext is still
- on its initial about:blank Document if
- browsingContext's session history's size
- is 1 and browsingContext's session history[0]'s document's is initial about:blank is
- true.
Each Document has a navigation
- id, which is a navigation id or null.
DocumentOrShadowRoot interfaceA Document has a document unload timing info previous document unload timing.
A Document has a boolean was created via cross-origin redirects,
+ initially false.
The document load timing info struct has the following items:
@@ -10674,7 +10690,7 @@ partial interface Document { exposedembed, form, iframe,
img, and exposed object elements that have a non-empty
name content attribute and are in a document tree with
- document as their root;the value of the id content attribute for all
exposed object elements that have a non-empty
@@ -10701,12 +10717,10 @@ partial interface Document {
then this algorithm wouldn't have been invoked by Web IDL.) -->
If elements has only one element, and that element is an iframe
- element, and that iframe element's nested browsing context is not
- null, then return the WindowProxy object of the element's nested browsing
- context.
If elements has only one element, and that element is an iframe
+ element, and that iframe element's nested navigable is not null, then
+ return the active WindowProxy of the element's
+ nested navigable.
Otherwise, if elements has only one element, return that element.
@@ -14039,8 +14053,8 @@ interface HTMLBaseElement : HTMLElement {The base element allows authors to specify the document base URL for
the purposes of parsing URLs, and the name of the default
- browsing context for the purposes of following hyperlinks. The element
- does not represent any content beyond this information.
There must be no more than one base element per document.
The target attribute,
- if specified, must contain a valid browsing context name or keyword, which specifies
- which browsing context is to be used as the default when valid navigable target name or keyword, which specifies
+ which navigable is to be used as the default when hyperlinks and forms in the
Document cause navigation.
Run the linked resource fetch setup steps, given el and request. If the result is false, then return.
Let initiatorType be " Set request's initiator
+ type to "css" if el's css" if el's rel attribute contains the keyword stylesheet; "link" otherwise.
Finalize and report timing with response, - el's node document's relevant global object, and - initiatorType.
Let success be true.
replace" and the source browsing context set to
- document's browsing context.
+ document's node navigable to urlRecord using
+ document, with historyHandling set to "replace".
For the purposes of the previous paragraph, a refresh is said to have come due as soon as the later of the following two conditions occurs:
@@ -16331,10 +16341,8 @@ people expect to have work and what is necessary.Provide the user with an interface that, when selected, navigates a browsing context - to urlRecord, with document's browsing context as the source browsing - context.
Do nothing.
A Document has a script-blocking style sheet counter, which is a
number, initially 0.
A Document has a style sheet that is blocking scripts if its
- script-blocking style sheet counter is greater than 0, or if that
- Document has a non-null browsing context
- whose container document is non-null and has a
- script-blocking style sheet counter greater than 0.
A Document document has a style sheet that is blocking
+ scripts if the following steps return true:
If document's script-blocking style sheet counter is greater than + 0, then return true.
If document's node navigable is null, then return false.
Let containerDocument be document's node navigable's + container document.
If containerDocument is non-null and containerDocument's + script-blocking style sheet counter is greater than 0, then return true.
Return false.
A Document has no style sheet that is blocking scripts if it does not
have a style sheet that is blocking
- scripts as defined in the previous paragraph.
The target
- attribute, if present, must be a valid browsing context name or keyword. It gives the
- name of the browsing context that will be used. User agents use this
+ attribute, if present, must be a valid navigable target name or keyword. It gives the
+ name of the navigable that will be used. User agents use this
name when following hyperlinks.
When an a or area element's activation behavior is
@@ -24195,9 +24215,8 @@ document.body.appendChild(wbr);
Set url's query to the empty string.
Basic URL parse input, with null,
- this element's node document's document's character encoding,
- url as url, and query
+ Basic URL parse input, with
+ url as url and query
state as state
override.
Let replace be false.
Let source be subject's node document's browsing context.
Let targetAttributeValue be the empty string.
If subject is an a or area element, then set
@@ -24307,44 +24323,36 @@ document.body.appendChild(wbr);
an element's noopener with subject and
targetAttributeValue.
Let target be the first return value of applying the rules for choosing a - browsing context given targetAttributeValue, source, and - noopener.
Let targetNavigable be the first return value of applying the rules for + choosing a navigable given targetAttributeValue, subject's + node navigable, and noopener.
If target is null, then return.
If targetNavigable is null, then return.
Parse a URL given subject's href attribute, relative to subject's node
document.
If that is successful, let URL be the resulting URL string.
+If that is successful, let url be the resulting URL string.
-Otherwise, if parsing the URL failed, the user - agent may report the error to the user in a user-agent-specific manner, may queue an - element task on the DOM manipulation task source given subject to - navigate the target browsing context - to an error page to report the error, or may ignore the error and do nothing. In any case, the - user agent must then return.
+Otherwise, if parsing the URL failed, then + return.
If hyperlinkSuffix is non-null, then append it to URL.
If hyperlinkSuffix is non-null, then append it to url.
Let request be a new request whose URL is URL and whose referrer policy is the current state of
- subject's referrerpolicy content attribute.
Let referrerPolicy be the current state of subject's referrerpolicy content attribute.
If subject's link
types includes the noreferrer keyword, then set
- request's referrer to "no-referrer".
no-referrer".
Queue an element task on the DOM manipulation task source given - subject to navigate target to - request with the source browsing context set to - source.
+Navigate targetNavigable to url + using subject's node document, with referrerPolicy set to referrerPolicy.
Unlike many other types of navigations, following hyperlinks does not have
special "replace" behavior for when documents are not
@@ -24383,18 +24391,13 @@ document.body.appendChild(wbr);
The following allowed to download algorithm takes an initiator browsing - context and an instantiator browsing context, and returns a boolean indicating - whether or not downloading is allowed:
+The following allowed to download algorithm takes two booleans + sourceAllowsDownloading and targetAllowsDownloading, and returns a boolean + indicating whether or not downloading is allowed:
If the initiator browsing context's sandboxing flags has the sandboxed downloads - browsing context flag set, then return false.
If the instantiator browsing context is non-null, and its sandboxing flags has the sandboxed downloads - browsing context flag set, then return false.
If either sourceAllowsDownloading or targetAllowsDownloading are + false, then return false.
Optionally, the user agent may return false, if it believes doing so would safeguard the user from a potentially hostile download.
If subject cannot navigate, then return.
Run the allowed to download algorithm with the subject's node - document's browsing context and null. If the - algorithm returns false, then return.
Let sourceAllowsDownloading be false if subject's node + document's active sandboxing flag set has the sandboxed downloads + browsing context flag set; otherwise true.
If the result of the allowed to download algorithm with + sourceAllowsDownloading and true is false, then return.
Parse a URL given subject's href attribute, relative to subject's node
document.
If parsing the URL fails, the user agent may report the - error to the user in a user-agent-specific manner, may - navigate to an error page to report the error, or may - ignore the error and do nothing. In either case, the user agent must return.
+If parsing the URL fails, then return.
Otherwise, let URL be the resulting URL string.
include", referrer is "no-referrer", and whose use-URL-credentials flag is set.ping".
Let target URL be the resulting URL string obtained from
Fetch request, with processResponseEndOfBody given response res set to finalize and report
- timing with res, settingsObject's global object, and "ping".
Fetch request.
This may be done in parallel with the primary fetch, and is independent of the @@ -24904,9 +24904,9 @@ document.body.appendChild(wbr);
target attribute value).target attribute value)._blank" as target attribute value)._blank" as target
+ attribute value).
Let context be el's node document's browsing context.
Let navigable be el's node document's node + navigable.
If context is null, then return false.
If navigable is null, then return false.
If context is not a top-level browsing context, then return +
If navigable is not a top-level traversable, then return false.
Set request's initiator to @@ -25771,28 +25771,27 @@ document.body.appendChild(wbr); hyperlink, but annotates any other hyperlinks created by the element (the implied hyperlink, if no other keywords create one).
-The keyword indicates that any newly created top-level browsing context which
- results from following the hyperlink will not be an auxiliary browsing
- context. E.g., its window.opener attribute will be
- null.
The keyword indicates that any newly created top-level traversable which results
+ from following the hyperlink will not contain an auxiliary browsing
+ context. E.g., the resulting Window's opener
+ getter will return null.
See also the processing model where the branching - between an auxiliary browsing context and a top-level browsing context - is defined.
+See also the processing model.
This typically creates an auxiliary browsing context (assuming there is no
- existing browsing context whose browsing context name is
- "example"):
This typically creates a top-level traversable with an auxiliary browsing
+ context (assuming there is no existing navigable whose target name is "example"):
<a href=help.html target=example>Help!</a>This creates a top-level browsing context that is not an auxiliary browsing
+ This creates a top-level traversable with a non-auxiliary browsing
context (assuming the same thing): These are equivalent and only navigate the parent browsing context: These are equivalent and only navigate the parent
+ navigable:
- <a href=help.html target=example rel=noopener>Help!</a><a href=index.html target=_parent>Home</a>
@@ -25827,8 +25826,8 @@ document.body.appendChild(wbr);
hyperlink, but annotates any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).<a href=index.html target=_parent rel=noopener>Home</a>
The keyword indicates that any newly created top-level browsing context which
- results from following the hyperlink will be an auxiliary browsing
+ The keyword indicates that any newly created top-level traversable which results
+ from following the hyperlink will contain an auxiliary browsing
context. See also the processing model. Let key be the result of creating a
preload key given request. Let finalize be the following step given a If options's document is " Let controller be null. Let reportTiming given a Fetch request, with Set controller to the result of fetching request, with processResponseConsumeBody set to the following steps
given a response response and null, failure,
or a byte sequence bodyBytes: Set unsafeEndTime to the unsafe shared current time. If options's document is not
- null, then call finalize given options's document and response.Document
- document and a response response:
- finalize and report timing given response,
- document's relevant global object, options's
- initiator, and unsafeEndTime.pending", then set request's initiator type to "early
+ hint".Document document be to
+ report timing for controller given document's relevant
+ global object.
If entry's on response available is null, then set entry's response is not null, then - call finalize given document and entry's - response.
Set document's map of preloaded resources[key] to entry.
If any of the following conditions are true about this img element:
its node document is not an active document;
its node document is not fully active;
its current request's state is broken,
img element's node document stops being an active
- documentimg element's node document stops being fully
+ activeimg element's current request changes or is mutatedimg element's current request's state becomes brokenIf the element's node document is not the active document, - then:
+If the element's node document is not fully active, then:
Continue running this algorithm in parallel.
Wait until the element's node document is the active document.
Wait until the element's node document is fully + active.
If another instance of this algorithm for this img element was started after this instance
(even if it aborted and is no longer running), then return.
Fetch the image: Fetch request. Return - from this algorithm, and run the remaining steps as part of the fetch's processResponse for the response - response.
+ from this algorithm, and run the remaining steps as part of the fetch's processResponse for the response response. @@ -29594,19 +29598,6 @@ was an English <a href="/wiki/Music_hall">music hall</a> singer, ...Let finalize image loading given eventName be the following:
- -Finalize and report timing with response, the img
- element's node document's relevant global object, and "img".
Fire an event named eventName at
- the img element.
As soon as possible, jump to the first applicable entry from the following list:
@@ -29664,8 +29655,8 @@ was an English <a href="/wiki/Music_hall">music hall</a> singer, ....Queue an element task on the DOM manipulation task source
- given the img element to finalize image loading with load.
img element to fire an event
+ named load at the img element.
@@ -29692,20 +29683,37 @@ was an English <a href="/wiki/Music_hall">music hall</a> singer, ...state to partially
available.
- Otherwise, if the user agent is able to determine that image request's
- image is corrupted in some fatal way such that the image dimensions cannot be obtained, and
- image request is pending request, abort the image
- request for the current request and the pending request,
- upgrade the pending request to the current request, set current
- request's state to broken, and call finalize image loading with error.
Otherwise, if the user agent is able to determine that image request's
- image is corrupted in some fatal way such that the image dimensions cannot be obtained, and
- image request is current request, abort the image
- request for image request and call finalize image loading with
- error.
Otherwise, if the user agent is able to determine that image request's image + is corrupted in some fatal way such that the image dimensions cannot be obtained, and + image request is pending request:
+ +Abort the image request for the current request and the + pending request.
Upgrade the pending request to the current request.
Set current request's state to + broken.
Fire an event named error at the img element.
Otherwise, if the user agent is able to determine that image request's image + is corrupted in some fatal way such that the image dimensions cannot be obtained, and + image request is current request:
+ +Abort the image request for image request.
Fire an event named error at the img element.
That task, and each subsequent music hall</a> singer, ... Add the image to the list of available images using the key
key, with the ignore higher-layer caching flag set. Call finalize image loading with Fire an event named load.load at the img element.img element to finalize image loading with error.
img element to fire an event named
+ error at the img element.
@@ -30369,15 +30377,16 @@ was an English <a href="/wiki/Music_hall">music hall</a> singer, ...synchronous sections are marked with ⌛.)
⌛ If the img element does not use srcset or
- picture, its node document is not the active
- document, has image data whose resource type is multipart/x-mixed-replace, or
- the pending request is not null, then return.
picture, its node document is not fully active, has
+ image data whose resource type is multipart/x-mixed-replace, or the pending
+ request is not null, then return.
⌛ Let selected source and selected pixel - density be the URL and pixel density that results from selecting an image source, respectively.
⌛ If selected source is null, then return.
The iframe element represents its nested browsing
- context.
The iframe element represents its nested navigable.
The src attribute
- gives the URL of a page that the element's nested browsing context is to
+ gives the URL of a page that the element's nested navigable is to
contain. The attribute, if present, must be a valid non-empty URL potentially surrounded by
spaces. If the itemprop attribute is specified on an
iframe element, then the src attribute must
also be specified.
The srcdoc
- attribute gives the content of the page that the element's nested browsing context is
+ attribute gives the content of the page that the element's nested navigable is
to contain. The value of the attribute is the source of an iframe srcdoc document.
Create a new nested browsing context for element.
Create a new nested navigable for element.
If element has a sandbox attribute,
then parse the sandboxing directive given the
@@ -31626,26 +31634,25 @@ interface HTMLIFrameElement : HTMLElement {
When an iframe element is removed
- from a document, the user agent must discard the element's nested browsing context, if it is not null,
- and then set the element's nested browsing context to null.
This happens without any unload events firing
- (the element's nested browsing context and its Document are discarded, not destroyed, not unloaded).
Whenever an iframe element with a non-null nested browsing context
- has its srcdoc attribute set, changed, or removed, the
- user agent must process the iframe attributes.
Whenever an iframe element with a non-null nested navigable has its
+ srcdoc attribute set, changed, or removed, the user agent
+ must process the iframe attributes.
Similarly, whenever an iframe element with a non-null nested browsing
- context but with no srcdoc attribute specified has
- its src attribute set, changed, or removed, the user agent
- must process the iframe attributes.
Similarly, whenever an iframe element with a non-null nested
+ navigable but with no srcdoc attribute specified
+ has its src attribute set, changed, or removed, the user
+ agent must process the iframe attributes.
To process the iframe attributes for an element element,
with an optional boolean HTMLIFrameElement : HTMLElement {
Navigate to the srcdoc resource: navigate an iframe or
- frame given element and a new response whose URL
- list is « about:srcdoc », header list is « (`Content-Type`, `text/html`) », and body is the value of element's srcdoc attribute.
frame given element, about:srcdoc, the empty
+ string, and the value of element's srcdoc
+ attribute.
The resulting Document must be considered an iframe srcdoc document.
Otherwise, run the shared attribute processing steps for iframe and
- frame elements given element and
- initialInsertion.
Otherwise:
+ +Let url be the result of running the shared attribute processing steps
+ for iframe and frame elements given element and
+ initialInsertion.
If url is null, then return.
If url matches about:blank and
+ initialInsertion is true, then:
Run the iframe load event steps given element.
Return.
Let referrerPolicy be the current state of element's referrerpolicy content attribute.
Set element's current navigation was lazy loaded boolean to + false.
If the will lazy load element steps given element return true, + then:
+ +Set element's lazy load resumption steps to the rest of this + algorithm starting with the step labeled navigate.
Set element's current navigation was lazy loaded boolean to + true.
Start intersection-observing a lazy loading element for + element.
Return.
Navigate: navigate an iframe or frame
+ given element, url, and referrerPolicy.
The shared attribute processing steps @@ -31711,96 +31760,47 @@ interface HTMLIFrameElement : HTMLElement { that attribute relative to element's node document. If this is successful, then set url to the resulting URL record.
-If there exists an ancestor browsing context of element's - nested browsing context whose active document's URL, ignoring fragments, is equal to url, then return.
If the inclusive ancestor navigables of element's node + navigable contains a navigable whose active + document's URL equals url with exclude fragments set to true, then return null.
If url matches about:blank and
- initialInsertion is true, then:
Perform the URL and history update steps given element's - nested browsing context's active document and url.
- -This is necessary in case url is something like about:blank?foo. If url is just plain about:blank, this will do nothing.
Run the iframe load event steps given element.
Return.
Let resource be a new request whose URL is url and whose referrer policy is the current state of
- element's referrerpolicy content
- attribute.
If element is an iframe element, then set element's
- current navigation was lazy loaded boolean to false.
If element is an iframe element, and the will lazy load element
- steps given element return true, then:
Set element's lazy load resumption steps to the rest of this - algorithm starting with the step labeled navigate to the resource.
Set element's current navigation was lazy loaded boolean to - true.
Start intersection-observing a lazy loading element for - element.
Return.
This is necessary in case url is something like about:blank?foo. If url is just plain about:blank, this will do nothing.
Navigate to the resource: navigate an iframe or
- frame given element and resource.
Return url.
To navigate an iframe or frame given an element
- element and a resource resource:
Let historyHandling be "default".
Let historyHandling be "push".
If element's nested browsing context's active
+ If element's nested navigable's active
document is not completely loaded, then set historyHandling to
" Let reportFrameTiming be the following step given response response: queue an element
- task on the networking task source given element's node
- document's relevant global object to finalize and report timing
- given response, element's node document's relevant
- global object, and element's local
- name. Navigate element's nested
- browsing context to resource, with historyHandling set to historyHandling, the
- source browsing context set to element's node document's
- browsing context, and
- processResponseEndOfBody set to
- reportFrameTiming.replace".
A load event is also fired at the
- iframe element when it is created if no other data is loaded in it.
Each Document has an iframe load in progress flag and a mute
iframe load flag. When a Document is created, these flags must be unset for
that Document.
Assert: element's nested browsing context is not +
Assert: element's nested navigable is not null.
Let childDocument be the active document of element's - nested browsing context.
Let childDocument be element's nested navigable's active document.
If childDocument has its mute iframe load flag set, then return.
If an element type potentially delays the load event, then for each element element of that type, the user agent must delay the load event of - element's node document if element's nested browsing - context is non-null and any of the following are true: + element's node document if element's nested + navigable is non-null and any of the following are true:
element's nested browsing context's active document - is not ready for post-load tasks.
element's nested navigable's active + document is not ready for post-load tasks.
element's nested navigable's is delaying load events is true.
Anything is delaying the load event of - element's nested browsing context's active + element's nested navigable's active document.
element's nested browsing context is in the delaying load events mode.
If, during the handling of the load event,
- element's nested browsing context is again element's nested navigable is again navigated, that will further delay the load event.
Each If, when the element is created, the iframe element has an associated current navigation was lazy
@@ -31864,20 +31866,23 @@ interface HTMLIFrameElement : HTMLElement {
srcdoc attribute is not set, and the src attribute is either also not set or set but its value cannot
- be parsed, the browsing context will remain at the initial about:blank Document.about:blank
+ Document.
If the user navigates away from this page, the
- iframe's nested browsing context's WindowProxy object will
- proxy new Window objects for new Document objects, but the src attribute will not change.
iframe's nested navigable's active
+ WindowProxy object will proxy new Window objects for new
+ Document objects, but the src attribute will
+ not change.
The name attribute,
- if present, must be a valid browsing context name. The given value is used to name
- the element's nested browsing context if present when that is created.
When the attribute is set, the content is treated as being from a unique origin,
- forms, scripts, and various potentially annoying APIs are disabled, links are prevented from
- targeting other browsing contexts, and plugins are secured.
- The allow-same-origin keyword causes
- the content to be treated as being from its real origin instead of forcing it into a unique
- origin; the allow-top-navigation
- keyword allows the content to navigate its top-level browsing context;
- the navigables. The allow-same-origin keyword causes the
+ content to be treated as being from its real origin instead of forcing it into a unique origin;
+ the allow-top-navigation keyword
+ allows the content to navigate its traversable
+ navigable; the allow-top-navigation-by-user-activation
keyword behaves similarly but allows such navigation only when the
- browsing context's active window has transient activation; the active window has transient
+ activation; the allow-top-navigation-to-custom-protocols
reenables navigations toward non fetch scheme to be handed off to external software; and the HTMLIFrameElement : HTMLElement {
the presentation API, scripts, and the creation of unsandboxed auxiliary browsing contexts respectively. The allow-downloads keyword allows content to
- perform downloads.
The allow-top-navigation and HTMLIFrameElement : HTMLElement {
allows the embedded page to simply remove the sandbox
attribute and then reload itself, effectively breaking out of the sandbox altogether.
These flags only take effect when the nested browsing context of
- the iframe element is navigated. Removing them, or
+
These flags only take effect when the nested navigable of the
+ iframe element is navigated. Removing them, or
removing the entire sandbox attribute, has no effect on
an already-loaded page.
When an iframe element's sandbox
- attribute is set or changed while it has a non-null nested browsing context, the user
- agent must parse the sandboxing directive given
- the attribute's value and the iframe element's iframe sandboxing
- flag set.
iframe element's iframe sandboxing flag
+ set.
When an iframe element's sandbox
- attribute is removed while it has a non-null nested browsing context, the user agent
- must empty the iframe element's iframe sandboxing flag
- set.
iframe element's iframe sandboxing flag set.
iframe in B, page D would now act as if the iframe in B had the allow-same-origin and allow-forms keywords set, because that was the
- state of the nested browsing context in the iframe in A when page B was
+ state of the nested navigable in the iframe in A when page B was
loaded.
Generally speaking, dynamically removing or changing the HTMLIFrameElement : HTMLElement {
attribute, when specified, determines the container
policy that will be used when the permissions policy for a Document
- in the iframe's nested browsing context is initialized. Its value must
- be a serialized permissions policy.
-
iframe's nested navigable is initialized. Its value must be a
+ serialized permissions policy.
In this example, an iframe is used to embed a map from an online navigation
@@ -32090,8 +32096,8 @@ interface HTMLIFrameElement : HTMLElement {
The allowfullscreen attribute is a boolean
attribute. When specified, it indicates that Document objects in the
- iframe element's nested browsing context will be initialized with a
- permissions policy which allows the
+ iframe element's nested navigable will be initialized with a permissions policy which allows the
"fullscreen" feature to be used from any origin. This is
enforced by the process permissions policy
attributes algorithm.
Neither allow nor
allowfullscreen can grant access to a feature
- in an iframe element's nested browsing context if the element's
- node document is not already allowed to use that feature.
iframe element's nested navigable if the element's node
+ document is not already allowed to use that feature.
To determine whether a Document object document
@@ -32127,8 +32133,7 @@ interface HTMLIFrameElement : HTMLElement {
If document's browsing context is null, then return false.
If document's browsing context's - active document is not document, then return false.
If document is not fully active, then return false.
If the result of running is feature enabled in document for origin on feature, document, and document's HTMLIFrameElement : HTMLElement {
Because they only influence the permissions policy of the nested browsing
- context's active document, the allow
- and allowfullscreen attributes only take effect
- when the nested browsing context of the iframe is permissions policy of the nested
+ navigable's active document, the allow and allowfullscreen attributes only take effect when the
+ nested navigable of the iframe is navigated. Adding or removing them has no effect on an already-loaded
document.
An iframe element never has fallback content, as it will always
- create a new nested browsing context, regardless of whether the specified initial
+ create a new nested navigable, regardless of whether the specified initial
contents are successfully used.
The contentDocument IDL attribute, on getting, must
- return the iframe element's content
- document.
The contentWindow IDL attribute must return the
- WindowProxy object of the iframe element's nested browsing
- context, if its nested browsing context is non-null, or null otherwise.
[Exposed=Window]
interface HTMLEmbedElement : HTMLElement {
[HTMLConstructor] constructor();
@@ -32305,28 +32309,16 @@ interface HTMLEmbedElement : HTMLElement {
// also has obsolete members
};Depending on the type of content instantiated by the
- embed element, the node may also support other
- interfaces.
HTMLEmbedElement.The embed element provides an integration point for an external (typically
- non-HTML) application or interactive content.
The embed element provides an integration point for an external application or
+ interactive content.
The src attribute
gives the URL of the resource being embedded. The attribute, if present, must contain
a valid non-empty URL potentially surrounded by spaces.
Authors should avoid referencing untrusted resources, as such a resource can be - used to instantiate plugins or run scripts, even if the author has used features such as the Flash - "allowScriptAccess" parameter.
-If the itemprop attribute is specified on an
embed element, then the src attribute must also
be specified.
embed",
credentials mode is "include", mode is "navigate", and whose use-URL-credentials flag is set.Let processResponseEndOfBody given response res be to finalize and report
- timing with res, element's node document's
- relevant global object, and "embed".
embed", and whose use-URL-credentials flag
+ is set.
Fetch request, with processResponseEndOfBody set to - processResponseEndOfBody, and processResponse set - to the following steps given response - response:
+ data-x="processResponse">processResponse set to the following steps given response response:If another task has since been queued to run @@ -32455,41 +32442,37 @@ interface HTMLEmbedElement : HTMLElement {
image/svg+xmlIf element's nested browsing context is null, then - create a new nested browsing context for element.
If element's nested navigable is null, then + create a new nested navigable for element.
Navigate element's nested browsing context to
- response, with historyHandling set to
- "replace" and the source browsing context
- set to element's node document's browsing context.
Navigate element's nested
+ navigable to response's URL using element's node
+ document, with response set to
+ response, and historyHandling set to "replace".
element's src attribute
- does not get updated if the browsing context gets further navigated to other
- locations.
element now represents its nested browsing - context.
Display a plugin for element, given type and - response.
element now represents its nested + navigable.
Fetching the resource must delay the load event of element's + node document.
@@ -32497,19 +32480,7 @@ interface HTMLEmbedElement : HTMLElement { node document. -Otherwise:
- -Let type be the value of element's type attribute.
If type is a type that a plugin supports, then display a - plugin for element given type.
Otherwise, display no plugin for element.
Otherwise, display no plugin for element.
To determine the type of the content given an @@ -32546,50 +32517,13 @@ interface HTMLEmbedElement : HTMLElement { non-ok status. This allows servers to return data for plugins even with error responses (e.g., HTTP 500 Internal Server Error codes can still contain plugin data).
-To display a plugin for an embed element element, given a
- string type and optionally a response
- response:
If element's nested browsing context is not null, then:
- -Discard element's - nested browsing context.
Set element's nested browsing context to null.
Find and instantiate an appropriate plugin based on type, - replacing any previously-instantiated plugin for element. If response was - given, forward it to the plugin.
element now represents this plugin instance.
Once the plugin, and response if given, are completely loaded, queue an
- element task on the DOM manipulation task source give element to
- fire an event named load at element.
To display no plugin for an embed element element:
If element's nested browsing context is not null, then:
- -Discard element's - nested browsing context.
Set element's nested browsing context to null.
Destroy the nested navigable of element.
Display an indication that no plugin could be found for element, - replacing any previously-instantiated plugin for element.
element now represents nothing.
When a plugin is to be instantiated but the
- sandboxed plugins browsing context flag is set on the embed element's
- node document's active sandboxing flag set, then the user agent must
- not instantiate the plugin, and must instead render the embed element
- in a manner that conveys that the plugin was disabled.
The embed element potentially delays the load event.
Any namespace-less attribute other than name, align, hspace, and vspace may be
- specified on the embed element, so long as its name is XML-compatible
- and contains no ASCII upper alphas. These attributes are
- then passed as parameters to the plugin.
All attributes in HTML documents get lowercased automatically, so the - restriction on uppercase letters doesn't affect such documents.
- -The four exceptions are to exclude legacy attributes that have side-effects beyond - just sending parameters to the plugin.
- -The user agent should pass the names and values of all the attributes of the embed
- element that have no namespace to the plugin used, when one is instantiated.
The HTMLEmbedElement object representing the element must expose the scriptable
- interface of the plugin instantiated for the embed element, if any.
The embed element supports dimension attributes.
The object element can represent an external resource, which, depending on the
- type of the resource, will either be treated as an image, as a child browsing
- context, or as an external resource to be processed by a plugin.
The data attribute
specifies the URL of the resource. It must be present, and must contain a
valid non-empty URL potentially surrounded by spaces.
Authors should avoid referencing untrusted resources, as such a resource can be - used to instantiate plugins or run scripts, even if the author has used features such as the Flash - "allowScriptAccess" parameter.
-The type attribute,
if present, specifies the type of the resource. If present, the attribute must be a valid
MIME type string.
The name attribute,
- if present, must be a valid browsing context name. The given value is used to name
- the element's nested browsing context, if applicable, and if present when the
- element's nested browsing context is created.
If the classid attribute is present, and has a
- value that isn't the empty string, then: if the user agent can find a plugin
- suitable according to the value of the classid
- attribute, and plugins aren't being sandboxed, then that
- plugin should be used, and the value of the data attribute, if any, should be passed to the
- plugin. If no suitable plugin can be found, or if the
- plugin reports an error, jump to the step below labeled fallback.
Let request be a new request whose
- URL is the resulting URL record,
- client is the element's node
- document's relevant settings object, URL is the resulting URL record, client is the element's node document's
+ relevant settings object, destination is "object",
credentials mode is "include", mode is "navigate", and whose use-URL-credentials flag is set.
object", and whose use-URL-credentials
+ flag is set.
Fetch request, with processResponseEndOfBody given response res set to finalize and report
- timing with res, the element's node document's
- relevant global object, and "object".
Fetch request.
Fetching the resource must delay the load event of the element's node @@ -32956,21 +32827,13 @@ interface HTMLObjectElement : HTMLElement { labeled handler.
This can introduce a vulnerability, wherein a site is trying to embed a - resource that uses a particular plugin, but the remote site overrides that and instead - furnishes the user agent with a resource that triggers a different plugin with different + resource that uses a particular type, but the remote site overrides that and instead + furnishes the user agent with a resource that triggers a different type of content with different security characteristics.
If there is a type attribute present on the
- object element, and that attribute's value is not a type that the user agent
- supports, but it is a type that a plugin supports, then let the resource type be the type specified in that type attribute, and jump to the step below labeled
- handler.
Run the appropriate set of steps from the following list:
@@ -33012,8 +32875,7 @@ interface HTMLObjectElement : HTMLElement {If the attribute's value is a type that a plugin supports, or the
- attribute's value is a type that starts with "image/" that is
+
If the attribute's value is a type that starts with "image/" that is
not also an XML MIME type, then let the resource type be the
type specified in that type attribute.
image/"If the object element's nested browsing context is non-null,
- then it must be discarded and then set
- to null.
If the object element's nested navigable is null, then
+ create a new nested navigable for the element.
If plugins are being sandboxed, then jump to the step - below labeled fallback.
- -Otherwise, the user agent should use the plugin that supports - resource type and pass the content of the resource to that - plugin. If the plugin reports an error, then jump to the step - below labeled fallback.
-Let response be the response from + fetch.
+If response's URL does not match about:blank, then
+ navigate the element's nested navigable to
+ response's URL using the element's
+ node document, with historyHandling set to
+ "replace".
image/"The data attribute of the
+ object element doesn't get updated if the nested navigable gets
+ further navigated to other locations.
If the object element's nested browsing context is null, then
- create a new nested browsing context for the element.
If the URL of the given resource does not match about:blank, then navigate the element's nested browsing context to that resource, with historyHandling set to "replace" and the source browsing context set to the
- object element's node document's browsing context. (The data attribute of the object element doesn't
- get updated if the browsing context gets further navigated to other locations.)
The object element represents its nested browsing
- context.
The object element represents its nested
+ navigable.
If the object element's nested browsing context is non-null,
- then it must be discarded and then set
- to null.
Destroy the nested navigable of the object element.
Apply the image sniffing rules to determine the type of the image.
@@ -33157,51 +33002,25 @@ interface HTMLObjectElement : HTMLElement { represents.If the object element does not represent its nested browsing
- context, then once the resource is completely loaded, queue an element
- task on the DOM manipulation task source given the object
- element to fire an event named load at the element.
If the element does represent its nested browsing
- context, then an analogous task will be queued when the created Document
- is completely finished loading.
If the object element does not represent its nested navigable,
+ then once the resource is completely loaded, queue an element task on the
+ DOM manipulation task source given the object element to fire an event named load
+ at the element.
If the element does represent its nested navigable,
+ then an analogous task will be queued when the created Document is completely finished loading.
Return.
If the data attribute is absent but the type attribute is present, and the user agent can find a
- plugin suitable according to the value of the type attribute, and plugins
- aren't being sandboxed, then that plugin should be
- used. If these conditions cannot be met, or if the plugin reports an error,
- jump to the step below labeled fallback. Otherwise return; once the plugin is completely
- loaded, queue an element task on the DOM manipulation task source
- given the object element to fire an event
- named load at the element.
Fallback: The object element represents the element's
- children. This is the element's fallback content. If the element has an
- instantiated plugin, then unload it. If the element's nested browsing
- context is non-null, then it must be discarded and then set to null.
When the algorithm above instantiates a plugin, the user agent
- should pass to the plugin used the names and values of all the attributes on the
- element, in the order they were added to the element, with the attributes added by the parser
- being ordered in source order. If the plugin supports a scriptable interface, the
- HTMLObjectElement object representing the element should expose that interface. The
- object element represents the plugin. The
- plugin is not a nested browsing context.
Plugins are considered sandboxed for the purpose of an
- object element if the sandboxed plugins browsing context flag is set on
- the object element's node document's active sandboxing flag
- set.
Due to the algorithm above, the contents of object elements act as fallback
content, used only when referenced resources can't be shown (e.g. because it returned a 404
@@ -33227,15 +33046,12 @@ interface HTMLObjectElement : HTMLElement {
attributes of the same name.
The contentDocument IDL attribute, on getting, must
- return the object element's content
- document.
The contentWindow IDL attribute must return the
- WindowProxy object of the object element's nested browsing
- context, if its nested browsing context is non-null; otherwise, it must return
- null.
The willValidate, validity, and HTMLVideoElement : HTMLMediaElement
data-x="attr-video-poster">poster attribute's value relative to the element's node
document. If this fails, then there is no poster frame; return.
Let request be a new request whose - URL is the resulting URL record, - client is the element's node document's +
Let request be a new request whose URL is the resulting URL record, client is the element's node document's
relevant settings object, destination is " Fetch request, with
- processResponseEndOfBody given
- response res set to
- finalize and report timing with res, the element's
- node document's relevant global object, and
- " Fetch request. This must
+ delay the load event of the element's node document.image", credentials mode is "initiator type is "video",
+ credentials mode is "include", and whose use-URL-credentials flag is set.
- video". This must delay the load event of the element's
- node document.
Set request's initiator + type to destination.
Let byteRange, which is "entire resource" or a
(number, number or "until end") tuple, be the byte range required to satisfy
missing data in media data. This value is implementation-defined
@@ -35175,7 +34990,7 @@ interface MediaError {
Fetch request, with - processResponse set to the following steps given + processResponse set to the following steps given response response:
Let finalize be to finalize and report timing with - response, global, and destination, and call - updateMedia.
Let processEndOfMedia be the following steps:
- -Call finalize.
- -If the fetching process has completes without errors, including decoding the - media data, and if all of the data is available to the user agent without network - access, then, the user agent must move on to the final step below. - This might never happen, e.g. when streaming an infinite resource such as web radio, or - if the resource is longer than the user agent's ability to cache data.
-Let processEndOfMedia be the following step: If the fetching process has + completes without errors, including decoding the media data, and if all of the data is + available to the user agent without network access, then, the user agent must move on to + the final step below. This might never happen, e.g. when streaming an infinite + resource such as web radio, or if the resource is longer than the user agent's ability to + cache data.
If the result of verifying - response given the current media resource and - byteRange is false, then call finalize. Otherwise, - incrementally read response's - body given updateMedia, - processEndOfMedia, finalize, and global.
Otherwise, incrementally read + response's body given + updateMedia, processEndOfMedia, an empty algorithm, and + global.
Update the media data with the contents of response's
unsafe response obtained in this fashion. response can be
@@ -38470,11 +38276,10 @@ interface VideoTrack {
track element's node document's relevant settings
object.
Fetch request, with processResponseEndOfBody given response res set to finalize and report
- timing with res, the element's node document's relevant
- global object, and "track".
Set request's initiator
+ type to "track".
Fetch request.
The tasks queued by the
@@ -40057,11 +39862,11 @@ dictionary TrackEventInit : EventInit {
code that attempts to interact with the Document that embeds the content. To avoid
this, user agents must ensure that there is no access from the content to the embedding page. In
the case of media content that uses DOM concepts, the embedded content must be treated as if it
- was in its own unrelated top-level browsing context.
For instance, if an SVG animation was embedded in a video element,
the user agent would not give it access to the DOM of the outer page. From the perspective of
- scripts in the SVG resource, the SVG file would appear to be in a lone top-level browsing context
+ scripts in the SVG resource, the SVG file would appear to be in a lone top-level traversable
with no parent.
The getSVGDocument() method must run the following
- steps:
Let document be this element's content document.
Let document be this's content document.
If document is non-null and was created by the page
load processing model for XML files section because the
Let request be a new request whose
- URL is the resulting URL record,
- client is the element's node document's
+ Let request be a new request whose URL is the resulting URL record, client is the element's node document's
relevant settings object, destination is "
-
is "image", credentials mode is "initiator typeinput",
+ credentials mode is "include", and whose use-URL-credentials flag is set.
Fetch request, with - processResponseEndOfBody set to the following steps +
Fetch request, with + processResponseEndOfBody set to the following step given response response:
Finalize and report timing with response, the input
- element's node document's relevant global object, and
- "input".
If the download was successful and the image is
- available, queue an element task on the
- user interaction task source given the input element to
- fire an event named
- load at the input element; and otherwise, if the
- fetching process fails without a response from the remote server, or completes but the image is
- not a valid or supported image, queue an element task on the user interaction
- task source given the input element to
- fire an event named
- error on the input element.
If the download was successful and the image is available, queue an element task on the
+ user interaction task source given the input element to fire an event named load
+ at the input element.
Otherwise, if the fetching process fails without a response from the remote server, or
+ completes but the image is not a valid or supported image, then queue an element
+ task on the user interaction task source given the input
+ element to fire an event named error on the input element.
The target and
formtarget
- content attributes, if specified, must have values that are valid browsing context names or keywords.
In addition, when an element's autofill field name is "off", values are reset
- when traversing the history.
If form document's active sandboxing flag set has its sandboxed forms browsing context flag set, then return.
Let form browsing context be the browsing - context of form document.
If the submitted from submit() method flag
is not set, then:
@@ -57881,13 +57679,13 @@ fur
Let noopener be the result of getting an element's noopener with form and target.
Let target browsing context be the first return value of applying the - rules for choosing a browsing context using target, form browsing - context, and noopener.
Let targetNavigable be the first return value of applying the rules for + choosing a navigable given target, form's node + navigable, and noopener.
If target browsing context is null, then return.
If targetNavigable is null, then return.
Let historyHandling be "default".
Let historyHandling be "push".
If form document has not yet completely loaded, then set
historyHandling to "replace".
Each form element has a planned navigation, which is either null or a
task; when the form is first created, its
planned navigation must be set to null. In the behaviors described below, when the
- user agent is required to plan to navigate to a particular resource destination, it must run the following steps:
If destination is not a request, then - set destination to a new request whose URL is destination.
Let referrerPolicy be the empty string.
If the form element's link types include the noreferrer keyword, then set destination's referrer to "noreferrer keyword, then set referrerPolicy to "no-referrer".
If the form has a non-null planned navigation, remove it from
@@ -57964,10 +57761,13 @@ fur
Set the form's planned navigation to null.
Navigate target browsing context to
- destination, with historyHandling set to
- historyHandling and navigationType
- set to "form-submission".
Navigate targetNavigable to url
+ using the form element's node document, with historyHandling set to historyHandling, referrerPolicy set to referrerPolicy, documentResource set to postResource, and cspNavigationType set to "form-submission".
Assert: method is POST.
+Switch on enctype:
Set body to the result of encoding body using encoding.
-Let mimeType be `text/plain`.
Let mimeType be `text/plain`.
Plan to navigate to a new request whose
- URL is parsed action, method is method, header list is « (`Content-Type`, mimeType) », and body is body.
Plan to navigate to parsed action given a POST + resource whose request body is + body and request + content-type is mimeType.
Let topDocument be the active document of control's - node document's browsing context's - top-level browsing context.
Let topDocument be control's node navigable's top-level traversable's active + document.
If control's node document's origin is not the same @@ -64830,7 +64631,7 @@ try {
If normalizedRadii's size is 1, then set upperLeft, upperRight, lowerRight, and lowerLeft to - normalizedRadii[0].
Corner curves must not overlap. Scale all radii to prevent this:
@@ -71730,13 +71531,12 @@ Demos: pseudo-class, an element has the focus when:it is not itself a browsing context container; and
it is not itself a navigable container; and
at least one of the following is true:
it is one of the elements listed in the current focus chain of the top-level browsing context, - or
its shadow root shadowRoot is not null and shadowRoot is the root of at @@ -74737,7 +74537,7 @@ END:VCARD
tentativeconfirmedcancelledcanceledA single property with the name status may be present
@@ -75772,19 +75572,33 @@ END:VCARD
A top-level browsing context has a system visibility state,
- which is either "hidden" or "visible".
The system visibility state is determined by the user-agent, and - represents, for example, whether the browser window is minimized, a browser tab is currently in - the background, or a system element such as a task switcher obscures the page.
+A traversable navigable's system visibility state, including its + initial value upon creation, is determined by the user agent. It represents, for example, whether + the browser window is minimized, a browser tab is currently in the background, or a system + element such as a task switcher obscures the page.
When a user-agent determines that the system visibility state for
- top-level browsing context context has changed to newState,
- it must queue a task on the user interaction task source to
- update the visibility state of all the Document objects in the
- top-level browsing context's document family with
- newState.
Let navigables be the inclusive descendant navigables of + traversable.
For each navigable of navigables + in what order?:
+ +Let document be navigable's active + document.
Queue a global task on the user interaction task source given + document's relevant global object to update the visibility + state of document with newState.
A Document has a visibility state, which is
either "hidden" or "visible", initially set to
@@ -75969,28 +75783,27 @@ END:VCARD
When a user interaction in a browsing context B causes firing of an - activation triggering input event in B's active document - D, the user agent must perform the following activation notification steps - before dispatching the event:
+When a user interaction in a causes firing of an activation triggering input
+ event in a Document document, the user agent must perform the
+ following activation notification steps before dispatching the event:
Let browsingContexts be a list consisting of:
-B,
Assert: document is fully active.
all ancestor browsing contexts of - B, and
Let windows be « document's relevant global object + ».
all the descendant browsing - contexts of D that have active - documents from the same origin as that of D.
Extend windows with the active window of each of document's ancestor + navigables.
Let windows be the list of Window objects constructed by taking
- the active window of each item in browsingContexts.
Extend windows with the active window of each of document's descendant + navigables, filtered to include only those navigables + whose active document's origin is same origin with + document's origin.
For each window in windows, set
window's last activation timestamp to the current high resolution
@@ -76015,29 +75828,24 @@ END:VCARD
steps, given a Window W:
If W's browsing context is null, then +
If W's navigable is null, then return.
Let top be W's browsing context's - top-level browsing context.
Let top be W's navigable's + top-level traversable.
Let browsingContexts be the list of the descendant browsing - contexts of top's active document.
Append top to - browsingContexts.
Let navigables be the inclusive descendant navigables of + top's active document.
Let windows be the list of Window objects constructed by taking
- the active window of each item in browsingContexts.
For each window in windows, if window's last activation timestamp is not positive infinity, then set window's last activation timestamp to negative infinity.
The spec is not clear about how to traverse a tree of documents. See issue #5020.
-Note the asymmetry in the sets of browsing contexts in the page that are affected by an activation notification vs an activation consumption: an activation consumption @@ -76230,9 +76038,10 @@ partial interface {
A top-level browsing context has system focus when it can receive keyboard input channeled - from the operating system.
+A top-level traversable has system focus when it can receive keyboard input channeled from the operating + system, possibly targeted at one of its active document's + descendant navigables.
System focus is lost when a browser window loses focus, but might also be lost to other system widgets in the browser window such as a URL bar.
@@ -76365,12 +76174,12 @@ partial interface { -A browsing context container (e.g. an
- iframe) is a focusable area, but key events routed to a browsing
- context container get immediately routed to its nested browsing context's
- active document. Similarly, in sequential focus navigation a browsing context
- container essentially acts merely as a placeholder for its nested browsing
- context's active document.
A navigable container (e.g. an
+ iframe) is a focusable area, but key events routed to a navigable
+ container get immediately routed to its nested navigable's active document. Similarly, in sequential focus navigation a
+ navigable container essentially acts merely as a placeholder for its nested
+ navigable's active document.
The currently focused area of a top-level browsing context topLevelBC at - any particular time is the focusable area-or-null returned by this algorithm:
+The currently focused area of + a top-level traversable traversable is the focusable area-or-null + returned by this algorithm:
If topLevelBC does not have system - focus, then return null.
If traversable does not have system focus, then return + null.
Let candidate be topLevelBC's active document.
Let candidate be traversable's active + document.
While candidate's focused - area is a browsing context container with a non-null nested browsing - context: set candidate to the active document of that - browsing context container's nested browsing context.
If candidate's focused area is non-null, set candidate to candidate's Navigator {
Return candidate.
The current focus chain of a top-level browsing context topLevelBC at any - particular time is the focus chain of the currently focused area of topLevelBC, if - topLevelBC is non-null, or an empty list otherwise.
+The current focus chain of a + top-level traversable traversable is the focus chain of the currently focused area of + traversable, if traversable is non-null, or an empty list otherwise.
-An element that is the DOM anchor of a focusable area is said to gain focus when that focusable area becomes the - currently focused area of a top-level browsing context. When an element is the - DOM anchor of a focusable area of the currently focused area of a - top-level browsing context, it is focused.
+An element that is the DOM anchor of a focusable area is said to + gain focus when that focusable area becomes the + currently focused area of a top-level traversable. When an element is the DOM + anchor of a focusable area of the currently focused area of a top-level + traversable, it is focused.
Otherwise, if currentObject is a Document whose browsing context is a child browsing context,
- then set currentObject to currentObject's browsing context's container.
Otherwise, if currentObject is a Document whose node
+ navigable's parent is non-null, then set
+ currentObject to currentObject's node navigable's parent.
Otherwise, break.
@@ -76461,8 +76271,8 @@ partial interface {Return output.
The chain starts with subject and (if subject is or can be
- the currently focused area of a top-level browsing context) continues up the focus
- hierarchy up to the Document of the top-level browsing context.
Document of the top-level traversable.
@@ -76721,7 +76531,7 @@ partial interface {
To get the focusable area for a focus target that is either an element
- that is not a focusable area, or is a browsing context, given an
+ that is not a focusable area, or is a navigable, given an
optional string focus trigger (default "other"), run the first
matching set of steps from the following list:
Return the Document's viewport.
Return the browsing context's active document.
Return the navigable's active + document.
Return the browsing context container's nested browsing - context's active document.
Return the navigable container's nested navigable's active document.
If focus target is a shadow-including inclusive ancestor of the - currently focused area of a top-level browsing context's DOM anchor, - then return null.
Return the focus delegate for focus target given focus trigger.
The focusing steps for an object new focus target that is either a focusable area, or an element that is not a focusable area, or a - browsing context, are as follows. They can optionally be run with a fallback + navigable, are as follows. They can optionally be run with a fallback target and a string focus trigger.
If new focus target is a browsing context container with non-null - nested browsing context, then set new focus target to the nested - browsing context's active document.
If new focus target is a navigable container with non-null + nested navigable, then set new focus target to the nested + navigable's active document.
If new focus target is a focusable area and its DOM anchor is inert, then return.
If new focus target is the currently focused area of a - top-level browsing context, then return.
If new focus target is the currently focused area of a top-level + traversable, then return.
Let old chain be the current focus chain of the top-level browsing context in which new focus
+ Let old chain be the current focus chain of the top-level traversable in which new focus
target finds itself. Let new chain be the focus chain of new
focus target. Run the focus update steps with old chain, new chain, and new focus target respectively. Run the focus update steps with old chain, new chain,
+ and new focus target respectively.
User agents must immediately run the focusing steps for a - focusable area or browsing context candidate whenever the + focusable area or navigable candidate whenever the user attempts to move the focus to candidate.
The unfocusing steps for an object old focus target that is @@ -77018,22 +76830,19 @@ partial interface { data-x="concept-element-shadow-root">shadow root's delegates focus is true, and old focus target's shadow root is a shadow-including inclusive ancestor of the currently focused area of a - top-level browsing context's DOM anchor, then set old focus - target to that currently focused area of a top-level browsing - context.
+ top-level traversable's DOM anchor, then set old focus target to + that currently focused area of a top-level traversable.If old focus target is inert, then return.
If old focus target is an area element and one of its shapes is the
- currently focused area of a top-level browsing context, or, if old focus
- target is an element with one or more scrollable regions, and one of them is the
- currently focused area of a top-level browsing context, then let old focus
- target be that currently focused area of a top-level browsing context.
If old focus target is an area element and one of its shapes is
+ the currently focused area of a top-level traversable, or, if old focus
+ target is an element with one or more scrollable regions, and one of them is the
+ currently focused area of a top-level traversable, then let old focus
+ target be that currently focused area of a top-level traversable.
Let old chain be the current focus chain of the top-level browsing context in which old focus
+ Let old chain be the current focus chain of the top-level traversable in which old focus
target finds itself. If old focus target is not one of the entries in old
@@ -77044,24 +76853,22 @@ partial interface {
Let topDocument be old chain's last entry. If topDocument's browsing context has
- system focus, then run the focusing steps
- for topDocument's viewport. If topDocument's node navigable has system focus, then
+ run the focusing steps for topDocument's viewport. Otherwise, apply any relevant platform-specific conventions for removing system focus from topDocument's browsing context, and run the focus update
- steps with old chain, an empty list, and null respectively. Otherwise, apply any relevant platform-specific conventions for removing system
+ focus from topDocument's node navigable, and run the focus
+ update steps given old chain, an empty list, and null. When the currently focused area of a top-level browsing context is somehow
- unfocused without another element being explicitly focused in its stead, the user agent must
+ When the currently focused area of a top-level traversable is somehow unfocused
+ without another element being explicitly focused in its stead, the user agent must
immediately run the unfocusing steps for that object. The unfocusing steps do not always result in the focus changing, even
- when applied to the currently focused area of a top-level browsing context. For
- example, if the currently focused area of a top-level browsing context is a
+ The unfocusing steps do not always result in the focus changing,
+ even when applied to the currently focused area of a top-level traversable. For
+ example, if the currently focused area of a top-level traversable is a
viewport, then it will usually keep its focus regardless until another
focusable area is explicitly focused with the focusing steps. When a key event is to be routed in a top-level browsing context, the user agent
- must run the following steps: When a key event is to be routed in a top-level traversable, the user agent must
+ run the following steps: Let target area be the currently focused area of the top-level browsing
- context. Let target area be the currently focused area of the top-level traversable. Assert: target area is not null, since key events are only routed
- to top-level browsing contexts that have system focus. Therefore, target area is a
- focusable area. Let target node be target area's DOM anchor.
-
-
If target's browsing context's - top-level browsing context does not have system focus, then return false.
If target's node navigable's top-level + traversable does not have system focus, then return false.
Let candidate be target's browsing context's top-level browsing context's - active document.
Let candidate be target's node navigable's top-level traversable's active document.
While true:
@@ -77254,9 +77057,10 @@ partial interface {If candidate is target, then return true.
If the focused area of - candidate is a browsing context container with a non-null nested - browsing context, then set candidate to the active document of - that browsing context container's nested browsing context.
Otherwise, return false.
When the user requests that focus move from the currently focused area of a top-level - browsing context to the next or previous focusable area (e.g. as the default action - of pressing the tab key), or when the user requests that focus sequentially move to a - top-level browsing context in the first place (e.g. from the browser's location bar), - the user agent must use the following algorithm:
+ traversable to the next or previous focusable area (e.g. as the default + action of pressing the tab key), or when the user requests that focus + sequentially move to a top-level traversable in the first place (e.g. from the + browser's location bar), the user agent must use the following algorithm:Let starting point be the currently focused area of a top-level - browsing context, if the user requested to move focus sequentially from there, or else the - top-level browsing context itself, if the user instead requested to move focus from - outside the top-level browsing context.
If there is a sequential focus navigation starting point defined and it is
inside starting point, then let starting point be the sequential
@@ -77316,7 +77120,7 @@ partial interface {
Loop: Let selection mechanism be sequential if the starting
- point is a browsing context or if starting point is in its
+ point is a navigable or if starting point is in its
Otherwise, starting point is not in its Otherwise, unset the sequential focus navigation starting point. If starting point is the top-level browsing context, or a
- focusable area in the top-level browsing context, the user agent
+ If starting point is a top-level traversable, or a
+ focusable area in the top-level traversable, the user agent
should transfer focus to its own controls appropriately (if any), honouring
direction, and then return.Document's sequential focus navigation order.Document's
@@ -77334,8 +77138,8 @@ partial interface {
If the user agent has no sequentially focusable controls — a kiosk-mode - browser, for instance — then the user agent may instead restart these steps with the - starting point being the top-level browsing context itself.
+ browser, for instance — then the user agent may instead restart these steps with the + starting point being the top-level traversable itself. -Otherwise, starting point is a focusable area in a child - browsing context. Set starting point to that child browsing - context's container and return to the step labeled - loop.
Returns the deepest element in the document through which or to which key events are being routed. This is, roughly speaking, the focused element in the document.
-For the purposes of this API, when a child browsing context is focused, its
- container is focused
- in the parent browsing context. For example, if the user moves the focus to a text
- control in an iframe, the iframe is the element returned by the For the purposes of this API, when a child navigable is focused, its container is focused
+ within its parent's active
+ document. For example, if the user moves the focus to a text control in an
+ iframe, the iframe is the element returned by the activeElement API in the
iframe's node document.
Moves the focus to the window's browsing context, if any.
+Moves the focus to the window's navigable, if any.
Origins are the fundamental currency of the web's security model. Two actors in the web + platform that share an origin are assumed to trust each other and to have the same authority. + Actors with differing origins are considered potentially hostile versus each other, and are + isolated from each other to varying degrees.
-A browsing context is an environment in which Document objects
- are presented to the user.
For example, if Example Bank's web site, hosted at bank.example.com, tries to examine the DOM of Example Charity's web site, hosted
+ at charity.example.org, a "SecurityError"
+ DOMException will be raised.
A tab or window in a web browser typically contains a browsing
- context, as does an iframe or frames in a
- frameset.
A browsing context has a corresponding WindowProxy object.
An origin is one of the following:
-A browsing context has an opener browsing context, which is null - or a browsing context. It is initially null.
+An internal value, with no serialization it can be recreated from (it is serialized as
+ "null" per serialization of an origin), for which the only
+ meaningful operation is testing for equality.
A browsing context has a disowned boolean. It - is initially false.
+A tuple consists of: -
A browsing context has an is closing boolean. It is initially - false.
+The following example illustrates the various possibilities of a browsing context. - It can be disowned, is closing, neither, or both.
+Origins can be shared, e.g., among multiple
+ Document objects. Furthermore, origins are generally
+ immutable. Only the domain of a tuple origin can be changed, and only through the document.domain API.
// Neither disowned nor is closing:
-const popup1 = window.open();
+
-// Disowned, but not is closing:
-const popup2 = window.open();
-popup2.opener = null;
+ The effective domain of an
+ origin origin is computed as follows:
-// Not disowned, but is closing:
-const popup3 = window.open();
-popup3.close();
+
+ If origin is an opaque origin,
+ then return null.
+ If origin's domain is non-null,
+ then return origin's domain.
A browsing context has a session history, which lists the
- Document objects that the browsing context has presented, is presenting,
- or will present. A Document's browsing context is the browsing
- context whose session history contains the Document, if any such
- browsing context exists and has not been discarded, and null otherwise.
+ Return origin's host.
A Document does not necessarily have a non-null browsing context. In particular, data mining tools are likely
- to never instantiate browsing contexts. A Document created using an API such as createDocument() never has a non-null browsing context. And the Document originally
- created for an iframe element, which has since been removed from the document, has no associated browsing context, since that
- browsing context was discarded.
+ The serialization of an origin is the string obtained
+ by applying the following algorithm to the given origin origin:
- A browsing context's active window is its
- WindowProxy object's [[Window]]
- internal slot value. A browsing context's active document is its
- active window's associated
- Document.
+
+ If origin is an opaque origin,
+ then return "null".
In general, there is a 1-to-1 mapping from the Window object to the
- Document object, as long as the Document object has a non-null browsing context. There is one exception. A
- Window can be reused for the presentation of a second Document in the
- same browsing context, such that the mapping is then 1-to-2. This occurs when a
- browsing context is navigated from the initial about:blank Document to
- another, with historyHandling set to "replace".
+ Otherwise, let result be origin's scheme.
A browsing context has a virtual
- browsing context group ID integer. It is initially 0. This is used by cross-origin opener policy reporting, to keep track
- of the browsing context group switches that would have happened if the report-only policy had been
- enforced.
+ Append "://" to result.
A browsing context has an initial
- URL, which is a URL or null. It is initially null.
+ Append origin's host, serialized, to result.
A browsing context has an opener origin at
- creation, which is an origin or null. It is initially null.
+ If origin's port is non-null, append
+ a U+003A COLON character (:), and origin's port, serialized,
+ to result.
Creating browsing contexts
+ Return result.
- To set the active document of a browsing context
- browsingContext to a Document object document, run these
- steps:
+ Let window be document's relevant global - object.
The serialization of ("https", "xn--maraa-rta.example", null, null) is "https://xn--maraa-rta.example".
Set document's visibility state to browsingContext's - top-level browsing context's system visibility state.
Set browsingContext's active window to window.
There used to also be a + Unicode serialization of an origin. However, it was never widely adopted.
-Set window's associated
- Document to document.
Set window's relevant settings object's execution ready flag.
Two origins, A and B, are said to be same origin if the following algorithm returns true:
-If A and B are the same opaque + origin, then return true.
A browsing context has an associated creator origin (null or returns an - origin), creator URL (null or returns a URL), and creator - base URL (null or returns a URL). These are all initially null.
+If A and B are both tuple + origins and their schemes, hosts, and port + are identical, then return true.
Return false.
To determine the origin, given browsing - context browsingContext, URL url, sandboxing flag - set sandboxFlags, and an origin invocationOrigin:
+Two origins, A and B, are said to be same origin-domain if the following algorithm returns true:
If sandboxFlags has its sandboxed origin browsing - context flag set, then return a new opaque - origin.
If url is null, then return a new opaque - origin.
If A and B are the same opaque + origin, then return true.
If invocationOrigin is non-null and url matches
- about:blank, then return invocationOrigin.
If A and B are both tuple + origins, run these substeps:
-The result here is that two documents end up with the same underlying
- origin, meaning that document.domain
- affects both.
If A and B's schemes + are identical, and their domains are identical and + non-null, then return true.
If url is about:srcdoc, then return the origin of browsingContext's container document.
Otherwise, if A and B are same origin and their + domains are identical and null, then return + true.
Return url's origin.
Return false.
To create a new browsing context, given
- null or a Document object creator, null or an element embedder,
- and a browsing context group group, run these steps:
The following table shows examples of when two tuple + origins are same origin and same + origin-domain.
-Let browsingContext be a new browsing context.
| A + | B + | same origin + | same origin-domain + |
|---|---|---|---|
("https", "example.org", null, null)
+ | ("https", "example.org", null, null)
+ | ✅ + | ✅ + |
("https", "example.org", 314, null)
+ | ("https", "example.org", 420, null)
+ | ❌ + | ❌ + |
("https", "example.org", 314, "example.org")
+ | ("https", "example.org", 420, "example.org")
+ | ❌ + | ✅ + |
("https", "example.org", null, null)
+ | ("https", "example.org", null, "example.org")
+ | ✅ + | ❌ + |
("https", "example.org", null, "example.org")
+ | ("http", "example.org", null, "example.org")
+ | ❌ + | ❌ + |
Let unsafeContextCreationTime be the - unsafe shared current time.
If creator is non-null, then set - browsingContext's creator origin to return creator's origin, browsingContext's creator - URL to return creator's URL, - browsingContext's creator base URL to return creator's base URL, and browsingContext's virtual browsing context group ID to - creator's top-level browsing context's virtual browsing context group ID.
Let sandboxFlags be the result of determining the creation sandboxing - flags given browsingContext and embedder.
A scheme-and-host is a tuple of a scheme (an ASCII string) and a host (a host).
- -Let origin be the result of determining the
- origin given browsingContext, about:blank,
- sandboxFlags, and browsingContext's creator origin.
A site is an opaque origin or a + scheme-and-host.
-Let permissionsPolicy be the result of creating a permissions policy - given browsingContext and origin.
+This needs to use embedder.
- +To obtain a site, given an origin origin, run these steps:
-Let agent be the result of obtaining a similar-origin window agent given - origin, group, and false.
If origin is an opaque origin, + then return origin.
Let realm execution context be the result of creating a new realm - given agent and the following customizations:
+If origin's host's registrable + domain is null, then return (origin's scheme, origin's host).
For the global object, create a new Window object.
Return (origin's scheme, + origin's host's registrable + domain).
For the global this binding, use browsingContext's
- WindowProxy object.
Two sites, A and B, are said to be same site if the following algorithm + returns true:
-Let topLevelCreationURL be about:blank if embedder is
- null; otherwise embedder's relevant settings object's top-level
- creation URL.
If A and B are the same opaque + origin, the return true.
Let topLevelOrigin be origin if embedder is null; - otherwise embedder's relevant settings object's top-level - origin.
If A or B is an opaque + origin, then return false.
Set up a window environment settings object with about:blank,
- realm execution context, null, topLevelCreationURL, and
- topLevelOrigin.
If A's and B's scheme values are different, then return + false.
Let loadTimingInfo be a new document load timing info with - its navigation start time set to the result of calling coarsen time - with unsafeContextCreationTime and the new environment settings object's - cross-origin isolated - capability.
If A's and B's host values are not equal, then return false.
Let coop be a new cross-origin opener policy.
Return true.
If creator is non-null and creator's origin is same origin with - creator's relevant settings object's top-level origin, then - set coop to creator's browsing - context's top-level browsing context's active document's cross-origin opener policy.
Let document be a new Document, marked as an HTML document in quirks mode, whose content type is "text/html",
- origin is origin, active
- sandboxing flag set is sandboxFlags, permissions policy is
- permissionsPolicy, cross-origin opener
- policy is coop, load timing info is
- loadTimingInfo, navigation id is
- null, and which is ready for post-load tasks.
The serialization of a site is the string obtained by applying the following + algorithm to the given site site:
-Assert: document's URL
- and document's relevant settings object's creation URL are
- about:blank.
If site is an opaque origin, then
+ return "null".
Set document's is initial about:blank to
- true.
Let result be site[0].
Ensure that document has a single child html node, which itself
- has two empty child nodes: a head element, and a body element.
Append "://" to result.
Set the active document of browsingContext to - document.
Append site[1], serialized, to + result.
If browsingContext's creator URL is non-null, then set - document's referrer to the serialization of it.
Return result.
If creator is non-null, then set document's policy container to a clone of creator's policy container.
It needs to be clear from context that the serialized value is a site, not an
+ origin, as there is not necessarily a syntactic difference between the two. For example, the
+ origin ("https", "shop.example", null, null) and
+ the site ("https", "shop.example") have the same
+ serialization: "https://shop.example".
Append a new session history entry to browsingContext's
- session history whose URL is about:blank
- and document is document.
Two origins, A and B, are said to be schemelessly same site if the following algorithm returns true:
-Completely finish loading document.
If A and B are the same opaque + origin, then return true.
Return browsingContext.
If A and B are both tuple + origins, then:
-To create a new top-level browsing - context:
+Let hostA be A's host, + and let hostB be B's host.
Let group be the result of creating a new browsing context - group.
If hostA equals hostB and + hostA's registrable domain is null, then return true.
Return group's browsing context set[0].
If hostA's registrable domain equals hostB's registrable domain and is non-null, then + return true.
This creates a top-level browsing context.
+Return false.
To create a new auxiliary browsing - context, given a browsing context opener:
+Two origins, A and B, are said to be same site if the following algorithm returns true:
Let group be opener's top-level browsing context's - group
Let siteA be the result of obtaining a + site given A.
Assert: group is non-null, as navigating invokes this directly.
Let siteB be the result of obtaining a + site given B.
Let browsingContext be the result of creating a new browsing - context with opener's active document, null, and - group.
If siteA is same site with + siteB, then return true.
Append browsingContext to - group.
Return false.
Set browsingContext's opener browsing context to - opener.
Set browsingContext's virtual - browsing context group ID to opener's top-level browsing context's - virtual browsing context group - ID.
Unlike the same origin and same origin-domain concepts, + for schemelessly same site and same site, the port and domain + components are ignored.
-Set browsingContext's opener origin at - creation to opener's active document's origin.
For the reasons explained in URL, the + same site and schemelessly same site concepts should be avoided when + possible, in favor of same origin checks.
-Legacy-clone a browsing session storage shed with - opener's browsing session and - browsingContext's browsing session.
The following table shows examples of when two tuple + origins are schemelessly same site and same + site.
-Return browsingContext.
Given that wildlife.museum, museum, and com are public suffixes and that example.com is not:
This creates a top-level browsing context that is also an - auxiliary browsing context.
+| A + | B + | schemelessly same site + | same site + |
|---|---|---|---|
("https", "example.com")
+ | ("https", "sub.example.com")
+ | ✅ + | ✅ + |
("https", "example.com")
+ | ("https", "sub.other.example.com")
+ | ✅ + | ✅ + |
("https", "example.com")
+ | ("http", "non-secure.example.com")
+ | ✅ + | ❌ + |
("https", "r.wildlife.museum")
+ | ("https", "sub.r.wildlife.museum")
+ | ✅ + | ✅ + |
("https", "r.wildlife.museum")
+ | ("https", "sub.other.r.wildlife.museum")
+ | ✅ + | ✅ + |
("https", "r.wildlife.museum")
+ | ("https", "other.wildlife.museum")
+ | ❌ + | ❌ + |
("https", "r.wildlife.museum")
+ | ("https", "wildlife.museum")
+ | ❌ + | ❌ + |
("https", "wildlife.museum")
+ | ("https", "wildlife.museum")
+ | ✅ + | ✅ + |
("https", "example.com")
+ | ("https", "example.com.")
+ | ❌ + | ❌ + |
To create a new nested browsing context, - given an element element:
+(Here we have omitted the port and domain components since they are not considered.)
+Let group be element's node document's browsing context's top-level browsing context's - group.
Let browsingContext be the result of creating a new browsing - context with element's node document, element, and - group.
Set element's nested browsing context to - browsingContext.
document.domain [ = domain ]If element has a name attribute, then set
- browsingContext's name to the value of
- this attribute.
Returns the current domain used for security checks.
-Can be set to a value that removes subdomains, to change the origin's domain to allow pages on other subdomains of the same + domain (if they do the same thing) to access each other. This enables pages on different hosts + of a domain to synchronously access each other's DOMs.
+In sandboxed iframes, Documents with opaque origins, Documents without a browsing context, and when the "document-domain" feature is disabled, the setter will
+ throw a "SecurityError" exception. In cases where crossOriginIsolated or originAgentCluster return true, the setter will do
+ nothing.
Avoid using the document.domain setter. It
+ undermines the security protections provided by the same-origin policy. This is especially acute
+ when using shared hosting; for example, if an untrusted third party is able to host an HTTP
+ server at the same IP address but on a different port, then the same-origin protection that
+ normally protects two different sites on the same host will fail, as the ports are ignored when
+ comparing origins after the document.domain setter has
+ been used.
Certain elements (for example, iframe elements) can instantiate further browsing contexts. These elements are called browsing context
- containers.
Because of these security pitfalls, this feature is in the process of being removed from the + web platform. (This is a long process that takes many years.)
-Each browsing context container has a nested browsing context, - which is either a browsing context or null. It is initially null.
+Instead, use postMessage() or
+ MessageChannel objects to communicate across origins in a safe manner.
The container of a browsing context bc - is the browsing context container whose nested browsing context is - bc, or null if there is no such element.
+Each browsing context bc has a container document, which is the result of running these - steps:
+The domain
+ getter steps are:
If bc's container is null, then return - null.
Let effectiveDomain be this's origin's effective domain. -
Return bc's container's node - document.
+If effectiveDomain is null, then return the empty string.
This is equal to bc's container's - shadow-including root as bc's container has to be connected.
- +Return effectiveDomain, serialized.
A browsing context child is said to be a child browsing - context of another browsing context parent, if child's - container document is non-null and child's - container document's browsing context is parent.
+The domain setter steps are:
A browsing context child is a document-tree child browsing - context of parent if child is a child browsing context - and child's container is in a document - tree.
+If this's browsing context is
+ null, then throw a "SecurityError" DOMException.
A browsing context child may have a parent browsing - context. This is the unique browsing context that has child as a - child browsing context, if any such browsing context exists. Otherwise, the - browsing context has no parent browsing context.
+If this's active sandboxing flag set has its sandboxed
+ document.domain browsing context flag set, then
+ throw a "SecurityError" DOMException.
A browsing context A is said to be an ancestor of a browsing context - B if there exists a browsing context A' that is a child browsing - context of A and that is itself an ancestor of B, or if the browsing context A is the - parent browsing context of B.
+If this is not allowed to use the "document-domain" feature, then throw a
+ "SecurityError" DOMException.
A browsing context that has no parent browsing context is the top-level browsing context for itself and all of the browsing contexts for which it - is an ancestor browsing context.
+Let effectiveDomain be this's origin's effective domain. -
If effectiveDomain is null, then throw a
+ "SecurityError" DOMException.
A top-level browsing context has an associated group (null or a browsing context group). It is initially null.
+If the given value is not
+ a registrable domain suffix of and is not equal to effectiveDomain, then throw
+ a "SecurityError" DOMException.
A top-level browsing context has an is popup boolean. It is initially - false.
+If the surrounding agent's agent cluster's is + origin-keyed is true, then return.
The only mandatory impact in this specification of is popup is on the
- visible getter of the relevant BarProp
- objects. However, user agents might also use it in the following ways:
Set this's origin's domain to the result of parsing the given value.
To determine if a string hostSuffixString is a + registrable domain suffix of or is equal to a host + originalHost, run these steps:
+ -If hostSuffixString is the empty string, then return false.
In both cases user agents might additionally incorporate user preferences, or present a choice - as to whether to go down the popup route.
+Let hostSuffix be the result of parsing + hostSuffixString.
User agents that provides a minimal web browser user interface for such popups are encouraged - to not hide the browser's location bar.
-If hostSuffix is failure, then return false.
If hostSuffix does not equal + originalHost, then:
-It is possible to create new browsing contexts that are related to a top-level browsing - context while their container is null. Such browsing - contexts are called auxiliary browsing contexts. Auxiliary browsing contexts are always top-level browsing contexts.
+If hostSuffix or originalHost is not a domain, then return false.
-The transitive closure of parent browsing - contexts for a browsing context that is a child browsing context - gives the list of ancestor browsing contexts.
+This excludes hosts that are IP addresses.
+The list of the descendant browsing contexts of a Document d
- is the (ordered) list returned by the following algorithm:
If hostSuffix, prefixed by U+002E (.), does not match the end of + originalHost, then return false.
Let list be an empty list.
If one of the following is true
-For each browsing context container container, whose nested - browsing context is non-null and whose shadow-including root is - d, in shadow-including tree order:
+hostSuffix equals + hostSuffix's public suffix
Let nestedBC be container's nested browsing - context.
hostSuffix, prefixed by U+002E (.), matches the end + originalHost's public suffix
Append nestedBC to - list.
Extend list with the list of the - descendant browsing contexts of nestedBC's active - document.
Assert: originalHost's public suffix, prefixed by + U+002E (.), matches the end of hostSuffix.
Return list.
Return true.
A Document d is said to be fully
- active when d's browsing context is
- non-null, d's browsing context's active
- document is d, and either d's browsing context is a top-level browsing context,
- or d's browsing context's container document is fully active.
Because they are associated with an element, child
- browsing contexts are always tied to a specific Document in their parent
- browsing context. User agents must not allow the user to interact with child browsing contexts of elements that are in Documents
- that are not themselves fully active.
The following example illustrates the differences between active and fully active Document objects. Here a.html is loaded into a browser window, b-1.html starts
- out loaded into an iframe as shown, and b-2.html and c.html are omitted (they can simply be an empty document).
<!-- a.html -->
-<!DOCTYPE html>
-<html lang="en">
-<title>Browsing context A</title>
-
-<iframe src="b-1.html"></iframe>
-<button onclick="frames[0].location.href = 'b-2.html'">Click me</button>
-
-<!-- b-1.html -->
-<!DOCTYPE html>
-<html lang="en">
-<title>Browsing context B</title>
-
-<iframe src="c.html"></iframe>At this point, the documents given by a.html, b-1.html, and c.html are all the active documents of their respective browsing
- contexts. They are also all fully active.
After clicking on the button, and thus loading a new Document from
- b-2.html into browsing context B, we have the following results:
The a.html Document remains both the active
- document of browsing context A, and fully active.
The b-1.html Document is now not the
- active document of browsing context B. As such it is also not fully
- active.
| hostSuffixString | +originalHost | +Outcome of is a registrable domain suffix of or is equal to | +Notes | +
|---|---|---|---|
"0.0.0.0" |
+ 0.0.0.0 |
+ ✅ | ++ |
"0x10203" |
+ 0.1.2.3 |
+ ✅ | ++ |
"[0::1]" |
+ ::1 |
+ ✅ | ++ |
"example.com" |
+ example.com |
+ ✅ | ++ |
"example.com" |
+ example.com. |
+ ❌ | +Trailing dot is significant. | +
"example.com." |
+ example.com |
+ ❌ | +|
"example.com" |
+ www.example.com |
+ ✅ | ++ |
"com" |
+ example.com |
+ ❌ | +At the time of writing, com is a public suffix. |
+
"example" |
+ example |
+ ✅ | ++ |
"compute.amazonaws.com" |
+ example.compute.amazonaws.com |
+ ❌ | +At the time of writing, *.compute.amazonaws.com is a public suffix. |
+
"example.compute.amazonaws.com" |
+ www.example.compute.amazonaws.com |
+ ❌ | +|
"amazonaws.com" |
+ www.example.compute.amazonaws.com |
+ ❌ | +|
"amazonaws.com" |
+ test.amazonaws.com |
+ ✅ | +At the time of writing, amazonaws.com is a registrable domain. |
+
The new b-2.html Document is now the active
- document of browsing context B, and is also fully active.
The c.html Document is still the active
- document of browsing context C. However, since C's container document is the b-1.html
- Document, which is itself not fully active, this means the c.html Document is now not fully active (even though
- it is active).
For more explorations of the complexities involved here, especially as it impacts the session history, see A Model of Navigation History.
-A child browsing context can be put into a delaying load events mode. This is used when it is navigated, to delay the load event of its
- container before the new Document is created.
window.originAgentClusterThe document family of a browsing context consists of the union of all
- the Document objects in that browsing context's session
- history and the document families of all those
- Document objects. The document family of a Document object
- consists of the union of all the document families of the
- browsing contexts in the list of the descendant
- browsing contexts of the Document object.
Returns true if this Window belongs to an agent cluster which is
+ origin-keyed, in the manner described in
+ this section.
The content document of a browsing - context container container is the result of the following algorithm:
+A Document delivered over a secure context can request that it be
+ placed in an origin-keyed agent
+ cluster, by using the `Origin-Agent-Cluster` HTTP
+ response header. This header is a structured header
+ whose value must be a boolean.
If container's nested browsing context is null, then return - null.
Per the processing model in the create
+ and initialize a new Document object, valuesValues
+ that are not the structured header boolean
+ true value (i.e., `?1`) will be ignored.
Let context be container's nested browsing - context.
The consequences of using this header are that the resulting
+ Document's agent cluster key is its origin, instead of the corresponding site. In terms of observable effects, this means that
+ attempting to relax the same-origin
+ restriction using document.domain will instead do
+ nothing, and it will not be possible to send WebAssembly.Module objects to
+ cross-origin Documents (even if they are same site). Behind the scenes,
+ this isolation can allow user agents to allocate implementation-specific resources corresponding
+ to agent clusters, such as processes or threads, more
+ efficiently.
Note that within a browsing context group, the
+ `Origin-Agent-Cluster` header can never cause same-origin Document
+ objects to end up in different agent clusters, even if one
+ sends the header and the other doesn't. This is prevented by means of the
+ historical agent cluster key map.
Let document be context's active document.
This means that the originAgentCluster getter can return false, even if the
+ header is set, if the header was omitted on a previously-loaded same-origin page in the same
+ browsing context group. Similarly, it can return true even when the header is not
+ set.
If document's origin and - container's node document's origin are not same origin-domain, then - return null.
The originAgentCluster getter steps are to return the
+ surrounding agent's agent cluster's is origin-keyed.
Return document.
Documents with an opaque
+ origin can be considered unconditionally origin-keyed; for them the header has no effect,
+ and the originAgentCluster getter will always return
+ true.
Similarly, Documents whose agent cluster's cross-origin isolation mode is not "none" are automatically origin-keyed. The
+ `Origin-Agent-Cluster` header might be useful as an additional hint to
+ implementations about resource allocation, since the `Cross-Origin-Opener-Policy`
+ and `Cross-Origin-Embedder-Policy` headers used to achieve cross-origin isolation
+ are more about ensuring that everything in the same address space opts in to being there. But
+ adding it would have no additional observable effects on author code.
window.topReturns the WindowProxy for the top-level browsing
- context.
window.opener [ = value ]Returns the WindowProxy for the opener browsing context.
A cross-origin opener policy value allows a document which is navigated to in a + top-level browsing context to force the creation of a new top-level browsing + context, and a corresponding group. The possible values + are:
-Returns null if there isn't one or if it has been set to null.
+unsafe-none"This is the (current) default and means that the document will occupy the same + top-level browsing context as its predecessor, unless that document specified a + different cross-origin opener policy.
Can be set to null.
-same-origin-allow-popups"This forces the creation of a new top-level browsing context for the + document, unless its predecessor specified the same cross-origin opener policy and + they are same origin.
window.parentReturns the WindowProxy for the parent browsing
- context.
same-origin"This behaves the same as "same-origin-allow-popups", with the addition that
+ any auxiliary browsing context created needs to contain same origin
+ documents that also have the same cross-origin opener policy or it will appear
+ closed to the opener.
window.frameElementsame-origin-plus-COEP"Returns the Element for the browsing context container.
This behaves the same as "same-origin", with the
+ addition that it sets the (new) top-level browsing context's group's cross-origin isolation
+ mode to one of "logical" or "concrete".
Returns null if there isn't one, and in cross-origin situations.
+"same-origin-plus-COEP" cannot
+ be directly set via the `Cross-Origin-Opener-Policy` header, but results from a
+ combination of setting both `Cross-Origin-Opener-Policy: same-origin` and a
+ `Cross-Origin-Embedder-Policy` header whose value is compatible with
+ cross-origin isolation together.
The top attribute's getter must
- run these steps:
If this Window object's browsing context is
- null, then return null.
Return this Window object's browsing
- context's top-level browsing context's WindowProxy
- object.
A cross-origin opener policy consists of:
-The opener getter steps
- are:
A value, which is a cross-origin opener policy value, initially "unsafe-none".
Let current be this's browsing - context.
A reporting endpoint, which is string or + null, initially null.
If current is null, then return null.
A report-only value, which is a cross-origin opener policy value, initially
+ "unsafe-none".
If current's disowned is true, then return null.
A report-only reporting endpoint, + which is a string or null, initially null.
If current's opener browsing context is null, then return - null.
To match cross-origin opener policy values, given a + cross-origin opener policy value A, an origin + originA, a cross-origin opener policy value B, and an + origin originB:
-Return current's opener browsing context's
- WindowProxy object.
If A is "unsafe-none" and B
+ is "unsafe-none", then return true.
The opener setter steps are:
If A is "unsafe-none" or B
+ is "unsafe-none", then return false.
If the given value is null and this's browsing - context is non-null, then set this's browsing - context's disowned to true.
If A is B and originA is same origin with + originB, then return true.
If the given value is non-null, then return ?
- OrdinaryDefineOwnProperty(this, "opener", {
- [[Value]]: the given value, [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true
- }).
Return false.
If a browsing context's disowned is true, its window.opener attribute is null. That prevents scripts in the
- browsing context from changing any properties of its opener browsing
- context's Window object (i.e., the Window object from which the
- browsing context was created).
Otherwise, if a browsing context's disowned is false, then scripts
- in that browsing context can use window.opener to
- change properties of its opener browsing context's Window object. For
- example, a script running in the browsing context can change the value of window.opener.location, causing the opener browsing context to
- navigate to a completely different document.
The parent attribute's
- getter must run these steps:
Let current be this Window object's browsing context.
If current is null, then return null.
A Document's cross-origin opener
+ policy is derived from the `Cross-Origin-Opener-Policy` and `Cross-Origin-Opener-Policy-Report-Only` HTTP response headers.
+ These headers are structured headers whose value
+ must be a token.
If current is a child browsing context of another browsing
- context parent, then return parent's WindowProxy
- object.
The valid token values are the opener policy values. The token may also have
+ attached parameters; of these, the "report-to" parameter can have a valid URL
+ string identifying an appropriate reporting endpoint.
Assert: current is a top-level browsing - context.
Per the processing model described below, userUser agents will ignore this header if it contains an invalid value. Likewise, user + agents will ignore this header if the value cannot be parsed as a token.
-Return current's WindowProxy object.
The frameElement
- getter steps are:
To obtain a cross-origin opener policy given a response response and an environment + reservedEnvironment:
Let current be this Window object's browsing context.
Let policy be a new cross-origin opener policy.
If current is null, then return null.
If reservedEnvironment is a non-secure context, then return + policy.
Let container be current's container.
Let value be the result of getting a structured field value given
+ `Cross-Origin-Opener-Policy` and "item" from
+ response's header list.
If container is null, then return null.
If parsedItem is not null, then:
-If container's node document's origin is not same origin-domain with the - current settings object's origin, then return null.
If parsedItem[0] is "same-origin",
+ then:
Return container.
Let coep be the result of obtaining a cross-origin embedder policy from response and + reservedEnvironment.
An example of when these IDL attributes can return null is as follows:
+If coep's value is
+ compatible with cross-origin isolation, then set policy's value to "same-origin-plus-COEP".
<!DOCTYPE html>
-<iframe></iframe>
+ Otherwise, set policy's value to
+ "same-origin".
If parsedItem[0] is "same-origin-allow-popups", then set
+ policy's value to "same-origin-allow-popups".
If parsedItem[1]["report-to"] exists and it is a string, then set policy's reporting endpoint to
+ parsedItem[1]["report-to"].
Here the browsing context corresponding to iframeWindow
- was discarded when element was removed from the document.
Set parsedItem to the result of getting a structured field value
+ given `Cross-Origin-Opener-Policy-Report-Only` and "item"
+ from response's header
+ list.
If parsedItem is not null, then:
+If parsedItem[0] is "same-origin",
+ then:
Let coep be the result of obtaining a cross-origin embedder policy from response and + reservedEnvironment.
A browsing context A is familiar - with a second browsing context B if one of the following - conditions is true:
+If coep's value is
+ compatible with cross-origin isolation or coep's report-only value is compatible
+ with cross-origin isolation, then set policy's report-only value to "same-origin-plus-COEP".
Report only COOP also considers report-only COEP to assign the special
+ "same-origin-plus-COEP" value. This allows
+ developers more freedom in the order of deployment of COOP and COEP.
Otherwise, set policy's report-only value to "same-origin".
If parsedItem[0] is "same-origin-allow-popups", then set
+ policy's report-only value to
+ "same-origin-allow-popups".
If parsedItem[1]["report-to"] exists and it is a string, then set policy's report-only reporting endpoint to
+ parsedItem[1]["report-to"].
Return policy.
A browsing context A is allowed to navigate a - second browsing context B if the following algorithm returns true:
+To check if COOP values require a + browsing context group switch, given a boolean isInitialAboutBlank, two origins responseOrigin and + activeDocumentNavigationOrigin, and two cross-origin + opener policy values responseCOOPValue and + activeDocumentCOOPValue:
If A is not the same browsing context as B, and - A is not one of the ancestor browsing - contexts of B, and B is not a top-level browsing - context, and A's active document's active sandboxing flag - set has its sandboxed navigation browsing context flag set, then return - false.
If the result of matching + activeDocumentCOOPValue, activeDocumentNavigationOrigin, + responseCOOPValue, and responseOrigin is true, return false.
Otherwise, if B is a top-level browsing context, and is one of the - ancestor browsing contexts of A, - then:
- -If A's active window has transient activation and - A's active document's active sandboxing flag set has its - sandboxed top-level navigation with user activation browsing context flag set, - then return false.
Otherwise, if A's active window does not have transient - activation and A's active document's active sandboxing - flag set has its sandboxed top-level navigation without user activation browsing - context flag set, then return false.
Otherwise, if B is a top-level browsing context, and is
- neither A nor one of the ancestor
- browsing contexts of A, and A's
- Document's active sandboxing flag set has its sandboxed
- navigation browsing context flag set, and A is not the one
- permitted sandboxed navigator of B, then return false.
Return true.
If all of the following are true:
-isInitialAboutBlank;
An element has a browsing context scope origin if its Document's
- browsing context is a top-level browsing
- context or if all of its Document's ancestor browsing contexts all have active
- documents whose origins are the same
- origin as the element's node document's origin. If an element has a browsing context scope
- origin, then its value is the origin of the
- element's node document.
activeDocumentCOOPValue's value is
+ "same-origin-allow-popups"; and
responseCOOPValue is "unsafe-none"
then return false.
+ -Return true.
+ -To check if enforcing report-only COOP + would require a browsing context group switch, given a boolean + isInitialAboutBlank, two origins + responseOrigin, activeDocumentNavigationOrigin, and two cross-origin opener policies responseCOOP + and activeDocumentCOOP:
-A user agent holds a browsing context group set (a set of browsing context groups).
+If the result of checking if + COOP values require a browsing context group switch given + isInitialAboutBlank, responseOrigin, + activeDocumentNavigationOrigin, responseCOOP's report-only value and + activeDocumentCOOPReportOnly's report-only value is false, then return + false.
-A browsing context group holds a browsing context set (a set - of top-level browsing contexts).
+Matching report-only policies allows a website to specify the same report-only + cross-origin opener policy on all its pages and not receive violation reports for navigations + between these pages.
+A top-level browsing context is added to the group when the group is created. All subsequent top-level browsing - contexts added to the group will be auxiliary browsing contexts.
+If the result of checking + if COOP values require a browsing context group switch given + isInitialAboutBlank, responseOrigin, + activeDocumentNavigationOrigin, responseCOOP's value and activeDocumentCOOPReportOnly's report-only value is true, then return + true.
A browsing context group has an associated agent cluster map (a weak - map of agent cluster - keys to agent clusters). User agents are responsible - for collecting agent clusters when it is deemed that nothing can access them anymore.
+If the result of checking + if COOP values require a browsing context group switch given + isInitialAboutBlank, responseOrigin, + activeDocumentNavigationOrigin, responseCOOP's report-only value and + activeDocumentCOOPReportOnly's value is true, + then return true.
A browsing context group has an associated historical agent cluster key - map, which is a map of origins to agent cluster keys. This - map is used to ensure the consistency of the origin-keyed - agent clusters feature by recording what agent cluster keys were previously used for a given - origin.
+Return false.
The historical agent cluster key map only ever gains entries over the - lifetime of the browsing context group.
+A cross-origin opener policy enforcement result is + a struct with the following items:
-A browsing context group has a cross-origin isolation mode, which is a
- cross-origin isolation mode. It is initially "none".
A boolean needs a browsing context group + switch, initially false.
A cross-origin isolation mode is one of three possible values: "none", "logical", or "concrete".
A boolean would need a browsing + context group switch due to report-only, initially false.
"logical" and "concrete" are similar. They are both used for
- browsing context groups where:
A URL url.
every top-level Document has `Cross-Origin-Opener-Policy: same-origin`, and
An origin origin.
every Document has a `Cross-Origin-Embedder-Policy` header
- whose value is compatible with cross-origin isolation.
A cross-origin opener policy cross-origin opener policy.
On some platforms, it is difficult to provide the security properties required to grant safe
- access to the APIs gated by the cross-origin isolated
- capability. As a result, only "concrete" can grant access that capability.
- "logical" is used on platform not supporting
- this capability, where various restrictions imposed by cross-origin isolation will still apply,
- but the capability is not granted.
A boolean current context is navigation + source.
To create a new browsing context - group, run these steps:
+To enforce a response's cross-origin opener policy, given a + browsing context browsingContext, a URL + responseURL, an origin responseOrigin, a cross-origin + opener policy responseCOOP, a cross-origin opener policy enforcement result + currentCOOPEnforcementResult, and a referrer referrer:
Let group be a new browsing context group.
Append group to the user agent's - browsing context group set.
Let browsingContext be the result of creating a new browsing - context with null, null, and group.
Append browsingContext to - group.
Let newCOOPEnforcementResult be a new cross-origin opener policy enforcement result whose + needs a browsing context group switch is + currentCOOPEnforcementResult's needs a + browsing context group switch, would need a browsing context group switch due + to report-only is currentCOOPEnforcementResult's would need a browsing context group switch due + to report-only, url is responseURL, + origin is responseOrigin, coop is responseCOOP, and current context is navigation source is true.
Return group.
Let isInitialAboutBlank be browsingContext's active
+ document's is initial about:blank.
To append a top-level browsing context - browsingContext to a browsing context group group, run these - steps:
+If isInitialAboutBlank is true and browsingContext's initial URL is null, set + browsingContext's initial URL to + responseURL.
Append browsingContext to group's - browsing context set.
If the result of checking if + COOP values require a browsing context group switch given + isInitialAboutBlank, currentCOOPEnforcementResult's cross-origin opener policy's value, currentCOOPEnforcementResult's origin, responseCOOP's value, and responseOrigin is true, then:
-Set browsingContext's group to - group.
Set newCOOPEnforcementResult's needs a browsing context group switch to + true.
To remove a top-level browsing context - browsingContext, run these steps:
+If browsingContext's group's browsing + context set's size is greater than 1, then:
-Assert: browsingContext's group - is non-null, because a browsing context only gets discarded once.
Let group be browsingContext's group.
Set browsingContext's group to null.
Remove browsingContext from - group's browsing context set.
If group's browsing context set is - empty, then remove group from the user - agent's browsing context group set.
Append and remove are primitive operations that help define the lifetime of a browsing - context group. They are called from creating a new browsing context group, - creating a new auxiliary browsing context, and discarding a browsing context.
- -The HTML Standard used to define "" and "". These have been removed as they were not adequate.
- -Browsing contexts can have a browsing context name. Unless stated otherwise, it is - the empty string.
+Queue a violation report for browsing
+ context group switch when navigating to a COOP response with responseCOOP,
+ "enforce", responseURL,
+ currentCOOPEnforcementResult's url,
+ currentCOOPEnforcementResult's origin, responseOrigin, and
+ referrer.
A valid browsing context name is any string with at least one character that does - not start with a U+005F LOW LINE character. (Names starting with an underscore are reserved for - special keywords.)
+Queue a violation report for browsing
+ context group switch when navigating away from a COOP response with
+ currentCOOPEnforcementResult's cross-origin
+ opener policy, "enforce",
+ currentCOOPEnforcementResult's url,
+ responseURL, currentCOOPEnforcementResult's origin, responseOrigin, and
+ currentCOOPEnforcementResult's current
+ context is navigation source.
A valid browsing context name or keyword is any string that is either a valid
- browsing context name or that is an ASCII case-insensitive match for one of:
- _blank, _self, _parent, or
- _top.
If the result of checking if + enforcing report-only COOP would require a browsing context group switch given + isInitialAboutBlank, responseOrigin, + currentCOOPEnforcementResult's origin, + responseCOOP, and currentCOOPEnforcementResult's cross-origin opener policy, is true, then:
-These values have different meanings based on whether the page is sandboxed or not, as
- summarized in the following (non-normative) table. In this table, "current" means the
- browsing context that the link or script is in, "parent" means the parent
- browsing context of the one the link or script is in, "top" means the top-level
- browsing context of the one the link or script is in, "new" means a new top-level
- browsing context or auxiliary browsing context is to be created, subject to
- various user preferences and user agent policies, "none" means that nothing will happen, and
- "maybe new" means the same as "new" if the "allow-popups" keyword is also specified on the
- sandbox attribute (or if the user overrode the
- sandboxing), and the same as "none" otherwise.
Set result's would + need a browsing context group switch due to report-only to true.
| Keyword - | Ordinary effect - | Effect in an iframe with...
- | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
sandbox=""
- | sandbox="allow-top-navigation"
+ If browsingContext's group's browsing + context set's size is greater than 1, then: - -none specified, for links and form submissions
- | current
- | current
- | current
+ |
empty string
- | current
- | current
- | current
+ | _blank
- new
- | maybe new
- | maybe new
+ | _self
- current
- | current
- | current
+ | To obtain a browsing context to use for a + navigation response, given a browsing context browsingContext, a + sandboxing flag set sandboxFlags, a cross-origin opener + policy navigationCOOP, and a cross-origin opener policy enforcement result + coopEnforcementResult: -_parent if there isn't a parent
- current
- | current
- | current
+ |
_parent if parent is also top
- parent/top
- | none
- | parent/top
+ | | ||||||||||||||||||||||||||||||||||||||||||||||||||||
An accessor-accessed relationship is an enum that describes the relationship + between two browsing contexts between which an access + happened. It can take the following values:
-Most of the restrictions on sandboxed browsing contexts are applied by - other algorithms, e.g. the navigation algorithm, not the - rules for choosing a browsing context given below.
+The accessor browsing context or one of its ancestors is the opener browsing context of the accessed + browsing context's top-level browsing + context.
The accessed browsing context or one of its ancestors is the opener browsing context of the accessor + browsing context's top-level browsing + context.
There is no opener relationship between the accessor browsing context, the + accessor browsing context, or any of their ancestors.
The rules for - choosing a browsing context, given a browsing context name name, a - browsing context current, and a boolean noopener are as - follows:
+To check if an access between two browsing contexts + should be reported, given two browsing contexts + accessor and accessed, a JavaScript property name P, and an + environment settings object environment:
Let chosen be null.
If P is not a cross-origin accessible window property name, then + return.
Let windowType be "existing or none".
Assert: accessor's active document and + accessed's active document are both fully active.
Let sandboxingFlagSet be current's active document's - active sandboxing flag set.
Let accessorTopDocument be accessor's top-level browsing context's active document.
If name is the empty string or an ASCII case-insensitive match for
- "_self", then set chosen to current.
Let accessorInclusiveAncestorOrigins be the list obtained by taking the origin of the active + document of each of accessor's active document's inclusive + ancestor navigables.
Otherwise, if name is an ASCII case-insensitive match for "_parent", set chosen to current's parent browsing
- context, if any, and current otherwise.
Let accessedTopDocument be accessed's top-level browsing context's active document.
Otherwise, if name is an ASCII case-insensitive match for "_top", set chosen to current's top-level browsing
- context, if any, and current otherwise.
Let accessedInclusiveAncestorOrigins be the list obtained by taking the origin of the active + document of each of accessed's active document's inclusive + ancestor navigables.
Otherwise, if name is not an ASCII case-insensitive match for "_blank", there exists a browsing context whose name is the same as name, current is familiar
- with that browsing context, and the user agent determines that the two browsing contexts
- are related enough that it is ok if they reach each other, set chosen to that
- browsing context. If there are multiple matching browsing contexts, the user agent should set
- chosen to one in some arbitrary consistent manner, such as the most recently opened,
- most recently focused, or more closely related.
If any of accessorInclusiveAncestorOrigins are not same origin with + accessorTopDocument's origin, or if + any of accessedInclusiveAncestorOrigins are not same origin with + accessedTopDocument's origin, then + return.
-This will be made more precise in issue #313.
+This avoids leaking information about cross-origin iframes to a top level frame + with cross-origin opener policy reporting.
Otherwise, a new browsing context is being requested, and what happens depends on the user - agent's configuration and abilities — it is determined by the rules given for the first - applicable option from the following list:
+If accessor's top-level browsing context's virtual browsing context group ID is + accessed's top-level browsing context's virtual browsing context group ID, then + return.
Let accessorAccessedRelationship be a new accessor-accessed + relationship with value none.
The user agent may inform the user that a popup has been blocked.
If accessed's top-level browsing context's + opener browsing context is accessor or is an ancestor of accessor, then set + accessorAccessedRelationship to accessor is + opener.
If accessor's top-level browsing context's + opener browsing context is accessed or is an ancestor of accessed, then set + accessorAccessedRelationship to accessor is + openee.
The user agent may report to a developer console that a popup has been blocked.
Queue violation reports for accesses, given + accessorAccessedRelationship, accessorTopDocument's cross-origin opener policy, + accessedTopDocument's cross-origin opener + policy, accessor's active document's URL, accessed's active document's + URL, accessor's top-level browsing context's initial URL, accessed's top-level browsing context's initial URL, accessor's active + document's origin, accessed's + active document's origin, + accessor's top-level browsing context's opener origin at creation, accessed's top-level browsing context's opener origin at creation, + accessorTopDocument's referrer, + accessedTopDocument's referrer, + P, and environment.
Set windowType to "new and unrestricted".
To sanitize a URL to send in a report given a + URL url:
-If current's top-level browsing context's active
- document's cross-origin opener policy's
- value is "same-origin" or "same-origin-plus-COEP", then:
Let sanitizedURL be a copy of url.
Let currentDocument be current's active - document.
Set the username given sanitizedURL and + the empty string. -
If currentDocument's origin is
- not same origin with currentDocument's relevant settings
- object's top-level origin, then set noopener to true,
- name to "_blank", and windowType to "new with no opener".
In the presence of a cross-origin opener policy, nested - documents that are cross-origin with their top-level browsing context's active document - always set noopener to true.
-Set the password given sanitizedURL and + the empty string. +
Return the serialization of + sanitizedURL with exclude + fragment set to true.
If noopener is true, then set chosen to the result - of creating a new top-level browsing context.
To queue a violation report for browsing context + group switch when navigating to a COOP response given a cross-origin opener policy coop, a string disposition, a + URL coopURL, a URL previousResponseURL, two origins coopOrigin and previousResponseOrigin, and a + referrer referrer:
-Otherwise:
+If coop's reporting endpoint + is null, return.
Set chosen to the result of creating a new auxiliary browsing - context with current.
Let coopValue be coop's value.
If sandboxingFlagSet's sandboxed navigation browsing context - flag is set, then current must be set as chosen's one - permitted sandboxed navigator.
If disposition is "reporting", then set
+ coopValue to coop's report-only value.
If sandboxingFlagSet's sandbox propagates to auxiliary browsing - contexts flag is set, then all the flags that are set in sandboxingFlagSet - must be set in chosen's popup sandboxing flag set.
Let serializedReferrer be an empty string.
If name is not an ASCII case-insensitive match for "_blank", then set chosen's name to name.
If referrer is a URL, set serializedReferrer to the + serialization of referrer. -
If the newly created browsing context is immediately navigated, then the navigation will be done with a "replace" history handling behavior.
Let body be a new object containing the following properties:
-| key | +value | +
|---|---|
| disposition | +disposition | +
| effectivePolicy | +coopValue | +
| previousResponseURL | +If coopOrigin and previousResponseOrigin are same origin this is the sanitization of previousResponseURL, null otherwise. | +
| referrer | +serializedReferrer | +
| type | +"navigation-to-response" |
+
Set chosen to current.
Queue body as "coop" for coop's reporting endpoint with coopURL.
To queue a violation report for browsing context + group switch when navigating away from a COOP response given a cross-origin opener policy coop, a string + disposition, a URL coopURL, a URL + nextResponseURL, two origins coopOrigin and + nextResponseOrigin, and a boolean isCOOPResponseNavigationSource:
-Do nothing.
If coop's reporting endpoint + is null, return.
User agents are encouraged to provide a way for users to configure the user - agent to always reuse current.
- +Let coopValue be coop's value.
Return chosen and windowType.
If disposition is "reporting", then set
+ coopValue to coop's report-only value.
Let body be a new object containing the following properties:
-Window,
- WindowProxy, and Location objects| key | +value | +
|---|---|
| disposition | +disposition | +
| effectivePolicy | +coopValue | +
| nextResponseURL | +If coopOrigin and nextResponseOrigin are same origin or isCOOPResponseNavigationSource is true, this is the sanitization of previousResponseURL, null otherwise. | +
| type | +"navigation-from-response" |
+
Although typically objects cannot be accessed across origins, the - web platform would not be true to itself if it did not have some legacy exceptions to that rule - that the web depends upon. +
Queue body as "coop" for coop's reporting endpoint with coopURL.
To queue violation reports for accesses, given an + accessor-accessed relationship accessorAccessedRelationship, two + cross-origin opener policies + accessorCOOP and accessedCOOP, four URLs + accessorURL, accessedURL, accessorInitialURL, + accessedInitialURL, four origins + accessorOrigin, accessedOrigin, accessorCreatorOrigin and + accessedCreatorOrigin, two referrers + accessorReferrer and accessedReferrer, a string propertyName, and + an environment settings object environment:
-If coop's reporting endpoint + is null, return.
When perform a security check is invoked, with a platformObject, - identifier, and type, run these steps:
+Let coopValue be coop's value.
If platformObject is not a Window or Location object,
- then return.
If disposition is "reporting", then set
+ coopValue to coop's report-only value.
For each e of CrossOriginProperties(platformObject):
+If accessorAccessedRelationship is accessor is opener:
If SameValue(e.[[Property]], identifier) is true, - then:
+Queue a violation report + for access to an opened window, given accessorCOOP, accessorURL, + accessedURL, accessedInitialURL, accessorOrigin, + accessedOrigin, accessedCreatorOrigin, propertyName, + and environment.
If type is "method" and e has neither
- [[NeedsGet]] nor [[NeedsSet]], then return.
Queue a violation report for access + from the opener, given accessedCOOP, accessedURL, + accessorURL, accessedOrigin, accessorOrigin, + propertyName, and accessedReferrer.
Otherwise, if type is "getter" and
- e.[[NeedsGet]] is true, then return.
Otherwise, if accessorAccessedRelationship is accessor is openee:
-Otherwise, if type is "setter" and
- e.[[NeedsSet]] is true, then return.
Queue a violation report for access to + the opener, given accessorCOOP, accessorURL, + accessedURL, accessorOrigin, accessedOrigin, + propertyName, accessorReferrer, and environment.
Queue a violation report for access + from an opened window, given accessedCOOP, accessedURL, + accessorURL, accessorInitialURL, accessedOrigin, + accessorOrigin, accessorCreatorOrigin, and + propertyName.
If IsPlatformObjectSameOrigin(platformObject) is false, then
- throw a "SecurityError" DOMException.
Otherwise:
+Queue a violation report for + access to another window, given accessorCOOP, accessorURL, + accessedURL, accessorOrigin, accessedOrigin, + propertyName, and environment
Queue a violation report for + access from another window, given accessedCOOP, accessedURL, + accessorURL, accessedOrigin, accessorOrigin, and + propertyName.
Window and Location objects both have a
- [[CrossOriginPropertyDescriptorMap]] internal slot, whose value is initially an empty
- map.
+
To queue a violation report for access to the + opener, given a cross-origin opener + policy coop, two URLs coopURL and + openerURL, two origins coopOrigin and + openerOrigin, a string propertyName, a referrer referrer, and an environment + settings object environment:
-The [[CrossOriginPropertyDescriptorMap]] internal slot contains a map
- with entries whose keys are (currentGlobal, objectGlobal,
- propertyKey)-tuples and values are property descriptors, as a memoization of what is
- visible to scripts when currentGlobal inspects a Window or
- Location object from objectGlobal. It is filled lazily by
- CrossOriginGetOwnPropertyHelper, which consults it on future lookups.
Let sourceFile, lineNumber and columnNumber be the + relevant script URL and problematic position which triggered this report.
User agents should allow a value held in the map to be garbage collected along with its - corresponding key when nothing holds a reference to any part of the value. That is, as long as - garbage collection is not observable.
+Let serializedReferrer be an empty string.
For example, with const href =
- Object.getOwnPropertyDescriptor(crossOriginLocation, "href").set the value and its
- corresponding key in the map cannot be garbage collected as that would be observable.
If referrer is a URL, set serializedReferrer to the + serialization of referrer. -
User agents may have an optimization whereby they remove key-value pairs from the map when
- document.domain is set. This is not observable as document.domain cannot revisit an earlier value.
Let body be a new object containing the following properties:
-For example, setting document.domain
+
| key | +value | +
|---|---|
| disposition | +"reporting" |
+
| effectivePolicy | +coop's report-only + value | +
| property | +propertyName | +
| openerURL | +If coopOrigin and openerOrigin are same origin, this + is the sanitization of openerURL, null + otherwise. | +
| referrer | +serializedReferrer | +
| sourceFile | +sourceFile | +
| lineNumber | +lineNumber | +
| columnNumber | +columnNumber | +
| type | +"access-to-opener" |
+
Queue body as "coop" for coop's reporting endpoint with coopURL and
+ environment.
To queue a violation report for access to an + opened window, given a cross-origin opener + policy coop, three URLs coopURL, + openedWindowURL and initialWindowURL, three origins coopOrigin, openedWindowOrigin, and + openerInitialOrigin, a string propertyName, and an environment + settings object environment:
+ +Let sourceFile, lineNumber and columnNumber be the + relevant script URL and problematic position which triggered this report.
Let body be a new object containing the following properties:
+ +| key | +value | +
|---|---|
| disposition | +"reporting" |
+
| effectivePolicy | +coop's report-only + value | +
| property | +propertyName | +
| openedWindowURL | +If coopOrigin and openedWindowOrigin are same origin, this + is the sanitization of openedWindowURL, + null otherwise. | +
| openedWindowInitialURL | +If coopOrigin and openerInitialOrigin are same origin, + this is the sanitization of + initialWindowURL, null otherwise. | +
| sourceFile | +sourceFile | +
| lineNumber | +lineNumber | +
| columnNumber | +columnNumber | +
| type | +"access-to-opener" |
+
Queue body as "coop"
+ for coop's reporting endpoint with
+ coopURL and environment.
To queue a violation report for access to another + window, given a cross-origin opener policy + coop, two URLs coopURL and + otherURL, two origins coopOrigin and + otherOrigin, a string propertyName, and an environment settings + object environment:
+ +Let sourceFile, lineNumber and columnNumber be the + relevant script URL and problematic position which triggered this report.
Let body be a new object containing the following properties:
+ +| key | +value | +
|---|---|
| disposition | +"reporting" |
+
| effectivePolicy | +coop's report-only + value | +
| property | +propertyName | +
| otherURL | +If coopOrigin and otherOrigin are same origin, this + is the sanitization of otherURL, null + otherwise. | +
| sourceFile | +sourceFile | +
| lineNumber | +lineNumber | +
| columnNumber | +columnNumber | +
| type | +"access-to-opener" |
+
Queue body as "coop"
+ for coop's reporting endpoint with
+ coopURL and environment.
To queue a violation report for access from the + opener, given a cross-origin opener policy + coop, two URLs coopURL and + openerURL, two origins coopOrigin and + openerOrigin, a string propertyName, and a referrer referrer:
+ +If coop's reporting endpoint + is null, return.
Let serializedReferrer be an empty string.
If referrer is a URL, set serializedReferrer to the + serialization of referrer. + +
Let body be a new object containing the following properties:
+ +| key | +value | +
|---|---|
| disposition | +"reporting" |
+
| effectivePolicy | +coop's report-only + value | +
| property | +propertyName | +
| openerURL | +If coopOrigin and openerOrigin are same origin, this + is the sanitization of openerURL, null + otherwise. | +
| referrer | +serializedReferrer | +
| type | +"access-to-opener" |
+
Queue body as "coop"
+ for coop's reporting endpoint with
+ coopURL.
To queue a violation report for access from an + opened window, given a cross-origin opener + policy coop, three URLs coopURL, + openedWindowURL and initialWindowURL, three origins coopOrigin, openedWindowOrigin, and + openerInitialOrigin, and a string propertyName:
+ +If coop's reporting endpoint + is null, return.
Let body be a new object containing the following properties:
+ +| key | +value | +
|---|---|
| disposition | +"reporting" |
+
| effectivePolicy | +coopValue | +
| property | +coop's report-only + value | +
| openedWindowURL | +If coopOrigin and openedWindowOrigin are same origin, this + is the sanitization of openedWindowURL, + null otherwise. | +
| openedWindowInitialURL | +If coopOrigin and openerInitialOrigin are same origin, + this is the sanitization of + initialWindowURL, null otherwise. | +
| type | +"access-to-opener" |
+
Queue body as "coop"
+ for coop's reporting endpoint with
+ coopURL.
To queue a violation report for access from another + window, given a cross-origin opener policy + coop, two URLs coopURL and otherURL, two + origins coopOrigin and otherOrigin, and a string + propertyName:
+ +If coop's reporting endpoint + is null, return.
Let body be a new object containing the following properties:
+ +| key | +value | +
|---|---|
| disposition | +"reporting" |
+
| effectivePolicy | +coop's report-only + value | +
| property | +propertyName | +
| otherURL | +If coopOrigin and otherOrigin are same origin, this + is the sanitization of otherURL, null + otherwise. | +
| type | +access-to-opener |
+
Queue body as "coop"
+ for coop's reporting endpoint with
+ coopURL.
An embedder policy value is one of three strings that controls the fetching + of cross-origin resources without explicit permission from resource owners.
+ +unsafe-none"This is the default value. When this value is used, cross-origin resources can be fetched
+ without giving explicit permission through the CORS protocol or the
+ `Cross-Origin-Resource-Policy` header.
require-corp"When this value is used, fetching cross-origin resources requires the server's
+ explicit permission through the CORS protocol or the
+ `Cross-Origin-Resource-Policy` header.
credentialless"When this value is used, fetching cross-origin no-CORS resources omits credentials. In
+ exchange, an explicit `Cross-Origin-Resource-Policy` header is not required. Other
+ requests sent with credentials require the server's explicit permission through the CORS
+ protocol or the `Cross-Origin-Resource-Policy` header.
Before supporting "credentialless", implementers are
+ strongly encouraged to support both:
+
+
Otherwise, it would allow attackers to leverage the client's network position to read non + public resources, using the cross-origin isolated + capability.
+An embedder policy value is compatible with cross-origin isolation if
+ it is "credentialless" or "require-corp".
An embedder policy consists of:
+ +A value, which is an embedder policy value, initially "unsafe-none".
A reporting endpoint string, initially the empty string.
A report only value, which is an embedder policy value, initially
+ "unsafe-none".
A report only reporting endpoint string, initially the empty + string.
The "coep" report type is a report type whose value
+ is "coep". It is visible to
+ ReportingObservers.
The ` The valid token values are the embedder policy values. The token may also have attached parameters; of these, the " The processing model fails open (by defaulting
+ to " (The same applies to ` To obtain an embedder policy from a response response and an environment
+ environment: Let policy be a new embedder policy. If environment is a non-secure context, then return
+ policy. Let parsedItem be the result of getting a structured field value
+ with ` If parsedItem is non-null and parsedItem[0] is compatible with
+ cross-origin isolation: Set policy's value to
+ parsedItem[0]. If parsedItem[1][" Set parsedItem to the result of getting a structured field value
+ with ` If parsedItem is non-null and parsedItem[0] is compatible with
+ cross-origin isolation: Set policy's report only value to
+ parsedItem[0]. If parsedItem[1][" Return policy. To check a navigation response's adherence to its embedder policy given a response response, a navigable
+ navigable, and an embedder policy responsePolicy: If navigable is not a child navigable, then return
+ true. Let parentPolicy be navigable's container document's policy container's embedder policy. If parentPolicy's report-only
+ value is compatible with cross-origin isolation and
+ responsePolicy's value is not, then
+ queue a cross-origin embedder policy inheritance violation with response,
+ " If parentPolicy's value is not
+ compatible with cross-origin isolation or responsePolicy's value is compatible with cross-origin
+ isolation, then return true. Queue a cross-origin embedder policy inheritance violation with
+ response, " Return false. To check a global object's embedder policy given a If workerGlobalScope is not a Let policy be workerGlobalScope's embedder policy.
+
+ Let ownerPolicy be owner's policy container's embedder policy.
+
+ If ownerPolicy's report-only
+ value is compatible with cross-origin isolation and policy's
+ value is not, then queue a cross-origin
+ embedder policy inheritance violation with response, " If ownerPolicy's value is not
+ compatible with cross-origin isolation or policy's value is compatible with cross-origin
+ isolation, then return true. Queue a cross-origin embedder policy inheritance violation with
+ response, " Return false. To queue a cross-origin embedder policy inheritance violation given a response response, a string type, a string
+ endpoint, a string disposition, and an environment settings
+ object settings: Let serialized be the result of serializing a response URL for
+ reporting with response. Let body be a new object containing the following properties: Queue body as the
+ " A sandboxing flag set is a set of zero or more of the following flags, which
+ are used to restrict the abilities that potentially untrusted resources have: This flag prevents content from navigating browsing contexts other
+ than the sandboxed browsing context itself (or browsing contexts further nested inside it),
+ auxiliary browsing contexts (which are protected
+ by the sandboxed auxiliary navigation browsing context flag defined next), and the
+ top-level browsing context (which is protected by the sandboxed top-level
+ navigation without user activation browsing context flag and sandboxed top-level
+ navigation with user activation browsing context flag defined below). If the sandboxed auxiliary navigation browsing context flag is not set, then in
+ certain cases the restrictions nonetheless allow popups (new top-level browsing contexts) to be opened. These browsing contexts always have one permitted sandboxed navigator, set
+ when the browsing context is created, which allows the browsing context that
+ created them to actually navigate them. (Otherwise, the sandboxed navigation browsing
+ context flag would prevent them from being navigated even if they were opened.) This flag prevents content from creating new auxiliary browsing
+ contexts, e.g. using the This flag prevents content from navigating their top-level
+ browsing context and prevents content from closing their
+ top-level browsing context. It is consulted only when the sandboxed browsing
+ context's active window does not have transient activation. When the sandboxed top-level navigation without user activation browsing context
+ flag is not set, content can navigate its top-level browsing
+ context, but other browsing contexts are still
+ protected by the sandboxed navigation browsing context flag and possibly
+ the sandboxed auxiliary navigation browsing context flag. This flag prevents content from navigating their top-level
+ browsing context and prevents content from closing their
+ top-level browsing context. It is consulted only when the sandboxed browsing
+ context's active window has transient activation. As with the sandboxed top-level navigation without user activation browsing context
+ flag, this flag only affects the top-level browsing context; if it is not
+ set, other browsing contexts might still be protected by
+ other flags. This flag forces content into a unique origin, thus preventing
+ it from accessing other content from the same origin. This flag also prevents script from reading from or writing to the
+ This flag blocks form submission. This flag blocks script execution. This flag blocks features that trigger automatically, such as automatically playing a video or automatically focusing a form control. This flag prevents content from using the
+ This flag prevents content from escaping the sandbox by ensuring that any
+ auxiliary browsing context it creates inherits the content's
+ active sandboxing flag set. This flag prevents content from using any of the following features to produce modal
+ dialogs: This flag disables the ability to lock the screen orientation. This flag prevents content from initiating or instantiating downloads, whether through downloading hyperlinks or through navigation that gets handled as a
+ download. This flag prevents navigations toward non fetch schemes
+ from being handed off to external
+ software. When the user agent is to parse a sandboxing directive, given a string
+ input, a sandboxing flag set output, it must run the following
+ steps: Split input on ASCII
+ whitespace, to obtain tokens. Let output be empty. Add the following flags to output: The sandboxed navigation browsing context flag. The sandboxed auxiliary navigation browsing context flag, unless
+ tokens contains the The sandboxed top-level navigation without user activation browsing context
+ flag, unless tokens contains the The sandboxed top-level navigation with user activation browsing context flag,
+ unless tokens contains either the This means that if the The sandboxed origin browsing context flag, unless the tokens
+ contains the The First, it can be used to allow content from the same site to be sandboxed to disable
+ scripting, while still allowing access to the DOM of the sandboxed content. Second, it can be used to embed content from a third-party site, sandboxed to prevent that
+ site from opening popups, etc, without preventing the embedded page from communicating back
+ to its originating site, using the database APIs to store data, etc. The sandboxed forms browsing context flag, unless tokens
+ contains the The sandboxed pointer lock browsing context flag, unless tokens
+ contains the The sandboxed scripts browsing context flag, unless tokens
+ contains the The sandboxed automatic features browsing context flag, unless
+ tokens contains the This flag is relaxed by the same keyword as scripts, because when scripts are
+ enabled these features are trivially possible anyway, and it would be unfortunate to force
+ authors to use script to do them when sandboxed rather than allowing them to use the
+ declarative features. The sandboxed The sandbox propagates to auxiliary browsing contexts flag, unless
+ tokens contains the The sandboxed modals flag, unless tokens contains the The sandboxed orientation lock browsing context flag, unless
+ tokens contains the The sandboxed presentation browsing context flag, unless tokens
+ contains the The sandboxed downloads browsing context flag, unless tokens
+ contains the The sandboxed custom protocols navigation browsing context flag, unless
+ tokens contains either the Every top-level browsing context has a popup sandboxing flag set, which
+ is a sandboxing flag set. When a browsing context is created, its
+ popup sandboxing flag set must be empty. It is populated by the rules for
+ choosing a navigable and the obtain
+ a browsing context to use for a navigation response algorithm. Every Every Every CSP list
+ cspList has CSP-derived sandboxing flags, which is a sandboxing flag
+ set. It is the return value of the following algorithm: Let directives be an empty ordered set. For each policy in cspList: If policy's disposition is not " If policy's directive set contains a directive whose name is " If directives is empty, then return an empty sandboxing flag
+ set. Let directive be directives[directives's size − 1]. Return the result of parsing the sandboxing
+ directive directive. To determine the creation sandboxing
+ flags for a browsing context browsing
+ context, given null or an element embedder, return the union of the flags that are present in the following sandboxing flag sets: If embedder is null, then: the flags set on browsing context's
+ popup sandboxing flag set. If embedder is an element, then: the flags set on embedder's
+ If embedder is an element, then: the flags set on embedder's
+ node document's active sandboxing flag set. A policy container is a struct containing policies that apply to
+ a A CSP list,
+ which is a CSP list. It is initially empty. An embedder
+ policy, which is an embedder policy. It is initially a new embedder
+ policy. A referrer
+ policy, which is a referrer policy. It is initially the default referrer
+ policy. Move other policies into the policy container. To clone a policy container given a policy container
+ policyContainer: Let clone be a new policy container. For each policy in
+ policyContainer's CSP list, append a copy of policy into clone's CSP list. Set clone's embedder
+ policy to a copy of policyContainer's embedder policy. Set clone's referrer
+ policy to policyContainer's referrer policy. Return clone. To determine whether a URL url requires storing the policy
+ container in history: If url's scheme is " If url is local, then return true. Return false. To create a policy container from a fetch response
+ given a response response and an
+ environment-or-null environment: If response's URL's scheme is " Let result be a new policy container. Set result's CSP list to the
+ result of parsing a response's Content Security Policies
+ given response. If environment is non-null, then set result's embedder policy to the result of obtaining an embedder policy given response
+ and environment. Otherwise, set it to " Set result's referrer
+ policy to the result of parsing the
+ ` Return result. To determine navigation params
+ policy container given a URL responseURL and four policy container-or-nulls historyPolicyContainer,
+ initiatorPolicyContainer, parentPolicyContainer, and
+ responsePolicyContainer: If historyPolicyContainer is not null, then: Assert: responseURL requires storing the policy container
+ in history. Return a clone of
+ historyPolicyContainer. If responseURL is Assert: parentPolicyContainer is not null. Return a clone of
+ parentPolicyContainer. If responseURL is local and
+ initiatorPolicyContainer is not null, then return a clone of initiatorPolicyContainer. If responsePolicyContainer is not null, then return
+ responsePolicyContainer. Return a new policy container. To initialize a worker global scope's policy
+ container given a If workerGlobalScope's url
+ is local but its scheme
+ is not " Assert: workerGlobalScope's owner set's size is 1. Set workerGlobalScope's policy container to a clone of workerGlobalScope's owner
+ set[0]'s relevant settings object's policy container. Otherwise, set workerGlobalScope's policy container to the result of
+ creating a policy container from a fetch response given
+ response and environment. Although typically objects cannot be accessed across origins, the
+ web platform would not be true to itself if it did not have some legacy exceptions to that rule
+ that the web depends upon. This section uses the terminology and typographic conventions from the JavaScript
+ specification. When perform a security check is invoked, with a platformObject,
+ identifier, and type, run these steps: If platformObject is not a For each e of CrossOriginProperties(platformObject): If SameValue(e.[[Property]], identifier) is true,
+ then: If type is " Otherwise, if type is " Otherwise, if type is " If IsPlatformObjectSameOrigin(platformObject) is false, then
+ throw a " The [[CrossOriginPropertyDescriptorMap]] internal slot contains a map
+ with entries whose keys are (currentGlobal, objectGlobal,
+ propertyKey)-tuples and values are property descriptors, as a memoization of what is
+ visible to scripts when currentGlobal inspects a User agents should allow a value held in the map to be garbage collected along with its
+ corresponding key when nothing holds a reference to any part of the value. That is, as long as
+ garbage collection is not observable. For example, with User agents may have an optimization whereby they remove key-value pairs from the map when
+ For example, setting Assert: O is a If O is a Return «
+ { [[Property]]: " This abstract operation does not return a Completion Record. Indexed properties do not need to be safelisted in this algorithm, as they are
+ handled directly by the A JavaScript property name P is a cross-origin accessible window property
+ name if it is " If P is " Throw a " Return true if the current settings object's origin is same origin-domain with
+ O's relevant settings object's origin, and false otherwise. This abstract operation does not return a Completion Record. Here the current settings object roughly corresponds to the "caller",
+ because this check occurs before the execution
+ context for the getter/setter/method in question makes its way onto the JavaScript
+ execution context stack. For example, in the code If this abstract operation returns undefined and there is no custom behavior, the
+ caller needs to throw a " Let crossOriginKey be a tuple consisting of the current settings
+ object, O's relevant settings object, and P. For each e of CrossOriginProperties(O): If SameValue(e.[[Property]], P) is true, then: If the value of the [[CrossOriginPropertyDescriptorMap]] internal slot of
+ O contains an entry whose key is crossOriginKey, then return that
+ entry's value. Let originalDesc be OrdinaryGetOwnProperty(O,
+ P). Let crossOriginDesc be undefined. If e.[[NeedsGet]] and e.[[NeedsSet]] are absent, then: Let value be originalDesc.[[Value]]. If IsCallable(value) is true, then set value to
+ an anonymous built-in function, created in the current realm, that performs
+ the same steps as the IDL operation P on object O. Set crossOriginDesc to PropertyDescriptor{
+ [[Value]]: value,
+ [[Enumerable]]: false,
+ [[Writable]]: false,
+ [[Configurable]]: true }. Otherwise: Let crossOriginGet be undefined. If e.[[NeedsGet]] is true, then set crossOriginGet to an
+ anonymous built-in function, created in the current realm, that performs the
+ same steps as the getter of the IDL attribute P on object
+ O. Let crossOriginSet be undefined. If e.[[NeedsSet]] is true, then set crossOriginSet to an
+ anonymous built-in function, created in the current realm, that performs the
+ same steps as the setter of the IDL attribute P on object
+ O. Set crossOriginDesc to PropertyDescriptor{
+ [[Get]]: crossOriginGet,
+ [[Set]]: crossOriginSet,
+ [[Enumerable]]: false,
+ [[Configurable]]: true }. Create an entry in the value of the [[CrossOriginPropertyDescriptorMap]]
+ internal slot of O with key crossOriginKey and value
+ crossOriginDesc. Return crossOriginDesc. Return undefined. This abstract operation does not return a Completion Record. The reason that the property descriptors produced here are configurable is to
+ preserve the invariants of the essential internal methods required by the JavaScript
+ specification. In particular, since the value of the property can change as a consequence of
+ navigation, it is required that the property be configurable. (However, see tc39/ecma262 issue #672 and references to it
+ elsewhere in this specification for cases where we are not able to preserve these invariants, for
+ compatibility with existing web content.) The reason the property descriptors are non-enumerable, despite this mismatching
+ the same-origin behavior, is for compatibility with existing web content. See issue #3183 for details. Let desc be ? O.[[GetOwnProperty]](P). Assert: desc is not undefined. If IsDataDescriptor(desc) is true, then return
+ desc.[[Value]]. Assert: IsAccessorDescriptor(desc) is true. Let getter be desc.[[Get]]. If getter is undefined, then throw a " Return ? Call(getter, Receiver). Let desc be ? O.[[GetOwnProperty]](P). Assert: desc is not undefined. If desc.[[Set]] is present and its value is not undefined, then:
+
+ Perform ? Call(setter, Receiver,
+ «V»). Return true. Throw a " Let keys be a new empty List. For each e of CrossOriginProperties(O), append e.[[Property]] to keys. Return the concatenation of keys and « " This abstract operation does not return a Completion Record. These attributes all return window. Returns the Returns the The A A The The The The If this's browsing context is null,
+ then return null. Return this's browsing context's
+ For historical reasons, Opens a window to show url (defaults to " These behave equivalently to the Encourages user agents to provide a minimal web browser user interface for the new
+ window. (Impacts the Returns the name of the window. Can be set, to change the name. Closes the window. Returns true if the window has been closed, false otherwise. Cancels the document load. The window open steps, given a string url, a string target,
+ and a string features, are as follows: If the event loop's termination nesting level is nonzero,
+ return null. Let sourceDocument be the entry global object's associated If target is the empty string, then set target to " Let tokenizedFeatures be the result of tokenizing features. Let noopener and noreferrer be false. If tokenizedFeatures[" Set noopener to the result of parsing
+ tokenizedFeatures[" Remove tokenizedFeatures[" If tokenizedFeatures[" Set noreferrer to the result of parsing
+ tokenizedFeatures[" Remove tokenizedFeatures[" Let referrerPolicy be the empty string. If noreferrer is true, then set noopener to true and set
+ referrerPolicy to " Let targetNavigable and windowType be the result of applying the
+ rules for choosing a navigable given target, sourceDocument's
+ node navigable, and noopener. If there is a user agent that supports control-clicking a link to open it in
+ a new tab, and the user control-clicks on an element whose If targetNavigable is null, then return null. If windowType is either " Set targetNavigable's active browsing context's
+ is popup to the result of checking if a
+ popup window is requested, given tokenizedFeatures. Set up browsing context features for targetNavigable's active browsing context given tokenizedFeatures. Let urlRecord be the URL record
+ If url is not the empty string, then parse
+ url relative to the entry settings object, and set
+ urlRecord to the resulting URL record, if any. If the parse a
+ URL algorithm failed, then throw a " If urlRecord matches This is necessary in case url is something like Otherwise, navigate targetNavigable
+ to urlRecord using sourceDocument, with referrerPolicy set to referrerPolicy and
+ exceptionsEnabled set to true. Otherwise: If url is not the empty string, then: Let urlRecord be the URL record
+ Parse url relative to the entry
+ settings object, and set urlRecord to the resulting URL
+ record, if any. If the parse a URL algorithm failed, then throw a
+ " Navigate targetNavigable to
+ urlRecord using sourceDocument, with referrerPolicy set to referrerPolicy and
+ exceptionsEnabled set to true. If noopener is false, then set targetNavigable's active browsing context's opener browsing context to
+ sourceDocument's browsing
+ context. If noopener is true or windowType is " Return targetNavigable's active
+ The The method provides a mechanism for navigating an
+ existing browsing context or opening and navigating an auxiliary browsing
+ context. To tokenize the features
+ argument: Let tokenizedFeatures be a new ordered map. Let position point at the first code point of features. While position is not past the end of features: Let name be the empty string. Let value be the empty string. Collect a sequence of code points that are feature separators from features given position. This
+ skips past leading separators before the name. Collect a sequence of code points that are not feature separators from features given position. Set
+ name to the collected characters, converted to ASCII lowercase. Set name to the result of normalizing the feature name
+ name. While position is not past the end of features and the
+ code point at position in features is not U+003D (=): If the code point at position in features is U+002C (,), or if
+ it is not a feature separator, then break. Advance position by 1. This skips to the first U+003D (=) but does not skip past a U+002C (,) or a
+ non-separator. If the code point at position in features is a feature
+ separator: While position is not past the end of features and the code point
+ at position in features is a feature separator: If the code point at position in features is U+002C (,), then
+ break. Advance position by 1. This skips to the first non-separator but does not skip past a U+002C
+ (,). Collect a sequence of code points that are not feature separators code points from features given
+ position. Set value to the collected code points, converted to
+ ASCII lowercase. If name is not the empty string, then set
+ tokenizedFeatures[name] to value. Return tokenizedFeatures. To check if a window feature is set, given
+ tokenizedFeatures, featureName, and defaultValue: If tokenizedFeatures[featureName] exists, then return the result of parsing
+ tokenizedFeatures[featureName] as a boolean feature. Return defaultValue. To check if a popup window is requested, given
+ tokenizedFeatures: If tokenizedFeatures is empty, then return
+ false. If tokenizedFeatures[" Let location be the result of checking if
+ a window feature is set, given tokenizedFeatures, " Let toolbar be the result of checking if
+ a window feature is set, given tokenizedFeatures, " If location and toolbar are both false, then return true. Let menubar be the result of checking if
+ a window feature is set, given tokenizedFeatures, If menubar is false, then return true. Let resizable be the result of checking if
+ a window feature is set, given tokenizedFeatures, " If resizable is false, then return true. Let scrollbars be the result of checking
+ if a window feature is set, given tokenizedFeatures, " If scrollbars is false, then return true. Let status be the result of checking if
+ a window feature is set, given tokenizedFeatures, " If status is false, then return true. Return false. A code point is a feature separator if it is ASCII whitespace, U+003D
+ (=), or U+002C (,). For legacy reasons, there are some aliases of some feature names. To normalize a feature name name, switch on name: To parse a boolean feature given
+ a string value: If value is the empty string, then return true. If value is " If value is " Let parsed be the result of parsing
+ value as an integer. If parsed is an error, then set it to 0. Return false if parsed is 0, and true otherwise. The If this's navigable is null, then
+ return the empty string. Return this's navigable's target name. The If this's navigable is null, then
+ return. Set this's navigable's active session history entry's document state's navigable target name to the given value. The name gets reset when the navigable is navigated to another origin. The Let thisTraversable be null. For each top-level traversable
+ traversable of the user agent's top-level traversable set: if
+ traversable's active document's relevant
+ global object equals this, then set thisTraversable to
+ traversable and break. If thisTraversable is null, then return. In this case the method is being called on a If thisTraversable's is closing is true, then return. Let browsingContext be thisTraversable's active browsing context. Let sourceSnapshotParams be the result of snapshotting source snapshot
+ params given thisTraversable's active
+ document. If all the following are true: then: Set thisTraversable's is closing to true. Queue a task on the DOM manipulation task source to close thisTraversable. A navigable is script-closable if its active
+ browsing context is an auxiliary browsing context that was created by a
+ script (as opposed to by an action of the user), or if it is a top-level traversable
+ whose session history entries's size is 1. The The If this's navigable is null, then
+ return. Stop loading this's navigable. Returns the number of document-tree child navigables. Returns the The Indexed access to document-tree child navigables is defined through
+ the [[GetOwnProperty]] internal method of the
+ Returns the indicated element or collection of elements. As a general rule, relying on this will lead to brittle code. Which IDs end up mapping to
+ this API can vary over time, as new features are added to the web platform, for example. Instead
+ of this, use The document-tree child
+ navigable target name property set of a Let children be the document-tree child navigables of
+ window's associated
+ Let firstNamedChildren be an empty ordered
+ set. For each navigable of children: Let name be navigable's target name. If name is the empty string, then continue. If names contains name, then
+ continue. Append navigable to
+ firstNamedChildren. Let names be an empty ordered set. For each navigable of
+ firstNamedChildren: Let name be navigable's target name. If navigable's active document's origin is same origin with
+ window's relevant settings object's origin, then append name to names. Return names. The two seperate iterations mean that in the following example, hosted on The window's document-tree child navigable target name property
+ set; the value of the the value of the To determine the value of a named property
+ name in a Let objects be the list of named
+ objects of window with the name name. There will be at least one such object, by definition. If objects contains a navigable, then: Let container be the first navigable container in
+ window's associated
+ Return container's nested navigable's active Otherwise, if objects has only one element, return that element. Otherwise return an Named objects of document-tree child navigables of window's associated HTML elements that have an Returns the Returns the Returns null if there isn't one or if it has been set to null. Can be set to null. Returns the Returns the navigable container element. Returns null if there isn't one, and in cross-origin situations. The If this's navigable is null, then
+ return null. Return this's navigable's top-level traversable's active
+ The Let current be this's browsing
+ context. If current is null, then return null. If current's disowned is true, then return null. If current's opener browsing context is null, then return
+ null. Return current's opener browsing context's
+ The If the given value is null and this's browsing
+ context is non-null, then set this's browsing
+ context's disowned to true. If the given value is non-null, then return ?
+ OrdinaryDefineOwnProperty(this, " If a browsing context's disowned is true, its Otherwise, if a browsing context's disowned is false, then scripts
+ in that browsing context can use The Let navigable be this's navigable. If navigable is null, then return null. If navigable's parent is not null, then set
+ navigable to navigable's parent. Return navigable's active
+ The Let current be this's node navigable. If current is null, then return null. Let container be current's container. If container is null, then return null. If container's node document's origin is not same origin-domain with the
+ current settings object's origin, then return null. Return container. An example of when these properties can return null is as follows: Here the browsing context corresponding to For historical reasons, the For privacy and interoperability reasons, those properties now return values that
+ represent whether the For privacy and interoperability reasons, those properties now return all return the same value:
+ whether or not the window represents a popup window. Each interface element is represented by a Returns true if the The Let browsingContext be this's relevant global
+ object's browsing context. If browsingContext is null, then return true. Return the negation of browsingContext's top-level
+ browsing context's is popup. The following The The The The The The For historical reasons, the To set up a window environment settings object, given a URL
+ creationURL, a JavaScript execution context execution context,
+ null or an environment reservedEnvironment, a URL
+ topLevelCreationURL, and an origin topLevelOrigin, run these
+ steps: Let realm be the value of execution context's Realm
+ component. Let window be realm's global
+ object. Let settings object be a new environment settings object whose
+ algorithms are defined as follows: Return execution context. Return the module map of
+ window's associated
+ Return the current character encoding
+ of window's associated
+ Return the current base URL of window's
+ associated Return the origin of window's
+ associated Return the policy container of
+ window's associated
+ Return true if both of the following hold, and false otherwise: realm's agent cluster's cross-origin-isolation mode is " window's associated
+ Return window's associated
+ If reservedEnvironment is non-null, then: Set settings object's id to
+ reservedEnvironment's id, target browsing context to
+ reservedEnvironment's target browsing context, and active service worker to
+ reservedEnvironment's active service worker. Set reservedEnvironment's id to
+ the empty string. The identity of the reserved environment is considered to be fully
+ transferred to the created environment settings object. The reserved environment
+ is not searchable by the environment’s id from this point on. Otherwise, set settings object's id to a new unique opaque string, settings
+ object's target browsing
+ context to null, and settings object's active service worker to null. Set settings object's creation
+ URL to creationURL, settings object's top-level creation
+ URL to topLevelCreationURL, and settings object's top-level
+ origin to topLevelOrigin. Set realm's [[HostDefined]] field to settings object. A The There is no Every Although Let W be the value of the
+ [[Window]] internal slot of
+ this. If IsPlatformObjectSameOrigin(W) is true, then return !
+ OrdinaryGetPrototypeOf(W). Return null. Return ! SetImmutablePrototype(this, V). Return true. Return false. Let W be the value of the
+ [[Window]] internal slot of
+ this. If P is an array index property name, then: Let index be ! ToUint32(P). Let children be the document-tree child navigables of
+ W's associated
+ Let value be undefined. If index is less than children's size, then: Sort children in ascending order, with
+ navigableA being less than navigableB if navigableA's container was inserted into W's associated Set value to children[index]'s active If value is undefined, then: If IsPlatformObjectSameOrigin(W) is true, then return
+ undefined. Throw a " Return PropertyDescriptor{
+ [[Value]]: value,
+ [[Writable]]: false,
+ [[Enumerable]]: true,
+ [[Configurable]]: true }. If IsPlatformObjectSameOrigin(W) is true, then return !
+ OrdinaryGetOwnProperty(W, P). This is a willful violation of the JavaScript specification's
+ invariants of the essential internal methods to maintain compatibility with
+ existing web content. See tc39/ecma262
+ issue #672 for more information. Let property be CrossOriginGetOwnPropertyHelper(W,
+ P). If property is not undefined, then return property. If property is undefined and P is in W's document-tree
+ child navigable target name property set, then: Let value be the active
+ Return PropertyDescriptor{
+ [[Value]]: value,
+ [[Enumerable]]: false,
+ [[Writable]]: false,
+ [[Configurable]]: true }. The reason the property descriptors are non-enumerable, despite this
+ mismatching the same-origin behavior, is for compatibility with existing web content. See issue #3183 for details. Return ? CrossOriginPropertyFallback(P). Let W be the value of the
+ [[Window]] internal slot of
+ this. If IsPlatformObjectSameOrigin(W) is true, then:
+
+ If P is an array index property name, return false. Return ? OrdinaryDefineOwnProperty(W, P,
+ Desc). This is a willful violation of the JavaScript specification's
+ invariants of the essential internal methods to maintain compatibility with
+ existing web content. See tc39/ecma262
+ issue #672 for more information. Throw a " Let W be the value of the
+ [[Window]] internal slot of
+ this. Check if an access between two browsing contexts
+ should be reported, given the current global object's
+ browsing context, W's browsing context, P, and the current settings
+ object. If IsPlatformObjectSameOrigin(W) is true, then return ?
+ OrdinaryGet(this, P, Receiver). Return ? CrossOriginGet(this, P,
+ Receiver). this is passed rather than W as OrdinaryGet and
+ CrossOriginGet will invoke the [[GetOwnProperty]] internal method. Let W be the value of the
+ [[Window]] internal slot of
+ this. Check if an access between two browsing contexts
+ should be reported, given the current global object's browsing
+ context, W's browsing context, P,
+ and the current settings object. If IsPlatformObjectSameOrigin(W) is true, then: If P is an array index property name,
+ then return false. Return ? OrdinarySet(W, P, V,
+ Receiver). Return ? CrossOriginSet(this, P, V,
+ Receiver). this is passed rather than W as CrossOriginSet
+ will invoke the [[GetOwnProperty]]
+ internal method. Let W be the value of the
+ [[Window]] internal slot of
+ this. If IsPlatformObjectSameOrigin(W) is true, then:
+
+ If P is an array index property name, then: Let desc be ! this.[[GetOwnProperty]](P). If desc is undefined, then return true. Return false. Return ? OrdinaryDelete(W, P). Throw a " Assert: O is a Let W be the value of the [[Window]] internal slot of this. If O is a Let maxProperties be W's associated Return «
- { [[Property]]: " Let keys be the range 0 to
+ maxProperties, exclusive. If IsPlatformObjectSameOrigin(W) is true, then return the
+ concatenation of keys and
+ OrdinaryOwnPropertyKeys(W). Return the concatenation of keys and !
+ CrossOriginOwnPropertyKeys(W). This abstract operation does not return a Completion Record. Indexed properties do not need to be safelisted in this algorithm, as they are
- handled directly by the A JavaScript property name P is a cross-origin accessible window property
- name if it is " Each The To create a If P is " Let location be a new Let valueOf be location's relevant
+ realm.[[Intrinsics]].[[%Object.prototype.valueOf%]]. Perform ! location.[[DefineOwnProperty]](" Perform ! location.[[DefineOwnProperty]](@@toPrimitive, {
[[Value]]: undefined,
[[Writable]]: false,
[[Enumerable]]: false,
- [[Configurable]]: true }. Throw a " Set the value of the [[DefaultProperties]] internal slot of
+ location to location.[[OwnPropertyKeys]](). Return location. The addition of Returns a Can be set, to navigate to another page. The The Returns the Can be set, to navigate to the given URL. Returns the Returns the Can be set, to navigate to the same URL with a changed scheme. Returns the Can be set, to navigate to the same URL with a changed host and port. Returns the Can be set, to navigate to the same URL with a changed host. Returns the Can be set, to navigate to the same URL with a changed port. Returns the Can be set, to navigate to the same URL with a changed path. Returns the Can be set, to navigate to the same URL with a changed query (ignores leading " Returns the Can be set, to navigate to the same URL with a changed fragment (ignores leading " Navigates to the given URL. Removes the current page from the session history and navigates to the given URL. Reloads the current page. Returns a A A A Return true if the current settings object's origin is same origin-domain with
- O's relevant settings object's origin, and false otherwise. Let output be a new list of strings. Let current be the While current's container document
+ is non-null: Set current to current's container document. Append the serialization of current's origin to output. Return output. This abstract operation does not return a Completion Record. To Here the current settings object roughly corresponds to the "caller",
- because this check occurs before the execution
- context for the getter/setter/method in question makes its way onto the JavaScript
- execution context stack. For example, in the code Let navigable be location's relevant global object's
+ navigable. Let sourceDocument be the incumbent
+ global object's associated
+ If location's relevant If this abstract operation returns undefined and there is no custom behavior, the
- caller needs to throw a " Navigate navigable to url using
+ sourceDocument, with exceptionsEnabled set to true and historyHandling set to historyHandling. The Let crossOriginKey be a tuple consisting of the current settings
- object, O's relevant settings object, and P. If this's relevant Return this's url, serialized. The If this's relevant Parse the given value relative to the entry
+ settings object. If that failed, throw a " The The If this's relevant Return the serialization of
+ this's url's origin. The If this's relevant Return this's url's scheme, followed by " The If this's relevant If this's relevant Let copyURL be a copy of this's url. For each e of CrossOriginProperties(O): Let possibleFailure be the result of basic URL
+ parsing the given value, followed by " If SameValue(e.[[Property]], P) is true, then: Because the URL parser ignores multiple consecutive colons, providing a value
+ of " If the value of the [[CrossOriginPropertyDescriptorMap]] internal slot of
- O contains an entry whose key is crossOriginKey, then return that
- entry's value. If possibleFailure is failure, then throw a
+ " Let originalDesc be OrdinaryGetOwnProperty(O,
- P). If copyURL's scheme is not an
+ HTTP(S) scheme, then terminate these steps. Let crossOriginDesc be undefined. If e.[[NeedsGet]] and e.[[NeedsSet]] are absent, then: The Let value be originalDesc.[[Value]]. If this's relevant If IsCallable(value) is true, then set value to
- an anonymous built-in function, created in the current realm, that performs
- the same steps as the IDL operation P on object O. Let url be this's url. Set crossOriginDesc to PropertyDescriptor{
- [[Value]]: value,
- [[Enumerable]]: false,
- [[Writable]]: false,
- [[Configurable]]: true }. If url's host is null, return the empty
+ string. Otherwise: If url's port is null, return
+ url's host, serialized. Let crossOriginGet be undefined. Return url's host, serialized, followed by " The If this's relevant If this's relevant Let copyURL be a copy of this's url. If copyURL has an opaque path, then return. Basic URL parse the given value, with
+ copyURL as url and host
+ state as state
+ override. The If this's relevant If this's url's host is null, return the empty string. Return this's url's host, serialized. The If this's relevant If this's relevant Let copyURL be a copy of this's url. If copyURL has an opaque path, then return. Basic URL parse the given value, with
+ copyURL as url and hostname
+ state as state
+ override. The If this's relevant If this's url's port is null, return the empty string. Return this's url's port, serialized. The If this's relevant If this's relevant Let copyURL be a copy of this's url. If e.[[NeedsGet]] is true, then set crossOriginGet to an
- anonymous built-in function, created in the current realm, that performs the
- same steps as the getter of the IDL attribute P on object O. If copyURL cannot have a username/password/port, then
+ return. Let crossOriginSet be undefined. If the given value is the empty string, then set copyURL's port to null. If e.[[NeedsSet]] is true, then set crossOriginSet to an
- anonymous built-in function, created in the current realm, that performs the
- same steps as the setter of the IDL attribute P on object O. Otherwise, basic URL parse the given value, with
+ copyURL as url and port
+ state as state
+ override. Set crossOriginDesc to PropertyDescriptor{
- [[Get]]: crossOriginGet,
- [[Set]]: crossOriginSet,
- [[Enumerable]]: false,
- [[Configurable]]: true }. Create an entry in the value of the [[CrossOriginPropertyDescriptorMap]]
- internal slot of O with key crossOriginKey and value
- crossOriginDesc. The Return crossOriginDesc. If this's relevant Return undefined. Return the result of URL path serializing this
+ This abstract operation does not return a Completion Record. The The reason that the property descriptors produced here are configurable is to
- preserve the invariants of the essential internal methods required by the JavaScript
- specification. In particular, since the value of the property can change as a consequence of
- navigation, it is required that the property be configurable. (However, see tc39/ecma262 issue #672 and references to it
- elsewhere in this specification for cases where we are not able to preserve these invariants, for
- compatibility with existing web content.) If this's relevant The reason the property descriptors are non-enumerable, despite this mismatching
- the same-origin behavior, is for compatibility with existing web content. See issue #3183 for details. If this's relevant Let copyURL be a copy of this's url. Let desc be ? O.[[GetOwnProperty]](P). If copyURL has an opaque path, then return. Assert: desc is not undefined. Set copyURL's path to the empty
+ list. If IsDataDescriptor(desc) is true, then return
- desc.[[Value]]. Basic URL parse the given value, with
+ copyURL as url and path start
+ state as state
+ override. Assert: IsAccessorDescriptor(desc) is true. Let getter be desc.[[Get]]. The If getter is undefined, then throw a " If this's relevant Return ? Call(getter, Receiver). If this's url's query is either null or the empty string, return the empty
+ string. Return " The Let desc be ? O.[[GetOwnProperty]](P). If this's relevant Assert: desc is not undefined. If this's relevant Let copyURL be a copy of this's url. If the given value is the empty string, set copyURL's query to null.
If desc.[[Set]] is present and its value is not undefined, then:
+ Otherwise, run these substeps: Perform ? Call(setter, Receiver,
- «V»). Let input be the given value with a single leading " Return true. Set copyURL's query to the empty
+ string. Basic URL parse input, with null, the
+ relevant Throw a " The Let keys be a new empty List. If this's relevant For each e of CrossOriginProperties(O), append e.[[Property]] to keys. If this's url's fragment is either null or the empty string, return the
+ empty string. Return the concatenation of keys and « " Return " This abstract operation does not return a Completion Record. The If this's relevant If this's relevant Let copyURL be a copy of this's url. Let input be the given value with a single leading " Set copyURL's fragment to the empty
+ string. Basic URL parse input, with
+ copyURL as url and fragment
+ state as state
+ override. If copyURL's fragment is
+ this's url's fragment, then return. This bailout is necessary for compatibility with deployed content, which redundantly sets Unlike the equivalent API for the These attributes all return window. The Returns the If this's relevant If this's relevant Returns the Parse url relative to the entry
+ settings object. If that failed, throw a " The The The If this's relevant The Parse url relative to the entry
+ settings object. If that failed, throw a " The The The The The If this's browsing context is null,
- then return null. Let document be this's relevant
+ Return this's browsing context's
- If document is null, then return. If document's origin is not
+ same origin-domain with the entry settings object's origin, then throw a
+ " Reload document's node navigable. For historical reasons, The If this's relevant If this's relevant Opens a window to show url (defaults to " Otherwise, return this's ancestor origins list. These behave equivalently to the The details of how the Encourages user agents to provide a minimal web browser user interface for the new
- window. (Impacts the As explained earlier, the Returns the name of the window. Also, every Can be set, to change the name. Closes the window. If IsPlatformObjectSameOrigin(this) is true, then return !
+ OrdinaryGetPrototypeOf(this). Returns true if the window has been closed, false otherwise. Return null. Cancels the document load.Cross-Origin-Embedder-Policy` and
+ `Cross-Origin-Embedder-Policy-Report-Only` HTTP response
+ headers allow a server to declare an embedder policy for an environment
+ settings object. These headers are structured
+ headers whose values must be token.
+
+ report-to" parameter can have a valid URL
+ string identifying an appropriate reporting endpoint. unsafe-none") in the presence of a header that cannot
+ be parsed as a token. This includes inadvertent lists created by combining multiple instances of
+ the `Cross-Origin-Embedder-Policy` header present in a given response:
+
+
+
+
+
+
+
+ `
+ Cross-Origin-Embedder-Policy`Final embedder policy value
+
+
+ No header delivered
+ "
+ unsafe-none"
+
+ `
+ require-corp`"
+ require-corp"
+
+ `
+ unknown-value`"
+ unsafe-none"
+
+ `
+ require-corp, unknown-value`"
+ unsafe-none"
+
+ `
+ unknown-value, unknown-value`"
+ unsafe-none"
+
+ `
+ unknown-value, require-corp`"
+ unsafe-none"
+
+
+ `
+ require-corp, require-corp`"
+ unsafe-none"Cross-Origin-Embedder-Policy-Report-Only`.)
+
+
+
+
+
+ Cross-Origin-Embedder-Policy` and "item" from
+ response's header list.
+
+ report-to"] exists, then set policy's endpoint to
+ parsedItem[1]["report-to"].Cross-Origin-Embedder-Policy-Report-Only` and "item"
+ from response's header
+ list.
+
+ report-to"] exists, then set policy's endpoint to
+ parsedItem[1]["report-to"].Embedder policy checks
+
+
+
+
+ navigation", parentPolicy's report only reporting endpoint,
+ "reporting", and navigable's container document's relevant settings
+ object.navigation", parentPolicy's reporting endpoint,
+ "enforce", and navigable's
+ container document's relevant settings
+ object.WorkerGlobalScope
+ workerGlobalScope, an environment settings object owner, and
+ a response response:
+
+
+ DedicatedWorkerGlobalScope object,
+ then return true.worker
+ initialization", owner's policy's report only reporting endpoint,
+ "reporting", and owner.worker initialization", owner's policy's
+ reporting endpoint,
+ "enforce", and owner.
+
+
+
+
+
+
+
+
+
+ key
+ value
+
+
+ type
+ type
+
+
+ blockedURL
+ serialized
+
+
+
+ disposition
+ disposition
+ coep" report type for endpoint on settings.
+ Sandboxing
+
+
+
+
+ target attribute or
+ the window.open() method.document.cookie IDL attribute, and blocks access
+ to localStorage.document.domain
+ browsing context flagdocument.domain setter.
+
+ window.alert()window.confirm()window.print()window.prompt()beforeunload event
+
+
+
+
+
+ allow-popups keyword.allow-top-navigation
+ keyword.allow-top-navigation-by-user-activation
+ keyword or the allow-top-navigation keyword.allow-top-navigation is present, the allow-top-navigation-by-user-activation
+ keyword will have no effect. For this reason, specifying both is a document conformance error.allow-same-origin keyword.allow-same-origin keyword
+ is intended for two cases.allow-forms keyword.allow-pointer-lock
+ keyword.allow-scripts keyword.allow-scripts keyword (defined above).document.domain browsing
+ context flag.allow-popups-to-escape-sandbox
+ keyword.allow-modals keyword.allow-orientation-lock
+ keyword.allow-presentation
+ keyword.allow-downloads keyword.allow-top-navigation-to-custom-protocols
+ keyword, the allow-popups keyword, or
+ the allow-top-navigation
+ keyword.
+
+ iframe element has an iframe sandboxing flag set,
+ which is a sandboxing flag set. Which flags in an iframe
+ sandboxing flag set are set at any particular time is determined by the iframe
+ element's sandbox attribute.Document has an active sandboxing flag set,
+ which is a sandboxing flag set. When the Document is created, its
+ active sandboxing flag set must be empty. It is populated by the navigation algorithm.
+
+
+
+
+ enforce", then continue.sandbox",
+ then append that directive to
+ directives.
+
+
+
+
+
+ iframe sandboxing flag set.Policy containers
+
+ Document, a WorkerGlobalScope, or a WorkletGlobalScope.
+ It has the following items:
+
+
+
+
+
+
+
+
+ blob", then return false.
+
+
+ blob", then return a clone of response's URL's blob URL
+ entry's environment's policy
+ container.unsafe-none".Referrer-Policy` header given response.
+
+
+
+
+ about:srcdoc, then:
+
+ WorkerGlobalScope workerGlobalScope, a response response, and an environment
+ environment:
+
+
+ blob":
+
+ APIs related to navigation and
+ session history
+
+ Security infrastructure for
+
+ Window,
+ WindowProxy, and Location objectsIntegration with IDL
+
+
+
+
+
+ Window or Location object,
+ then return.
+
+
+
+ method" and e has neither
+ [[NeedsGet]] nor [[NeedsSet]], then return.getter" and
+ e.[[NeedsGet]] is true, then return.setter" and
+ e.[[NeedsSet]] is true, then return.SecurityError" DOMException.Shared internal slot: [[CrossOriginPropertyDescriptorMap]]
+
+ Window and Location objects both have a
+ [[CrossOriginPropertyDescriptorMap]] internal slot, whose value is initially an empty
+ map.Window or
+ Location object from objectGlobal. It is filled lazily by
+ CrossOriginGetOwnPropertyHelper, which consults it on future lookups.const href =
+ Object.getOwnPropertyDescriptor(crossOriginLocation, "href").set the value and its
+ corresponding key in the map cannot be garbage collected as that would be observable.document.domain is set. This is not observable as document.domain cannot revisit an earlier value.document.domain
to "example.com" on www.example.com means user agents can remove all
key-value pairs from the map where part of the key is www.example.com, as that can never be part
of the origin again and therefore the corresponding value could never be retrieved
from the map.Shared abstract operations
+ Shared abstract operations
+
+ CrossOriginProperties ( O )
+
+
+
+
+ Location or Window
+ object.Location object, then return «
+ { [[Property]]: "href", [[NeedsGet]]: false, [[NeedsSet]]: true },
+ { [[Property]]: "replace" } ».window", [[NeedsGet]]: true, [[NeedsSet]]: false },
+ { [[Property]]: "self", [[NeedsGet]]: true, [[NeedsSet]]: false },
+ { [[Property]]: "location", [[NeedsGet]]: true, [[NeedsSet]]: true },
+ { [[Property]]: "close" },
+ { [[Property]]: "closed", [[NeedsGet]]: true, [[NeedsSet]]: false },
+ { [[Property]]: "focus" },
+ { [[Property]]: "blur" },
+ { [[Property]]: "frames", [[NeedsGet]]: true, [[NeedsSet]]: false },
+ { [[Property]]: "length", [[NeedsGet]]: true, [[NeedsSet]]: false },
+ { [[Property]]: "top", [[NeedsGet]]: true, [[NeedsSet]]: false },
+ { [[Property]]: "opener", [[NeedsGet]]: true, [[NeedsSet]]: false },
+ { [[Property]]: "parent", [[NeedsGet]]: true, [[NeedsSet]]: false },
+ { [[Property]]: "postMessage" } ».WindowProxy object.window", "self", "location", "close", "closed",
+ "focus", "blur", "frames",
+ "length", "top", "opener",
+ "parent", "postMessage", or an array index
+ property name.CrossOriginPropertyFallback ( P )
+
+
+
+
+ then", @@toStringTag,
+ @@hasInstance, or @@isConcatSpreadable, then return
+ PropertyDescriptor{
+ [[Value]]: undefined,
+ [[Writable]]: false,
+ [[Enumerable]]: false,
+ [[Configurable]]: true }.SecurityError" DOMException.IsPlatformObjectSameOrigin ( O )
+
+
+
+
+ w.document, this
+ step is invoked before the document getter is reached as part
+ of the [[Get]] algorithm for the WindowProxy
+ w.CrossOriginGetOwnPropertyHelper ( O, P )
+
+ SecurityError" DOMException. In
+ practice this is handled by the caller calling CrossOriginPropertyFallback.
+
+
+
+
+
+
+
+
+
+
+ CrossOriginGet ( O, P, Receiver )
+
+
+
+
+ SecurityError"
+ DOMException.CrossOriginSet ( O, P, V,
+ Receiver )
+
+
+
+
+
+
+ SecurityError" DOMException.CrossOriginOwnPropertyKeys ( O )
+
+
+
+
+ then",
+ @@toStringTag, @@hasInstance, @@isConcatSpreadable
+ ».The
+
+ Window object
+
+ [Global=Window,
+ Exposed=Window,
+ LegacyUnenumerableNamedProperties]
+interface Window : EventTarget {
+ // the current browsing context
+ [LegacyUnforgeable] readonly attribute WindowProxy window;
+ [Replaceable] readonly attribute WindowProxy self;
+ [LegacyUnforgeable] readonly attribute Document document;
+ attribute DOMString name;
+ [PutForwards=href, LegacyUnforgeable] readonly attribute Location location;
+ readonly attribute History history;
+ readonly attribute CustomElementRegistry customElements;
+ [Replaceable] readonly attribute BarProp locationbar;
+ [Replaceable] readonly attribute BarProp menubar;
+ [Replaceable] readonly attribute BarProp personalbar;
+ [Replaceable] readonly attribute BarProp scrollbars;
+ [Replaceable] readonly attribute BarProp statusbar;
+ [Replaceable] readonly attribute BarProp toolbar;
+ attribute DOMString status;
+ undefined close();
+ readonly attribute boolean closed;
+ undefined stop();
+ undefined focus();
+ undefined blur();
+
+ // other browsing contexts
+ [Replaceable] readonly attribute WindowProxy frames;
+ [Replaceable] readonly attribute unsigned long length;
+ [LegacyUnforgeable] readonly attribute WindowProxy? top;
+ attribute any opener;
+ [Replaceable] readonly attribute WindowProxy? parent;
+ readonly attribute Element? frameElement;
+ WindowProxy? open(optional USVString url = "", optional DOMString target = "_blank", optional [LegacyNullToEmptyString] DOMString features = "");
+ getter object (DOMString name);
+ // Since this is the global object, the IDL named getter adds a NamedPropertiesObject exotic
+ // object on the prototype chain. Indeed, this does not make the global object an exotic object.
+ // Indexed access is taken care of by the WindowProxy exotic object.
+
+ // the user agent
+ readonly attribute Navigator navigator;
+ readonly attribute Navigator clientInformation; // legacy alias of .navigator
+ readonly attribute boolean originAgentCluster;
+
+ // user prompts
+ undefined alert();
+ undefined alert(DOMString message);
+ boolean confirm(optional DOMString message = "");
+ DOMString? prompt(optional DOMString message = "", optional DOMString default = "");
+ undefined print();
+
+ undefined postMessage(any message, USVString targetOrigin, optional sequence<object> transfer = []);
+ undefined postMessage(any message, optional WindowPostMessageOptions options = {});
+
+ // also has obsolete members
+};
+Window includes GlobalEventHandlers;
+Window includes WindowEventHandlers;
+
+dictionary WindowPostMessageOptions : StructuredSerializeOptions {
+ USVString targetOrigin = "/";
+};
+
+
+ window.windowwindow.frameswindow.selfwindow.documentDocument associated with window.document.defaultViewWindow associated with document, if there is one, or null otherwise.Window object has an associated
+ Document, which is a Document object. It is set when the
+ Window object is created, and only ever changed during navigation from the initial
+ about:blank Document.Window's browsing context is
+ its associated Document's browsing context. It is either null or a
+ browsing context.Window's navigable is the
+ navigable whose active document is the
+ Window's associated
+ Document's, or null if there is no such navigable.window, frames, and self getter steps are to return this's relevant realm.[[GlobalEnv]].[[GlobalThisValue]].document getter steps
+ are to return this's associated
+ Document.Document object associated with a Window object can
+ change in exactly one case: when the navigate algorithm creates a new Document object for the
+ first page loaded in a browsing context. In that specific case, the
+ Window object of the initial
+ about:blank page is reused and gets a new Document object.defaultView getter steps are:
+
+
+ WindowProxy object.
+
+ Window objects must also have a writable, configurable,
+ non-enumerable property named HTMLDocument whose value is the
+ Document interface object.Opening and closing windows
+
+
+
+
+ window = window.open([ url [, target [, features ] ] ])about:blank"), and returns
+ it. target (defaults to "_blank") gives the name of the new
+ window. If a window already exists with that name, it is reused. The features
+ argument can contain a set of comma-separated tokens:
+
+
+ noopener"noreferrer"noopener and noreferrer link types on hyperlinks.popup"visible getter on all
+ BarProp objects as well.)
+ globalThis.open("https://email.example/message/CAOOOkFcWW97r8yg=SsWg7GgCmp4suVX9o85y8BvNRqMjuc5PXg", undefined, "noopener,popup");window.name [ = value ]window.close()window.closedwindow.stop()
+
+
+ Document._blank".noopener"] exists, then:
+
+ noopener"] as a boolean
+ feature.noopener"].noreferrer"] exists, then:
+
+ noreferrer"] as a boolean
+ feature.noreferrer"].no-referrer".onclick handler uses the window.open() API to open a page in an iframe element,
+ the user agent could override the selection of the target browsing context to instead target a
+ new tab.new and unrestricted" or "new with no opener", then:
+
+ about:blank.SyntaxError"
+ DOMException.about:blank, then perform the
+ URL and history update steps given targetNavigable's active document and urlRecord.about:blank?foo. If url is just plain about:blank, this will do nothing.
+
+
+
+ about:blank.SyntaxError" DOMException.new with no
+ opener", then return null.WindowProxy.open(url, target,
+ features) method steps are to run the window open steps with
+ url, target, and features.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ popup"] exists, then return the result of parsing
+ tokenizedFeatures["popup"] as a boolean
+ feature.location", and false.toolbar", and false.menubar", and false.resizable", and true.scrollbars", and false.status", and false.
+
+
+ screenx"
+ left".
+ screeny"
+ top".
+ innerwidth"
+ width".
+ innerheight"
+ height".
+
+
+
+ yes", then return
+ true.true", then return
+ true.
+
+ name getter steps are:
+
+
+ name setter steps are:
+
+
+
+
+ close() method steps
+ are:
+
+
+ Window that does not
+ correspond to a top-level traversable, and so closing is not allowed.
+
+
+
+
+ closed getter
+ steps are to return true if this's browsing context
+ is null or its is closing is true; otherwise false.stop() method steps
+ are:
+
+
+ Indexed access on the
+
+ Window object
+
+
+ window.lengthwindow[index]WindowProxy corresponding to the indicated document-tree child navigables.length getter steps are
+ to return this's associated
+ Document's document-tree child navigables's size.WindowProxy object.Named access on the
+
+ Window object
+
+
+ window[name]document.getElementById() or document.querySelector().Window object window is the
+ return value of running these steps:
+
+
+ Document.
+
+
+
+ https://example.org/, assuming https://elsewhere.example/
+ sets window.name to "spices", evaluating
+ window.spices after everything has loaded will yield undefined:
+ <iframe src=https://elsewhere.example.com/></iframe>
+<iframe name=spices></iframe>Window object supports named
+ properties. The supported property names of a Window object
+ window at any moment consist of the following, in tree order according to
+ the element that contributed them, ignoring later duplicates:
+
+
+ name content attribute for all embed,
+ form, img, and object elements that
+ have a non-empty name content attribute and are in a document
+ tree with window's associated
+ Document as their root; andid content attribute for all HTML
+ elements that have a non-empty id content attribute and are
+ in a document tree with window's associated Document as their
+ root.Window object window, the user agent must return the
+ value obtained using the following steps:
+
+
+
+
+
+ Document's descendants whose nested
+ navigable is in objects.WindowProxy.HTMLCollection rooted at window's associated Document, whose filter matches
+ only named objects of window with
+ the name name. (By definition, these will all be elements.)Window object
+ window with the name name, for the purposes of the above algorithm, consist
+ of the following:
+
+
+ Document whose target name is name;embed, form, img, or
+ object elements that have a name content attribute whose
+ value is name and are in a document tree with window's associated Document as their
+ root; andid content attribute
+ whose value is name and are in a document tree with window's
+ associated Document as their
+ root.Accessing related windows
+
+
+
+
+ window.topWindowProxy for the top-level traversable.window.opener [ = value ]WindowProxy for the opener browsing context.window.parentWindowProxy for the parent
+ navigable.window.frameElementtop getter steps are:
+
+
+ WindowProxy.opener getter steps
+ are:
+
+
+ WindowProxy object.opener setter steps are:
+
+
+ opener", {
+ [[Value]]: the given value, [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true
+ }).window.opener attribute is null. That prevents scripts in the
+ browsing context from changing any properties of its opener browsing
+ context's Window object (i.e., the Window object from which the
+ browsing context was created).window.opener to
+ change properties of its opener browsing context's Window object. For
+ example, a script running in the browsing context can change the value of window.opener.location, causing the opener browsing context to
+ navigate to a completely different document.parent getter steps
+ are:
+
+
+ WindowProxy.frameElement
+ getter steps are:
+
+
+
+
+ <!DOCTYPE html>
+<iframe></iframe>
+
+<script>
+"use strict";
+const element = document.querySelector("iframe");
+const iframeWindow = element.contentWindow;
+element.remove();
+
+console.assert(iframeWindow.top === null);
+console.assert(iframeWindow.parent === null);
+console.assert(iframeWindow.frameElement === null);
+</script>iframeWindow
+ was nulled out when element was
+ removed from the document.Historical browser interface element APIs
+
+ Window interface had some properties that represented
+ the visibility of certain web browser interface elements.Window's browsing context's
+ is popup property is true or false.BarProp object:
+
+ [Exposed=Window]
+interface BarProp {
+ readonly attribute boolean visible;
+};
+
+
+ window.locationbar.visiblewindow.menubar.visiblewindow.personalbar.visiblewindow.scrollbars.visiblewindow.statusbar.visiblewindow.toolbar.visibleWindow is not a popup; otherwise, returns false.visible getter
+ steps are:
+
+
+ BarProp objects must exist for each Window object:
+
+
+ BarProp objectBarProp objectBarProp objectBarProp objectBarProp objectBarProp objectlocationbar
+ attribute must return the location bar BarProp object.menubar
+ attribute must return the menu bar BarProp object.personalbar
+ attribute must return the personal bar BarProp object.scrollbars
+ attribute must return the scrollbar BarProp object.statusbar
+ attribute must return the status bar BarProp object.toolbar
+ attribute must return the toolbar BarProp object.
+
+ status attribute on the Window object must,
+ on getting, return the last string it was set to, and on setting, must set itself to the new
+ value. When the Window object is created, the attribute must be set to the empty
+ string. It does not do anything else.Script settings for
+
+ Window objects
+
+
+
+
+ Document.Document.Document.Document.Document.
+
+ concrete", andDocument is allowed to use the "cross-origin-isolated" feature.Document's load timing info's navigation start
+ time.
+
+ The
+
+ WindowProxy exotic objectWindowProxy is an exotic object that wraps a
+ Window ordinary object, indirecting most operations through to the wrapped object.
+ Each browsing context has an associated WindowProxy object. When the
+ browsing context is navigated, the Window
+ object wrapped by the browsing context's associated WindowProxy object
+ is changed.WindowProxy exotic object must use the ordinary internal methods except where
+ it is explicitly specified otherwise below.WindowProxy interface object.WindowProxy object has a [[Window]] internal slot representing the wrapped Window object.WindowProxy is named as a "proxy", it does not do
+ polymorphic dispatch on its target's internal methods as a real proxy would, due to a desire to
+ reuse machinery between WindowProxy and Location objects. As long as the
+ Window object remains an ordinary object this is unobservable and can be implemented
+ either way.[[GetPrototypeOf]] ( )
+
+
+
+
+ [[SetPrototypeOf]] ( V )
+
+
+
+
+ [[IsExtensible]] ( )
+
+
+
+
+ [[PreventExtensions]] ( )
+
+
+
+
+ [[GetOwnProperty]] ( P )
+
+
+
+
+
+
+ Document.
+
+ Document earlier than
+ navigableB's container was.WindowProxy.
+
+ SecurityError" DOMException.
+
+
+ WindowProxy of the named
+ object of W with the name P.[[DefineOwnProperty]] ( P, Desc
+ )
+
+
+
+
+
+
+
+ SecurityError" DOMException.[[Get]] ( P, Receiver )
+
+
+
+
+ [[Set]] ( P, V, Receiver )
+
+
+
+
+
+
+ [[Delete]] ( P )
+
+
+
-
+
+
+
+
+ SecurityError" DOMException.CrossOriginProperties ( O )
+ [[OwnPropertyKeys]] ( )
-
- Location or Window
- object.Location object, then return «
- { [[Property]]: "href", [[NeedsGet]]: false, [[NeedsSet]]: true },
- { [[Property]]: "replace" } ».Document's document-tree
+ child navigables's size.window", [[NeedsGet]]: true, [[NeedsSet]]: false },
- { [[Property]]: "self", [[NeedsGet]]: true, [[NeedsSet]]: false },
- { [[Property]]: "location", [[NeedsGet]]: true, [[NeedsSet]]: true },
- { [[Property]]: "close" },
- { [[Property]]: "closed", [[NeedsGet]]: true, [[NeedsSet]]: false },
- { [[Property]]: "focus" },
- { [[Property]]: "blur" },
- { [[Property]]: "frames", [[NeedsGet]]: true, [[NeedsSet]]: false },
- { [[Property]]: "length", [[NeedsGet]]: true, [[NeedsSet]]: false },
- { [[Property]]: "top", [[NeedsGet]]: true, [[NeedsSet]]: false },
- { [[Property]]: "opener", [[NeedsGet]]: true, [[NeedsSet]]: false },
- { [[Property]]: "parent", [[NeedsGet]]: true, [[NeedsSet]]: false },
- { [[Property]]: "postMessage" } ».WindowProxy object.window", "self", "location", "close", "closed",
- "focus", "blur", "frames",
- "length", "top", "opener",
- "parent", "postMessage", or an array index
- property name.The
+
+ Location interfaceWindow object is associated with a unique instance of a Location
+ object, allocated when the Window object is created.Location exotic object is defined through a mishmash of IDL,
+ invocation of JavaScript internal methods post-creation, and overridden JavaScript internal
+ methods. Coupled with its scary security policy, please take extra care while implementing
+ this excrescence.CrossOriginPropertyFallback ( P )
+ Location object, run these steps:
-
- then", @@toStringTag,
- @@hasInstance, or @@isConcatSpreadable, then return
- PropertyDescriptor{
+ Location platform
+ object.valueOf", {
+ [[Value]]: valueOf,
+ [[Writable]]: false,
+ [[Enumerable]]: false,
+ [[Configurable]]: false }).SecurityError" DOMException.IsPlatformObjectSameOrigin ( O )
+ valueOf and @@toPrimitive own
+ data properties, as well as the fact that all of Location's IDL attributes are marked
+ [LegacyUnforgeable], is required by legacy code that consulted
+ the Location interface, or stringified it, to determine the document URL, and then used it in a security-sensitive way.
+ In particular, the valueOf, @@toPrimitive, and [LegacyUnforgeable] stringifier mitigations ensure that code such as
+ foo[location] = bar or location + "" cannot be
+ misdirected.
+
+
+ document.location [ = value ]window.location [ = value ]Location object with the current page's location.Document object's location getter steps are to return
+ this's relevant global object's Location object, if
+ this is fully active, and null otherwise.Window object's location getter steps are to return this's
+ Location object.Location objects provide a representation of the URL of their associated Document, as well as
+ methods for navigating and reloading
+ the associated navigable.
+
+ [Exposed=Window]
+interface Location { // but see also additional creation steps and overridden internal methods
+ [LegacyUnforgeable] stringifier attribute USVString href;
+ [LegacyUnforgeable] readonly attribute USVString origin;
+ [LegacyUnforgeable] attribute USVString protocol;
+ [LegacyUnforgeable] attribute USVString host;
+ [LegacyUnforgeable] attribute USVString hostname;
+ [LegacyUnforgeable] attribute USVString port;
+ [LegacyUnforgeable] attribute USVString pathname;
+ [LegacyUnforgeable] attribute USVString search;
+ [LegacyUnforgeable] attribute USVString hash;
+
+ [LegacyUnforgeable] undefined assign(USVString url);
+ [LegacyUnforgeable] undefined replace(USVString url);
+ [LegacyUnforgeable] undefined reload();
+
+ [LegacyUnforgeable, SameObject] readonly attribute DOMStringList ancestorOrigins;
+};
+
+
+ location.toString()location.hrefLocation object's URL.location.originLocation object's URL's origin.location.protocolLocation object's URL's scheme.location.hostLocation object's URL's host and port (if different from the default
+ port for the scheme).location.hostnameLocation object's URL's host.location.portLocation object's URL's port.location.pathnameLocation object's URL's path.location.searchLocation object's URL's query (includes leading "?" if non-empty).?").location.hashLocation object's URL's fragment (includes leading "#" if non-empty).#").location.assign(url)location.replace(url)location.reload()location.ancestorOriginsDOMStringList object listing the origins of the ancestor navigables' active documents.Location object has an associated relevant Document,
+ which is its relevant global object's browsing context's active document, if this
+ Location object's relevant global object's browsing context is non-null, and null otherwise.Location object has an associated url,
+ which is this Location object's relevant Document's URL, if this Location object's relevant
+ Document is non-null, and about:blank otherwise.Location object has an associated ancestor origins list. When a
+ Location object is created, its ancestor origins list must be set to a
+ DOMStringList object whose associated list is the list of strings that
+ the following steps would produce:
-
- Location object's relevant
+ Document.
+
+ Location-object navigate a Location object
+ location to a URL url, optionally given a history
+ handling behavior historyHandling (default "push"):w.document, this
- step is invoked before the document getter is reached as part
- of the [[Get]] algorithm for the WindowProxy
- w.
+
+
+ Document.CrossOriginGetOwnPropertyHelper ( O, P )
+ Document is not yet
+ completely loaded, and the incumbent global
+ object does not have transient activation, then set
+ historyHandling to "replace".SecurityError" DOMException. In
- practice this is handled by the caller calling CrossOriginPropertyFallback.href getter
+ steps are:
-
+
+ Document is non-null and its
+ origin is not same origin-domain with
+ the entry settings object's origin, then throw a
+ "SecurityError" DOMException.href setter steps are:
+
+
+ Document is null, then
+ return.SyntaxError"
+ DOMException.Location-object navigate this to the
+ resulting URL record.href setter intentionally has no
+ security check.origin
+ getter steps are:
+
+
+ Document is non-null and its
+ origin is not same origin-domain with
+ the entry settings object's origin, then throw a
+ "SecurityError" DOMException.protocol
+ getter steps are:
+
+
+ Document is non-null and its
+ origin is not same origin-domain with
+ the entry settings object's origin, then throw a
+ "SecurityError" DOMException.:".protocol setter steps are:
+
- Document is null, then
+ return.Document's origin is not same origin-domain with the
+ entry settings object's origin, then throw a
+ "SecurityError" DOMException.:", with copyURL
+ as url and scheme start state as
+ state override.
-
https:" (or even "https::::") is the same as
+ providing a value of "https".
-
- SyntaxError" DOMException.Location-object navigate this to
+ copyURL.host getter
+ steps are:
-
+
- Document is non-null and its
+ origin is not same origin-domain with
+ the entry settings object's origin, then throw a
+ "SecurityError" DOMException.
-
+
+ :" and url's port, serialized.host setter steps are:
+
+
+ Document is null, then
+ return.Document's origin is not same origin-domain with the
+ entry settings object's origin, then throw a
+ "SecurityError" DOMException.Location-object navigate this to
+ copyURL.hostname
+ getter steps are:
+
+
+ Document is non-null and its
+ origin is not same origin-domain with
+ the entry settings object's origin, then throw a
+ "SecurityError" DOMException.hostname setter steps are:
+
+
+ Document is null, then
+ return.Document's origin is not same origin-domain with the
+ entry settings object's origin, then throw a
+ "SecurityError" DOMException.Location-object navigate this to
+ copyURL.port getter
+ steps are:
+
+
+ Document is non-null and its
+ origin is not same origin-domain with
+ the entry settings object's origin, then throw a
+ "SecurityError" DOMException.port setter steps are:
+
- Document is null, then
+ return.Document's origin is not same origin-domain with the
+ entry settings object's origin, then throw a
+ "SecurityError" DOMException.Location-object navigate this to
+ copyURL.pathname
+ getter steps are:
+
- Document is non-null and its
+ origin is not same origin-domain with
+ the entry settings object's origin, then throw a
+ "SecurityError" DOMException.Location object's url.pathname setter steps are:
+
Document is null, then
+ return.Document's origin is not same origin-domain with the
+ entry settings object's origin, then throw a
+ "SecurityError" DOMException.CrossOriginGet ( O, P, Receiver )
+
-
- Location-object navigate this to
+ copyURL.search
+ getter steps are:SecurityError"
- DOMException.
+
- Document is non-null and its
+ origin is not same origin-domain with
+ the entry settings object's origin, then throw a
+ "SecurityError" DOMException.?", followed by this's url's query.CrossOriginSet ( O, P, V,
- Receiver )
+ search setter steps are:
-
- Document is null, then
+ return.Document's origin is not same origin-domain with the
+ entry settings object's origin, then throw a
+ "SecurityError" DOMException.
-
?" removed, if any.Document's document's character encoding,
+ copyURL as url, and query
+ state as state
+ override.SecurityError" DOMException.Location-object navigate this to
+ copyURL.CrossOriginOwnPropertyKeys ( O )
+ hash getter
+ steps are:
-
- Document is non-null and its
+ origin is not same origin-domain with
+ the entry settings object's origin, then throw a
+ "SecurityError" DOMException.then",
- @@toStringTag, @@hasInstance, @@isConcatSpreadable
- ».#", followed by this's url's fragment.hash setter steps are:
+
-dictionary WindowPostMessageOptions : StructuredSerializeOptions {
- USVString targetOrigin = "/";
-};
+ Document is null, then
+ return.Document's origin is not same origin-domain with the
+ entry settings object's origin, then throw a
+ "SecurityError" DOMException.The
+ Window object[Global=Window,
- Exposed=Window,
- LegacyUnenumerableNamedProperties]
-interface Window : EventTarget {
- // the current browsing context
- [LegacyUnforgeable] readonly attribute WindowProxy window;
- [Replaceable] readonly attribute WindowProxy self;
- [LegacyUnforgeable] readonly attribute Document document;
- attribute DOMString name;
- [PutForwards=href, LegacyUnforgeable] readonly attribute Location location;
- readonly attribute History history;
- readonly attribute CustomElementRegistry customElements;
- [Replaceable] readonly attribute BarProp locationbar;
- [Replaceable] readonly attribute BarProp menubar;
- [Replaceable] readonly attribute BarProp personalbar;
- [Replaceable] readonly attribute BarProp scrollbars;
- [Replaceable] readonly attribute BarProp statusbar;
- [Replaceable] readonly attribute BarProp toolbar;
- attribute DOMString status;
- undefined close();
- readonly attribute boolean closed;
- undefined stop();
- undefined focus();
- undefined blur();
+ #"
+ removed, if any.location.hash on scroll. It does not apply to other
+ mechanisms of fragment navigation, such as the location.href setter or location.assign().Location-object navigate this to
+ copyURL.a and area elements,
+ the hash setter does not special case the empty string, to
+ remain compatible with deployed scripts.
-
+ window.windowwindow.frameswindow.self
+ assign(url) method steps are:window.documentDocument associated with window.
+
Document is null, then
+ return.Document's origin is not same origin-domain with the
+ entry settings object's origin, then throw a
+ "SecurityError" DOMException.document.defaultViewWindow object of the active document.SyntaxError"
+ DOMException.Location-object navigate this to the
+ resulting URL record.Window object has an associated
- Document, which is a Document object. It is set when the
- Window object is created, and only ever changed during navigation from the initial
- about:blank Document.replace(url) method steps are:Window object's browsing
- context is the Window object's associated Document's browsing context. It is either null or a
- browsing context.
+
- Document is null, then
+ return.window, frames, and self getter steps are to return this's relevant realm.[[GlobalEnv]].[[GlobalThisValue]].SyntaxError"
+ DOMException.document getter steps
- are to return this's associated
- Document.Location-object navigate this to the
+ resulting URL record given "replace".Document object associated with a Window object can
- change in exactly one case: when the navigate algorithm creates a new Document object for the
- first page loaded in a browsing context. In that specific case, the
- Window object of the initial
- about:blank page is reused and gets a new Document object.replace() method intentionally has
+ no security check.defaultView getter steps are:reload() method
+ steps are:
-
Document.WindowProxy object.SecurityError" DOMException.
- Window objects must also have a writable, configurable,
- non-enumerable property named HTMLDocument whose value is the
- Document interface object.ancestorOrigins getter steps are:
+
- Document is null, then return
+ an empty list.APIs for creating and navigating browsing contexts by name
+ Document's origin is not same origin-domain with the
+ entry settings object's origin, then throw a
+ "SecurityError" DOMException.
-
window = window.open([ url [, target [, features ] ] ])about:blank"), and returns
- it. target (defaults to "_blank") gives the name of the new
- window. If a window already exists with that name, it is reused. The features
- argument can contain a set of comma-separated tokens:
-
+ noopener"noreferrer"noopener and noreferrer link types on hyperlinks.ancestorOrigins attribute works are still
+ controversial and might change. See issue
+ #1918 for more information.popup"visible getter on all
- BarProp objects as well.)
-
-
+ globalThis.open("https://email.example/message/CAOOOkFcWW97r8yg=SsWg7GgCmp4suVX9o85y8BvNRqMjuc5PXg", undefined, "noopener,popup");Location exotic object
+ requires additional logic beyond IDL for security purposes. The Location object must
+ use the ordinary internal methods except where it is explicitly specified otherwise below.window.name [ = value ]Location object has a [[DefaultProperties]] internal slot
+ representing its own properties at time of its creation.[[GetPrototypeOf]] ( )
- window.close()
+
- window.closedwindow.stop()
Return ! SetImmutablePrototype(this, V).
The window open steps, given a string url, a string target, - and a string features, are as follows:
+If the event loop's termination nesting level is nonzero, return - null.
Let source browsing context be the entry global object's browsing context.
Return true.
If target is the empty string, then set target to "_blank".
Let tokenizedFeatures be the result of tokenizing features.
Return false.
Let noopener and noreferrer be false.
If tokenizedFeatures["noopener"] exists, then:
If IsPlatformObjectSameOrigin(this) is true, then:
Set noopener to the result of parsing tokenizedFeatures["noopener"] as a boolean feature.
Remove tokenizedFeatures["noopener"].
If tokenizedFeatures["noreferrer"] exists, then:
Let desc be OrdinaryGetOwnProperty(this, + P).
Set noreferrer to the result of parsing tokenizedFeatures["noreferrer"] as a boolean feature.
If the value of the [[DefaultProperties]] internal slot of this + contains P, then set desc.[[Configurable]] to true.
Remove tokenizedFeatures["noreferrer"].
Return desc.
If noreferrer is true, then set noopener to true.
Let property be CrossOriginGetOwnPropertyHelper(this, + P).
Let target browsing context and windowType be the result of applying - the rules for choosing a browsing context given target, source - browsing context, and noopener.
+If property is not undefined, then return property.
If there is a user agent that supports control-clicking a link to open it in
- a new tab, and the user control-clicks on an element whose onclick handler uses the window.open() API to open a page in an iframe element, the
- user agent could override the selection of the target browsing context to instead target a new
- tab.
Return ? CrossOriginPropertyFallback(P).
If target browsing context is null, then return null.
If windowType is either "new and unrestricted" or "new with no opener", then:
If IsPlatformObjectSameOrigin(this) is true, then:
Set the target browsing context's is popup to the result of - checking if a popup window is requested, given - tokenizedFeatures.
Set up browsing context features for target browsing context - given tokenizedFeatures.
Let urlRecord be the URL record
- about:blank.
If url is not the empty string, then parse
- url relative to the entry settings object, and set urlRecord
- to the resulting URL record, if any. If the parse a URL algorithm
- failed, then throw a "SyntaxError"
- DOMException.
If urlRecord matches about:blank, then perform the
- URL and history update steps given target browsing context's
- active document and urlRecord.
This is necessary in case url is something like about:blank?foo. If url is just plain about:blank, this will do nothing.
Otherwise:
- -Let request be a new request whose - URL is urlRecord.
If noreferrer is true, then set request's referrer to "no-referrer".
If the value of the [[DefaultProperties]] internal slot of this + contains P, then return false.
Navigate target browsing context to - request, with exceptionsEnabled set to true and the - source browsing context set to source browsing context.
Return ? OrdinaryDefineOwnProperty(this, P, + Desc).
Otherwise:
- -If url is not the empty string, then:
- -Let urlRecord be the URL record
- about:blank.
Parse url relative to the entry
- settings object, and set urlRecord to the resulting URL
- record, if any. If the parse a URL algorithm failed, then throw a
- "SyntaxError" DOMException.
Let request be a new request whose - URL is urlRecord.
If noreferrer is true, then set request's referrer to "noreferrer".
Navigate target browsing context to - request, with exceptionsEnabled set to true and the - source browsing context set to source browsing context.
Throw a "SecurityError" DOMException.
If noopener is false, then set target browsing context's - opener browsing context to source browsing context.
If noopener is true or windowType is "new with no opener", then return null.
If IsPlatformObjectSameOrigin(this) is true, then return ? + OrdinaryGet(this, P, Receiver).
Return target browsing context's WindowProxy object.
Return ? CrossOriginGet(this, P, + Receiver).
The open(url, target,
- features) method steps are to run the window open steps with
- url, target, and features.
The method provides a mechanism for navigating an - existing browsing context or opening and navigating an auxiliary browsing - context.
+If IsPlatformObjectSameOrigin(this) is true, then return ? + OrdinarySet(this, P, V, Receiver).
Return ? CrossOriginSet(this, P, V, + Receiver).
To tokenize the features - argument:
+Let tokenizedFeatures be a new ordered map.
Let position point at the first code point of features.
If IsPlatformObjectSameOrigin(this) is true, then return ? + OrdinaryDelete(this, P).
While position is not past the end of features:
+Throw a "SecurityError" DOMException.
Let name be the empty string.
Let value be the empty string.
If IsPlatformObjectSameOrigin(this) is true, then return + OrdinaryOwnPropertyKeys(this).
Collect a sequence of code points that are feature separators from features given position. This - skips past leading separators before the name.
Return CrossOriginOwnPropertyKeys(this).
Collect a sequence of code points that are not feature separators from features given position. Set - name to the collected characters, converted to ASCII lowercase.
Set name to the result of normalizing the feature name - name.
While position is not past the end of features and the - code point at position in features is not U+003D (=):
+History interfaceIf the code point at position in features is U+002C (,), or if - it is not a feature separator, then break.
enum ScrollRestoration { "auto", "manual" };
- Advance position by 1.
This skips to the first U+003D (=) but does not skip past a U+002C (,) or a - non-separator.
-history.lengthIf the code point at position in features is a feature - separator:
+Returns the number of overall session history + entries for the current traversable navigable.
While position is not past the end of features and the code point - at position in features is a feature separator:
+history.scrollRestorationIf the code point at position in features is U+002C (,), then - break.
Returns the scroll restoration mode of + the active session history entry.
Advance position by 1.
history.scrollRestoration = valueThis skips to the first non-separator but does not skip past a U+002C - (,).
-Set the scroll restoration mode of the + active session history entry to + value.
Collect a sequence of code points that are not feature separators code points from features given - position. Set value to the collected code points, converted to - ASCII lowercase.
history.stateIf name is not the empty string, then set - tokenizedFeatures[name] to value.
Returns the serialized state of the active session history entry, deserialized into a + JavaScript value.
Return tokenizedFeatures.
history.go()To check if a window feature is set, given - tokenizedFeatures, featureName, and defaultValue:
+Reloads the current page.
If tokenizedFeatures[featureName] exists, then return the result of parsing - tokenizedFeatures[featureName] as a boolean feature.
history.go(delta)Return defaultValue.
Goes back or forward the specified number of steps in the overall session history entries list for the current + traversable navigable.
-To check if a popup window is requested, given - tokenizedFeatures:
+A zero delta will reload the current page.
-If tokenizedFeatures is empty, then return - false.
If the delta is out of range, does nothing.
+If tokenizedFeatures["popup"] exists, then return the result of parsing
- tokenizedFeatures["popup"] as a boolean
- feature.
history.back()Let location be the result of checking if
- a window feature is set, given tokenizedFeatures, "location", and false.
Goes back one step in the overall session history + entries list for the current traversable navigable.
-Let toolbar be the result of checking if
- a window feature is set, given tokenizedFeatures, "toolbar", and false.
If there is no previous page, does nothing.
+If location and toolbar are both false, then return true.
history.forward()Let menubar be the result of checking if
- a window feature is set, given tokenizedFeatures, menubar", and false.
Goes forward one step in the overall session + history entries list for the current traversable navigable.
-If menubar is false, then return true.
If there is no next page, does nothing.
+Let resizable be the result of checking if
- a window feature is set, given tokenizedFeatures, "resizable", and true.
history.pushState(data, "")Adds a new entry into session history with its serialized state set to a serialization of + data. The active history entry's + URL will be copied over and used for the new entry's URL.
-If resizable is false, then return true.
(The second parameter exists for historical reasons, and cannot be omitted; passing the + empty string is traditional.)
+Let scrollbars be the result of checking
- if a window feature is set, given tokenizedFeatures, "scrollbars", and false.
history.pushState(data, "", url)Adds a new entry into session history with its serialized state set to a serialization of + data, and with its URL set to url.
-If scrollbars is false, then return true.
If the current Document cannot have
+ its URL rewritten to url, a "SecurityError"
+ DOMException will be thrown.
Let status be the result of checking if
- a window feature is set, given tokenizedFeatures, "status", and false.
(The second parameter exists for historical reasons, and cannot be omitted; passing the + empty string is traditional.)
+If status is false, then return true.
history.replaceState(data, "")Updates the serialized state of the active session history entry to a structured clone of + data.
-Return false.
(The second parameter exists for historical reasons, and cannot be omitted; passing the + empty string is traditional.)
+A code point is a feature separator if it is ASCII whitespace, U+003D - (=), or U+002C (,).
+history.replaceState(data, "", url)Updates the serialized state of the active session history entry to a structured clone of + data, and its URL to url.
-For legacy reasons, there are some aliases of some feature names. To normalize a feature name name, switch on name:
+If the current Document cannot have
+ its URL rewritten to url, a "SecurityError"
+ DOMException will be thrown.
screenx"
- left".
- screeny"
- top".
- innerwidth"
- width".
- innerheight"
- height".
- (The second parameter exists for historical reasons, and cannot be omitted; passing the + empty string is traditional.)
+To parse a boolean feature given - a string value:
+If value is the empty string, then return true.
A Document has a history object, a
+ History object.
If value is "yes", then return
- true.
The history getter steps
+ are to return this's associated
+ Document's history object.
If value is "true", then return
- true.
Let parsed be the result of parsing - value as an integer.
Each History object has state,
+ initially null.
If parsed is an error, then set it to 0.
Each History object has a length, a
+ non-negative integer, initially 0.
Return false if parsed is 0, and true otherwise.
Each History object has an index, a
+ non-negative integer, initially 0.
Although the index is not directly + exposed, it can be inferred from changes to the length during synchronous navigations. In fact, that is + what it's used for.
-The name getter steps are:
The length getter
+ steps are:
If this's browsing context is null, then - return the empty string.
If this's relevant global object's associated Document is not fully
+ active, then throw a "SecurityError"
+ DOMException.
Return this's browsing context's name.
Return this's length.
The name setter steps are:
The scrollRestoration getter steps are:
If this's browsing context is null, then - return.
If this's relevant global object's associated Document is not fully
+ active, then throw a "SecurityError"
+ DOMException.
Set this's browsing context's name to the given value.
Return this's node navigable's active session history entry's scroll restoration mode.
The name gets reset when the browsing context is navigated to another origin.
+The scrollRestoration setter steps
+ are:
If this's relevant global object's associated Document is not fully
+ active, then throw a "SecurityError"
+ DOMException.
The close() method steps
- are:
Set this's node navigable's active session history entry's scroll restoration mode to the given value.
The state getter
+ steps are:
Let current be this's browsing - context.
If this's relevant global object's associated Document is not fully
+ active, then throw a "SecurityError"
+ DOMException.
If current is null or its is closing is true, then - return.
Return this's state.
If all the following are true
+The go(delta)
+ method steps are to delta traverse this given delta.
The back() method steps
+ are to delta traverse this given −1.
The forward() method
+ steps are to delta traverse this given +1.
To delta traverse a History object history given an integer
+ delta:
then:
+Let document be history's relevant global object's
+ associated Document.
Set current's is closing to true.
If document is not fully active, then throw a
+ "SecurityError" DOMException.
Queue a task on the DOM manipulation task source to close current.
If delta is 0, then reload document's node + navigable.
Traverse the history by a delta given document's node + navigable's traversable navigable, + delta, and document.
A browsing context is script-closable if it is an auxiliary
- browsing context that was created by a script (as opposed to by an action of the user), or
- if it is a top-level browsing context whose session history contains
- only one Document.
The pushState(data,
+ unused, url) method steps are to run the shared history
+ push/replace state steps given this, data, url, and
+ "push".
The closed getter
- steps are to return true if this's browsing context
- is null or its is closing is true; otherwise false.
The replaceState(data, unused,
+ url) method steps are to run the shared history push/replace state
+ steps given this, data, url, and "replace".
The stop() method steps
- are to stop document loading given this's associated Document.
The shared history push/replace state steps, given a History
+ history, a value data, a scalar value string-or-null
+ url, and a history handling behavior historyHandling, are:
Let document be history's associated Document.
If document is not fully active, then throw a
+ "SecurityError" DOMException.
Optionally, return. (For example, the user agent might disallow calls to these + methods that are invoked on a timer, or from event listeners that are not triggered in response + to a clear user action, or that are invoked in rapid succession.)
window.lengthLet serializedData be ? + StructuredSerializeForStorage(data).
Returns the number of document-tree child - browsing contexts.
-Let newURL be document's URL.
window[index]If url is not null, then:
-Returns the indicated document-tree child browsing context.
Parse url, relative to the relevant + settings object of history.
If that fails, then throw a "SecurityError"
+ DOMException.
The number of document-tree child browsing
- contexts of a Window object W is the result of running these
- steps:
Set newURL to the resulting URL record.
If W's browsing context is null, then return - 0.
If document cannot have its URL
+ rewritten to newURL, then throw a "SecurityError"
+ DOMException.
Return the number of document-tree - child browsing contexts of W's browsing - context.
Run the URL and history update steps given document and + newURL, with serializedData set to + serializedData and historyHandling set to + historyHandling.
The length getter steps are
- to return the number of document-tree child browsing contexts of
- this.
User agents may limit the number of state objects added to the session history per page. If a
+ page hits the implementation-defined limit, user agents must remove the entry
+ immediately after the first entry for that Document object in the session history
+ after having added the new entry. (Thus the state history acts as a FIFO buffer for eviction, but
+ as a LIFO buffer for navigation.)
Indexed access to document-tree child browsing contexts is defined through the [[GetOwnProperty]] internal method of the
- WindowProxy object.
A Document document can have its URL rewritten to a
+ URL targetURL if the following algorithm returns true:
Let documentURL be document's URL.
If targetURL and documentURL differ in their scheme, username, + password, host, or port + components, then return false.
If targetURL's scheme is an
+ HTTP(S) scheme, then return true. (Differences in path, query, and fragment are allowed for http: and https: URLs.)
Window objectIf targetURL's scheme is "file", and targetURL and documentURL differ in their
+ path component, then return false. (Differences in query and fragment
+ are allowed for file: URLs.)
window[name]If targetURL and documentURL differ in their path component or query + components, then return false. (Only differences in fragment are allowed for other types of URLs.)
Returns the indicated element or collection of elements.
+Return true.
As a general rule, relying on this will lead to brittle code. Which IDs end up mapping to
- this API can vary over time, as new features are added to the web platform, for example. Instead
- of this, use document.getElementById() or document.querySelector().
| document's URL + | targetURL + | can have its URL rewritten + |
|---|---|---|
https://example.com/home
+ | https://example.com/home#about
+ | ✅ + |
https://example.com/home
+ | https://example.com/home?page=shop
+ | ✅ + |
https://example.com/home
+ | https://example.com/shop
+ | ✅ + |
https://example.com/home
+ | https://user:pass@example.com/home
+ | ❌ + |
https://example.com/home
+ | http://example.com/home
+ | ❌ + |
file:///path/to/x
+ | file:///path/to/x#hash
+ | ✅ + |
file:///path/to/x
+ | file:///path/to/x?search
+ | ✅ + |
file:///path/to/x
+ | file:///path/to/y
+ | ❌ + |
about:blank
+ | about:blank#hash
+ | ✅ + |
about:blank
+ | about:blank?search
+ | ❌ + |
about:blank
+ | about:srcdoc
+ | ❌ + |
data:text/html,foo
+ | data:text/html,foo#hash
+ | ✅ + |
data:text/html,foo
+ | data:text/html,foo?search
+ | ❌ + |
data:text/html,foo
+ | data:text/html,bar
+ | ❌ + |
data:text/html,foo
+ | data:bar
+ | ❌ + |
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43
+ | blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43#hash
+ | ✅ + |
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43
+ | blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43?search
+ | ❌ + |
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43
+ | blob:https://example.com/anything
+ | ❌ + |
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43
+ | blob:path
+ | ❌ + |
The document-tree child browsing context
- name property set of a Window object window is the return value of
- running these steps:
Note how only the URL of the Document
+ matters, and not its origin. They can mismatch in
+ cases like about:blank Documents with inherited origins, in sandboxed
+ iframes, or when the document.domain
+ setter has been used.
If window's browsing context is null, then - return the empty list.
Let childBrowsingContexts be all document-tree child browsing contexts of window's browsing context whose browsing context name is not the empty string, in - order, and including only the first document-tree child browsing context with a - given name if multiple document-tree child browsing contexts have the same one.
Consider a game where the user can navigate along a line, such that the user is always at some + coordinate, and such that the user can bookmark the page corresponding to a particular + coordinate, to return to it later.
-Remove each browsing context from childBrowsingContexts whose
- active document's origin is not
- same origin with window's relevant settings object's origin and whose browsing context
- name does not match the name of its container's name content attribute value.
A static page implementing the x=5 position in such a game could look like the following:
-Return the browsing context names of - childBrowsingContexts, in the same order.
<!DOCTYPE HTML>
+<!-- this is https://example.com/line?x=5 -->
+<html lang="en">
+<title>Line Game - 5</title>
+<p>You are at coordinate 5 on the line.</p>
+<p>
+ <a href="?x=6">Advance to 6</a> or
+ <a href="?x=4">retreat to 4</a>?
+</p>This means that in the following example, hosted on https://example.org/, assuming https://elsewhere.example/
- sets window.name to "spices", evaluating
- window.spices after everything has loaded will yield undefined:
The problem with such a system is that each time the user clicks, the whole page has to be + reloaded. Here instead is another way of doing it, using script:
-<iframe src=https://elsewhere.example.com/></iframe>
-<iframe name=spices></iframe><!DOCTYPE HTML>
+<!-- this starts off as https://example.com/line?x=5 -->
+<html lang="en">
+<title>Line Game - 5</title>
+<p>You are at coordinate <span id="coord">5</span> on the line.</p>
+<p>
+ <a href="?x=6" onclick="go(1); return false;">Advance to 6</a> or
+ <a href="?x=4" onclick="go(-1); return false;">retreat to 4</a>?
+</p>
+<script>
+ var currentPage = 5; // prefilled by server
+ function go(d) {
+ setupPage(currentPage + d);
+ history.pushState(currentPage, "", '?x=' + currentPage);
+ }
+ onpopstate = function(event) {
+ setupPage(event.state);
+ }
+ function setupPage(page) {
+ currentPage = page;
+ document.title = 'Line Game - ' + currentPage;
+ document.getElementById('coord').textContent = currentPage;
+ document.links[0].href = '?x=' + (currentPage+1);
+ document.links[0].textContent = 'Advance to ' + (currentPage+1);
+ document.links[1].href = '?x=' + (currentPage-1);
+ document.links[1].textContent = 'retreat to ' + (currentPage-1);
+ }
+</script>The Window object supports named
- properties. The supported property names of a Window object
- window at any moment consist of the following, in tree order according to
- the element that contributed them, ignoring later duplicates:
In systems without script, this still works like the previous example. However, users that + do have script support can now navigate much faster, since there is no network access + for the same experience. Furthermore, contrary to the experience the user would have with just a + naïve script-based approach, bookmarking and navigating the session history still work.
- -window's document-tree child browsing context name property - set;
In the example above, the data argument to the pushState() method is the same information as would be sent
+ to the server, but in a more convenient form, so that the script doesn't have to parse the URL
+ each time the user navigates.
the value of the name content attribute for all embed,
- form, img, and object elements that
- have a non-empty name content attribute and are in a document
- tree with window's associated
- Document as their root; and
Most applications want to use the same scroll restoration mode value for all of
+ their history entries. To achieve this they can set the scrollRestoration attribute as soon as possible
+ (e.g., in the first script element in the document's head element) to
+ ensure that any entry added to the history session gets the desired scroll restoration mode.
<head>
+ <script>
+ if ('scrollRestoration' in history)
+ history.scrollRestoration = 'manual';
+ </script>
+</head>
+ the value of the id content attribute for all HTML
- elements that have a non-empty id content attribute and are
- in a document tree with window's associated Document as their
- root.
To determine the value of a named property
- name in a Window object window, the user agent must return the
- value obtained using the following steps:
Let objects be the list of named - objects of window with the name name.
-There will be at least one such object, by definition.
-PopStateEvent interfaceIf objects contains a browsing context, then return the
- WindowProxy object of the nested browsing context of the first
- browsing context container in tree order whose nested browsing
- context is in objects.
[Exposed=Window]
+interface PopStateEvent : Event {
+ constructor(DOMString type, optional PopStateEventInit eventInitDict = {});
- -
-
Otherwise, if objects has only one element, return that element.
-
+ readonly attribute any state;
+};
- Otherwise return an HTMLCollection rooted at window's associated Document, whose filter matches
- only named objects of window with
- the name name. (By definition, these will all be elements.)
Named objects of Window object
- window with the name name, for the purposes of the above algorithm, consist
- of the following:
event.statedocument-tree child browsing
- contexts of window's associated
- Document whose name is
- name;
Returns a copy of the information that was provided to pushState() or replaceState().
embed, form, img, or
- object elements that have a name content attribute whose
- value is name and are in a document tree with window's associated Document as their
- root; and
HTML elements that have an id content attribute
- whose value is name and are in a document tree with window's
- associated Document as their
- root.
The state attribute must return the value it was
+ initialized to. It represents the context information for the event, or null, if the state
+ represented is the initial state of the Document.
HashChangeEvent interface[Exposed=Window]
+interface HashChangeEvent : Event {
+ constructor(DOMString type, optional HashChangeEventInit eventInitDict = {});
- Discarding browsing contexts
+ readonly attribute USVString oldURL;
+ readonly attribute USVString newURL;
+};
- To discard a
- Document document:
+dictionary HashChangeEventInit : EventInit {
+ USVString oldURL = "";
+ USVString newURL = "";
+};Set document's salvageable state - to false.
event.oldURLRun any unloading document cleanup steps for document that - are defined by this specification and other applicable specifications.
Returns the URL of the session history entry that was previously + current.
+Abort document.
Remove any tasks associated with - document in any task source, without running those tasks.
event.newURLDiscard all the child browsing contexts of document.
Returns the URL of the session history entry that is now + current.
+For each session history entry entry whose document is equal to document, set entry's - document to null.
Set document's browsing context to - null.
The oldURL attribute must return the value it was
+ initialized to. It represents context information for the event, specifically the URL of the
+ session history entry that was traversed from.
Remove document from the
- owner set of each WorkerGlobalScope object whose set contains document.
The newURL attribute must return the value it was
+ initialized to. It represents context information for the event, specifically the URL of the
+ session history entry that was traversed to.
For each workletGlobalScope in - document's worklet global - scopes, terminate - workletGlobalScope.
To discard a browsing - context browsingContext, run these steps:
-Discard all Document objects for all
- the entries in browsingContext's session history.
PageTransitionEvent interfaceIf browsingContext is a top-level browsing context, then - remove browsingContext.
[Exposed=Window]
+interface PageTransitionEvent : Event {
+ constructor(DOMString type, optional PageTransitionEventInit eventInitDict = {});
+
+ readonly attribute boolean persisted;
+};
- User agents may discard top-level browsing contexts at any time (typically, in
- response to user requests, e.g., when a user force-closes a window containing one or more top-level browsing contexts). Other browsing contexts must be discarded once their
- WindowProxy object is eligible for garbage collection, in addition to the other
- places where this specification requires them to be discarded.
+dictionary PageTransitionEventInit : EventInit {
+ boolean persisted = false;
+};event.persistedFor the pageshow event, returns false if the page is
+ newly being loaded (and the load event will fire). Otherwise,
+ returns true.
For the pagehide event, returns false if the page is
+ going away for the last time. Otherwise, returns true, meaning that the page might be reused if
+ the user navigates back to this page (if the Document's salvageable state stays true).
To close a browsing context browsingContext, run these steps:
+Things that can cause the page to be unsalvageable include:
-If the result of calling prompt to unload with browsingContext's
- active document is "refuse", then return.
Document alive in a session
+ history entry after unloadUnload browsingContext's active - document.
iframes that are not salvageableRemove browsingContext from the user interface (e.g., close or hide its tab in - a tabbed browser).
WebSocket objectsDiscard - browsingContext.
DocumentUser agents should offer users the ability to arbitrarily close any top-level browsing context.
+The persisted attribute must return the value
+ it was initialized to. It represents the context information for the event.
To fire a page transition event named eventName at a Window
+ window with a boolean persisted, fire
+ an event named eventName at window, using
+ PageTransitionEvent, with the persisted attribute initialized to
+ persisted, the cancelable attribute
+ initialized to true, the bubbles attribute initialized to
+ true, and legacy target override flag set.
The values for cancelable and bubbles don't make any sense, since canceling the event does
+ nothing and it's not possible to bubble past the Window object. They are set to true
+ for historical reasons.
For historical reasons, the Window interface had some attributes that represented
- the visibility of certain web browser interface elements.
For privacy and interoperability reasons, those attributes now return values that represent
- whether the Window's browsing context's is
- popup property is true or false.
Each interface element is represented by a BarProp object:
BeforeUnloadEvent interface[Exposed=Window]
-interface BarProp {
- readonly attribute boolean visible;
+interface BeforeUnloadEvent : Event {
+ attribute DOMString returnValue;
};window.locationbar.visiblewindow.menubar.visiblewindow.personalbar.visiblewindow.scrollbars.visiblewindow.statusbar.visiblewindow.toolbar.visibleReturns true if the top-level browsing context is not a popup; otherwise, - returns false.
There are no BeforeUnloadEvent-specific initialization methods.
The BeforeUnloadEvent interface is a legacy interface which allows checking
+ if unloading is user-canceled to be controlled not only by canceling the event, but by
+ setting the returnValue attribute to a
+ value besides the empty string. Authors should use the preventDefault() method, or other means of canceling
+ events, instead of using returnValue.
The visible getter steps - are:
+Let browsingContext be this's relevant global - object's browsing context.
The returnValue attribute controls the
+ process of checking if unloading is user-canceled. When the event is created, the
+ attribute must be set to the empty string. On getting, it must return the last value it was set
+ to. On setting, the attribute must be set to the new value.
If browsingContext is null, then return true.
This attribute is a DOMString only for historical reasons.
+ Any value besides the empty string will be treated as a request to ask the user for
+ confirmation.
Return the negation of browsingContext's top-level browsing - context's is popup.
The following BarProp objects must exist for each Window object:
BarProp objectThis standard contains several related concepts for grouping sequences of documents. As a + brief, non-normative summary:
-BarProp objectNavigables are a user-facing representation of a sequence
+ of documents, i.e., they represent something that can be navigated between documents. Typical
+ examples are tabs or windows in a web browser, or iframes, or
+ frames in a frameset.
Traversable navigables are a special type of + navigable which control the session history of themselves and of their descendant navigables. + That is, in addition to their own series of documents, they represent a tree of further series + of documents, plus the ability to linearly traverse back and forward through a flattened view of + this tree.
Browsing contexts are a developer-facing
+ representation of a series of documents. They correspond 1:1 with WindowProxy
+ objects. Each navigable can present a series of browsing contexts, with switches between
+ those browsing contexts occuring under certain well-defined circumstances.
BarProp objectMost of this standard works in the language of navigables, but certain APIs expose the + existence of browsing context switches, and so some parts of the standard need to work in terms + of browsing contexts.
-BarProp objectBarProp objectA navigable presents a Document to the user via its active session history entry. Each navigable has:
BarProp objectAn id, a new unique internal value.
The locationbar
- attribute must return the location bar BarProp object.
A parent, a + navigable or null.
The menubar
- attribute must return the menu bar BarProp object.
A current session history + entry, a session history entry.
-The personalbar
- attribute must return the personal bar BarProp object.
This can only be modified within the session history traversal queue of the + parent traversable navigable.
+The scrollbars
- attribute must return the scrollbar BarProp object.
An active session history entry, a + session history entry.
-The statusbar
- attribute must return the status bar BarProp object.
This can only be modified from the event loop of the active session history entry's document.
+The toolbar
- attribute must return the toolbar BarProp object.
An is closing boolean, initially false.
-This is only ever set to true for top-level traversable navigables.
+For historical reasons, the status attribute on the Window object must,
- on getting, return the last string it was set to, and on setting, must set itself to the new
- value. When the Window object is created, the attribute must be set to the empty
- string. It does not do anything else.
An is delaying load
+ events boolean, initially false.
This is only ever set to true in cases where the navigable's parent is non-null.
+Window objectsThe current session history entry and the + active session history entry are usually the same, + but they get out of sync when:
-To set up a window environment settings object, given a URL - creationURL, a JavaScript execution context execution context, - null or an environment reservedEnvironment, a URL - topLevelCreationURL, and an origin topLevelOrigin, run these - steps:
+Synchronous navigations are performed. This causes the active session history entry to temporarily step ahead + of the current session history entry.
A non-displayable, non-error response is received during history traversal. This updates the current session history entry but leaves the active session history entry as-is.
Let realm be the value of execution context's Realm - component.
Let window be realm's global - object.
A navigable's active document is its active session history entry's document.
-Let settings object be a new environment settings object whose - algorithms are defined as follows:
+This can be safely read from within the session history traversal queue of the
+ navigable's top-level traversable. Although a
+ navigable's active history entry can
+ change synchronously, the new entry will always have the same Document.
Return execution context.
-A navigable's active browsing context is its active document's browsing + context. If this navigable is a traversable navigable, then its + active browsing context will be a top-level browsing + context.
-Return the module map of
- window's associated
- Document.
A navigable's active WindowProxy is its
+ active browsing context's associated WindowProxy.
Return the current character encoding
- of window's associated
- Document.
A navigable's active window is its active WindowProxy's [[Window]].
Return the current base URL of window's
- associated Document.
This will always equal the navigable's active + document's relevant global object; this is kept in sync by the make + active algorithm.
-Return the origin of window's
- associated Document.
A navigable's target + name is its active session history entry's + document state's navigable target name.
-Return the policy container of
- window's associated
- Document.
Return true if both of the following hold, and false otherwise:
-realm's agent cluster's cross-origin-isolation mode is "concrete", and
To get the node navigable of a node node, return the + navigable whose active document is + node's node document, or null if there is no such + navigable.
-window's associated
- Document is allowed to use the "cross-origin-isolated" feature.
Return window's associated
- Document's load timing info's navigation start
- time.
To initialize the navigable navigable navigable, given a + document state documentState and an optional + navigable-or-null parent (default null):
+If reservedEnvironment is non-null, then:
+Let entry be a new session history entry, with
-Set settings object's id to - reservedEnvironment's id, target browsing context to - reservedEnvironment's target browsing context, and active service worker to - reservedEnvironment's active service worker.
Set reservedEnvironment's id to - the empty string.
+The identity of the reserved environment is considered to be fully - transferred to the created environment settings object. The reserved environment - is not searchable by the environment’s id from this point on.
-The caller of this algorithm is responsible for initializing entry's
+ step; it will be left as "pending" until
+ that is complete.
Otherwise, set settings object's id to a new unique opaque string, settings - object's target browsing - context to null, and settings object's active service worker to null.
Set navigable's current session + history entry to entry.
Set settings object's creation - URL to creationURL, settings object's top-level creation - URL to topLevelCreationURL, and settings object's top-level - origin to topLevelOrigin.
Set navigable's active session history + entry to entry.
Set realm's [[HostDefined]] field to settings object.
Set navigable's parent to + parent.
WindowProxy exotic objectA traversable navigable is a navigable that also controls which + session history entry should be the current + session history entry and active session history + entry for itself and its descendant navigables.
-A WindowProxy is an exotic object that wraps a
- Window ordinary object, indirecting most operations through to the wrapped object.
- Each browsing context has an associated WindowProxy object. When the
- browsing context is navigated, the Window
- object wrapped by the browsing context's associated WindowProxy object
- is changed.
In addition to the properties of a navigable, a traversable + navigable has:
-The WindowProxy exotic object must use the ordinary internal methods except where
- it is explicitly specified otherwise below.
A current session history + step, a number, initially 0.
There is no WindowProxy interface object.
Session history + entries, a list of session history + entries, initially a new list.
Every WindowProxy object has a [[Window]] internal slot representing the wrapped Window object.
A session history traversal queue, + a session history traversal parallel queue, the result of starting a new + session history traversal parallel queue.
Although WindowProxy is named as a "proxy", it does not do
- polymorphic dispatch on its target's internal methods as a real proxy would, due to a desire to
- reuse machinery between WindowProxy and Location objects. As long as the
- Window object remains an ordinary object this is unobservable and can be implemented
- either way.
A running nested apply history + step boolean, initially false.
A system visibility state, which is either "hidden" or
+ "visible".
Let W be the value of the - [[Window]] internal slot of - this.
See the page visibility section for the requirements on this + item.
+If IsPlatformObjectSameOrigin(W) is true, then return ! - OrdinaryGetPrototypeOf(W).
To get the traversable navigable of + a navigable inputNavigable:
-Return null.
Let navigable be inputNavigable.
While navigable is not a traversable navigable, set + navigable to navigable's parent.
Return ! SetImmutablePrototype(this, V).
Return navigable.
Return true.
A top-level traversable is a traversable navigable with a null + parent.
-Currently, all traversable navigables + are top-level traversables. Future proposals envision + introducing non-top-level traversables.
-Return false.
A user agent holds a top-level traversable set (a set of top-level traversables). These are typically presented to + the user in the form of browser windows or browser tabs.
-To get the top-level traversable of a navigable + inputNavigable:
Let W be the value of the - [[Window]] internal slot of - this.
Let navigable be inputNavigable.
If P is an array index property name, then:
+While navigable's parent is not null, set + navigable to navigable's parent.
Let index be ! ToUint32(P).
Return navigable.
Let maxProperties be the number of document-tree child browsing - contexts of W.
To create a new top-level traversable + given a browsing context-or-null opener and a string + targetName:
-Let value be undefined.
Let document be null.
If maxProperties is greater than 0 and index is less than
- maxProperties, then set value to the WindowProxy object of
- the indexth document-tree child browsing context of W's
- browsing context, sorted in the order that their browsing context container elements were most
- recently inserted into W's associated
- Document, the WindowProxy object of the most recently inserted
- browsing context container's nested browsing context being
- last.
If opener is null, then set document to the second return value of + creating a new top-level browsing context and document.
If value is undefined, then:
+Otherwise, set document to the second return value of creating a new + auxiliary browsing context and document given opener.
If IsPlatformObjectSameOrigin(W) is true, then return - undefined.
Let documentState be a new document state, with
-Throw a "SecurityError" DOMException.
Return PropertyDescriptor{ - [[Value]]: value, - [[Writable]]: false, - [[Enumerable]]: true, - [[Configurable]]: true }.
If IsPlatformObjectSameOrigin(W) is true, then return ! - OrdinaryGetOwnProperty(W, P).
- -This is a willful violation of the JavaScript specification's - invariants of the essential internal methods to maintain compatibility with - existing web content. See tc39/ecma262 - issue #672 for more information.
-Let traversable be a new traversable navigable.
Let property be CrossOriginGetOwnPropertyHelper(W, - P).
Initialize the navigable traversable given + documentState.
If property is not undefined, then return property.
Let initialHistoryEntry be traversable's active session history entry.
If property is undefined and P is in W's document-tree - child browsing context name property set, then:
+Set initialHistoryEntry's step to 0.
Let value be the WindowProxy object of the named object of W with the name
- P.
+
Append initialHistoryEntry to + traversable's session history + entries.
Return PropertyDescriptor{ - [[Value]]: value, - [[Enumerable]]: false, - [[Writable]]: false, - [[Configurable]]: true }.
+If opener is non-null, then legacy-clone a + traversable storage shed given opener's top-level traversable and traversable.
The reason the property descriptors are non-enumerable, despite this - mismatching the same-origin behavior, is for compatibility with existing web content. See issue #3183 for details.
- -Append traversable to the user agent's + top-level traversable set.
Return ? CrossOriginPropertyFallback(P).
Return traversable.
To create a fresh top-level traversable given a URL + initialNavigationURL and an optional POST resource-or-null + initialNavigationPostResource (default null):
Let W be the value of the - [[Window]] internal slot of - this.
Let traversable be the result of creating a new top-level + traversable given null and the empty string.
If IsPlatformObjectSameOrigin(W) is true, then: +
Navigate traversable to initialNavigationURL using + traversable's active document, with documentResource set to + initialNavigationPostResource.
-If P is an array index property name, return false.
Return ? OrdinaryDefineOwnProperty(W, P, - Desc).
- -This is a willful violation of the JavaScript specification's - invariants of the essential internal methods to maintain compatibility with - existing web content. See tc39/ecma262 - issue #672 for more information.
-We treat these initial navigations as traversable navigating itself, + which will ensure all relevant security checks pass.
+Throw a "SecurityError" DOMException.
Return traversable.
Let W be the value of the - [[Window]] internal slot of - this.
Check if an access between two browsing contexts - should be reported, given the current global object's - browsing context, W's browsing context, P, and the current settings - object.
If IsPlatformObjectSameOrigin(W) is true, then return ? - OrdinaryGet(this, P, Receiver).
Certain elements (for example, iframe elements)
+ can present a navigable to the user. These elements are called navigable containers.
Return ? CrossOriginGet(this, P, - Receiver).
Each navigable container has a nested + navigable, which is either a navigable or null. It is initially null.
-this is passed rather than W as OrdinaryGet and - CrossOriginGet will invoke the [[GetOwnProperty]] internal method.
+The container of a navigable + navigable is the navigable container whose nested navigable + is navigable, or null if there is no such element.
-The container document + of a navigable navigable is the result of running these steps:
Let W be the value of the - [[Window]] internal slot of - this.
Check if an access between two browsing contexts - should be reported, given the current global object's browsing - context, W's browsing context, P, - and the current settings object.
If IsPlatformObjectSameOrigin(W) is true, then:
- -If P is an array index property name, - then return false.
Return ? OrdinarySet(W, P, V, - Receiver).
If navigable's container is null, then + return null.
Return ? CrossOriginSet(this, P, V, - Receiver).
+Return navigable's container's node + document.
-this is passed rather than W as CrossOriginSet - will invoke the [[GetOwnProperty]] - internal method.
+This is equal to navigable's container's shadow-including root as + navigable's container has to be + connected.
The container document of a Document
+ document is the result of running these steps:
Let W be the value of the - [[Window]] internal slot of - this.
If document's node navigable is null, then return null.
If IsPlatformObjectSameOrigin(W) is true, then: +
Return document's node navigable's container document.
If P is an array index property name, then:
+A navigable navigable is a child + navigable of another navigable potentialParent when navigable's parent is potentialParent. We can also just say that a + navigable "is a child navigable", which means that its parent is non-null.
-Let desc be ! this.[[GetOwnProperty]](P).
All child navigables are the nested + navigable of their container.
-If desc is undefined, then return true.
The content document of a navigable + container container is the result of running these steps:
-Return false.
If container's nested navigable is null, then return + null.
Return ? OrdinaryDelete(W, P).
Let document be container's nested navigable's active document.
Throw a "SecurityError" DOMException.
If document's origin and + container's node document's origin are not same origin-domain, then + return null.
Return document.
The content window of a navigable container container is the + result of running these steps:
Let W be the value of the - [[Window]] internal slot of - this.
If container's nested navigable is null, then return + null.
Let keys be a new empty List.
Return container's nested navigable's active
+ WindowProxy's object.
Let maxProperties be the number of document-tree child browsing - contexts of W.
Let index be 0.
To create a new nested navigable, given + an element element:
+ +Let parentNavigable be element's node + navigable.
Let group be element's node document's browsing context's top-level browsing + context's group.
Let browsingContext and document be the result of creating a + new browsing context and document given element's node document, + element, and group.
Let targetName be null.
If element has a name content attribute, then set
+ targetName to the value of that attribute.
Repeat while index < maxProperties, +
Let documentState be a new document state, with
-Add ! ToString(index) as the last element of - keys.
Increment index by 1.
If IsPlatformObjectSameOrigin(W) is true, then return the - concatenation of keys and - OrdinaryOwnPropertyKeys(W).
Let navigable be a new navigable.
Return the concatenation of keys and ! - CrossOriginOwnPropertyKeys(W).
Initialize the navigable navigable given documentState + and parentNavigable.
Set element's nested navigable to navigable.
Let historyEntry be navigable's active session history entry.
Let traversable be parentNavigable's traversable navigable.
Append the following session + history traversal steps to traversable:
-Origins are the fundamental currency of the web's security model. Two actors in the web - platform that share an origin are assumed to trust each other and to have the same authority. - Actors with differing origins are considered potentially hostile versus each other, and are - isolated from each other to varying degrees.
+Let parentDocState be parentNavigable's active session history entry's document state.
For example, if Example Bank's web site, hosted at bank.example.com, tries to examine the DOM of Example Charity's web site, hosted
- at charity.example.org, a "SecurityError"
- DOMException will be raised.
Let targetStepSHE be the first session history entry in + traversable's session history + entries whose document state equals + parentDocState.
Set historyEntry's step to + targetStepSHE's step.
An origin is one of the following:
+Let nestedHistory be a new nested history whose id is navigable's id + and entries list is « historyEntry + ».
An internal value, with no serialization it can be recreated from (it is serialized as
- "null" per serialization of an origin), for which the only
- meaningful operation is testing for equality.
Append nestedHistory to + parentDocState's nested + histories.
A tuple consists of: +
Apply pending history changes to traversable.
Origins can be shared, e.g., among multiple
- Document objects. Furthermore, origins are generally
- immutable. Only the domain of a tuple origin can be changed, and only through the document.domain API.
A useful method for visualizing sequences of documents, and in particular navigables and their session + history entries, is the Jake diagram. A typical Jake diagram is the + following:
-The effective domain of an - origin origin is computed as follows:
+ +| 0 | 1 | 2 | 3 | 4 | |
|---|---|---|---|---|---|
top | /t-a | /t-a#foo | /t-b | ||
frames[0] | /i-0-a | /i-0-b | |||
frames[1] | /i-1-a | /i-1-b | |||
Here, each numbered column denotes a possible value for the traversable's session history step. Each labeled row depicts a
+ navigable, as it transitions between different URLs and documents. The first,
+ labeled top, being the top-level traversable, and the others
+ being nested navigables. The documents are given by the
+ background color of each cell, with a new background color indicating a new document in that
+ navigable. The URLs are given by the text content of the cells; usually they are
+ given as relative URLs for brevity, unless a cross-origin case
+ is specifically under investigation. A given navigable might not exist at a given step, in which
+ case the corresponding cells are empty. The bold-italic step number depicts the current session history step of the traversable,
+ and all cells with bold-italic URLs represent the current session history entry for that row's
+ navigable.
Thus, the above Jake diagram depicts the following sequence of events:
+ +A top-level traversable is created, starting a the URL /t-a, with two nested navigables
+ starting at /i-0-a and /i-1-a
+ respectively.
If origin is an opaque origin, then - return null.
The first nested navigable is navigated to another
+ document, with URL /i-0-b.
If origin's domain is non-null, - then return origin's domain.
The second nested navigable is navigated to another
+ document, with URL /i-1-b.
Return origin's host.
The top-level traversable is navigated to the
+ same document, updating its URL to /t-a#foo.
The top-level traversable is navigated to another
+ document, with URL /t-b. (Notice how this document, of course, does not
+ carry over the old document's nested navigables.)
The traversable was traversed by a + delta of −3, back to step 1.
The serialization of an origin is the string obtained - by applying the following algorithm to the given origin origin:
+Jake diagrams are a powerful tool for visualizing the + interactions of multiple navigables, navigations, and traversals. They cannot capture every + possible interaction — for example, they only work with a single level of nesting — + but we will have ocassion to use them to illustrate several complex situations throughout this + standard.
-If origin is an opaque origin, then
- return "null".
Jake diagrams are named after their creator, + the imitable Jake Archibald.
-Otherwise, let result be origin's scheme.
Append "://" to result.
Append origin's host, serialized, to result.
It is often helpful in this standard's algorithms to look at collections of navigables starting at a given Document. This section
+ contains a curated set of algorithms for collecting those navigables.
If origin's port is non-null, append - a U+003A COLON character (:), and origin's port, serialized, - to result.
The return values of these algorithms are ordered so that parents appears before + their children. Callers rely on this ordering.
-Return result.
Starting with a Document, rather than a navigable, is
+ generally better because it makes the caller cognizant of whether they are starting with a
+ fully active Document or not. Although non-fully active
+ Documents do have ancestor and descendant navigables, they often behave as if they
+ don't (e.g., in the window.parent getter).
The ancestor navigables of a Document document are given by
+ these steps:
The serialization of ("https", "xn--maraa-rta.example", null, null) is "https://xn--maraa-rta.example".
Let navigable be document's node navigable's parent.
Let ancestors be an empty list.
-There used to also be a - Unicode serialization of an origin. However, it was never widely adopted.
+While navigable is not null:
-Prepend navigable to + ancestors.
Set navigable to navigable's parent.
Return ancestors.
Two origins, A and B, are said to be - same origin if the following algorithm returns true:
+The inclusive ancestor navigables of a Document document
+ are given by these steps:
If A and B are the same opaque - origin, then return true.
Let navigables be document's ancestor + navigables.
If A and B are both tuple - origins and their schemes, hosts, and port are - identical, then return true.
Append document's node + navigable to navigables.
Return false.
Return navigables.
Two origins, A and B, are said to be - same origin-domain if the following algorithm returns true:
+The descendant navigables of a
+ Document document are given by these steps:
If A and B are the same opaque - origin, then return true.
Let navigables be new list.
Let navigableContainers be a list of all shadow-including descendants of document + that are navigable containers, in + shadow-including tree order.
If A and B are both tuple - origins, run these substeps:
+For each navigableContainer of + navigableContainers:
If A and B's schemes - are identical, and their domains are identical and - non-null, then return true.
If navigableContainer's nested navigable is null, + continue.
Otherwise, if A and B are same origin and their domains are identical and null, then return - true.
Extend navigables with + navigableContainer's nested navigable's active document's inclusive descendant + navigables.
Return false.
Return navigables.
The inclusive descendant navigables of a Document document
+ are given by these steps:
| A - | B - | same origin - | same origin-domain - |
|---|---|---|---|
("https", "example.org", null, null)
- | ("https", "example.org", null, null)
- | ✅ - | ✅ - |
("https", "example.org", 314, null)
- | ("https", "example.org", 420, null)
- | ❌ - | ❌ - |
("https", "example.org", 314, "example.org")
- | ("https", "example.org", 420, "example.org")
- | ❌ - | ✅ - |
("https", "example.org", null, null)
- | ("https", "example.org", null, "example.org")
- | ✅ - | ❌ - |
("https", "example.org", null, "example.org")
- | ("http", "example.org", null, "example.org")
- | ❌ - | ❌ - |
Let navigables be « document's node navigable + ».
Extend navigables with document's + descendant navigables.
Return navigables.
A scheme-and-host is a tuple of a scheme (an ASCII string) and a host (a host).
+These descendant-collecting algorithms are described as looking at the DOM tree
+ of descendant Document objects. In reality, this is often not feasible since the DOM
+ tree can be in another process from the caller of the algorithm. Instead, implementations
+ generally replicate the appropriate trees across processes.
A site is an opaque origin or a - scheme-and-host.
+The document-tree child navigables of a
+ Document document are given by these steps:
If document's node navigable is null, then return the empty + list.
To obtain a site, given an origin origin, run these steps:
+Let navigables be new list.
If origin is an opaque origin, then - return origin.
Let navigableContainers be a list of all descendants of document that are navigable containers, in tree order.
If origin's host's registrable - domain is null, then return (origin's scheme, origin's host).
For each navigableContainer of + navigableContainers:
-Return (origin's scheme, - origin's host's registrable - domain).
If navigableContainer's nested navigable is null, then + continue.
Append navigableContainer's nested + navigable to navigables.
Return navigables.
Two sites, A and B, are said to be same site if the following algorithm - returns true:
-If A and B are the same opaque - origin, the return true.
If A or B is an opaque - origin, then return false.
To destroy the nested navigable for a navigable container + container:
-If A's and B's scheme values are different, then return - false.
Let nestedNavigable be container's nested + navigable.
If A's and B's host values are not equal, then return false.
If nestedNavigable is null, then return.
Return true.
Set container's nested navigable to null.
The serialization of a site is the string obtained - by applying the following algorithm to the given site site:
+Destroy nestedNavigable's active document.
If site is an opaque origin, then
- return "null".
Let parentDocState be container's node navigable's + active session history entry's document state.
Let result be site[0].
Remove the nested history from + parentDocState's nested + histories whose id equals + nestedNavigable's id.
Append "://" to result.
Let traversable be container's node navigable's traversable navigable.
Append site[1], serialized, to - result.
Append the following session + history traversal steps to traversable:
-Return result.
Apply pending history changes to traversable.
It needs to be clear from context that the serialized value is a site, not an
- origin, as there is not necessarily a syntactic difference between the two. For example, the
- origin ("https", "shop.example", null, null) and
- the site ("https", "shop.example") have the same
- serialization: "https://shop.example".
Two origins, A and B, are said to be schemelessly same site if the following algorithm returns true:
+To destroy a top-level traversable given a top-level traversable + traversable:
If A and B are the same opaque - origin, then return true.
Let browsingContext be traversable's active browsing context.
If A and B are both tuple - origins, then:
+For each historyEntry in + traversable's session history + entries in what order?:
Let hostA be A's host, and let hostB be B's host.
If hostA equals hostB and - hostA's registrable domain is null, then return true.
Let document be historyEntry's document.
If hostA's registrable domain equals hostB's registrable domain and is non-null, then - return true.
If document is not null, then destroy document.
Return false.
Remove browsingContext.
Remove traversable from the user interface (e.g., close or hide its tab in + a tabbed browser).
Remove traversable from the user agent's + top-level traversable set.
Two origins, A and B, are said to be same site if the following algorithm returns true:
+User agents may destroy a top-level traversable at any time (typically, in response to user requests).
+ +To close a + top-level traversable traversable:
Let siteA be the result of obtaining a site - given A.
Let toUnload be traversable's active + document's inclusive descendant navigables.
Let siteB be the result of obtaining a site - given B.
If the result of checking if unloading is user-canceled for + toUnload is true, then return.
If siteA is same site with - siteB, then return true.
Unload the active + documents of each of toUnload. In what + order?
Return false.
Destroy + traversable.
Unlike the same origin and same origin-domain concepts, - for schemelessly same site and same site, the port and domain - components are ignored.
-For the reasons explained in URL, the - same site and schemelessly same site concepts should be avoided when - possible, in favor of same origin checks.
+Given that wildlife.museum, museum, and
- com are public suffixes and that
- example.com is not:
Navigables can be given target
+ names, which are strings allowing certain APIs (such as window.open() or the a element's target attribute) to target navigations at that navigable.
| A - | B - | schemelessly same site - | same site - |
|---|---|---|---|
("https", "example.com")
- | ("https", "sub.example.com")
- | ✅ - | ✅ - |
("https", "example.com")
- | ("https", "sub.other.example.com")
- | ✅ - | ✅ - |
("https", "example.com")
- | ("http", "non-secure.example.com")
- | ✅ - | ❌ - |
("https", "r.wildlife.museum")
- | ("https", "sub.r.wildlife.museum")
- | ✅ - | ✅ - |
("https", "r.wildlife.museum")
- | ("https", "sub.other.r.wildlife.museum")
- | ✅ - | ✅ - |
("https", "r.wildlife.museum")
- | ("https", "other.wildlife.museum")
- | ❌ - | ❌ - |
("https", "r.wildlife.museum")
- | ("https", "wildlife.museum")
- | ❌ - | ❌ - |
("https", "wildlife.museum")
- | ("https", "wildlife.museum")
- | ✅ - | ✅ - |
("https", "example.com")
- | ("https", "example.com.")
- | ❌ - | ❌ - |
A valid navigable target name is any string with + at least one character that does not start with a U+005F LOW LINE character. (Names starting with + an underscore are reserved for special keywords.)
-(Here we have omitted the port and domain components since they are not considered.)
-A valid navigable target name or
+ keyword is any string that is either a valid navigable target name or that is
+ an ASCII case-insensitive match for one of: _blank, _self, _parent, or _top.
These values have different meanings based on whether the page is sandboxed or not, as
+ summarized in the following (non-normative) table. In this table, "current" means the
+ navigable that the link or script is in, "parent" means the parent of the navigable that the link or script is in,
+ "top" means the top-level traversable of the navigable
+ that the link or script is in, "new" means a new traversable navigable with a null
+ parent (which may use an auxiliary browsing
+ context, subject to various user preferences and user agent policies), "none" means that
+ nothing will happen, and "maybe new" means the same as "new" if the "allow-popups" keyword is also specified on the
+ sandbox attribute (or if the user overrode the
+ sandboxing), and the same as "none" otherwise.
| Keyword + | Ordinary effect + | Effect in an iframe with...
+ | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
sandbox=""
+ | sandbox="allow-top-navigation"
-
none specified, for links and form submissions
+ | current
+ | current
+ | current
- | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
If the surrounding agent's agent cluster's is - origin-keyed is true, then return.
Most of the restrictions on sandboxed browsing contexts are applied by + other algorithms, e.g. the navigation algorithm, not the + rules for choosing a navigable given below.
-Set this's origin's domain to the result of parsing the given value.
To determine if a string hostSuffixString is a - registrable domain suffix of or is equal to a host - originalHost, run these steps:
- +The rules + for choosing a navigable, given a string name, a navigable + currentNavigable, and a boolean noopener are as follows:
If hostSuffixString is the empty string, then return false.
Let chosen be null.
Let windowType be "existing or none".
Let hostSuffix be the result of parsing - hostSuffixString.
Let sandboxingFlagSet be currentNavigable's active document's active sandboxing flag set.
If hostSuffix is failure, then return false.
If name is the empty string or an ASCII case-insensitive match
+ for "_self", then set chosen to
+ currentNavigable.
If hostSuffix does not equal - originalHost, then:
+Otherwise, if name is an ASCII case-insensitive match for "_parent", set chosen to currentNavigable's parent, if any, and currentNavigable otherwise.
If hostSuffix or originalHost is not a domain, then return false.
+Otherwise, if name is an ASCII case-insensitive match for "_top", set chosen to currentNavigable's traversable navigable.
This excludes hosts that are IP addresses.
- +Otherwise, if name is not an ASCII case-insensitive match for "_blank", there exists a navigable whose target name is the same as name,
+ currentNavigable's active browsing context is
+ familiar with that navigable's active browsing
+ context, and the user agent determines that the two browsing contexts are related enough
+ that it is ok if they reach each other, set chosen to that navigable. If there are
+ multiple matching navigables, the user agent should pick one in
+ some arbitrary consistent manner, such as the most recently opened, most recently focused, or
+ more closely related, and set chosen to it.
If hostSuffix, prefixed by U+002E (.), does not match the end of - originalHost, then return false.
This will be made more precise in issue #313.
+ -If one of the following is true
+Otherwise, a new top-level traversable is being requested, and what happens + depends on the user agent's configuration and abilities — it is determined by the rules + given for the first applicable option from the following list:
-hostSuffix equals hostSuffix's - public suffix
hostSuffix, prefixed by U+002E (.), matches the end - originalHost's public suffix
The user agent may inform the user that a popup has been blocked.
Assert: originalHost's public suffix, prefixed by - U+002E (.), matches the end of hostSuffix.
The user agent may report to a developer console that a popup has been blocked.
Return true.
| hostSuffixString | -originalHost | -Outcome of is a registrable domain suffix of or is equal to | -Notes | -
|---|---|---|---|
"0.0.0.0" |
- 0.0.0.0 |
- ✅ | -- |
"0x10203" |
- 0.1.2.3 |
- ✅ | -- |
"[0::1]" |
- ::1 |
- ✅ | -- |
"example.com" |
- example.com |
- ✅ | -- |
"example.com" |
- example.com. |
- ❌ | -Trailing dot is significant. | -
"example.com." |
- example.com |
- ❌ | -|
"example.com" |
- www.example.com |
- ✅ | -- |
"com" |
- example.com |
- ❌ | -At the time of writing, com is a public suffix. |
-
"example" |
- example |
- ✅ | -- |
"compute.amazonaws.com" |
- example.compute.amazonaws.com |
- ❌ | -At the time of writing, *.compute.amazonaws.com is a public suffix. |
-
"example.compute.amazonaws.com" |
- www.example.compute.amazonaws.com |
- ❌ | -|
"amazonaws.com" |
- www.example.compute.amazonaws.com |
- ❌ | -|
"amazonaws.com" |
- test.amazonaws.com |
- ✅ | -At the time of writing, amazonaws.com is a registrable domain. |
-
Set windowType to "new and unrestricted".
Let currentDocument be currentNavigable's active document.
If currentDocument's cross-origin opener
+ policy's value is "same-origin" or "same-origin-plus-COEP", and
+ currentDocument's origin is not
+ same origin with currentDocument's relevant settings
+ object's top-level origin, then:
Set noopener to true.
Set name to "_blank".
window.originAgentClusterSet windowType to "new with no opener".
Returns true if this Window belongs to an agent cluster which is
- origin-keyed, in the manner described in
- this section.
In the presence of a cross-origin opener policy, nested + documents that are cross-origin with their top-level browsing context's active document + always set noopener to true.
+A Document delivered over a secure context can request that it be
- placed in an origin-keyed agent
- cluster, by using the `Origin-Agent-Cluster` HTTP
- response header. This header is a structured header
- whose value must be a boolean.
Let chosen be null.
Per the processing model in the create
- and initialize a new Document object, valuesValues
- that are not the structured header boolean
- true value (i.e., `?1`) will be ignored.
Let targetName be the empty string.
The consequences of using this header are that the resulting
- Document's agent cluster key is its origin, instead of the corresponding site. In terms of observable effects, this means that attempting
- to relax the same-origin restriction using
- document.domain will instead do nothing, and it will not
- be possible to send WebAssembly.Module objects to cross-origin Documents
- (even if they are same site). Behind the scenes, this isolation can allow user agents
- to allocate implementation-specific resources corresponding to agent
- clusters, such as processes or threads, more efficiently.
Note that within a browsing context group, the `Origin-Agent-Cluster`
- header can never cause same-origin Document objects to end up in different agent clusters, even if one sends the header and the other
- doesn't. This is prevented by means of the historical agent cluster key
- map.
If name is not an ASCII case-insensitive match for "_blank", then set targetName to name.
This means that the originAgentCluster getter can return false, even if the
- header is set, if the header was omitted on a previously-loaded same-origin page in the same
- browsing context group. Similarly, it can return true even when the header is not
- set.
If noopener is true, then set chosen to the + result of creating a new top-level traversable given null and + targetName.
The originAgentCluster getter steps are to return the
- surrounding agent's agent cluster's is origin-keyed.
Otherwise:
-Documents with an opaque
- origin can be considered unconditionally origin-keyed; for them the header has no effect,
- and the originAgentCluster getter will always return
- true.
Set chosen to the result of creating a new top-level + traversable given currentNavigable's active + browsing context and targetName.
Similarly, Documents whose agent cluster's
- cross-origin isolation mode is not
- "none" are automatically origin-keyed. The
- `Origin-Agent-Cluster` header might be useful as an additional hint to
- implementations about resource allocation, since the `Cross-Origin-Opener-Policy` and
- `Cross-Origin-Embedder-Policy` headers used to achieve cross-origin isolation are
- more about ensuring that everything in the same address space opts in to being there. But adding
- it would have no additional observable effects on author code.
If sandboxingFlagSet's sandboxed navigation browsing context + flag is set, then set chosen's active browsing + context's one permitted sandboxed navigator to + currentNavigable's active browsing + context.
If sandboxingFlagSet's sandbox propagates to auxiliary browsing + contexts flag is set, then all the flags that are set in sandboxingFlagSet + must be set in chosen's active browsing context's + popup sandboxing flag set.
If the newly created navigable chosen is immediately navigated, then the navigation will be done with "replace" history handling behavior.
A sandboxing flag set is a set of zero or more of the following flags, which - are used to restrict the abilities that potentially untrusted resources have:
+Set chosen to currentNavigable.
This flag prevents content from navigating browsing contexts other - than the sandboxed browsing context itself (or browsing contexts further nested inside it), - auxiliary browsing contexts (which are protected - by the sandboxed auxiliary navigation browsing context flag defined next), and the - top-level browsing context (which is protected by the sandboxed top-level - navigation without user activation browsing context flag and sandboxed top-level - navigation with user activation browsing context flag defined below).
+Do nothing.
If the sandboxed auxiliary navigation browsing context flag is not set, then in - certain cases the restrictions nonetheless allow popups (new top-level browsing contexts) to be opened. These browsing contexts always have one permitted sandboxed navigator, set - when the browsing context is created, which allows the browsing context that - created them to actually navigate them. (Otherwise, the sandboxed navigation browsing - context flag would prevent them from being navigated even if they were opened.)
- +User agents are encouraged to provide a way for users to configure the user + agent to always choose currentNavigable.
+ +Return chosen and windowType.
This flag prevents content from creating new auxiliary browsing
- contexts, e.g. using the target attribute or
- the window.open() method.
A browsing context is a programmatic representation of a series of documents,
+ multiple of which can live within a single navigable. Each browsing
+ context has a corresponding WindowProxy object, as well as the following:
An opener browsing context, a browsing context or null, + initially null.
This flag prevents content from navigating their top-level - browsing context and prevents content from closing their - top-level browsing context. It is consulted only when the sandboxed browsing - context's active window does not have transient activation.
+An opener origin at creation, an + origin or null, initially null.
-When the sandboxed top-level navigation without user activation browsing context - flag is not set, content can navigate its top-level browsing - context, but other browsing contexts are still - protected by the sandboxed navigation browsing context flag and possibly - the sandboxed auxiliary navigation browsing context flag.
-A disowned boolean, initially false.
An is popup boolean, initially false.
-The only mandatory impact in this specification of is popup is on
+ the visible getter of the relevant
+ BarProp objects. However, user agents might also use it for user interface considerations.
This flag prevents content from navigating their top-level - browsing context and prevents content from closing their - top-level browsing context. It is consulted only when the sandboxed browsing - context's active window has transient activation.
+An is auxiliary boolean, initially false.
As with the sandboxed top-level navigation without user activation browsing context - flag, this flag only affects the top-level browsing context; if it is not - set, other browsing contexts might still be protected by - other flags.
-An initial URL, a URL or + null, initially null.
A creator base URL, null or an algorithm that returns a URL, + initially null.
A virtual browsing context group ID + integer, initially 0. This is used by cross-origin + opener policy reporting, to keep track of the browsing context group switches that would + have happened if the report-only policy had been enforced.
This flag prevents content from instantiating plugins,
- whether using the embed element, the object element, or through navigation of their nested browsing
- context.
A browsing context's active window is its
+ WindowProxy object's [[Window]]
+ internal slot value. A browsing context's active document is its
+ active window's associated
+ Document.
A browsing context's top-level traversable is + its active document's node navigable's top-level + traversable.
-A browsing context whose is auxiliary is true is known as an auxiliary browsing context. Auxiliary browsing contexts are always top-level browsing contexts.
-This flag forces content into a unique origin, thus preventing - it from accessing other content from the same origin.
+It's unclear whether a separate is auxiliary concept is necessary. In + issue #5680, it is indicated that we may + be able to simplify this by using whether or not the opener browsing context is + null.
-This flag also prevents script from reading from or writing to the
- document.cookie IDL attribute, and blocks access to
- localStorage.
Modern specifications should avoid using the
+ browsing context concept in most cases, unless they are dealing with the subtleties
+ of browsing context
+ group switches and agent cluster allocation. Instead,
+ the Document and navigable concepts are usually more appropriate.
A Document's browsing context is a browsing context or null,
+ initially null.
This flag blocks form submission.
-A Document does not necessarily have a non-null browsing context. In particular, data mining tools are likely
+ to never instantiate browsing contexts. A Document created using an API such as createDocument() never has a non-null browsing context. And the Document originally
+ created for an iframe element, which has since been removed from the document, has no associated browsing context, since that
+ browsing context was nulled out.
In general, there is a 1-to-1 mapping from the Window object to the
+ Document object, as long as the Document object has a non-null browsing context. There is one exception. A
+ Window can be reused for the presentation of a second Document in the
+ same browsing context, such that the mapping is then 1-to-2. This occurs when a
+ browsing context is navigated from the initial about:blank Document to
+ another, which will be done with replacement.
To create a new browsing context and document, given null or a Document
+ object creator, null or an element embedder, and a browsing context
+ group group:
Let browsingContext be a new browsing context.
This flag blocks script execution.
-Let unsafeContextCreationTime be the + unsafe shared current time.
Let creatorOrigin be null.
-If creator is non-null, then:
-This flag blocks features that trigger automatically, such as automatically playing a video or automatically focusing a form control.
-Set creatorOrigin to creator's origin.
Set browsingContext's creator base URL to an algorithm which + returns creator's base URL.
document.domain
- browsing context flagSet browsingContext's virtual browsing context group ID to + creator's browsing context's top-level browsing context's virtual browsing context group ID.
This flag prevents content from using the
- document.domain setter.
Let sandboxFlags be the result of determining the creation sandboxing + flags given browsingContext and embedder.
Let origin be the result of determining the
+ origin given about:blank, sandboxFlags, creatorOrigin,
+ and null.
Let permissionsPolicy be the result of creating a permissions policy + given browsingContext and origin.
-This flag prevents content from escaping the sandbox by ensuring that any - auxiliary browsing context it creates inherits the content's - active sandboxing flag set.
-This needs to use embedder.
+Let agent be the result of obtaining a similar-origin window agent given + origin, group, and false.
This flag prevents content from using any of the following features to produce modal - dialogs:
+Let realm execution context be the result of creating a new realm + given agent and the following customizations:
window.alert()window.confirm()window.print()window.prompt()beforeunload eventFor the global object, create a new Window object.
For the global this binding, use browsingContext's
+ WindowProxy object.
Let topLevelCreationURL be about:blank if embedder is
+ null; otherwise embedder's relevant settings object's top-level
+ creation URL.
This flag disables the ability to lock the screen orientation.
-Let topLevelOrigin be origin if embedder is null; + otherwise embedder's relevant settings object's top-level + origin.
Set up a window environment settings object with about:blank,
+ realm execution context, null, topLevelCreationURL, and
+ topLevelOrigin.
Let loadTimingInfo be a new document load timing info with + its navigation start time set to the result of calling coarsen time + with unsafeContextCreationTime and the new environment settings object's + cross-origin isolated + capability.
Let document be a new Document, with:
This flag prevents content from initiating or instantiating downloads, whether through downloading hyperlinks or through navigation that gets handled as a - download.
-html"text/html"This flag prevents navigations toward non fetch schemes - from being handed off to external - software.
-quirks"When the user agent is to parse a sandboxing directive, given a string - input, a sandboxing flag set output, it must run the following - steps:
+Split input on ASCII - whitespace, to obtain tokens.
Let output be empty.
Add the following flags to output:
+The sandboxed navigation browsing context flag.
about:blankThe sandboxed auxiliary navigation browsing context flag, unless
- tokens contains the allow-popups keyword.
If creator is non-null, then:
-The sandboxed top-level navigation without user activation browsing context
- flag, unless tokens contains the allow-top-navigation
- keyword.
Set document's referrer to the + serialization of creator's URL.
The sandboxed top-level navigation with user activation browsing context flag,
- unless tokens contains either the allow-top-navigation-by-user-activation
- keyword or the allow-top-navigation keyword.
Set document's policy + container to a clone of + creator's policy + container.
If creator's origin is + same origin with creator's relevant settings object's + top-level origin, then set document's cross-origin opener policy to creator's browsing context's top-level + browsing context's active document's cross-origin opener policy.
This means that if the allow-top-navigation is present, the allow-top-navigation-by-user-activation
- keyword will have no effect. For this reason, specifying both is a document conformance error.
Assert: document's URL
+ and document's relevant settings object's creation URL are
+ about:blank.
The sandboxed plugins browsing context flag.
Mark document as ready for post-load tasks.
The sandboxed origin browsing context flag, unless the tokens
- contains the allow-same-origin keyword.
Ensure that document has a single child html node, which itself
+ has two empty child nodes: a head element, and a body element.
The allow-same-origin keyword
- is intended for two cases.
Make active document.
First, it can be used to allow content from the same site to be sandboxed to disable - scripting, while still allowing access to the DOM of the sandboxed content.
+Completely finish loading document.
Second, it can be used to embed content from a third-party site, sandboxed to prevent that - site from opening popups, etc, without preventing the embedded page from communicating back - to its originating site, using the database APIs to store data, etc.
-Return browsingContext and document.
The sandboxed forms browsing context flag, unless tokens
- contains the allow-forms keyword.
To create a new top-level browsing context and document:
-The sandboxed pointer lock browsing context flag, unless tokens
- contains the allow-pointer-lock
- keyword.
Let group and document be the result of creating a new + browsing context group and document.
The sandboxed scripts browsing context flag, unless tokens
- contains the allow-scripts keyword.
Return group's browsing context set[0] and + document.
The sandboxed automatic features browsing context flag, unless tokens contains the allow-scripts keyword (defined above).
To create a new auxiliary browsing context and document, given + a browsing context opener:
-This flag is relaxed by the same keyword as scripts, because when scripts are - enabled these features are trivially possible anyway, and it would be unfortunate to force - authors to use script to do them when sandboxed rather than allowing them to use the - declarative features.
-Let openerTopLevelBrowsingContext be opener's top-level traversable's active browsing + context.
The sandboxed document.domain browsing
- context flag.
Let group be openerTopLevelBrowsingContext's group.
The sandbox propagates to auxiliary browsing contexts flag, unless
- tokens contains the allow-popups-to-escape-sandbox
- keyword.
Assert: group is non-null, as navigating invokes this directly.
The sandboxed modals flag, unless tokens contains the allow-modals keyword.
Set browsingContext and document be the result of creating a + new browsing context and document with opener's active document, null, and group.
The sandboxed orientation lock browsing context flag, unless
- tokens contains the allow-orientation-lock
- keyword.
Set browsingContext's is auxiliary to true.
The sandboxed presentation browsing context flag, unless tokens
- contains the allow-presentation
- keyword.
Append browsingContext to + group.
The sandboxed downloads browsing context flag, unless tokens
- contains the allow-downloads keyword.
Set browsingContext's opener browsing context to + opener.
The sandboxed custom protocols navigation browsing context flag, unless
- tokens contains either the allow-top-navigation-to-custom-protocols
- keyword, the allow-popups keyword, or
- the allow-top-navigation
- keyword.
Set browsingContext's virtual + browsing context group ID to openerTopLevelBrowsingContext's virtual browsing context group ID.
Set browsingContext's opener origin + at creation to opener's active document's + origin.
Return browsingContext and document.
To determine the origin, given a URL + url, a sandboxing flag set sandboxFlags, an + origin-or-null sourceOrigin, and an origin-or-null + containerOrigin:
+ +If sandboxFlags has its sandboxed origin browsing + context flag set, then return a new opaque + origin.
Every top-level browsing context has a popup sandboxing flag set, which - is a sandboxing flag set. When a browsing context is created, its - popup sandboxing flag set must be empty. It is populated by the rules for - choosing a browsing context and the obtain - a browsing context to use for a navigation response algorithm.
+If url is null, then return a new opaque + origin.
Every iframe element has an iframe sandboxing flag set,
- which is a sandboxing flag set. Which flags in an iframe
- sandboxing flag set are set at any particular time is determined by the iframe
- element's sandbox attribute.
If url is about:srcdoc, then:
Every Document has an active sandboxing flag set,
- which is a sandboxing flag set. When the Document is created, its
- active sandboxing flag set must be empty. It is populated by the navigation algorithm.
Assert: containerOrigin is non-null.
Every resource that is obtained by the navigation algorithm has - a forced sandboxing flag set, which is a sandboxing flag set. A - resource by default has no flags set in its forced sandboxing flag set, but other - specifications can define that certain flags are set.
+Return containerOrigin.
In particular, the forced sandboxing flag set is used by - Content Security Policy.
+If url matches about:blank and
+ sourceOrigin is non-null, then return sourceOrigin.
Return url's origin.
To determine the creation sandboxing - flags for a browsing context browsing - context, given null or an element embedder, return the union of the flags that are present in the following sandboxing flag sets:
+The cases that return sourceOrigin or containerOrigin
+ result in two Documents that end up with the same underlying origin, meaning that document.domain affects both.
If embedder is null, then: the flags set on browsing context's - popup sandboxing flag set.
If embedder is an element, then: the flags set on embedder's
- iframe sandboxing flag set.
If embedder is an element, then: the flags set on embedder's - node document's active sandboxing flag set.
A browsing context potentialDescendant is said to be an ancestor of a browsing context + potentialAncestor if the following algorithm returns true:
-After creation, the sandboxing flags for a - browsing context browsing context are the - result of determining the creation sandboxing flags given browsing context - and browsing context's container. +
Let potentialDescendantDocument be potentialDescendant's + active document.
If potentialDescendantDocument is not fully active, then return + false.
Let ancestorBCs be the list obtained by taking the browsing context of the active + document of each member of potentialDescendantDocument's ancestor + navigables.
If ancestorBCs contains + potentialAncestor, then return true.
A cross-origin opener policy value allows a document which is navigated to in a - top-level browsing context to force the creation of a new top-level browsing - context, and a corresponding group. The possible values - are:
+Return false.
unsafe-none"This is the (current) default and means that the document will occupy the same - top-level browsing context as its predecessor, unless that document specified a - different cross-origin opener policy.
A top-level browsing context is a browsing context whose + active document's node navigable is a traversable + navigable.
-same-origin-allow-popups"This forces the creation of a new top-level browsing context for the - document, unless its predecessor specified the same cross-origin opener policy and - they are same origin.
It is not required to be a top-level traversable.
-same-origin"This behaves the same as "same-origin-allow-popups", with the addition that
- any auxiliary browsing context created needs to contain same origin
- documents that also have the same cross-origin opener policy or it will appear
- closed to the opener.
The top-level browsing context of a browsing context + start is the result of the following algorithm:
-
same-origin-plus-COEP"This behaves the same as "same-origin", with the
- addition that it sets the (new) top-level browsing context's group's cross-origin isolation
- mode to one of "logical" or "concrete".
If start's active document is not fully active, then + return null.
"same-origin-plus-COEP" cannot
- be directly set via the `Cross-Origin-Opener-Policy` header, but results
- from a combination of setting both `Cross-Origin-Opener-Policy:
- same-origin` and a
- `Cross-Origin-Embedder-Policy` header whose value is compatible with
- cross-origin isolation together.
-
Let navigable be start's active document's node + navigable.
A cross-origin opener policy consists of:
+While navigable's parent is not null, set + navigable to navigable's parent.
A value, which is a cross-origin opener policy value, initially "unsafe-none".
Return navigable's active browsing + context.
A reporting endpoint, which is string or - null, initially null.
A report-only reporting endpoint, - which is a string or null, initially null.
To match cross-origin opener policy values, given a - cross-origin opener policy value A, an origin - originA, a cross-origin opener policy value B, and an - origin originB:
+A browsing context A is + familiar with a second browsing context B if the following + algorithm returns true:
If A is "unsafe-none" and B
- is "unsafe-none", then return true.
If A's active document's origin is same origin with B's + active document's origin, then return + true.
If A is "unsafe-none" or B is
- "unsafe-none", then return false.
If A's top-level browsing context is + B, then return true.
If A is B and originA is same origin with - originB, then return true.
If B is an auxiliary browsing context and A is + familiar with B's opener browsing context, then return + true.
If there exists an ancestor browsing context of B whose active + document has the same origin as the active document of + A, then return true.
+ +This includes the case where A is an ancestor browsing + context of B.
+Return false.
A Document's cross-origin opener
- policy is derived from the `Cross-Origin-Opener-Policy` and `Cross-Origin-Opener-Policy-Report-Only` HTTP response headers.
- These headers are structured headers whose value must
- be a token.
A top-level browsing context has an associated group (null or a browsing context group). It is initially null.
-The valid token values are the opener policy values. The token may also have
- attached parameters; of these, the "report-to" parameter can have a valid URL
- string identifying an appropriate reporting endpoint.
A user agent holds a browsing context group set (a set of browsing context groups).
-Per the processing model described below, user agents will ignore this header if - it contains an invalid value. Likewise, user agents will ignore this header if the value cannot be - parsed as a token.
+A browsing context group holds a browsing context set (a set + of top-level browsing contexts).
-A top-level browsing context is added to the group when the group is created. All subsequent top-level + browsing contexts added to the group will be + auxiliary browsing contexts.
-To obtain a cross-origin opener policy given a response response and an environment - reservedEnvironment:
+A browsing context group has an associated agent cluster map (a weak + map of agent cluster + keys to agent clusters). User agents are responsible + for collecting agent clusters when it is deemed that nothing can access them anymore.
-Let policy be a new cross-origin opener policy.
A browsing context group has an associated historical agent cluster key + map, which is a map of origins to agent cluster keys. This + map is used to ensure the consistency of the origin-keyed + agent clusters feature by recording what agent cluster keys were previously used for a given + origin.
-If reservedEnvironment is a non-secure context, then return - policy.
The historical agent cluster key map only ever gains entries over the + lifetime of the browsing context group.
-Let value be the result of getting a structured field value given
- `Cross-Origin-Opener-Policy` and "item" from
- response's header list.
A browsing context group has a cross-origin isolation mode, which is a
+ cross-origin isolation mode. It is initially "none".
If parsedItem is not null, then:
+A cross-origin isolation mode is one of three possible values: "none", "logical", or "concrete".
If parsedItem[0] is "same-origin", then:
"logical" and "concrete" are similar. They are both used for
+ browsing context groups where:
Let coep be the result of obtaining a cross-origin embedder policy from response and - reservedEnvironment.
every top-level Document has `Cross-Origin-Opener-Policy: same-origin`, and
If coep's value is
- compatible with cross-origin isolation, then set policy's value to "same-origin-plus-COEP".
every Document has a `Cross-Origin-Embedder-Policy` header
+ whose value is compatible with cross-origin isolation.
Otherwise, set policy's value to "same-origin".
On some platforms, it is difficult to provide the security properties required to grant safe
+ access to the APIs gated by the cross-origin isolated
+ capability. As a result, only "concrete" can grant access that capability.
+ "logical" is used on platform not supporting
+ this capability, where various restrictions imposed by cross-origin isolation will still apply,
+ but the capability is not granted.
If parsedItem[0] is "same-origin-allow-popups", then set
- policy's value to "same-origin-allow-popups".
To create a new browsing context group and document:
-If parsedItem[1]["report-to"] exists and it is a string, then set policy's reporting endpoint to
- parsedItem[1]["report-to"].
Let group be a new browsing context group.
Set parsedItem to the result of getting a structured field value
- given `Cross-Origin-Opener-Policy-Report-Only` and "item"
- from response's header
- list.
Append group to the user agent's + browsing context group set.
If parsedItem is not null, then:
+Let browsingContext and document be the result of creating a + new browsing context and document with null, null, and group.
If parsedItem[0] is "same-origin", then:
Append browsingContext to + group.
Let coep be the result of obtaining a cross-origin embedder policy from response and - reservedEnvironment.
Return group and document.
If coep's value is
- compatible with cross-origin isolation or coep's report-only value is compatible with
- cross-origin isolation, then set policy's report-only value to "same-origin-plus-COEP".
To append a top-level browsing context + browsingContext to a browsing context group group:
-Report only COOP also considers report-only COEP to assign the special
- "same-origin-plus-COEP" value. This allows
- developers more freedom in the order of deployment of COOP and COEP.
Append browsingContext to group's + browsing context set.
Otherwise, set policy's report-only value to "same-origin".
Set browsingContext's group to + group.
If parsedItem[0] is "same-origin-allow-popups", then set
- policy's report-only value to
- "same-origin-allow-popups".
To remove a top-level browsing context + browsingContext:
-If parsedItem[1]["report-to"] exists and it is a string, then set policy's report-only reporting endpoint to
- parsedItem[1]["report-to"].
Assert: browsingContext's group + is non-null.
Return policy.
Let group be browsingContext's group.
Set browsingContext's group to null.
Remove browsingContext from + group's browsing context set.
If group's browsing context set is + empty, then remove group from the user + agent's browsing context group set.
Append and remove are primitive operations that help define the lifetime of a browsing
+ context group. They are called by higher-level creation and destruction operations for
+ Documents and browsing contexts.
When there are no Document objects whose
+ browsing context equals a given browsing
+ context (i.e., all such Documents have been destroyed), and that browsing context's WindowProxy is
+ eligible for garbage collection, then the browsing context will never be accessed
+ again. If it is a top-level browsing context, then at this point the user agent must
+ remove it.
To check if COOP values require - a browsing context group switch, given a boolean isInitialAboutBlank, two origins responseOrigin and - activeDocumentNavigationOrigin, and two cross-origin - opener policy values responseCOOPValue and activeDocumentCOOPValue:
-If the result of matching - activeDocumentCOOPValue, activeDocumentNavigationOrigin, - responseCOOPValue, and responseOrigin is true, return - false.
If all of the following are true:
+A Document d is said to be fully
+ active when d is the active document of a
+ navigable navigable, and either navigable is a top-level
+ traversable or navigable's container
+ document is fully active.
Because they are associated with an element, child
+ navigables are always tied to a specific Document, their container document, in their parent navigable. User agents must not allow the user to interact with
+ child navigables whose container documents are not themselves fully
+ active.
isInitialAboutBlank,
The following example illustrates how a Document can be the active document of its node navigable, while not being
+ fully active. Here a.html is loaded into a browser window,
+ b-1.html starts out loaded into an iframe as shown, and
+ b-2.html and c.html are omitted (they can simply
+ be an empty document).
activeDocumentCOOPValue's value is
- "same-origin-allow-popups".
<!-- a.html -->
+<!DOCTYPE html>
+<html lang="en">
+<title>Navigable A</title>
- responseCOOPValue is "unsafe-none",
then return false.
-
+<!-- b-1.html -->
+<!DOCTYPE html>
+<html lang="en">
+<title>Navigable B</title>
- Return true.
-
+<iframe src="c.html"></iframe>To check if enforcing report-only COOP - would require a browsing context group switch, given a boolean - isInitialAboutBlank, two origins - responseOrigin, activeDocumentNavigationOrigin, and two cross-origin opener policies responseCOOP - and activeDocumentCOOP:
+At this point, the documents given by a.html, b-1.html, and c.html are all the active documents of their respective node navigables. They are also all fully active.
If the result of checking if - COOP values require a browsing context group switch given isInitialAboutBlank, - responseOrigin, activeDocumentNavigationOrigin, responseCOOP's - report-only value and - activeDocumentCOOPReportOnly's report-only value is false, then return false.
+After clicking on the button, and thus loading a new Document from
+ b-2.html into navigable B, we have the following results:
Matching report-only policies allows a website to specify the same report-only - cross-origin opener policy on all its pages and not receive violation reports for navigations - between these pages.
-The a.html Document remains both the active document of navigable A, and fully
+ active.
If the result of checking if - COOP values require a browsing context group switch given isInitialAboutBlank, - responseOrigin, activeDocumentNavigationOrigin, responseCOOP's - value and activeDocumentCOOPReportOnly's report-only value is true, then return true.
The b-1.html Document is now not the active document of navigable B. As such it is also not fully
+ active.
If the result of checking if - COOP values require a browsing context group switch given isInitialAboutBlank, - responseOrigin, activeDocumentNavigationOrigin, responseCOOP's - report-only value and - activeDocumentCOOPReportOnly's value is true, - then return true.
The new b-2.html Document is now the active document of navigable B, and is also fully
+ active.
Return false.
The c.html Document is still the active document of navigable C. However, since C's container document is the b-1.html Document, which is itself not fully active,
+ this means the c.html Document is now not fully
+ active.
A cross-origin opener policy enforcement result is - a struct with the following items:
-A boolean needs a browsing context group - switch, initially false.
A boolean would need a browsing context group switch due - to report-only, initially false.
Welcome to the dragon's maw. Navigation, session history, and the traversal through that + session history are some of the most complex parts of this standard.
-A URL url.
The basic concept may not seem so difficult:
-An origin origin.
The user is looking at a navigable that is presenting its active document. They navigate it to another + URL.
The browser fetches the given URL from the network, using it to populate a new session history entry
+ with a newly-created
+ Document.
The browser updates the navigable's active session history entry to the newly-populated + one, and thus updates the active document that it is showing + to the user.
At some point later, the user presses the + browser back button to go back to the previous session history + entry.
A cross-origin opener policy cross-origin opener policy.
The browser looks at the URL stored in that session + history entry, and uses it to re-fetch and populate that entry's document.
A boolean current context is - navigation source.
The browser again updates the navigable's active session history entry.
To enforce a response's cross-origin opener policy, given a - browsing context browsingContext, a URL - responseURL, an origin responseOrigin, a cross-origin - opener policy responseCOOP, a cross-origin - opener policy enforcement result currentCOOPEnforcementResult, and a referrer referrer:
+You can see some of the intertwined complexity peeking through here, in how traversal can + cause a navigation (i.e., a network fetch to a stored URL), and how a navigation necessarily + needs to interface with the session history list to ensure that when it finishes the user is + looking at the right thing. But the real problems come in with the various edge cases and + interacting web platform features:
-Let newCOOPEnforcementResult be a new cross-origin opener policy enforcement result whose needs a browsing context group switch is - currentCOOPEnforcementResult's needs a - browsing context group switch, would need a browsing context group switch due - to report-only is currentCOOPEnforcementResult's would need a browsing context group switch due - to report-only, url is responseURL, - origin is responseOrigin, - coop is responseCOOP, and - current context is navigation source is - true.
Nested navigables (e.g., iframes) can
+ also navigate and traverse, but those navigations need to be linearized into a single session history list since the user only has
+ a single back/forward interface for the entire traversable navigable (e.g., browser
+ tab).
Since the user can traverse back more than a single step in the session history (e.g., by + holding down their back button), they can end up traversing multiple navigables at the same time when nested navigables are involved. This needs to be synchronized across all of + the involved navigables, which might involve multiple event + loops or even agent clusters.
During navigation, servers can respond with 204 or 205 status codes or with `Content-Disposition: attachment` headers, which cause
+ navigation to abort and the navigable to stay on its original active document. (This is much worse if it happens during a traversal-initiated
+ navigation!)
Various other HTTP headers, such as `Location`,
+ `Refresh`, `X-Frame-Options`, and those for Content Security Policy,
+ contribute to either the fetching
+ process, or the Document-creation
+ process, or both. The `Cross-Origin-Opener-Policy` header even contributes
+ to the browsing
+ context selection and creation process!
Some navigations (namely fragment navigations and single-page app navigations) are synchronous, meaning that + JavaScript code expects to observe the navigation's results instantly. This then needs to be + synchronized with the view of the session history that all other navigables in the tree see, which can be subject to race conditions + and necessitate resolving conflicting views of the session history.
The platform has accumulated various exciting navigation-related features that need
+ special-casing, such as javascript: URLs, srcdoc iframes, and the beforeunload event.
Let isInitialAboutBlank be true if browsingContext is still on
- its initial about:blank Document; otherwise, false.
In what follows, we have attempted to guide the reader through these complexities by + appropriately cordoning them off into labeled sections and algorithms, and giving appropriate + words of introduction where possible. Nevertheless, if you wish to truly understand navigation + and session history, the usual advice will be + invaluable.
-If isInitialAboutBlank is true and browsingContext's initial URL is null, set - browsingContext's initial URL to - responseURL.
If the result of checking if - COOP values require a browsing context group switch given isInitialAboutBlank, - currentCOOPEnforcementResult's cross-origin - opener policy's value, - currentCOOPEnforcementResult's origin, - responseCOOP's value, and - responseOrigin is true, then:
+Set newCOOPEnforcementResult's needs a browsing context group switch to - true.
If browsingContext's group's browsing - context set's size is greater than 1, then:
+A session history entry is a struct with the following items:
-Queue a violation report for browsing
- context group switch when navigating to a COOP response with responseCOOP,
- "enforce", responseURL,
- currentCOOPEnforcementResult's url,
- currentCOOPEnforcementResult's origin, responseOrigin, and
- referrer.
step, a non-negative integer or "pending", initially "pending".
Queue a violation report for browsing
- context group switch when navigating away from a COOP response with
- currentCOOPEnforcementResult's cross-origin
- opener policy, "enforce",
- currentCOOPEnforcementResult's url,
- responseURL, currentCOOPEnforcementResult's origin, responseOrigin, and
- currentCOOPEnforcementResult's current
- context is navigation source.
URL, a URL
If the result of checking if - enforcing report-only COOP would require a browsing context group switch given - isInitialAboutBlank, responseOrigin, - currentCOOPEnforcementResult's origin, - responseCOOP, and currentCOOPEnforcementResult's cross-origin opener policy, is true, then:
+document state, a document + state.
Set result's would - need a browsing context group switch due to report-only to true.
serialized state, which is serialized + state or null, initially null.
If browsingContext's group's browsing - context set's size is greater than 1, then:
+scroll restoration mode, a scroll
+ restoration mode, initially "auto".
Queue a violation report for browsing context group switch
- when navigating to a COOP response with responseCOOP, "reporting", responseURL,
- currentCOOPEnforcementResult's url,
- currentCOOPEnforcementResult's origin,
- responseOrigin, and referrer.
scroll position data, which is scroll position + data for the document's restorable scrollable + regions.
Queue a violation report for browsing
- context group switch when navigating away from a COOP response with
- currentCOOPEnforcementResult's cross-origin
- opener policy, "reporting",
- currentCOOPEnforcementResult's url,
- responseURL, currentCOOPEnforcementResult's origin, responseOrigin, and
- currentCOOPEnforcementResult's current
- context is navigation source.
persisted user state, + which is implementation-defined, initially null
+ +For example, some user agents might want to persist the values of form + controls.
+ +User agents that persist the value of form controls are encouraged to also
+ persist their directionality (the value of the element's dir
+ attribute). This prevents values from being displayed incorrectly after a history traversal
+ when the user had originally entered the values with an explicit, non-default
+ directionality.
Return newCOOPEnforcementResult.
To get a session history entry's document, + return its document state's document.
-To obtain a browsing context to use for a - navigation response, given a browsing context - browsingContext, a sandboxing flag set sandboxFlags, a - cross-origin opener policy navigationCOOP, and a cross-origin opener policy enforcement result - coopEnforcementResult:
+If browsingContext is not a top-level browsing context, - return browsingContext.
Serialized state is a serialization (via + StructuredSerializeForStorage) of an object representing a user interface state. We + sometimes informally refer to "state objects", which are the objects representing user interface + state supplied by the author, or alternately the objects created by deserializing (via + StructuredDeserialize) serialized state.
-If coopEnforcementResult's needs a - browsing context group switch is false, then:
+Pages can add serialized state to the + session history. These are then deserialized and returned to the script when the user (or script) goes back in the + history, thus enabling authors to use the "navigation" metaphor even in one-page applications.
-If coopEnforcementResult's would need a browsing context group switch due - to report-only is true, set browsing context's virtual browsing context group ID to a new - unique identifier.
Serialized state is intended to be used for two main purposes: first, storing a
+ preparsed description of the state in the URL so that in the simple case an author
+ doesn't have to do the parsing (though one would still need the parsing for handling URLs passed around by users, so it's only a minor optimization). Second, so
+ that the author can store state that one wouldn't store in the URL because it only applies to the
+ current Document instance and it would have to be reconstructed if a new
+ Document were opened.
Return browsingContext.
An example of the latter would be something like keeping track of the precise coordinate from
+ which a popup div was made to animate, so that if the user goes back, it can be made
+ to animate to the same location. Or alternatively, it could be used to keep a pointer into a
+ cache of data that would be fetched from the server based on the information in the
+ URL, so that when going back and forward, the information doesn't have to be fetched
+ again.
Let newBrowsingContext be the result of creating a new top-level browsing - context.
If navigationCOOP's value is "same-origin-plus-COEP", then set
- newBrowsingContext's group's cross-origin isolation mode to either "logical" or "concrete". The choice of which is
- implementation-defined.
A scroll restoration mode indicates whether the user agent should restore the + persisted scroll position (if any) when traversing to an entry. A scroll restoration mode is one of the following:
-It is difficult on some platforms to provide the security properties required by
- the cross-origin
- isolated capability. "concrete"
- grants access to it and "logical" does
- not.
auto"manual"Document state holds state inside a session history entry regarding
+ how to present and, if necessary, recreate, a Document. It has:
A document, a Document or null,
+ initially null.
When a history entry is active, it has a
+ Document in its document state. However,
+ when a Document is not fully active, it's possible for it to be
+ destroyed to free resources. In such cases, this
+ document item will be nulled out. The URL and other data in the session history entry and document state is then used to bring a new
+ Document into being to take the place of the original, in the case where the user
+ agent finds itself having to traverse to the entry.
If the Document is not destroyed, then during history
+ traversal, it can be reactivated. The cache
+ in which browsers store such Documents is often called a back-forward
+ cache, or bfcache (or perhaps "blazingly fast" cache).
A history
+ policy container, a policy container or "client",
+ initially "client".
A request referrer, which is "no-referrer", "client", or a URL, initially
+ "client".
If sandboxFlags is not empty, then:
-Assert navigationCOOP's value is
- "unsafe-none".
A request referrer policy, which + is a referrer policy, initially the default referrer policy.
-Assert: newBrowsingContext's popup sandboxing flag - set is empty.
The request referrer + policy is distinct from the history policy container's referrer policy. The former is used for + fetches of this document, whereas the latter controls fetches by this + document.
+Set newBrowsingContext's popup sandboxing flag set to - a clone of sandboxFlags.
An initiator origin, which is an + origin or null, initially null.
Discard browsingContext.
+An origin, which is an origin or + null, initially null.
-This has no effect on browsingContext's group, unless browsingContext was its sole top-level browsing - context. In that case, the user agent might delete the browsing context - group which no longer contains any browsing - contexts.
+This is the origin that we set "about:"-schemed
+ Documents' origin to. We store it
+ here because it is also used when restoring these Documents during traversal,
+ since they are reconstructed locally without visiting the network. It is also used to compare
+ the origin before and after the session history entry is repopulated. If the origins change, the navigable target name is cleared.
Return newBrowsingContext.
Nested histories, a list + of nested histories, initially an empty + list.
The impact of swapping browsing context groups following a navigation is not - fully defined. It is currently under discussion in issue #5350.
+A resource, a string, POST resource + or null, initially null.
-A string is treated as HTML. It's used to store the source of an iframe srcdoc document.
An accessor-accessed relationship is an enum that describes the relationship between - two browsing contexts between which an access happened. It - can take the following values:
+A reload pending boolean, initially + false.
The accessor browsing context or one of its ancestors is the opener browsing context of the accessed - browsing context's top-level browsing context.
An ever populated boolean, initially + false.
The accessed browsing context or one of its ancestors is the opener browsing context of the accessor - browsing context's top-level browsing context.
A navigable target + name string, initially the empty string.
There is no opener relationship between the accessor browsing context, the - accessor browsing context, or any of their ancestors.
User agents may destroy the documents of document
+ states with non-null documents, as long as
+ the Document is not fully active.
To check if an access between two browsing contexts - should be reported, given two browsing contexts - accessor and accessed, a JavaScript property name - P, and an environment settings object environment:
+Apart from that restriction, this standard does not specify when user agents should destroy + the document stored in a document + state, versus keeping it cached.
-If P is not a cross-origin accessible window property name, then - return.
A POST resource has:
+ +If accessor's active document's origin or any of its ancestors' active document's origins are not same origin with - accessor's top-level browsing context's active document's - origin, or if accessed's active - document's origin or any of its ancestors' active document's origins are not same origin with - accessed's top-level browsing context's active document's - origin, then return.
+A request body, a + byte sequence or failure.
-This avoids leaking information about cross-origin iframes to a top level frame - with cross-origin opener policy reporting.
+This is only ever accessed in parallel, so it doesn't need to be stored in + memory. However, it must return the same byte sequence each time. If this isn't + possible due to resources changing on disk, or if resources can no longer be accessed, then + this must be set to failure.
If accessor's top-level browsing context's virtual browsing context group ID is - accessed's top-level browsing context's virtual browsing context group ID, then - return.
A request
+ content-type, which is `application/x-www-form-urlencoded`,
+ `multipart/form-data`, or `text/plain`.
Let accessorAccessedRelationship be a new accessor-accessed - relationship with value none.
If accessed's top-level browsing context's opener browsing - context is accessor or an ancestor of accessor, then set accessorAccessedRelationship to - accessor is opener.
A nested history has:
-If accessor's top-level browsing context's opener browsing - context is accessed or an ancestor of accessed, then set accessorAccessedRelationship to - accessor is openee.
An id, a unique internal value.
-Queue violation reports for accesses, given - accessorAccessedRelationship, accessor's top-level browsing - context's active document's cross-origin - opener policy, accessed's top-level browsing context's active - document's cross-origin opener policy, - accessor's active document's URL, - accessed's active document's URL, - accessor's top-level browsing context's initial URL, accessed's top-level - browsing context's initial URL, - accessor's active document's origin, accessed's active - document's origin, accessor's - top-level browsing context's opener origin - at creation, accessed's top-level browsing context's opener origin at creation, accessor's - top-level browsing context's active document's referrer, accessed's top-level browsing - context's active document's referrer, P, and - environment.
This is used to associate the nested history with a + navigable.
+ -Entries, a list of session history entries.
To sanitize a URL to send in a report given a - URL url:
+This will later contain ways to identify a nested navigable across reloads.
-Let sanitizedURL be a copy of url.
Set the username given sanitizedURL and - the empty string. +
Set the password given sanitizedURL and - the empty string. +
Several contiguous entries in a session history can share the same document state. This can occur when the initial entry is
+ reached via normal navigation, and the following entry is added
+ via history.pushState(). Or it can occur via navigation to a fragment.
Return the serialization of - sanitizedURL with exclude - fragment set to true.
All entries that share the same document + state (and that are therefore merely different states of one particular document) are + contiguous by construction.
-To queue a violation report for browsing context group - switch when navigating to a COOP response given a cross-origin opener policy coop, a string disposition, a - URL coopURL, a URL previousResponseURL, two origins coopOrigin and previousResponseOrigin, and a - referrer referrer:
+If coop's reporting endpoint - is null, return.
A Document has a latest entry, a session history entry or
+ null.
Let coopValue be coop's value.
This is the entry that was most recently represented by a given
+ Document. A single Document can represent many session history entries over time, as many contiguous session history entries can share the same document state as explained above.
To maintain a single source of truth, all modifications to a traversable + navigable's session history entries need + to be synchronized. This is especially important due to how session history is influenced by all + of the descendant navigables, and thus by multiple event loops. To accomplish this, we use the session history + traversal parallel queue structure.
+ +A session history traversal parallel queue is + very similar to a parallel queue. It has an algorithm set, an ordered set.
+ +The items in a session history traversal parallel + queue's algorithm + set are either algorithm steps, or synchronous navigation + steps, which are a particular brand of algorithm steps involving a target + navigable (a navigable).
+ +To append session history traversal + steps to a traversable navigable traversable given algorithm steps + steps, append steps to + traversable's session history + traversal queue's algorithm set.
+ +To append session history synchronous + navigation steps to a traversable navigable traversable given + algorithm steps steps and a navigable targetNavigable, append steps as synchronous navigation + steps targeting target + navigable targetNavigable to traversable's session history traversal queue's algorithm set.
+ +To start a new session history traversal parallel queue:
+ +Let sessionHistoryTraversalQueue be a new session history traversal + parallel queue.
If disposition is "reporting", then set
- coopValue to coop's report-only value.
Run the following steps in parallel:
-Let serializedReferrer be an empty string.
While true:
-If referrer is a URL, set serializedReferrer to the - serialization of referrer. +
If sessionHistoryTraversalQueue's algorithm set is + empty, then continue.
Let body be a new object containing the following properties:
+Let steps be the result of dequeuing from + sessionHistoryTraversalQueue's algorithm + set.
| key | -value | -
|---|---|
| disposition | -disposition | -
| effectivePolicy | -coopValue | -
| previousResponseURL | -If coopOrigin and previousResponseOrigin are same - origin this is the sanitization of - previousResponseURL, null otherwise. | -
| referrer | -serializedReferrer | -
| type | -"navigation-to-response" |
-
Run steps.
Queue body as "coop"
- for coop's reporting endpoint with
- coopURL.
Return sessionHistoryTraversalQueue.
To queue a violation report for browsing context group - switch when navigating away from a COOP response given a cross-origin opener policy coop, a string disposition, a - URL coopURL, a URL nextResponseURL, two origins coopOrigin and nextResponseOrigin, and a boolean - isCOOPResponseNavigationSource:
+ -If coop's reporting endpoint - is null, return.
Otherwise:
+ -To queue a violation report for access to another - window, given a cross-origin opener policy - coop, two URLs coopURL and - otherURL, two origins coopOrigin and - otherOrigin, a string propertyName, and an environment settings - object environment:
+This section contains a miscellaneous grab-bag of operations that we perform throughout the + standard when manipulating session history. The best way to get a sense of what they do is to + look at their call sites.
+ +To get session history entries for a + navigable, navigable:
Let sourceFile, lineNumber and columnNumber be the - relevant script URL and problematic position which triggered this report.
Let traversable be navigable's traversable navigable.
Assert: this is running within traversable's session history traversal queue.
If navigable is traversable, return traversable's session history entries.
Let docStates be an empty ordered set of document states.
For each entry of traversable's session history entries, append entry's document state + to docStates.
Let body be a new object containing the following properties:
+For each docState of docStates:
-| key | -value | -
|---|---|
| disposition | -"reporting" |
-
| effectivePolicy | -coop's report-only - value | -
| property | -propertyName | -
| otherURL | -If coopOrigin and otherOrigin are same origin, this - is the sanitization of otherURL, null - otherwise. | -
| sourceFile | -sourceFile | -
| lineNumber | -lineNumber | -
| columnNumber | -columnNumber | -
| type | -"access-to-opener" |
-
For each nestedHistory of + docState's nested + histories:
+ +If nestedHistory's id equals + navigable's id, return nestedHistory's + entries.
For each entry of nestedHistory's entries, append + entry's document state to + docStates.
Queue body as "coop"
- for coop's reporting endpoint with
- coopURL and environment.
Assert: this step is not reached.
To queue a violation report for access from the - opener, given a cross-origin opener policy - coop, two URLs coopURL and - openerURL, two origins coopOrigin and - openerOrigin, a string propertyName, and a referrer referrer:
+To clear the forward session history of a traversable navigable + navigable:
If coop's reporting endpoint - is null, return.
Assert: this is running within navigable's session history traversal queue.
Let serializedReferrer be an empty string.
Let step be the navigable's current session history step.
If referrer is a URL, set serializedReferrer to the - serialization of referrer. +
Let entryLists be the ordered set « + navigable's session history entries + ».
Let body be a new object containing the following properties:
+For each entryList of + entryLists:
-| key | -value | -
|---|---|
| disposition | -"reporting" |
-
| effectivePolicy | -coop's report-only - value | -
| property | -propertyName | -
| openerURL | -If coopOrigin and openerOrigin are same origin, this - is the sanitization of openerURL, null - otherwise. | -
| referrer | -serializedReferrer | -
| type | -"access-to-opener" |
-
Remove every session history entry from + entryList that has a step greater than + step.
For each entry of entryList:
-Queue body as "coop"
- for coop's reporting endpoint with
- coopURL.
For each nestedHistory of + entry's document state's nested histories, append nestedHistory's entries list to entryLists.
To queue a violation report for access from an - opened window, given a cross-origin opener - policy coop, three URLs coopURL, - openedWindowURL and initialWindowURL, three origins coopOrigin, openedWindowOrigin, and - openerInitialOrigin, and a string propertyName:
+To get all used history steps that are part + of traversable navigable traversable:
If coop's reporting endpoint - is null, return.
Assert: this is running within traversable's session history traversal queue.
Let steps be an empty ordered set of non-negative + integers.
Let entryLists be the ordered set « + traversable's session history + entries ».
Let body be a new object containing the following properties:
+For each entryList of + entryLists:
-| key | -value | -
|---|---|
| disposition | -"reporting" |
-
| effectivePolicy | -coopValue | -
| property | -coop's report-only - value | -
| openedWindowURL | -If coopOrigin and openedWindowOrigin are same origin, this - is the sanitization of openedWindowURL, - null otherwise. | -
| openedWindowInitialURL | -If coopOrigin and openerInitialOrigin are same origin, - this is the sanitization of - initialWindowURL, null otherwise. | -
| type | -"access-to-opener" |
-
For each entry of entryList:
+ +Append entry's step to steps.
For each nestedHistory of + entry's document state's nested histories, append nestedHistory's entries list to entryLists.
Queue body as "coop"
- for coop's reporting endpoint with
- coopURL.
Return steps, sorted.
To queue a violation report for access from another - window, given a cross-origin opener policy - coop, two URLs coopURL and otherURL, two - origins coopOrigin and otherOrigin, and a string - propertyName:
+To apply pending history changes to a traversable navigable + traversable with optional boolean checkForUserCancelation (default + false):
If coop's reporting endpoint - is null, return.
Let targetStep be traversable's current session history step.
Let body be a new object containing the following properties:
+Apply the history step targetStep to traversable with + checkForUserCancelation set to + checkForUserCancelation.
| key | -value | -
|---|---|
| disposition | -"reporting" |
-
| effectivePolicy | -coop's report-only - value | -
| property | -propertyName | -
| otherURL | -If coopOrigin and otherOrigin are same origin, this - is the sanitization of otherURL, null - otherwise. | -
| type | -access-to-opener |
-
Queue body as "coop"
- for coop's reporting endpoint with
- coopURL.
Certain actions cause a navigable to navigate to + a new resource.
+ +For example, following a hyperlink,
+ form submission, and the window.open() and location.assign() methods can all cause navigation.
Although in this standard the word "navigation" refers specifically to the + navigate algorithm, this doesn't always line up with web developer or user + perceptions. For example:
-An embedder policy value is one of three strings that controls the fetching - of cross-origin resources without explicit permission from resource owners.
+The URL and history update steps are often used during so-called + "single-page app navigations" or "same-document navigations", but they do not trigger the + navigate algorithm.
Reloads and traversals are sometimes talked about as a type of navigation, since all three + will often attempt to populate the history entry's document and thus could perform + navigational fetches. See, e.g., the APIs exposed Navigation Timing. But they have + their own entry point algorithms, separate from the navigate algorithm.
Although fragment navigations are always done + through the navigate algorithm, a user might perceive them as more like jumping + around a single page, than as a true navigation.
Before we can jump into the navigation algorithm itself, we + need to establish several important structures that it uses.
+ +The source snapshot params struct is used to capture data from a
+ Document initiating a navigation. It is snapshotted at the beginning of a navigation
+ and used throughout the navigation's lifetime. It has the following items:
unsafe-none"This is the default value. When this value is used, cross-origin resources can be fetched
- without giving explicit permission through the CORS protocol or the
- `Cross-Origin-Resource-Policy` header.
require-corp"When this value is used, fetching cross-origin resources requires the server's
- explicit permission through the CORS protocol or the
- `Cross-Origin-Resource-Policy` header.
credentialless"When this value is used, fetching cross-origin no-CORS resources omits credentials. In
- exchange, an explicit `Cross-Origin-Resource-Policy` header is not required. Other
- requests sent with credentials require the server's explicit permission through the CORS
- protocol or the `Cross-Origin-Resource-Policy` header.
Before supporting "credentialless", implementers are
- strongly encouraged to support both:
+
To snapshot source snapshot params
+ given a Document sourceDocument, return a new source snapshot
+ params with
Otherwise, it would allow attackers to leverage the client's network position to read non - public resources, using the cross-origin isolated - capability.
-An embedder policy value is compatible with cross-origin isolation if
- it is "credentialless" or "require-corp".
An embedder policy consists of:
+A value, which is an embedder policy value, initially "unsafe-none".
A reporting endpoint string, initially the empty string.
A report only value, which is an embedder policy value, initially
- "unsafe-none".
The target snapshot params struct is used to capture data from a + navigable being navigated. Like source snapshot params, it is + snapshotted at the beginning of a navigation and used throughout the navigation's lifetime. It + has the following items:
-A report only reporting endpoint string, initially the empty - string.
The "coep" report type is a report type whose value
- is "coep". It is visible to
- ReportingObservers.
To snapshot target snapshot params + given a navigable targetNavigable, return a new target snapshot + params with sandboxing flags set to + the result of determining the creation sandboxing flags given + targetNavigable's active browsing context and + targetNavigable's container.
-The ` Much of the navigation process is concerned with determining how to create a new
+ The valid token values are the embedder policy values. The token may also have attached parameters; of these, the " The processing model fails open (by defaulting
- to " (The same applies to ` Once a navigation params struct is created, this standard does not
+ mutate any of its items. They are only passed onward to other
+ algorithms. To obtain an embedder policy from a response response and an environment
- environment: A navigation ID is a UUID string generated during navigation. It is used to
+ interface with the WebDriver BiDi specification as well as to track the ongoing
+ navigation. Let policy be a new embedder policy. If environment is a non-secure context, then return
- policy. After Let parsedItem be the result of getting a structured field value
- with ` To navigate a navigable navigable to a
+ URL url using a Let sourceSnapshotParams be the result of snapshotting source snapshot
+ params given sourceDocument. Let initiatorOriginSnapshot be sourceDocument's origin. If sourceDocument's node navigable is not allowed by
+ sandboxing to navigate navigable given and sourceSnapshotParams,
+ then: If exceptionsEnabled is true, then throw a
+ " Return. If parsedItem is non-null and parsedItem[0] is compatible with
- cross-origin isolation: If the surrounding agent is equal to navigable's active document's relevant agent, then continue these
+ steps. Otherwise, queue a global task on the navigation and traversal task
+ source given navigable's active window to
+ continue these steps. We do this because we are about to look at a lot of properties of navigable's
+ active document, which are in theory only accessible over
+ in the appropriate event loop. (But, we do not want to unconditionally queue a
+ task, since — for example — same-event-loop fragment navigations need to take effect synchronously.) Another implementation strategy would be to replicate the relevant information across event
+ loops, or into a canonical "browser process", so that it can be consulted without queueing a
+ task. This could give different results than what we specify here in edge cases, where the
+ relevant properties have changed over in the target event loop but not yet been replicated.
+ Further testing is needed to determine which of these strategies best matches browser
+ behavior, in such racy edge cases. If navigable's active document's
+ unload counter is greater than 0, then invoke WebDriver BiDi navigation
+ failed with a WebDriver BiDi navigation status whose id is navigationId, status is " Set parsedItem to the result of getting a structured field value
- with ` If navigable's parent is non-null, then set
+ navigable's is delaying Let targetBrowsingContext be navigable's active browsing context. Let targetSnapshotParams be the result of snapshotting target snapshot
+ params given navigable. Invoke WebDriver BiDi navigation started with
+ targetBrowsingContext, and a new WebDriver BiDi navigation status whose
+ id is navigationId, url is url, and status is " If parsedItem is non-null and parsedItem[0] is compatible with
- cross-origin isolation: If navigable's ongoing navigation is " Set policy's report only value to
- parsedItem[0]. Invoke WebDriver BiDi navigation failed with
+ targetBrowsingContext and a new WebDriver BiDi navigation status whose
+ id is navigationId, status is " If parsedItem[1][" Return. Any attempts to navigate a navigable that is currently traversing are ignored. Return policy. Set navigable's ongoing navigation to navigationId. This will have the effect of aborting other ongoing navigations of
+ navigable, since at certain points during navigation changes to the ongoing
+ navigation will cause further work to be abandoned. To check a navigation response's adherence to its embedder policy given a response response, a browsing context
- target, and an embedder policy responsePolicy: If url's scheme is " If target is not a child browsing context, then return
- true. Queue a global task on the navigation and traversal task
+ source given navigable's active window to
+ navigate to a Let parentPolicy be target's container document's policy container's embedder policy. Return. If parentPolicy's report-only
- value is compatible with cross-origin isolation and
- responsePolicy's value is not, then
- queue a cross-origin embedder policy inheritance violation with response,
- " In parallel, run these steps: If parentPolicy's value is not
- compatible with cross-origin isolation or responsePolicy's value is compatible with cross-origin
- isolation, then return true. Let unloadPromptCanceled be the result of checking if unloading is
+ user-canceled for navigable's active
+ document's inclusive descendant navigables. Queue a cross-origin embedder policy inheritance violation with
- response, " If unloadPromptCanceled is true, or navigable's ongoing
+ navigation is no longer navigationId, then: Return false. Invoke WebDriver BiDi navigation failed with
+ targetBrowsingContext and a new WebDriver BiDi navigation status
+ whose id is navigationId, status is " Abort these steps. To check a global object's embedder policy given a Queue a global task on the navigation and traversal task
+ source given navigable's active window to
+ abort navigable's active document. If workerGlobalScope is not a Let policy be workerGlobalScope's embedder policy.
+ Let ownerPolicy be owner's policy container's embedder policy.
+ If ownerPolicy's report-only
- value is compatible with cross-origin isolation and policy's
- value is not, then queue a cross-origin
- embedder policy inheritance violation with response, " If ownerPolicy's value is not
- compatible with cross-origin isolation or policy's value is compatible with cross-origin
- isolation, then return true. Queue a cross-origin embedder policy inheritance violation with
- response, " The navigable target
+ name can get cleared under various conditions later in the navigation process, before
+ the document state is finalized. Return false. If url is To queue a cross-origin embedder policy inheritance violation given a response response, a string type, a string
- endpoint, a string disposition, and an environment settings
- object settings: Otherwise, if url is Let serialized be the result of serializing a response URL for
- reporting with response. Let historyEntry be a new session history entry, with its URL set to url and its document state set to
+ documentState. Let body be a new object containing the following properties: Let navigationParams be null. If response is non-null: Let policyContainer be the result of determining navigation params policy container given response's URL,
+ null, a clone of the
+ sourceDocument's policy
+ container, navigable's container
+ document's policy container,
+ and null. Let finalSandboxFlags be the union of
+ targetSnapshotParams's sandboxing
+ flags and policyContainer's CSP
+ list's CSP-derived sandboxing flags. Let responseOrigin be the result of determining the origin
+ given response's URL,
+ finalSandboxFlags, documentState's initiator origin, and null. Let coop be a new cross-origin opener policy. Let coopEnforcementResult be a new cross-origin opener policy enforcement result whose
+ needs a browsing context group switch is
+ false, would need a browsing context
+ group switch due to report-only is false, url is response's URL, origin is responseOrigin, cross-origin opener policy is coop, and
+ current context is navigation source is
+ false. Queue body as the
- " Set navigationParams to a new navigation params, with A policy container is a struct containing policies that apply to
- a A CSP list,
- which is a CSP list. It is initially empty. An embedder
- policy, which is an embedder policy. It is initially a new embedder
- policy. A referrer
- policy, which is a referrer policy. It is initially the default referrer
- policy. Move other policies into the policy container. To clone a policy container given a policy container
- policyContainer: Let clone be a new policy container. For each policy in
- policyContainer's CSP list, append a copy of policy into clone's CSP list. Set clone's embedder
- policy to a copy of policyContainer's embedder policy. Set clone's referrer
- policy to policyContainer's referrer policy. Return clone. Attempt to populate the history entry's document for historyEntry,
+ given navigable, " Append session history
+ traversal steps to navigable's traversable's session history traversal queue to
+ finalize a cross-document navigation given navigable,
+ historyHandling, and historyEntry. To determine whether a URL url requires storing the policy
- container in history: If url's scheme is " If url is local, then return true. Although the usual cross-document navigation case will first foray into populating a session history entry with a
+ Return false. To create a policy container from a fetch response
- given a response response and an
- environment-or-null environment: To finalize a cross-document navigation given a navigable
+ navigable, history handling behavior historyHandling, and
+ session history entry historyEntry: If response's URL's scheme is " Assert: this is running on navigable's traversable navigable's session history traversal queue. Let result be a new policy container. Set navigable's is delaying Set result's CSP list to the
- result of parsing a response's Content Security Policies
- given response. If historyEntry's document is null, then
+ return. If environment is non-null, then set result's embedder policy to the result of obtaining an embedder policy given response
- and environment. Otherwise, set it to " This means that attempting to populate the history entry's document ended up not creating a
+ document, as a result of e.g., the navigation being canceled by a subsequent navigation, a 204
+ No Content response, etc. Set result's referrer
- policy to the result of parsing the
- ` If all of the following are true: Return result. navigable's parent is null; To determine navigation params
- policy container given a URL responseURL and four policy container-or-nulls historyPolicyContainer,
- initiatorPolicyContainer, parentPolicyContainer, and
- responsePolicyContainer: historyEntry's document's browsing context is not an auxiliary browsing
+ context whose disowned is false; and historyEntry's document's origin is not navigable's active document's origin then set historyEntry's document state's
+ navigable target name to the empty
+ string. Let entryToReplace be navigable's active session history entry if
+ historyHandling is " Let traversable be navigable's traversable navigable. Let targetStep be null. Let targetEntries be the result of getting session history
+ entries for navigable. If historyPolicyContainer is not null, then: If entryToReplace is null, then: Assert: responseURL requires storing the policy container
- in history. Clear the forward session history of traversable. Return a clone of
- historyPolicyContainer. Set targetStep to traversable's current session history step + 1. Set historyEntry's step to
+ targetStep. Append historyEntry to
+ targetEntries. If responseURL is Otherwise: Assert: parentPolicyContainer is not null. Replace entryToReplace with
+ historyEntry in targetEntries. Return a clone of
- parentPolicyContainer. Set historyEntry's step to
+ entryToReplace's step. Set targetStep to traversable's current session history step. If responseURL is local and
- initiatorPolicyContainer is not null, then return a clone of initiatorPolicyContainer. If responsePolicyContainer is not null, then return
- responsePolicyContainer. Return a new policy container. Apply the history step targetStep to
+ traversable. To initialize a worker global scope's policy
- container given a If workerGlobalScope's url
- is local but its scheme
- is not " Assert: workerGlobalScope's owner set's size is 1. Set workerGlobalScope's policy container to a clone of workerGlobalScope's owner
- set[0]'s relevant settings object's policy container. To navigate to a Otherwise, set workerGlobalScope's policy container to the result of
- creating a policy container from a fetch response given
- response and environment. Assert: historyHandling is " Set targetNavigable's ongoing navigation to null. If initiatorOrigin is not same origin-domain with
+ targetNavigable's active document's origin, then return. Let request be a new request whose URL is url. A browsing session is …. See whatwg/html issue #4782 and whatwg/html issue #5350 for defining
- browsing session. It is roughly analogous to a top-level browsing
- context except that it cannot be replaced due to a
- ` This is a synthetic request solely for
+ plumbing into the next step. It will never hit the network. A top-level browsing context has an associated browsing session which is a browsing
- session. If the result of should navigation request of type be blocked by Content Security
+ Policy? given request and cspNavigationType is " The browsing session of an environment settings object
- environment is the result of running these steps: Let newDocument be the result of evaluating a Assert: environment's global object is a If newDocument is null, then return. Return environment's global
- object's browsing context's top-level browsing
- context's browsing session. In this case, some JavaScript code was executed, but no new
+ Let entryToReplace be targetNavigable's active session history entry. Let oldDocState be entryToReplace's document state. Let documentState be a new document state with The sequence of Each The A session history entry is a struct with the following items: URL, a URL document, a Let historyEntry be a new session history entry, with Each entry, when first created, has a If a history navigation occurs, and the For the URL, we do not use
+ url, i.e. the actual serialized state, which is serialized
- state or null, initially null Append session history traversal
+ steps to targetNavigable's traversable's
+ session history traversal queue to
+ finalize a cross-document navigation with targetNavigable,
+ historyHandling, and historyEntry. policy container, a policy container
- or null To evaluate a scroll restoration mode, a scroll
- restoration mode, initially " Let urlString be the result of running the URL serializer on url. scroll position data, which is scroll position
- data for the document's restorable scrollable
- regions Let encodedScriptSource be the result of removing the leading " browsing context name, a browsing context
- name or null, initially null Let scriptSource be the UTF-8 decoding of
+ the percent-decoding of
+ encodedScriptSource. persisted user state,
- which is implementation-defined, initially null For example, some user agents might want to persist the values of form
- controls. User agents that persist the value of form controls are encouraged to also
- persist their directionality (the value of the element's Let settings be targetNavigable's active document's relevant settings object. Serialized state is a serialization (via
- StructuredSerializeForStorage) of an object representing a user interface state. We
- sometimes informally refer to "state objects", which are the objects representing user interface
- state supplied by the author, or alternately the objects created by deserializing (via
- StructuredDeserialize) serialized state. Let baseURL be settings's API base URL. Pages can add serialized state to the
- session history. These are then deserialized and returned to the script when the user (or script) goes back in the
- history, thus enabling authors to use the "navigation" metaphor even in one-page applications. Let script be the result of creating a classic script given
+ scriptSource, settings, baseURL, and the default classic
+ script fetch options. Serialized state is intended to be used for two main purposes: first, storing a
- preparsed description of the state in the URL so that in the simple case an author
- doesn't have to do the parsing (though one would still need the parsing for handling URLs passed around by users, so it's only a minor optimization). Second, so
- that the author can store state that one wouldn't store in the URL because it only applies to the
- current Let evaluationStatus be the result of running the classic script script. An example of the latter would be something like keeping track of the precise coordinate from
- which a popup Let result be null. A scroll restoration mode indicates whether the user agent should restore the
- persisted scroll position (if any) when traversing to an entry. A scroll restoration mode is one of the following: If evaluationStatus is a normal completion, and
+ evaluationStatus.[[Value]] is a String, then set result to
+ evaluationStatus.[[Value]]. Otherwise, return null. Let response be a new response with Several contiguous entries in a session history can share the same document. This can occur when the initial entry is reached via normal
- navigation, and the following entry is added via All entries that share the same document (and
- that are therefore merely different states of one particular document) are contiguous by
- definition. User agents may discard the documents of entries with non-null documents, as long as the following conditions are met: The encoding to UTF-8 means that unpaired surrogates will not roundtrip, once the HTML parser decodes the
+ response body. They must not discard the document of the current
- entry. Let policyContainer be targetNavigable's active document's policy container. They must not discard any Let finalSandboxFlags be policyContainer's CSP list's CSP-derived sandboxing
+ flags. Apart from these restrictions, this standard does not specify when user agents should discard
- an entry's document, versus keeping it cached. Let coop be targetNavigable's active
+ document's cross-origin opener
+ policy. Discarding a Let coopEnforcementResult be a new cross-origin opener policy enforcement result with At any point, one of the entries in the session history is the current entry. This
- is the entry representing the active document of the browsing context.
- Which entry is the current entry is changed by the algorithms defined in this
- specification, e.g., during session history
- traversal. The current entry is usually the initial entry created upon
- navigation. However, it can also be one of the contiguous entries that share the same document, as described above. Each Let navigationParams be a new navigation params, with Returns the number of entries in the joint session history. Returns the scroll restoration mode of the
- current entry in the session history. Can be set, to change the scroll restoration
- mode of the current entry in the session history. Returns the current serialized state, deserialized into an object. Goes back or forward the specified number of steps in the joint session
- history. A zero delta will reload the current page. Return the result of loading an HTML document given
+ navigationParams. If the delta is out of range, does nothing. Goes back one step in the joint session history. To navigate to a fragment given a navigable
+ navigable, a URL url, a history handling behavior
+ historyHandling, and a navigation ID navigationId: If there is no previous page, does nothing. Let historyEntry be a new session history entry, with Goes forward one step in the joint session history. If there is no next page, does nothing. Push a new entry into session history with the given data associated. The current
- entry's URL will be copied over and used for the new entry's URL. (The second parameter exists for historical reasons, and cannot be omitted; passing the
- empty string is traditional.) Let entryToReplace be navigable's active session history entry if
+ historyHandling is " Push a new entry into session history with the given data associated, and with
- its URL set to url. Let history be navigable's active
+ document's history object. If the current Let scriptHistoryIndex be history's index. (The second parameter exists for historical reasons, and cannot be omitted; passing the
- empty string is traditional.) Let scriptHistoryLength be history's length. Updates the data stored in the current session history entry to data. If historyHandling is " (The second parameter exists for historical reasons, and cannot be omitted; passing the
- empty string is traditional.) Set history's state to
+ null. Updates the data stored in the current session history entry to data, and its URL
- to url. Increment scriptHistoryIndex. If the current Set scriptHistoryLength to scriptHistoryIndex + 1. (The second parameter exists for historical reasons, and cannot be omitted; passing the
- empty string is traditional.) Set navigable's active session history
+ entry to historyEntry. Update document for history step application given navigable's
+ active document, historyEntry, true,
+ scriptHistoryIndex, and scriptHistoryLength. The joint session history of a top-level browsing context is the union
- of all the session histories of all browsing contexts of all the fully active
- This algorithm will be called twice as a result of a single fragment
+ navigation: once synchronously, where best-guess values scriptHistoryIndex and
+ scriptHistoryLength are set, The current entry of the joint session history is the entry that most recently
- became a current entry in its session history. Scroll to the fragment given navigable's active document. Entries in the joint session history are ordered chronologically by the time they
- were added to their respective session histories. Each entry
- has an index; the earliest entry has index 0, and the subsequent entries are numbered with
- consecutively increasing integers (1, 2, 3, etc.). If the scrolling fails because the Since each Let traversable be navigable's traversable navigable. Append the following session history
+ synchronous navigation steps involving navigable to
+ traversable: Finalize a same-document navigation given traversable,
+ navigable, historyEntry, and entryToReplace. Invoke WebDriver BiDi fragment navigated with navigable's active browsing context and a new WebDriver BiDi navigation
+ status whose id is navigationId,
+ url is resource's url, and status is " Each To finalize a same-document navigation given a traversable navigable
+ traversable, a navigable targetNavigable, a session
+ history entry targetEntry, and session history entry-or-null
+ entryToReplace: The This is used by both fragment navigations
+ and by the URL and history update steps, which are the only synchronous updates to
+ session history. By virtue of being synchronous, those algorithms are performed outside of the
+ top-level traversable's session
+ history traversal queue. This puts them out of sync with the top-level
+ traversable's current session history
+ step, so this algorithm is used to resolve conflicts due to race conditions. If this's associated Assert: this is running on traversable's session history traversal queue. Return the number of entries in the top-level browsing context's joint
- session history. If targetNavigable's active session
+ history entry is not targetEntry, then return. The actual entries are not accessible from script. Let targetStep be null. The Let targetEntries be the result of getting session history
+ entries for targetNavigable. If this's associated If entryToReplace is null, then: Return this's session history's current entry's
- scroll restoration mode. Clear the forward session history of traversable. The Set targetStep to traversable's current session history step + 1. If this's associated Set targetEntry's step to
+ targetStep. Set this's session history's current entry's scroll restoration mode to the given value. Append targetEntry to
+ targetEntries. The Otherwise: If this's associated Replace entryToReplace with
+ targetEntry in targetEntries. Return this's state. Set targetEntry's step to
+ entryToReplace's step. Set targetStep to traversable's current session history step. Apply the history step targetStep to traversable. This is done even for " The Let document be this's associated If document is not fully active, then throw a
- " One input to attempt to create a non-fetch scheme document is the non-fetch
+ scheme navigation params struct. It is a light weight version of
+ navigation params which only carries parameters relevant to the non-fetch
+ scheme navigation case. It has the following items: If delta is 0, then act as if the an origin possibly for use in a user-facing prompt to confirm the invocation of
+ an external software package Traverse the history by a delta with delta and
- document's browsing context. This differs slightly from a document
+ state's initiator origin in that a
+ non-fetch scheme navigation params's initiator origin follows redirects up
+ to the last fetch scheme URL in a redirect chain that ends in a non-fetch
+ scheme URL. The Let document be this's associated If url is to be handled using a mechanism that does not affect
+ navigable, e.g., because url's scheme is handled externally, then: If document is not fully active, then throw a
- " Hand-off to external software given url, navigable,
+ sandboxFlags, hasTransientActivation, and
+ initiatorOrigin. Return null. Handle url by displaying some sort of inline content, e.g., an error message
+ because the specified scheme is not one of the supported protocols, or an inline prompt to
+ allow the user to select a registered
+ handler for the given scheme. Return the result of displaying the inline content given navigable,
+ navigationId, and navTimingType. Traverse the history by a delta with −1 and
- document's browsing context. In the case of a registered handler being used, navigate will be
+ invoked with a new URL. The To hand-off to external software given a URL or response resource, a navigable
+ navigable, a sandboxing flag set sandboxFlags, a boolean
+ hasTransientActivation, and an origin initiatorOrigin user
+ agents should: Let document be this's associated If document is not fully active, then throw a
- " If all of the following conditions hold: Traverse the history by a delta with +1 and
- document's browsing context. navigable is not a top-level traversable; sandboxFlags has its sandboxed custom protocols navigation browsing
+ context flag set; and sandboxFlags has its sandboxed top-level navigation with user
+ activation browsing context flag set, or hasTransientActivation is
+ false Each top-level browsing context has a session history traversal queue,
- initially empty, to which tasks can be added. Each top-level browsing context, when created, must begin running
- the following algorithm, known as the session history event loop for that
- top-level browsing context, in parallel: then return without invoking the external software package. Wait until this top-level browsing context's session history traversal
- queue is not empty. Navigation inside an iframe toward external software can be seen by users as a
+ new popup or a new top-level navigation. That's why its is allowed in sandboxed
+ Pull the first task from this top-level browsing
- context's session history traversal queue, and execute it. Perform the appropriate handoff of resource while attempting to mitigate the risk
+ that this is an attempt to exploit the target software. For example, user agents could prompt
+ the user to confirm that initiatorOrigin is to be allowed to invoke the external
+ software in question. In particular, if hasTransientActivation is false, then the
+ user agent should not invoke the external software package without prior user confirmation. Return to the first step of this algorithm. 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. The session history event loop helps coordinate cross-browsing-context transitions
- of the joint session history: since each browsing context might, at any
- particular time, have a different event loop (this can happen if the user navigates
- from To traverse the history by a delta given delta and browsing
- context source browsing context, the user agent must append a task to this top-level browsing context's session
- history traversal queue, the task consisting of running
- the following steps: A couple of scenarios can intervene early in the navigation process and put the whole thing to
+ a halt. This can be especially exciting when multiple navigables
+ are navigating at the same time, due to a session history traversal. A navigable source is allowed by
+ sandboxing to navigate a second navigable target, given a
+ source snapshot params sourceSnapshotParams, if the following steps
+ return true: If the index of the current entry of the joint session history plus
- delta is less than zero or greater than or equal to the number of items in the
- joint session history, then return. If source is target, then return true. Let specified entry be the entry in the joint session
- history whose index is the sum of delta and the index of the
- current entry of the joint session history. If source is an ancestor of target, then return true. Let specified browsing context be the browsing context of
- the specified entry. If target is an ancestor of source, then: If source browsing context is not allowed to navigate
- specified browsing context, then return. If target is not a top-level traversable, then return
+ true. If the specified browsing context's active document's unload
- counter is greater than 0, then return. If sourceSnapshotParams's has transient activation is true, and
+ sourceSnapshotParams's sandboxing
+ flags's sandboxed top-level navigation with user activation browsing context
+ flag is set, then return false. Queue a global task on the history traversal task source given
- specified browsing context's active window to perform the following
- steps: If sourceSnapshotParams's has transient activation is false, and
+ sourceSnapshotParams's sandboxing
+ flags's sandboxed top-level navigation without user activation browsing context
+ flag is set, then return false. If there is an ongoing attempt to navigate specified browsing context
- that has not yet matured (i.e. it has not passed the
- point of making its Return true. If the specified browsing context's active document is not
- the same If target is a top-level traversable: If the result of calling prompt to unload with the active
- document of the specified browsing context is " If source is the one permitted sandboxed navigator of
+ target, then return true. Unload the active document of the
- specified browsing context. If sourceSnapshotParams's sandboxing flags's sandboxed navigation
+ browsing context flag is set, then return false. Traverse the history of the specified browsing context to
- the specified entry with explicitHistoryNavigation set to
- true. Return true. When the user navigates through a browsing context, e.g. using a browser's back
- and forward buttons, the user agent must traverse the history by a delta with a delta
- equivalent to the action specified by the user and the browsing context being operated on. If sourceSnapshotParams's sandboxing flags's sandboxed navigation
+ browsing context flag is set, then return false. Return true. The URL and history update steps, given a To check if unloading is user-canceled for list of navigables navigables: Let browsingContext be document's browsing context. Let documents be the active document of
+ each item in navigables. If browsingContext is still on its initial Let unloadPromptShown be false. This means that Let unloadPromptCanceled be false. Let totalTasks be the size of
+ documents. Let completedTasks be 0. If isPush is true, then: For each document of documents,
+ queue a global task on the navigation and traversal task source given
+ document's relevant global object to run the steps: Remove all the entries in browsingContext's session history after
- the current entry. If the current entry is the last entry in the
- session history, then no entries are removed. Increase the document's unload counter by 1. This doesn't necessarily have to affect the user
- agent's user interface. Increase the event loop's termination nesting level by
+ 1. Let event be the result of creating an event using
+ Remove any tasks queued by the history
- traversal task source that are associated with any Initialize event's Dispatch event at
+ document's relevant global object. Save persisted state to the current entry. Decrease the event loop's termination nesting level by
+ 1. Add a session history entry entry to browsingContext's
- session history, after the current entry, with If all of the following are true: newURL as the URL; unloadPromptShown is false; document as the document; document's active sandboxing flag set does not have its
+ sandboxed modals flag set; serializedData as the serialized
- state; document's relevant global object has sticky
+ activation; the scroll restoration mode of the
- current entry in the session history as the scroll restoration mode. event's canceled flag is set, or the showing an unload prompt is unlikely to be annoying, deceptive, or pointless then: Set unloadPromptShown to true. Invoke WebDriver BiDi user prompt opened with document's
+ relevant global object, " Ask the user to confirm that they wish to unload the document, and pause
+ while waiting for the user's response. The message shown to the user is not customizable, but instead determined
+ by the user agent. In particular, the actual value of the If the user did not confirm the page navigation, set unloadPromptCanceled
+ to true. Invoke WebDriver BiDi user prompt closed with document's
+ relevant global object and true if unloadPromptCanceled is false or
+ false otherwise. Update the current entry to be this newly added entry. Decrease the document's unload counter by 1. Increment completedTasks. Otherwise: Wait for completedTasks to be totalTasks. Let entry be browsingContext's session history's
- current entry. Return unloadPromptCanceled. Set entry's URL to newURL. If serializedData is not null, then set entry's serialized state to serializedData. Update entry so that it represents a GET request, if it currently represents a
- non-GET request (e.g. it was the result of a POST submission). To reload a navigable navigable: Set navigable's active session history
+ entry's document state's reload pending to true. Let traversable be navigable's traversable navigable. What does this mean? This is not a part of the definition of session
- history entry. Append the following session
+ history traversal steps to traversable: Apply pending history changes to traversable with true. It is intentional that the resulting call to apply the history
+ step does not pass sourceSnapshotParams or initiatorToCheck. Reloading is always treated as if
+ it were done by navigable itself, even in cases like To traverse the history by a delta given a traversable navigable
+ traversable, an integer delta, and an optional Let sourceSnapshotParams and initiatorToCheck be null. Set document's URL to
- newURL. If sourceDocument is given, then: Set sourceSnapshotParams to the result of snapshotting source snapshot
+ params given sourceDocument. Since this is neither a navigation of the
- browsing context nor a history traversal,
- it does not cause a Set initiatorToCheck to sourceDocument's node
+ navigable. If serializedData is not null, then: Append the following session
+ history traversal steps to traversable: Let state be StructuredDeserialize(serializedData,
- document's relevant realm). If this
- throws an exception, catch it, ignore the exception, and set state to null. Let allSteps be the result of getting all used history steps
+ for traversable. Let currentStepIndex be the index of traversable's current session history step within
+ allSteps. Let targetStepIndex be currentStepIndex plus
+ delta. If allSteps[targetStepIndex] does not exist, then abort these steps. Set document's Apply the history step allSteps[targetStepIndex] to
+ traversable, with checkForUserCancelation
+ set to true, sourceSnapshotParams set to
+ sourceSnapshotParams, and initiatorToCheck set to
+ initiatorToCheck. Set the current entry's document's
- latest entry to the current entry. The The The shared history push/replace state steps, given a Apart from the navigate algorithm, session
+ history entries can be pushed or replaced via one more mechanism, the URL and
+ history update steps. The most well-known callers of these steps are the The URL and history update steps, given a Let navigable be document's node navigable. Let activeEntry be navigable's active session history entry. Let newEntry be a new session history entry, with Let document be history's associated If document is not fully active, then throw a
- " Optionally, return. (For example, the user agent might disallow calls to these
- methods that are invoked on a timer, or from event listeners that are not triggered in response
- to a clear user action, or that are invoked in rapid succession.) Let serializedData be ?
- StructuredSerializeForStorage(data). Let newURL be the session history's current entry's
- URL. If url is not null, then: If document's is initial Parse url, relative to the relevant
- settings object of history. This means that If that fails, then throw a " Let entryToReplace be activeEntry if historyHandling is
+ " Set newURL to the resulting URL record. If historyHandling is " If document cannot have its URL
- rewritten to newURL, then throw a " Increment document's history object's
+ index. Set document's history object's length to its index + 1. These are temporary best-guess values for immediate synchronous access. Run the URL and history update steps given document and
- newURL, with serializedData set to
- serializedData and isPush set to
- isPush. If serializedData is not null, then restore the history object
+ state given document and newEntry. User agents may limit the number of state objects added to the session history per page. If a
- page hits the implementation-defined limit, user agents must remove the entry
- immediately after the first entry for that Set document's URL to
+ newURL. Since this is neither a navigation nor a history traversal, it does not cause a A Set document's latest entry to newEntry. Let documentURL be document's URL. Set navigable's active session history
+ entry to newEntry. If targetURL and documentURL differ in their scheme, username,
- password, host, or port
- components, then return false. Let traversable be navigable's traversable navigable. If targetURL's scheme is an
- HTTP(S) scheme, then return true. (Differences in path, query, and fragment are allowed for Append the following session history
+ synchronous navigation steps involving navigable to
+ traversable: If targetURL's scheme is " Finalize a same-document navigation given traversable,
+ navigable, newEntry, and entryToReplace. If targetURL and documentURL differ in their path component or query
- components, then return false. (Only differences in fragment are allowed for other types of URLs.) Although both fragment navigation and the
+ URL and history update steps perform synchronous history updates, only fragment
+ navigation contains a synchronous call to update document for history step
+ application. The URL and history update steps instead perform a few select
+ updates inside the above algorithm, omitting others. This is somewhat of an unfortunate
+ historical accident, and generally leads to web-developer sadness about the
+ inconsistency. For example, this means that Return true. Note how only the URL of the As explained in the overview, both navigation and traversal involve creating a session history
+ entry and then attempting to populate its document
+ member, so that it can be presented inside the navigable. This involves either: using an already-given
+ response; using the srcdoc resource stored in
+ the session history entry; or fetching. The process has several failure modes, which can either result in
+ doing nothing (leaving the navigable on its currently-active Consider a game where the user can navigate along a line, such that the user is always at some
- coordinate, and such that the user can bookmark the page corresponding to a particular
- coordinate, to return to it later. To attempt to populate the history entry's document for a session history
+ entry entry, given a navigable navigable, a
+ A static page implementing the x=5 position in such a game could look like the following: Assert: this is running in parallel. Assert: if navigationParams is non-null, then
+ navigationParams's response is
+ non-null. The problem with such a system is that each time the user clicks, the whole page has to be
- reloaded. Here instead is another way of doing it, using script: Let currentBrowsingContext be navigable's active browsing context. Let documentResource be entry's document state's resource. In systems without script, this still works like the previous example. However, users that
- do have script support can now navigate much faster, since there is no network access
- for the same experience. Furthermore, contrary to the experience the user would have with just a
- naïve script-based approach, bookmarking and navigating the session history still work. If navigationParams is null, then: In the example above, the data argument to the If documentResource is a string, then set navigationParams to the
+ result of creating navigation
+ params from a srcdoc resource given entry, navigable,
+ targetSnapshotParams, navigationId, and
+ navTimingType. Otherwise, if both of the following are true:
- Most applications want to use the same scroll restoration mode value for all of
- their history entries. To achieve this they can set the entry's URL is a fetch scheme;
+ and documentResource is null, or allowPOST is true and
+ documentResource's request body
+ is not failure then set navigationParams to the result of creating navigation params by fetching given entry,
+ navigable, sourceSnapshotParams, targetSnapshotParams,
+ cspNavigationType, navigationId, and navTimingType. Otherwise, if entry's URL's scheme is not a fetch scheme, then set
+ navigationParams to a new non-fetch scheme navigation params,
+ with Queue a global task on the navigation and traversal task source,
+ given navigable's active window, to run these steps: The If navigable's ongoing navigation no longer equals
+ navigationId, then run completionSteps and return. For example, session history could be implemented in a tree-like manner, with each page having
- multiple "forward" pages. This specification doesn't define how the linear list of pages in the
- Let failure be false. Similarly, a page containing two If navigationParams is a non-fetch scheme navigation params, then
+ set entry's document state's document to the result of running attempt to
+ create a non-fetch scheme document given entry's URL, navigable, targetSnapshotParams's sandboxing flags, navigationId,
+ navTimingType, sourceSnapshotParams's has transient activation, and
+ navigationParams's initiator origin.
+ The entry's URL might have been
+ changed within the previous step of this algorithm following an HTTP redirect. Security: It is suggested that to avoid letting a page "hijack" the history
- navigation facilities of a UA by abusing For both Otherwise, if navigationParams is null, then set failure to
+ true. Otherwise, if the result of should navigation response to navigation request of
+ type in target be blocked by Content Security Policy? given
+ navigationParams's request,
+ navigationParams's response,
+ navigationParams's policy
+ container's CSP list,
+ cspNavigationType, and currentBrowsingContext is " Otherwise, if navigationParams's reserved environment is non-null and
+ the result of checking a navigation response's adherence to its embedder policy given
+ navigationParams's response,
+ navigable, and navigationParams's policy container's embedder policy is false, then set
+ failure to true. Otherwise, if the result of checking a navigation response's adherence to
+ ` If failure is true, then: Set entry's document state's document to the result of creating a document for inline content that doesn't have a
+ DOM, given navigable, null, and
+ navTimingType. The inline content should indicate to the user the sort of error
+ that occurred. Each Set entry's document state's
+ document's salvageable to false. If navigationParams is not null, then: The Run the environment discarding
+ steps for navigationParams's reserved environment. Invoke WebDriver BiDi navigation failed with
+ currentBrowsingContext and a new WebDriver BiDi navigation status
+ whose id is navigationId, status is " To create a Otherwise, if navigationParams's response's status is 204 or 205, then: Let location be a new Let valueOf be location's relevant
- realm.[[Intrinsics]].[[%Object.prototype.valueOf%]]. Run completionSteps. Perform ! location.[[DefineOwnProperty]](" Return. Perform ! location.[[DefineOwnProperty]](@@toPrimitive, {
- [[Value]]: undefined,
- [[Writable]]: false,
- [[Enumerable]]: false,
- [[Configurable]]: false }). Set the value of the [[DefaultProperties]] internal slot of
- location to location.[[OwnPropertyKeys]](). Let sourceAllowsDownloading be sourceSnapshotParams's allows downloading. Return location. Let targetAllowsDownloading be false if navigationParams's
+ final sandboxing flag set has the
+ sandboxed downloads browsing context flag set; otherwise true. The addition of If the result of running allowed to download with
+ sourceAllowsDownloading and targetAllowsDownloading is true, then
+ handle navigationParams's response as a download. Invoke WebDriver BiDi download started with
+ currentBrowsingContext and a new WebDriver BiDi navigation status
+ whose id is navigationId, status is " Run completionSteps. Returns a Return. Can be set, to navigate to another page. Otherwise: Let document be the result of loading a document given
+ navigationParams, sourceSnapshotParams, and entry's document state's initiator origin. The If document is null, then run completionSteps and
+ return. The Set entry's document state's
+ document to document. Set entry's document state's
+ origin to document's origin. If entry's document state's request referrer is " This ensures that if we traverse back entry and have to refetch,
+ we use the same referrer, instead of deriving
+ the referrer from the fetch client. If entry's document state's document is not null, then set entry's
+ document state's ever populated to true. Run completionSteps. To create navigation params from a srcdoc resource given a session history
+ entry entry, a navigable navigable, a target
+ snapshot params targetSnapshotParams, a navigation ID-or-null
+ navigationId, and a Returns the Let documentResource be entry's document state's resource. Can be set, to navigate to the given URL. Let response be a new response with Returns the Returns the Can be set, to navigate to the same URL with a changed scheme. Returns the Let responseOrigin be the result of determining the origin given
+ response's URL,
+ targetSnapshotParams's sandboxing
+ flags, null, and entry's document
+ state's origin. Can be set, to navigate to the same URL with a changed host and port. Let coop be a new cross-origin opener policy. Returns the Let coopEnforcementResult be a new cross-origin opener policy enforcement result whose
+ needs a browsing context group switch is
+ false, would need a browsing context
+ group switch due to report-only is false, url
+ is response's URL, origin is responseOrigin, cross-origin opener policy is coop, and current context is navigation source is false. Let policyContainer be the result of determining navigation params policy container given
+ response's URL, entry's document state's history policy container, null,
+ navigable's container document's policy container, and null. Return a new navigation params, with Can be set, to navigate to the same URL with a changed host. Returns the Can be set, to navigate to the same URL with a changed port. Returns the Can be set, to navigate to the same URL with a changed path. Returns the Can be set, to navigate to the same URL with a changed query (ignores leading " Returns the Can be set, to navigate to the same URL with a changed fragment (ignores leading " Navigates to the given URL. Removes the current page from the session history and navigates to the given URL. Reloads the current page. Returns a This algorithm mutates entry. A Assert: this is running in parallel. A Let documentResource be entry's document state's resource. A Let request be a new request, with Let output be a new list of strings. Let current be the browsing context
- of the Loop: If current has no parent browsing context, jump to
- the step labeled end. Let current be current's parent browsing
- context. Append the serialization of current's active document's origin to output. Return to the step labeled loop. End: Return output. To Let browsingContext be this Let sourceBrowsingContext be the incumbent global object's browsing context. If this Navigate browsingContext to url,
- with exceptionsEnabled set to true, historyHandling set to historyHandling, and the
- source browsing context set to sourceBrowsingContext. If documentResource is a POST resource, then: The Set request's method to ` If this's relevant Set request's body to
+ documentResource's request
+ body. Return this's url, serialized. Set ` The If entry's document state's reload pending is true, then set
+ request's reload-navigation
+ flag. If this's relevant Otherwise, if entry's document
+ state's ever populated is true, then
+ set request's history-navigation flag. Parse the given value relative to the entry
- settings object. If that failed, throw a If sourceSnapshotParams's has
+ transient activation is true, then set request's user-activation to true. If navigable's container is non-null: The If the navigable's container has a
+ browsing context scope origin, then set request's origin to that browsing context scope
+ origin. The Set request's destination
+ and initiator type to
+ navigable's container's local name. If this's relevant Let response be null. Return the serialization of
- this's url's origin. Let responseOrigin be null. The Let fetchController be null. If this's relevant Let coopEnforcementResult be a new cross-origin opener policy enforcement result, with Return this's url's scheme, followed by " Let finalSandboxFlags be an empty sandboxing flag set. The Let responsePolicyContainer be null. If this's relevant Let responseCOOP be a new cross-origin opener policy. If this's relevant Let locationURL be null. Let copyURL be a copy of this's url. Let currentURL be request's current URL. Let commitEarlyHints be null. Let possibleFailure be the result of basic URL
- parsing the given value, followed by " While true: Because the URL parser ignores multiple consecutive colons, providing a value
- of " If request's reserved
+ client is not null and currentURL's origin is not the same
+ as request's reserved
+ client's creation URL's origin, then: If possibleFailure is failure, then throw a
- " Run the environment discarding steps for request's reserved client. If copyURL's scheme is not an
- HTTP(S) scheme, then terminate these steps. Set request's reserved
+ client to null. Set commitEarlyHints to null. The Preloaded links from early hint headers
+ remain in the preload cache after a same origin redirect, but get discarded
+ when the redirect is cross-origin. If this's relevant If request's reserved
+ client is null, then: Let url be this's url. Let topLevelCreationURL be currentURL. If url's host is null, return the empty
- string. Let topLevelOrigin be null. If url's port is null, return
- url's host, serialized. If navigable is not a top-level traversable, then: Return url's host, serialized, followed by " Let parentEnvironment be navigable's parent's active document's
+ relevant settings object. The Set topLevelCreationURL to parentEnvironment's
+ top-level creation URL. If this's relevant Set topLevelOrigin to parentEnvironment's top-level
+ origin. If this's relevant Set request's reserved
+ client to a new environment whose id is a unique opaque string, target browsing context is
+ navigable's active browsing context, creation URL is currentURL,
+ top-level creation URL is topLevelCreationURL, and top-level
+ origin is topLevelOrigin. Let copyURL be a copy of this's url. The created environment's active service worker is set in
+ the Handle Fetch algorithm during the
+ fetch if the request URL matches a service worker registration. If copyURL has an opaque path, then return. If the result of should navigation request of type be blocked by Content Security
+ Policy? given request and cspNavigationType is " Basic URL parse the given value, with
- copyURL as url and host
- state as state
- override. Set response to null. If fetchController is null, then set fetchController to the result
+ of fetching request, with processEarlyHintsResponse set to
+ processEarlyHintsResponse, processResponse set to
+ processResponse, and useParallelQueue set to
+ true. The Let processEarlyHintsResponse be the following algorithm given a response earlyResponse: If this's relevant If commitEarlyHints is null, then set commitEarlyHints to the
+ result of processing early hint headers
+ given earlyResponse and request's reserved client. If this's url's host is null, return the empty string. Let processResponse be the following algorithm given a response fetchedResponse: Return this's url's host, serialized. Set response to fetchedResponse. The Otherwise, process the next manual redirect for
+ fetchController. If this's relevant This will result in calling the processResponse we supplied above, during our first iteration
+ through the loop, and thus setting response. If this's relevant Navigation handles redirects manually as navigation is the only place in the
+ web platform that cares for redirects to Let copyURL be a copy of this's url. Wait until either response is non-null, or navigable's ongoing
+ navigation changes to no longer equal navigationId. If copyURL has an opaque path, then return. If the latter condition occurs, then abort
+ fetchController, and return. Basic URL parse the given value, with
- copyURL as url and hostname
- state as state
- override. Otherwise, proceed onward. If request's body is null, then set
+ entry's document state's resource to null. The Fetch unsets the body for
+ particular redirects. If this's relevant Set responsePolicyContainer to the result of creating a policy
+ container from a fetch response given response and request's
+ reserved client. If this's url's port is null, return the empty string. Set finalSandboxFlags to the union of
+ targetSnapshotParams's sandboxing
+ flags and responsePolicyContainer's CSP list's CSP-derived sandboxing
+ flags. Return this's url's port, serialized. Set responseOrigin to the result of determining the origin given
+ response's URL,
+ finalSandboxFlags, entry's document
+ state's initiator origin, and
+ null. The If navigable is a top-level traversable, then: If this's relevant Set responseCOOP to the result of obtaining a
+ cross-origin opener policy given response and request's reserved client. If this's relevant Set coopEnforcementResult to the result of enforcing the response's cross-origin opener policy given
+ navigable's active browsing context,
+ request's URL,
+ responseOrigin, responseCOOP, coopEnforcementResult and
+ request's referrer. Let copyURL be a copy of this's url. If sandboxFlags is not empty and responseCOOP's value is not " This results in a network error as one cannot simultaneously provide a
+ clean slate to a response using cross-origin opener policy and sandbox the result of
+ navigating to that response. If copyURL cannot have a username/password/port, then
- return. If response is not a network error, navigable is a
+ child navigable, and the result of performing a cross-origin resource
+ policy check with navigable's container document's origin, navigable's container document's relevant settings
+ object, request's destination, response, and true is
+ blocked, then set response to a network error and
+ break. Here we're running the cross-origin resource policy check
+ against the parent navigable rather than
+ navigable itself. This is because we care about the same-originness of the
+ embedded content against the parent context, not the navigation source. If the given value is the empty string, then set copyURL's port to null. Set locationURL to response's location URL given currentURL's fragment. Otherwise, basic URL parse the given value, with
- copyURL as url and port
- state as state
- override. If locationURL is failure or null, then break. Assert: locationURL is a URL. The Set entry's serialized state to
+ null. If this's relevant Let oldDocState be entry's document state. Return the result of URL path serializing this
- Set entry's document state to a new
+ document state, with
- The If this's relevant If this's relevant Let copyURL be a copy of this's url. If copyURL has an opaque path, then return. Set copyURL's path to the empty
- list. Basic URL parse the given value, with
- copyURL as url and path start
- state as state
- override. For the navigation case, only entry referenced
+ oldDocState, which was created early
+ in the navigate algorithm. So for navigations, this is functionally just an update to
+ entry's document state. For the traversal
+ case, it's possible adjacent session history
+ entries also reference oldDocState, in which case they will continue doing
+ so even after we've updated entry's document
+ state. The The setup is given by the following Jake diagram: If this's relevant If this's url's query is either null or the empty string, return the empty
- string. Also assume that the document state shared by
+ the entries in steps 0, 1, and 2 has a null document, i.e., bfcache
+ is not in play. Return " Now consider the scenario where we traverse back to step 2, but this time when fetching
+ The In this case, we replace the document state of
+ the session history entry occupying step 2, but we do not replace the
+ document state of the entries occupying steps 0 and 1. The resulting Jake
+ diagram looks like this: If this's relevant If this's relevant Note that we perform this replacement even if we end up in a redirect chain back to the
+ original URL, for example if Let copyURL be a copy of this's url. If the given value is the empty string, set copyURL's query to null.
+ If locationURL's scheme is not an
+ HTTP(S) scheme, then: Otherwise, run these substeps: Set entry's document state's
+ resource to null. Let input be the given value with a single leading " Break. Set copyURL's query to the empty
- string. Set currentURL to locationURL. Basic URL parse input, with
- copyURL as url, and query
- state as state
- override. Set entry's URL to
+ currentURL. By the end of this loop we will be in one of these scenarios: The locationURL is failure, because of an unparseable ` If this's relevant locationURL is null, either because response is a network
+ error or because we successfully fetched a non-network error HTTP(S)
+ response with no ` If this's url's fragment is either null or the empty string, return the
- empty string. locationURL is a URL with a non-HTTP(S) scheme. Return " If locationURL is a URL whose scheme is not a fetch scheme, then return a new
+ non-fetch scheme navigation params, with The If this's relevant At this point, request's current URL is the last URL in the
+ redirect chain with a fetch scheme before redirecting to a non-fetch scheme
+ URL. It is this URL's origin
+ that will be used as the initiator origin for navigations to non-fetch scheme
+ URLs. If this's relevant If any of the following are true: Let copyURL be a copy of this's url. response is a network error; Let input be the given value with a single leading " locationURL is failure; or Set copyURL's fragment to the empty
- string. locationURL is a URL whose scheme is a fetch scheme
+ Basic URL parse input, with
- copyURL as url and fragment
- state as state
- override. then return null. We allow redirects to non-fetch scheme URLs, but redirects to fetch scheme URLs that aren't HTTP(S) are treated
+ like network errors. Assert: locationURL is null and response is not a
+ network error. Let resultPolicyContainer be the result of determining navigation params
+ policy container given response's URL, entry's document state's history policy container,
+ sourceSnapshotParams's source
+ policy container, null, and responsePolicyContainer. If copyURL's fragment is
- this's url's fragment, then return. Return a new navigation params, with This bailout is necessary for compatibility with deployed content, which redundantly sets Unlike the equivalent API for the The If this's relevant If this's relevant Parse url relative to the entry
- settings object. If that failed, throw a " The If this's relevant Parse url relative to the entry
- settings object. If that failed, throw a " The An element has a browsing context scope origin if its The This definition is broken and needs investigation to see what it was intended to
+ express: see issue #4703. Return. To load a document given navigation params
+ navigationParams, source snapshot params sourceSnapshotParams,
+ and origin initiatorOrigin, perform the following steps. They return a
+ Throw a " Repaint the browsing context and return. Let type be the computed type of
+ navigationParams's response. Reprocess the If the user agent has been configured to process resources of the given type
+ using some mechanism other than rendering the content in a navigable, then
+ skip this step. Otherwise, if the type is one of the following types: Navigate the browsing context to
- this's relevant When a user requests that the active document of a browsing context
- be reloaded through a user interface element, the user agent should navigate the browsing context to the same resource as that
- The If this's relevant Otherwise, proceed onward. If this's relevant An explicitly supported XML MIME type is an XML MIME type for which
+ the user agent is configured to use an external application to render the content, or for which
+ the user agent has dedicated processing rules. For example, a web browser with a built-in Atom
+ feed viewer would be said to explicitly support the Otherwise, return this's ancestor origins list. An explicitly supported JSON MIME type is a JSON MIME type for which
+ the user agent is configured to use an external application to render the content, or for which
+ the user agent has dedicated processing rules. In both cases, the external application or user agent will either display the content inline directly in
+ navigationParams's navigable, or
+ hand it off to external software. Both
+ happen in the steps below. Otherwise, the document's type is such that the resource will not affect
+ navigationParams's navigable, e.g.,
+ because the resource is to be handed to an external application or because it is an unknown type
+ that will be processed as a download. Hand-off to external software
+ given navigationParams's response,
+ navigationParams's navigable,
+ navigationParams's final sandboxing flag
+ set, sourceSnapshotParams's has transient activation, and
+ initiatorOrigin. Return null. The details of how the As explained earlier, the For both navigation and traversal, once we have an idea of where we want to head to in the
+ session history, much of the work comes about in applying that notion to the traversable
+ navigable and the relevant Also, every Ensuring a traversable ends up at the right
+ session history step is particularly complex, as it can involve coordinating across multiple
+ navigable descendants of the traversable, populating them in parallel, and then
+ synchronizing back up to ensure everyone has the same view of the result. This is further
+ complicated by the existence of synchronous same-document navigations being mixed together with
+ cross-document navigations, and how web pages have come to have certain relative timing
+ expectations. If IsPlatformObjectSameOrigin(this) is true, then return !
- OrdinaryGetPrototypeOf(this). A changing navigable continuation state is used to store information during the
+ apply the history step algorithm, allowing parts of the algorithm to continue only
+ after other parts have finished. It is a struct with: Return null. Return ! SetImmutablePrototype(this, V). Return true. To apply the history step
+ non-negative integer step to a traversable navigable
+ traversable, with optional boolean checkForUserCancelation (default false),
+ optional source snapshot params-or-null sourceSnapshotParams (default null),
+ and optional navigable initiatorToCheck: sourceSnapshotParams and initiatorToCheck are always either
+ both given or both not given. They are usually not given, as most callers do not need the extra
+ checks on the navigation initiator that they cause. (Possibly because the caller has already
+ performed such checks themselves.) Return false. Assert: This is running within traversable's session history traversal queue. Let targetStep be the result of getting the used step given
+ traversable and step. If IsPlatformObjectSameOrigin(this) is true, then: If initiatorToCheck is given, then: Let desc be OrdinaryGetOwnProperty(this,
- P). If the value of the [[DefaultProperties]] internal slot of this
- contains P, then set desc.[[Configurable]] to true. Assert: sourceSnapshotParams is not null. Return desc. For each navigable of get all
+ navigables whose current session history entry will change or reload: if
+ initiatorToCheck is not allowed by sandboxing to navigate
+ navigable given sourceSnapshotParams, then return. Let property be CrossOriginGetOwnPropertyHelper(this,
- P). Let navigablesCrossingDocuments be the result of getting all navigables
+ that might experience a cross-document traversal given traversable and
+ targetStep. If property is not undefined, then return property. If checkForUserCancelation is true, and the result of checking if unloading
+ is user-canceled given navigablesCrossingDocuments given
+ traversable and targetStep is true, then return. Return ? CrossOriginPropertyFallback(P). Some algorithms check if
+ unloading is user-canceled as a prerequisite to modifying the history tree. Those
+ algorithms will set checkForUserCancelation to false when calling this algorithm to
+ avoid performing the check twice. It might not be correct to block on beforeunload results here. This may have
+ observable consequences. Let changingNavigables be the result of get all navigables whose current
+ session history entry will change or reload given traversable and
+ targetStep. Let nonchangingNavigablesThatStillNeedUpdates be the result of getting
+ all navigables that only need history object length/index update given
+ traversable and targetStep. If IsPlatformObjectSameOrigin(this) is true, then: For each navigable of
+ changingNavigables: If the value of the [[DefaultProperties]] internal slot of this
- contains P, then return false. Let targetEntry be the result of getting the target history
+ entry given navigable and targetStep. Return ? OrdinaryDefineOwnProperty(this, P,
- Desc). Set navigable's current session
+ history entry to targetEntry. Set navigable's ongoing navigation to " Throw a " Let totalChangeJobs be the size of
+ changingNavigables. Let completedChangeJobs be 0. If IsPlatformObjectSameOrigin(this) is true, then return ?
- OrdinaryGet(this, P, Receiver). Let changingNavigableContinuations be an empty queue of changing navigable continuation
+ states. Return ? CrossOriginGet(this, P,
- Receiver). This queue is used to split the operations on changingNavigables
+ into two parts. Specifically, changingNavigableContinuations holds data for the second part. For each navigable of
+ changingNavigables, queue a global task on the navigation and
+ traversal task source of navigable's active
+ window to run the steps: If IsPlatformObjectSameOrigin(this) is true, then return ?
- OrdinarySet(this, P, V, Receiver). This set of steps are split into two parts to allow synchronous navigations to
+ be processed before documents unload. State is stored in
+ changingNavigableContinuations for the second
+ part. Return ? CrossOriginSet(this, P, V,
- Receiver). Let displayedEntry be navigable's active session history entry. Let targetEntry be navigable's current session history entry. Let changingNavigableContinuation be a changing navigable continuation
+ state with: If IsPlatformObjectSameOrigin(this) is true, then return ?
- OrdinaryDelete(this, P). If displayedEntry is targetEntry and targetEntry's document state's reload pending is false, then: Throw a " Set changingNavigableContinuation's update-only to true. Enqueue changingNavigableContinuation on
+ changingNavigableContinuations. If IsPlatformObjectSameOrigin(this) is true, then return
- OrdinaryOwnPropertyKeys(this). Abort these steps. Return CrossOriginOwnPropertyKeys(this). This case occurs due to a synchronous navigation which already updated the active session history entry. Let oldOrigin be targetEntry's document state's origin. If targetEntry's document is null, or
+ targetEntry's document state's reload pending is true, then: Let navTimingType be " Let targetSnapshotParams be the result of snapshotting target
+ snapshot params given navigable. Let potentiallyTargetSpecificSourceSnapshotParams be
+ sourceSnapshotParams. Certain actions cause the browsing context to navigate to
- a new resource. A user agent may provide various ways for the user to explicitly cause a browsing
- context to navigate, in addition to those defined in this specification. If potentiallyTargetSpecificSourceSnapshotParams is null, then set it to the
+ result of snapshotting source snapshot params given navigable's
+ active document. In this case there is no clear source of the traversal/reload. We treat this
+ situation as if navigable navigated itself, but note that some properties of
+ targetEntry's original initiator are preserved in targetEntry's document state, such as the initiator origin and referrer, which will appropriately influence
+ the navigation. For example, following a hyperlink,
- form submission, and the Set targetEntry's document
+ state's reload pending to
+ false. A resource has a URL, but that might not be the only information necessary
- to identify it. For example, a form submission that uses HTTP POST would also have the HTTP method
- and payload. Similarly, an Let allowPOST be targetEntry's document state's reload pending. In parallel, attempt to populate the history entry's
+ document for targetEntry, given navigable,
+ potentiallyTargetSpecificSourceSnapshotParams, targetSnapshotParams,
+ with allowPOST set to allowPOST
+ and completionSteps set to
+ queue a global task on the navigation and traversal task source
+ given navigable's active window to run
+ afterDocumentPopulated. Much of the navigation process is concerned with determining how to create a new
- Otherwise, run afterDocumentPopulated immediately. In both cases, let afterDocumentPopulated be the following steps: If targetEntry's document is null, then
+ set changingNavigableContinuation's update-only to true. This means we tried to populate the document, but were unable to do so,
+ e.g. because of the server returning a 204. If targetEntry's document's origin is not oldOrigin, then set
+ targetEntry's serialized state to
+ null. This clears history state when the origin changed vs a previous load of
+ targetEntry without a redirect occuring. This can happen due to a change in CSP
+ sandbox headers. If all of the following are true: navigable's parent is null; targetEntry's document's browsing context is not an auxiliary browsing
+ context whose disowned is false; and targetEntry's document's origin is not oldOrigin then set targetEntry's document
+ state's navigable target name
+ to the empty string. Enqueue changingNavigableContinuation on
+ changingNavigableContinuations. The rest of this job runs later in
+ this algorithm. Let navigablesThatMustWaitBeforeHandlingSyncNavigation be an empty
+ set. Once a navigation params struct is created, this standard does not
- mutate any of its items. They are only passed onward to other
- algorithms. While completedChangeJobs does not equal totalChangeJobs: After If traversable's running
+ nested apply history step is false, then: Let changingNavigableContinuation be the result
+ of dequeuing from
+ changingNavigableContinuations. Navigation always involves source browsing context, which is the browsing
- context which was responsible for starting the navigation. If changingNavigableContinuation is nothing, then
+ continue. As explained in issue
- #1130 the use of a browsing context as source might not be the correct architecture. Let displayedDocument be changingNavigableContinuation's displayed document. A navigation has a navigation id, which is a unique
- string. Let targetEntry be changingNavigableContinuation's target entry. To navigate a browsing context browsingContext to a resource
- resource, with an optional boolean exceptionsEnabled (default false), an optional history handling
- behavior historyHandling (default " If resource is a URL, then set resource to a new request whose URL is
- resource. If resource is a request and
- historyHandling is " Let navigable be changingNavigableContinuation's navigable. If the source browsing context is not allowed to navigate
- browsingContext, then: Set navigable's ongoing navigation to null. If exceptionsEnabled is given and is true, then throw a
- " This allows new navigations of
+ navigable to start, whereas during the traversal they were blocked. Otherwise, the user agent may instead offer to open resource in a new
- top-level browsing context or in the top-level browsing context of
- the source browsing context, at the user's option, in which case the user agent
- must navigate that designated top-level
- browsing context to resource as if the user had requested it
- independently. Doing so, however, can be dangerous, as it means that the user is overriding
- the author's explicit request to sandbox the content. Let (scriptHistoryLength, scriptHistoryIndex) be the result of
+ getting the history object length and index given traversable and
+ targetStep. These values might have changed since they were last calculated. If navigationId is null: Append navigable to
+ navigablesThatMustWaitBeforeHandlingSyncNavigation. If browsingContext's active document's unload counter
- is greater than 0, then invoke WebDriver BiDi navigation failed with a
- WebDriver BiDi navigation status whose id is navigationId, status is " Once a navigable has reached this point in traversal, additionally queued
+ synchronous navigation steps are likely to be intended to occur after this traversal rather
+ than before it, so they no longer jump the queue. More details can be found here. Queue a global task on the navigation and traversal task source
+ given navigable's active window to run the
+ steps: browsingContext is still on its initial If changingNavigableContinuation's update-only is false, then: resource is a request whose URL equals
- browsingContext's active document's URL Unload displayedDocument given
+ targetEntry's document. resource is a request whose URL's scheme is
- " For each childNavigable of displayedDocument's
+ descendant navigables, queue a global task on the
+ navigation and traversal task source given childNavigable's active window to unload
+ childNavigable's active document. then set historyHandling to " Activate history entry targetEntry for
+ navigable. If targetEntry's document is not equal
+ to displayedDocument, then queue a global task on the
+ navigation and traversal task source given targetEntry's document's relevant global object to perform the
+ following step. Otherwise, continue onward to perform the following step within the
+ currently-queued task. Navigate to a fragment given
- browsingContext, resource's URL,
- historyHandling, and navigationId. Update document for history step application given
+ targetEntry's document,
+ targetEntry, changingNavigableContinuation's update-only,
+ scriptHistoryLength, and scriptHistoryIndex. Return. Increment completedChangeJobs. Let incumbentNavigationOrigin be the origin of the incumbent
- settings object, or if no script was involved, the origin of the node document of the element
- that initiated the navigation. Let totalNonchangingJobs be the size of
+ nonchangingNavigablesThatStillNeedUpdates. Let initiatorPolicyContainer be a clone of the source browsing context's active
- document's policy
- container. This step onwards deliberately waits for all the previous operations to
+ complete, as they include processing synchronous
+ navigations which will also post tasks to update history length and index. If resource is a request, then set
- resource's policy container to
- initiatorPolicyContainer. Let completedNonchangingJobs be 0. Cancel any preexisting but not yet mature
- attempt to navigate browsingContext, including canceling any instances of the fetch algorithm started by those attempts. If one of those attempts
- has already created and initialized a new
- Let (scriptHistoryLength, scriptHistoryIndex) be the result of
+ getting the history object length and index given traversable and
+ targetStep. Let unloadPromptResult be the result of calling prompt to unload
- with the active document of browsingContext. For each navigable of
+ nonchangingNavigablesThatStillNeedUpdates, queue a global task on the
+ navigation and traversal task source given navigable's active window to run the steps: Let document be navigable's active
+ document. Set document's history object's index to scriptHistoryIndex. If this instance of the navigation algorithm gets canceled
- while this step is running, the prompt to unload algorithm must nonetheless be run
- to completion. Set document's history object's length to scriptHistoryLength. Increment completedNonchangingJobs. If unloadPromptResult is " Wait for completedNonchangingJobs to equal
+ totalNonchangingJobs. Abort the active document of
- browsingContext. Set traversable's current
+ session history step to targetStep. If browsingContext is a child browsing context, then put it in the
- delaying To activate history entry session history entry entry for
+ navigable navigable: The user agent must take this child browsing context out of the delaying
- Save persisted state to the navigable's active session history entry. Let newDocument be entry's document. Let sandboxFlags be the result of determining the creation sandboxing
- flags given browsingContext and browsingContext's container. Assert: newDocument's is initial
+ Let allowedToDownload be the result of running the allowed to
- download algorithm given the source browsing context and
- browsingContext. Set navigable's active session history
+ entry to entry. Let hasTransientActivation be true if the source browsing
- context's active window has transient activation; otherwise
- false. Make active newDocument. Invoke WebDriver BiDi navigation started with browsingContext, and
- a new WebDriver BiDi navigation status whose id is navigationId, url is resource's url, and status is " To get the used step given a traversable
+ navigable traversable, and a non-negative integer step, perform the
+ following steps. They return a non-negative integer. Return, and continue running these steps in parallel. Let steps be the result of getting all used history steps within
+ traversable. This is the step that attempts to obtain resource, if necessary. Jump to the first
- appropriate substep: Return the greatest item in steps that is less
+ than or equal to step. Assert: browsingContext is not a top-level browsing
- context. This caters for situations where there's no session history entry
+ with step step, due to the removal of a
+ navigable. Let finalSandboxFlags be the union of
- browsingContext's sandboxing
- flags and resource's forced sandboxing flag set. To get the history object length and
+ index given a traversable navigable traversable, and a non-negative
+ integer step, perform the following steps. They return a tuple of two
+ non-negative integers. Let responseOrigin be the result of determining the origin
- given browsingContext, resource's url, finalSandboxFlags, and
- incumbentNavigationOrigin. Let steps be the result of getting all used history steps within
+ traversable. Let coop be a new cross-origin opener policy. Let scriptHistoryLength be the size of
+ steps. Let coopEnforcementResult be a new cross-origin opener policy enforcement result whose
- needs a browsing context group switch is
- false, would need a browsing context
- group switch due to report-only is false, url is resource's url, origin
- is responseOrigin, cross-origin opener policy is coop, and
- current context is navigation source is
- false. Assert: steps contains
+ step. Let policyContainer be the result of determining navigation params policy container given
- resource's url,
- historyPolicyContainer, initiatorPolicyContainer,
- browsingContext's parent browsing context's active
- document's policy container,
- and null. It is assumed that step has been adjusted by getting the used
+ step. Let navigationParams be a new navigation params whose id is navigationId, request is null, response is resource, origin is responseOrigin, policy container is
- policyContainer, final sandboxing
- flag set is finalSandboxFlags, cross-origin opener policy is coop, COOP enforcement result is
- coopEnforcementResult, reserved environment is null, browsing context is
- browsingContext, history handling is
- historyHandling, process response end of body
- is processResponseEndOfBody, and commit early hints is null. Run process a navigate response with navigationType,
- allowedToDownload, hasTransientActivation, and
- navigationParams. Let scriptHistoryIndex be the index of step in
+ sessionSteps. Return (scriptHistoryLength, scriptHistoryIndex). Queue a global task on the DOM manipulation task source given
- browsingContext's active window to run these steps: To get all navigables whose current session history entry will change or reload
+ given a traversable navigable traversable, and a non-negative integer
+ targetStep, perform the following steps. They return a list of navigables. Let response be the result of executing
- a Let results be an empty list. Let finalSandboxFlags be the union of
- browsingContext's sandboxing
- flags and response's forced sandboxing flag set. Let navigablesToCheck be « traversable ». Let coopEnforcementResult be a new cross-origin opener policy enforcement result whose
- needs a browsing context group switch is
- false, would need a browsing context
- group switch due to report-only is false, url is resource's URL, origin
- is browsingContext's active document's origin, cross-origin opener policy is
- browsingContext's active document's cross-origin opener policy, and current context is navigation source is false. Let navigationParams be a new navigation params whose id is navigationId, request is resource, response is response, origin is browsingContext's
- active document's origin, policy container is
- browsingContext's active document's policy container,
- final sandboxing flag set is
- finalSandboxFlags, cross-origin opener
- policy is browsingContext's active document's cross-origin opener policy, COOP enforcement result is
- coopEnforcementResult, reserved environment is null, browsing context is
- browsingContext, history handling is
- historyHandling, process response end of body
- is processResponseEndOfBody, and commit early hints is null. Run process a navigate response with navigationType,
- allowedToDownload, hasTransientActivation, and
- navigationParams. This list is extended in the loop below. So for example a For each navigable of
+ navigablesToCheck: Run process a navigate fetch given navigationId,
- resource, the source browsing context, browsingContext,
- navigationType, sandboxFlags, historyPolicyContainer,
- initiatorPolicyContainer, allowedToDownload,
- hasTransientActivation, incumbentNavigationOrigin,
- historyHandling, and processResponseEndOfBody. Run process a navigate URL scheme given resource's URL, browsingContext, sandboxFlags,
- and hasTransientActivation. Let targetEntry be the result of getting the target history
+ entry given navigable and targetStep. If targetEntry is not navigable's current session history entry or
+ targetEntry's document state's reload pending is true, then append navigable to results. If targetEntry's document is
+ navigable's document, and
+ targetEntry's document state's reload pending is false, then extend navigablesToCheck with the child navigables of navigable. Adding child navigables to
+ navigablesToCheck means those navigables will also be checked by this loop. Child navigables are only checked if the
+ navigable's active document will not change as
+ part of this traversal. Return results. To process a navigate fetch, given a navigation
- id navigationId, request
- request, two browsing contexts
- sourceBrowsingContext and browsingContext, a string
- navigationType, a sandboxing flag set sandboxFlags, two policy containers historyPolicyContainer and
- initiatorPolicyContainer, a boolean allowedToDownload, a boolean
- hasTransientActivation, an origin incumbentNavigationOrigin, a
- history handling behavior historyHandling, and
- processResponseEndOfBody, which is an algorithm accepting a response: To get
+ all navigables that only need history object length/index update given a traversable
+ navigable traversable, and a non-negative integer targetStep,
+ perform the following steps. They return a list of navigables. Other navigables might not be impacted by the
+ traversal. For example, if the response is a 204, the currently active document will remain.
+ Additionally, going 'back' after a 204 will change the current session history entry, but the active session history entry will already be
+ correct. Let response be null. Let results be an empty list. Set request's client to
- sourceBrowsingContext's active document's relevant settings
- object, destination to " If hasTransientActivation is true, then set request's user-activation to true. Let navigablesToCheck be « traversable ». This list is extended in the loop below. If browsingContext's container is non-null: For each navigable of
+ navigablesToCheck: If the browsingContext's container has a
- browsing context scope origin, then set request's origin to that browsing context scope
- origin. Let targetEntry be the result of getting the target history
+ entry given navigable and targetStep. Set request's destination to browsingContext's
- container's local
- name. If targetEntry is navigable's current session history entry and
+ targetEntry's document state's reload pending is false, then: Append navigable to
+ results. Extend navigablesToCheck with
+ navigable's child navigables. Adding child navigables to
+ navigablesToCheck means those navigables will also be checked by this loop.
+ child navigables are only checked if the
+ navigable's active document will not change
+ as part of this traversal. Let responseOrigin be null.
+ Return results. Let currentContextIsSource be the result of whether
- browsingContext's active document is same origin with
- sourceBrowsingContext's active document. To get the target history entry given a
+ navigable navigable, and a non-negative integer step, perform
+ the following steps. They return a session history entry. Let coopEnforcementResult be a new cross-origin opener policy enforcement result whose needs a browsing context group switch is false, would need a browsing context group switch due
- to report-only is false, url is
- browsingContext's active document's url, origin is browsingContext's active
- document's origin, cross-origin opener policy is browsingContext's
- active document's cross-origin opener
- policy, and current context is navigation
- source is currentContextIsSource. Let entries be the result of getting session history entries for
+ navigable. Let finalSandboxFlags be an empty sandboxing flag set. Return the item in entries that has the
+ greatest step less than or equal to step. Let responseCOOP be a new cross-origin opener policy. To see why getting the target history entry returns the entry with the greatest
+ step less than or equal to the input step, consider the following
+ Jake diagram: Let locationURL be null. Let currentURL be request's current URL. For the input step 1, the target history entry for the Let hasCrossOriginRedirects be false. Let commitEarlyHints be null. Similarly, given the input step 3 we get the Let fetchController be null. While true: To get
+ all navigables that might experience a cross-document traversal given a traversable
+ navigable traversable, and a non-negative integer targetStep,
+ perform the following steps. They return a list of navigables. If locationURL is non-null, then: From traversable's session
+ history traversal queue's perspective, these documents are candidates for going
+ cross-document during the traversal described by targetStep. They will not experience
+ a cross-document traversal if the status code for their target document is HTTP 204 No Content. If locationURL's origin is not the
- same as currentURL's origin, then set hasCrossOriginRedirects to
- true. Note that if a given navigable might experience a cross-document traversal, this
+ algorithm will return navigable but not its child
+ navigables. Those would end up unloaded, not
+ traversed. Set currentURL to locationURL. Let results be an empty list. If request's reserved
- client is not null and currentURL's origin is not the same as
- request's reserved client's
- creation URL's origin, then: Let navigablesToCheck be « traversable ». Run the environment discarding steps for
- request's reserved
- client. This list is extended in the loop below. Set request's reserved
- client to null. For each navigable of
+ navigablesToCheck: Set commitEarlyHints to null. Let targetEntry be the result of getting the target history
+ entry given navigable and targetStep. Preloaded links from early hint
- headers remain in the preload cache after a same origin redirect, but
- get discarded when the redirect is cross-origin. If targetEntry's document is not
+ navigable's document or
+ targetEntry's document state's reload pending is true, then append navigable to results. Although navigable's active history entry can change synchronously, the
+ new entry will always have the same If request's reserved
- client is null, then: Let topLevelCreationURL be currentURL. Let topLevelOrigin be null. Otherwise, extend navigablesToCheck with
+ navigable's child navigables. Adding child navigables to
+ navigablesToCheck means those navigables will also be checked by this loop. Child navigables are only checked if the
+ navigable's active document will not change as
+ part of this traversal. If browsingContext is not a top-level browsing context, then: Return results. Let parentEnvironment be browsingContext's container's relevant settings object. Set topLevelCreationURL to parentEnvironment's top-level
- creation URL and topLevelOrigin to parentEnvironment's
- top-level origin. Set request's reserved
- client to a new environment whose id is a unique opaque string, target browsing context is
- browsingContext, creation
- URL is currentURL, top-level creation URL is
- topLevelCreationURL, and top-level origin is
- topLevelOrigin. To update document for history step application given a The created environment's active service worker is set in
- the Handle Fetch algorithm during the fetch
- if the request URL matches a service worker registration. Let documentIsNew be true if document's latest entry
+ is null; otherwise false. If the result of Should navigation request of type be blocked by Content Security
- Policy? given request and navigationType is " Let documentsEntryChanged be true if document's latest
+ entry is not entry; otherwise false. Otherwise: Set document's history object's index to scriptHistoryIndex. If fetchController is null, then set fetchController to the
- result of fetching request, with
- processEarlyHintsResponse set to the following step
- given a response earlyResponse: If
- commitEarlyHints is null, then set commitEarlyHints to the result
- of processing early hint headers given
- earlyResponse and request's
- reserved client. Otherwise, process the next manual redirect given
- fetchController. Wait for the task on the networking task
- source to process response and set response to the
- result. Set finalSandboxFlags to the union of
- browsingContext's sandboxing
- flags and response's forced sandboxing flag set. Set responseOrigin to the result of determining the origin
- given browsingContext, request's URL, finalSandboxFlags, and
- incumbentNavigationOrigin. Set document's history object's length to scriptHistoryLength. If browsingContext is a top-level browsing context, then: If documentsEntryChanged is true, then: Set responseCOOP to the result of obtaining a
- cross-origin opener policy given response and
- request's reserved
- client. Set coopEnforcementResult to the result of enforcing the response's cross-origin opener policy given
- browsingContext, request's URL, responseOrigin,
- responseCOOP, coopEnforcementResult and request's referrer. Let oldURL be document's latest entry's URL. If sandboxFlags is not empty and responseCOOP's value is not " This results in a network error as one cannot simultaneously provide a
- clean slate to a response using cross-origin opener policy and sandbox the result of
- navigating to that response. Set document's latest entry to entry. If response is not a network error, browsingContext
- is a child browsing context, and the result of performing a
- cross-origin resource policy check with browsingContext's
- container document's origin, browsingContext's container document's relevant settings
- object, request's destination, response, and true is
- blocked, then set response to a network error and
- break. Here we're running the cross-origin resource policy check
- against the parent browsing context rather than
- sourceBrowsingContext. This is because we care about the same-originness of the
- embedded content against the parent context, not the navigation source. Restore the history object state given document and
+ entry. Set locationURL to response's location URL given currentURL's
- fragment. If documentIsNew is false, then fire an
+ event named If locationURL is not a URL whose scheme is an HTTP(S) scheme, then
- break. Restore persisted state given entry. Navigation handles redirects manually as navigation is the only place in
- the web platform that cares for redirects to If documentIsNew is false, and oldURL's fragment is not equal to entry's URL's fragment, then
+ queue a global task on the DOM manipulation task source given
+ document's relevant global object to fire an event named By the end of this loop we will be in one of these scenarios: If documentIsNew is true, then:
- response is a network error. Try to scroll to the fragment for document. locationURL is failure, because of an unparseable ` At this point scripts may run for the newly-created document
+ document. locationURL is null, because we successfully fetched a non-network
- error HTTP(S) response with no ` Otherwise, if documentsEntryChanged is false and doNotReactivate is
+ false, then reactivate document. locationURL is a URL with a non-HTTP(S) scheme. documentsEntryChanged can be false for one of two reasons: either we
+ are restoring from bfcache, or we are asynchronously finishing up a
+ synchronous navigation which already synchronously set document's latest
+ entry. The doNotReactivate argument distinguishes between these two
+ cases. If locationURL is failure, then set response to a network
- error. To restore the history object state given Otherwise, if locationURL is a URL whose scheme is a fetch scheme or " Let targetRealm be document's relevant realm. Otherwise, if locationURL is a URL, then process a navigate
- URL scheme given locationURL, browsingContext,
- sandboxFlags, and hasTransientActivation, and return. Let state be null. Let responsePolicyContainer be the result of creating a policy container
- from a fetch response given response and request's reserved client. If entry's serialized state is not
+ null, then set state to StructuredDeserialize(entry's serialized state, targetRealm). If this throws
+ an exception, catch it and ignore the exception. Let resultPolicyContainer be the result of determining navigation params
- policy container given response's URL, historyPolicyContainer,
- initiatorPolicyContainer, null, and responsePolicyContainer. Let navigationParams be a new navigation params whose id is navigationId, request is request, response is response, origin is responseOrigin, policy container is
- resultPolicyContainer, final sandboxing
- flag set is finalSandboxFlags, cross-origin opener policy is responseCOOP,
- COOP enforcement result is
- coopEnforcementResult, reserved
- environment is request's reserved client, browsing context is
- browsingContext, history handling is
- historyHandling, process response end of body is
- processResponseEndOfBody, and
- commit early hints is
- commitEarlyHints. Run process a navigate response with navigationType,
- allowedToDownload, hasTransientActivation, and
- navigationParams. Set document's history object's state to state. To process a navigate response, given a string navigationType, a
- boolean allowedToDownload, a boolean hasTransientActivation, and a
- navigation params navigationParams: To make active a Let response be navigationParams's response. Let window be document's relevant global
+ object. Let browsingContext be navigationParams's browsing context. Set document's browsing context's
+ Let failure be false. Set document's visibility state to document's
+ node navigable's traversable navigable's
+ system visibility state. If response is a network error, then set failure to
- true. Set window's relevant settings object's execution ready flag. Otherwise, if the result of Should navigation response to navigation request of type in
- target be blocked by Content Security Policy? given navigationParams's request, response,
- navigationParams's policy
- container's CSP list,
- navigationType, and browsingContext is " To reactivate a Otherwise, if navigationParams's reserved environment is non-null and
- the result of checking a navigation response's adherence to its embedder policy given
- response, browsingContext, and navigationParams's policy container's embedder policy is false, then set
- failure to true. This algorithm updates document after it has come out of bfcache, i.e., after it has been made fully active
+ again. Otherwise, if the result of checking a navigation response's adherence to
- ` For each
+ formControl of form controls in document with an autofill field
+ name of " If failure is true, then: If document's suspended timer handles is not empty: Call navigationParams's process response end of body
- with response. Display the inline content with an appropriate error
- shown to the user given browsingContext. Assert: document's suspension time is not
+ zero. Run the environment discarding steps
- for navigationParams's reserved environment. Let suspendDuration be the current high resolution time minus
+ document's suspension time. Invoke WebDriver BiDi navigation failed with browsingContext and
- a new WebDriver BiDi navigation status whose id is navigationParams's id, status is " Let activeTimers be document's relevant global
+ object's map of active timers. Return. For each handle in document's suspended timer
+ handles, if activeTimers[handle] exists, then increase activeTimers[handle] by
+ suspendDuration. This is where the network errors defined and propagated by Fetch,
- such as DNS or TLS errors, end up being displayed to users. If response's status is 204 or
- 205, then call navigationParams's process response end of body with
- response, and return. If response has a ` If document's current document readiness is " If allowedToDownload is true, then handle response as a
- download. Set document's page showing flag to true. Invoke WebDriver BiDi download started with browsingContext and
- a new WebDriver BiDi navigation status whose id is navigationParams's id, status is " Update the visibility state of document to " Return. Fire a page transition event named To try to scroll to the fragment for a Let type be the computed type of
- response. Wait for an implementation-defined amount of time. (This is intended to allow
+ the user agent to optimize the user experience in the face of performance concerns.) If the user agent has been configured to process resources of the given type
- using some mechanism other than rendering the content in a browsing context, then
- skip this step. Otherwise, if the type is one of the following types, jump to the
- appropriate entry in the following list, and process response as described there: Queue a global task on the navigation and traversal task source
+ given document's relevant global object to run these steps: If document has no parser, or its parser has stopped parsing, or the user agent has reason to believe the user is no longer
+ interested in scrolling to the fragment, then abort
+ these steps. Scroll to the fragment given document. If document's indicated part is still null, then try to
+ scroll to the fragment for document. If the user agent's PDF viewer supported is true, then either follow the steps
- given in the plugin section providing
- navigationParams and type, or display
- the inline content given browsingContext. Once the steps have completed,
- return. To scroll to the fragment given a
+ See issue #6003 for
- discussion on picking one of these two behaviors to standardize. If document's indicated part is null, then set
+ document's target element to null. Otherwise, proceed onward. Otherwise, if document's indicated part is top of the
+ document, then: An explicitly supported XML MIME type is an XML MIME type for which
- the user agent is configured to use an external application to render the content (either a
- plugin rendering directly in browsingContext, or a separate
- application), or one for which the user agent has dedicated processing rules (e.g., a web
- browser with a built-in Atom feed viewer would be said to explicitly support the
- Set document's target element to null. An explicitly supported JSON MIME type is a JSON MIME type for which
- the user agent is configured to use an external application to render the content (either a
- plugin rendering directly in browsingContext, or a separate
- application), or one for which the user agent has dedicated processing rules, or one for which
- the user agent has a dedicated handler. Return. Otherwise: Otherwise, the document's type is such that the resource will not affect
- browsingContext, e.g., because the resource is to be handed to an external application
- or because it is an unknown type that will be processed as a download.
- Hand-off to external software given response, browsingContext,
- navigationParams's final sandboxing flag
- set, and hasTransientActivation. Assert: document's indicated part is an
+ element. Let target be document's indicated part. To process a navigate URL scheme, given a URL url, a
- browsing context browsingContext, a sandboxing flag set
- sandboxFlags, and a boolean hasTransientActivation: Set document's target element to target. If url is to be handled using a mechanism that does not affect
- browsingContext, e.g., because url's scheme is handled externally, then hand-off to external
- software given url, browsingContext, sandboxFlags, and
- hasTransientActivation. Run the ancestor details revealing algorithm on target. Otherwise, url is to be handled by displaying some sort of inline content, e.g.,
- an error message because the specified scheme is not one of the supported protocols, or an
- inline prompt to allow the user to select a
- registered handler for the given scheme. Display the
- inline content given browsingContext. Run the ancestor hidden-until-found revealing algorithm on
+ target. In the case of a registered handler being used, navigate will be
- invoked with a new URL. Scroll target into view,
+ with behavior set to "auto", block set to "start", and inline
+ set to "nearest". Run the focusing steps for target, with the
+ Move the sequential focus navigation starting point to
+ target. To hand-off to external software given a URL or response resource, a browsing context
- browsingContext, a sandboxing flag set sandboxFlags, and a
- boolean hasTransientActivation, user agents should: A There is also a target element for each For an HTML document document, the following
+ processing model must be followed to determine its indicated part: Return without invoking the external sofware package if all of these conditions hold: Let fragment be document's URL's fragment. browsingContext is not a top-level browsing context; If fragment is the empty string, then return the special value top of the
+ document. sandboxFlags has its sandboxed custom protocols navigation browsing
- context flag set; and Let potentialIndicatedElement be the result of finding a potential indicated element given document and
+ fragment. sandboxFlags has its sandboxed top-level navigation with user
- activation browsing context flag set, or hasTransientActivation is
- false. If potentialIndicatedElement is not null, then return
+ potentialIndicatedElement. Navigation inside an iframe toward external software can be seen by users as a
- new popup or a new top-level navigation. That's why its is allowed in sandboxed
- Let fragmentBytes be the result of percent-decoding fragment. Perform the appropriate handoff of resource while attempting to mitigate the risk
- that this is an attempt to exploit the target software. For example, user agents could prompt
- the user to confirm that the source browsing context's active
- document's origin is to be allowed to
- invoke the external software in question. In particular, if hasTransientActivation is
- false, then the user agent should not invoke the external software package without prior user
- confirmation. Let decodedFragment be the result of running UTF-8 decode without
+ BOM on fragmentBytes. 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. Set potentialIndicatedElement to the result of finding a potential indicated element given document and
+ decodedFragment. If potentialIndicatedElement is not null, then return
+ potentialIndicatedElement. If decodedFragment is an ASCII case-insensitive match for the
+ string Return null. To execute a To find a potential indicated element given a Let response be a response whose status is If there is an element in the document tree
+ whose root is document and that has an ID equal to fragment, then return the first such element
+ in tree order. If both of the following are true: If there is an initiatorOrigin is same origin-domain with
- browsingContext's active document's origin. Return null. The result of Should navigation request of type be blocked by Content Security
- Policy? given request and navigationType is " then: Let urlString be the result of running the URL serializer on request's URL. To save persisted state to a session history entry
+ entry: Let encodedScriptSource be the result of removing the leading " Set the scroll position data of entry
+ to contain the scroll positions for all of entry's document's restorable scrollable regions. Let scriptSource be the UTF-8 decoding
- of the percent-decoding of
- encodedScriptSource. Optionally, update entry's persisted user state
+ to reflect any state that the user agent wishes to persist, such as the values of form
+ fields. To restore persisted state from a session
+ history entry entry: If entry's scroll restoration
+ mode is " Append browsingContext's active
- document's URL to request's URL list. The user agent not restoring scroll positions does not imply that scroll
+ positions will be left at any particular value (e.g., (0,0)). The actual scroll position depends
+ on the navigation type and the user agent's particular caching strategy. So web applications
+ cannot assume any particular scroll position but rather are urged to set it to what they want it
+ to be. Let settings be browsingContext's active document's
- relevant settings object. Optionally, update other aspects of entry's document and its rendering, for instance values of form fields,
+ that the user agent had previously recorded in entry's persisted user state. Let baseURL be settings's API base URL. This can even include updating the Let script be the result of creating a classic script given
- scriptSource, settings, baseURL, and the default
- classic script fetch options. Restoring the value of form controls as part of this process does not fire any
+ Let evaluationStatus be the result of running the classic script script. Let result be undefined if evaluationStatus is an abrupt completion or evaluationStatus.[[Value]] is
- empty, or evaluationStatus.[[Value]] otherwise. The restorable scrollable regions of a If Type(result) is String, then set
- response to a response whose header list is « (` The encoding to UTF-8 means that unpaired surrogates will not roundtrip, once the HTML parser decodes the
- response body. Child navigable scroll restoration is handled as part of state
+ restoration for the session history entry for those navigables' Return response. In addition to the specific issues linked above, Some of the sections below, to which the above algorithm defers in certain cases, use the
+ When loading a document using one of the below algorithms, we use the
following steps to create and initialize a Let browsingContext be the result of the obtaining a browsing context to use for a navigation
- response given navigationParams's browsing context,
- navigationParams's final sandboxing flag
- set, navigationParams's cross-origin
- opener policy, and navigationParams's COOP enforcement result. Let browsingContext be navigationParams's navigable's active browsing
+ context. Set browsingContext to the result of the obtaining a browsing context to use for a
+ navigation response given browsingContext, navigationParams's
+ final sandboxing flag set,
+ navigationParams's cross-origin opener
+ policy, and navigationParams's COOP enforcement result. This can result in a browsing context
+ group switch, in which case browsingContext will be a newly-created browsing context instead
+ of being navigationParams's navigable's active browsing
+ context. In such a case, the created Let permissionsPolicy be the result of creating a permissions policy from a
@@ -89575,8 +93052,9 @@ interface Location { // but see also
The creating a permissions policy from a response algorithm makes use of the
passed origin. If Let window be null. If browsingContext is still on its initial If browsingContext's active document's is initial
+ This means that both the initial
- Otherwise: Let oacHeader be the result of getting a structured field value
given ` Let requestsOAC be true if oacHeader is not
null and oacHeader[0] is the Location { // but see also
Set window to the global
+ object of realmExecutionContext's Realm component. Let topLevelCreationURL be creationURL. Let topLevelOrigin be navigationParams's origin. If browsingContext is not a top-level browsing context, then: If navigable's container is not null,
+ then: Let parentEnvironment be browsingContext's container's relevant settings object. Let parentEnvironment be navigable's container's relevant settings object. Set topLevelCreationURL to parentEnvironment's top-level
creation URL. Let document be a new The new Let document be a new Set document's URL to creationURL. Set document's current document readiness to " Set window's associated
+ Run CSP initialization for a Let navigationTimingType be the result of switching on
- navigationParams's history handling: If navigationParams's fetch
+ controller is not null, then: Let fullTimingInfo be the result of extracting the full timing info from navigationParams's fetch controller. Let redirectCount be 0 if navigationParams's response's has cross-origin redirects is
+ true; otherwise navigationParams's request's redirect count. Create the navigation timing entry for document, given
+ fullTimingInfo, redirectCount, navigationTimingType,
+ navigationParams's response's
+ service worker timing info,
+ and navigationParams's response's
+ body info. Let redirectCount be 0 if navigationParams's response's has-cross-origin-redirects is true;
- otherwise navigationParams's request's
- redirect count.
-
Create the navigation timing entry for document, with
navigationParams's response's timing info, redirectCount,
- navigationTimingType, and navigationParams's navigationParams's navigation timing
+ type, and navigationParams's response's service worker timing info. Process link headers given document,
navigationParams's response, and
@@ -89838,1167 +93341,359 @@ new PaymentRequest(…); // Not allowed to use
document.domain = 'example.com';
</script>
- Some of the sections below, to which the above algorithm defers in certain cases, require the
- user agent to update the session history with the new page, given some navigation
- params navigationParams and a Let sessionHistory be navigationParams's browsing context's session
- history. Let unloadTimingInfo be a new document unload timing
- info. Let previousDocument be sessionHistory's current
- entry's document. Unload previousDocument with
- unloadTimingInfo and newDocument's
- relevant global object. If this instance of the navigation algorithm is canceled while
- this step is running the unload a document algorithm, then the unload a
- document algorithm must be allowed to run to completion, but this instance of the navigation algorithm must not run beyond this step. (In particular, for
- instance, the cancelation of this algorithm does not abort any event dispatch or script
- execution occurring as part of unloading the document or its descendants.) If newDocument's event loop is not previousDocument's
- event loop, then the user agent may unload
- previousDocument in parallel, In that case, the user agent should set
- unloadTimingInfo to null. If navigationParams's response's has-cross-origin-redirects is false,
- and newDocument's origin is the same as previousDocument's origin, then set newDocument's previous
- document unload timing to unloadTimingInfo. Switch on navigationParams's history
- handling: Let oldDocument be sessionHistory's current entry's
- document. For each entry of
- sessionHistory: if entry's document
- is oldDocument, then set entry's document to newDocument. Traverse the history to sessionHistory's current
- entry with historyHandling set to
- navigationParams's history
- handling. Let newEntry be a new session history entry whose URL is newDocument's URL and document is
- newDocument. Some browsers copy over the serialized state sessionHistory's
- current entry in cases where its URL equals that of newDocument, but this is
- inconsistent. See issue #6213 for
- more discussion on this. If newDocument's URL
- requires storing the policy container in history, set newEntry's
- policy container to navigationParams's
- policy container. Insert newEntry into sessionHistory after its current
- entry. Traverse the history to newEntry with
- historyHandling set to " Remove all the entries in sessionHistory after its current entry.
- (If the current entry is the last entry in the session history, then no entries
- are removed.) This doesn't necessarily have to affect the
- user agent's user interface. Let newEntry be a new session history entry whose URL is newDocument's URL and document is
- newDocument. If newDocument's URL
- requires storing the policy container in history, then set newEntry's
- policy container to navigationParams's
- policy container. Append newEntry to
- sessionHistory. Traverse the history to newEntry. The navigation algorithm has now matured. Try to scroll to the fragment for newDocument. To try to scroll to the fragment for a Wait for an implementation-defined amount of time. (This is intended to allow
- the user agent to optimize the user experience in the face of performance concerns.) Queue a global task on the networking task source given
- document's relevant global object to run these steps: If document has no parser, or its parser has stopped parsing, or the user agent has reason to believe the user is no longer
- interested in scrolling to the fragment, then abort
- these steps. Scroll to the fragment given in document's URL. If this does not find an indicated part of the document, then try to scroll to the
- fragment for document. When an HTML document is to be loaded, given navigation params
- navigationParams, the user agent must queue a task on the networking task source
- to: Let document be the result of creating and initializing a Create an HTML parser and associate it with the document. Each
- task that the networking task source places on
- the task queue while fetching runs must then fill the parser's input byte
- stream with the fetched bytes and cause the HTML parser to perform the
- appropriate processing of the input stream. The first task that the networking task
- source places on the task queue while fetching runs must process link
- headers given document, navigationParams's response, and " The input byte stream converts bytes into characters for use in the
- tokenizer. This process relies, in part, on character encoding
- information found in the real Content-Type metadata of the
- resource; the computed type is not used for this purpose. When no more bytes are available, the user agent must queue a global task on the
- networking task source given the newly-created Call navigationParams's process response end of body with
- navigationParams's response. Have the parser process the implied EOF character, which eventually causes a After creating the When faced with displaying an XML file inline, provided navigation params
- navigationParams and a string type, user agents must follow the requirements
- defined in XML and Namespaces in XML, XML Media Types,
- DOM, and other relevant specifications to create and initialize a The first task that the networking task source
- places on the task queue while fetching runs must process link headers
- given document, navigationParams's response, and " At the time of writing, the XML specification community had not actually yet
- specified how XML and the DOM interact. The actual HTTP headers and other metadata, not the headers as mutated or implied by the
- algorithms given in this specification, are the ones that must be used when determining the
- character encoding according to the rules given in the above specifications. Once the character
- encoding is established, the document's character encoding must be set to that
- character encoding. Then, with document, the user agent must update the session history with the
- new page given navigationParams and document. User agents may do
- this before the complete document has been parsed (thus achieving incremental rendering),
- and must do this before any scripts are to be executed. When no more bytes are available, the user agent must queue a global task on the
- networking task source given document's relevant global
- object to call navigationParams's process response end of body with
- navigationParams's response. Once parsing is complete, the user agent must set document's navigation id to null. For HTML documents this is reset when parsing is complete, after firing the load
- event. Error messages from the parse process (e.g., XML namespace well-formedness errors) may be
- reported inline by mutating the When a plain text document is to be loaded, provided navigation params
- navigationParams and a string type, the user agent must queue a
- task on the networking task source to:
-
- Let document be the result of creating and initializing a Set document's parser cannot change the mode flag to
- true. Set document's mode
- to " Create an HTML parser and associate it with the document. Act as
- if the tokenizer had emitted a start tag token with the tag name "pre" followed by a single
- U+000A LINE FEED (LF) character, and switch the HTML parser's tokenizer to the
- PLAINTEXT state. Each task that the
- networking task source places on the task queue while fetching runs
- must then fill the parser's input byte stream with the fetched bytes and cause the
- HTML parser to perform the appropriate processing of the input stream. The rules for how to convert the bytes of the plain text document into actual characters, and
- the rules for actually rendering the text to the user, are defined by the specifications for the
- computed MIME type of the resource (i.e.,
- type). The document's character encoding must be set to the character encoding used to
- decode the document. The first task that the networking task source
- places on the task queue while fetching runs must process link headers
- given document, navigationParams's response, and " When no more bytes are available, the user agent must queue a global task on the
- networking task source given the newly-created Call navigationParams's process response end of body with
- navigationParams's response. Have the parser process the implied EOF character, which eventually causes a After creating the User agents may add content to the In particular, if the user agent supports the When a resource with the type This algorithm is passed navigation params, but it's unclear how
- exactly to use them. For each body part obtained from the resource, the user agent must run process a navigate
- response using the new body part and the same browsing context, with history handling set to " For the purposes of algorithms processing these body parts as if they were complete stand-alone
- resources, the user agent must act as if there were no more bytes for those resources whenever the
- boundary following the body part is reached. Thus, When an image, video, or audio resource is to be loaded, provided navigation params
- navigationParams and a string type, the user agent should:
-
- Let document be the result of creating and initializing a Set document's mode
- to " Append an Append a Append a Append an element host element for the media, as described below, to the
- Set the appropriate attribute of the element host element, as described below,
- to the address of the image, video, or audio resource. Process link headers given document,
- navigationParams's response, and
- " The element host element to create for the media is the element given in
- the table below in the second cell of the row whose first cell describes the media. The
- appropriate attribute to set is the one given by the third cell in that same row. Then, the user agent must act as if it had stopped
- parsing. After creating the User agents may add content to the When no more bytes are available, the user agent must queue a global task on the
- networking task source given the newly-created When a resource that requires an external resource to be rendered is to be loaded, provided
- navigation params navigationParams and a string type, the user
- agent should:
-
- Let document be the result of creating and initializing a Set document's mode
- to " Mark document as being a plugin document Append an Append a Append a Append an Set the Process link headers given document,
- navigationParams's response, and
- " The term plugin document is used by
- Content Security Policy as part of the mechanism that ensures Then, the user agent must act as if it had stopped
- parsing. After creating the User agents may add content to the When the user agent is to display a user agent page inline, provided a browsing
- context browsingContext, the user agent should: Let navigationParams be a new navigation params whose request is null, response is null, origin is a new opaque origin, final sandboxing flag set is an empty set, cross-origin opener policy is a new cross-origin
- opener policy, COOP enforcement
- result is a new cross-origin opener policy
- enforcement result, reserved
- environment is null, process response end of body is
- an algorithm that does nothing, and browsing context is
- browsingContext. The algorithm called in the next step is not prepared to deal with a null response. Probably we should synthesize one
- instead. Let document be the result of creating and initializing a Set document's mode
- to " Either associate document with a custom rendering that is not rendered using
- the normal Once the page has been set up, the user agent must act as if it had stopped parsing. After creating the To navigate to a fragment given a browsing
- context browsingContext, a URL url, a history
- handling behavior historyHandling, and a navigation
- id navigationId: If historyHandling is not " This doesn't necessarily have to affect the user
- agent's user interface. Remove any tasks queued by the history traversal
- task source that are associated with any Append a new session history entry to the session history whose
- URL is url, document
- is the current entry's document, policy container is the current entry's policy-container and scroll restoration mode is the current
- entry's scroll restoration
- mode. Traverse the history to the new entry, with historyHandling set to historyHandling. This will
- scroll to the fragment given in what is now the document's URL. Invoke WebDriver BiDi fragment navigated with browsingContext,
- and a new WebDriver BiDi navigation status whose id is navigationId, url is resource's url, and status is " If the scrolling fails because the relevant ID has
- not yet been parsed, then the original navigation algorithm will
- take care of the scrolling instead, as the last few steps of its update the session history
- with the new page algorithm. When the user agent is required to scroll to the fragment and the indicated part
- of the document, if any, is being rendered, the user agent must either change
- the scrolling position of the document using the following algorithm, or perform some other action
- such that the indicated part of the document is brought to the user's attention. If
- there is no indicated part, or if the indicated part is not being rendered, then the
- user agent must do nothing. The aforementioned algorithm is as follows: If there is no indicated part of the
- document, set the If the indicated part of the
- document is the top of the document, then: Otherwise: Let target be element that is the indicated part of the
- document. Set the Run the ancestor details revealing algorithm on target. Run the ancestor hidden-until-found revealing algorithm on
- target. Scroll target into view,
- with behavior set to "auto", block set to "start", and inline
- set to "nearest". Run the focusing steps for target, with the
- Move the sequential focus navigation starting point to
- target. The indicated part of the document is the one that the fragment, if any, identifies. The semantics of the fragment in terms of mapping it to a node is defined by the
- specification that defines the MIME type used by the There is also a target element for each For HTML documents (and HTML MIME types), the following
- processing model must be followed to determine what the indicated part of the
- document is. Let fragment be the document's URL's
- fragment. If fragment is the empty string, then the indicated part of the
- document is the top of the document; return. If find a potential indicated element with fragment returns
- non-null, then the return value is the indicated part of the document;
- return. Let fragmentBytes be the result of percent-decoding fragment. Let decodedFragment be the result of running UTF-8 decode without
- BOM on fragmentBytes. If find a potential indicated element with decodedFragment returns
- non-null, then the return value is the indicated part of the document;
- return. If decodedFragment is an ASCII case-insensitive match for the
- string There is no indicated part of the
- document. To find a potential indicated element given a string fragment, run these
- steps: If there is an element in the document tree that
- has an ID equal to fragment, then return the first
- such element in tree order. If there is an Return null.Cross-Origin-Embedder-Policy` and
- `Cross-Origin-Embedder-Policy-Report-Only` HTTP response
- headers allow a server to declare an embedder policy for an environment
- settings object. These headers are structured
- headers whose values must be token.
+ Document, which ultimately happens in the create and initialize a Document object
+ algorithm. The parameters to that algorithm are tracked via a navigation params
+ struct, which has the following items:report-to" parameter can have a valid URL
- string identifying an appropriate reporting endpoint.
+
+
+ unsafe-none") in the presence of a header that cannot
- be parsed as a token. This includes inadvertent lists created by combining multiple instances of
- the `Cross-Origin-Embedder-Policy` header present in a given response:
-
-
+
-
-
-
- `
- Cross-Origin-Embedder-Policy`Final embedder policy value
-
-
- No header delivered
- "
- unsafe-none"
-
- `
- require-corp`"
- require-corp"
-
- `
- unknown-value`"
- unsafe-none"
-
- `
- require-corp, unknown-value`"
- unsafe-none"
-
- `
- unknown-value, unknown-value`"
- unsafe-none"
-
- `
- unknown-value, require-corp`"
- unsafe-none"
-
-
- `
- require-corp, require-corp`"
- unsafe-none"Cross-Origin-Embedder-Policy-Report-Only`.)DocumentDocumentDocumentDocumentDocumentNavigationTimingType used for creating the navigation timing entry for the new DocumentDocument, once it has been created
-
-
+
-
- Document creation, the relevant traversable navigable's session history gets updated. A history handling
+ behavior is used to track the desired type of session history update throughout the
+ navigation process. It is one of the following:Cross-Origin-Embedder-Policy` and "item" from
- response's header list.
+
+
+ push"replace"Beginning navigation
+
+
+
+
+
+
+ Document sourceDocument, with an optional POST resource,
+ string, or null documentResource (default
+ null), an optional response-or-null response (default null), an optional boolean exceptionsEnabled (default false), an optional
+ history handling behavior historyHandling (default "push"), an optional string cspNavigationType (default "other"), and an optional referrer policy referrerPolicy (default the empty
+ string):
+
+
+
+ SecurityError" DOMException.canceled", and url is url, and return.Cross-Origin-Embedder-Policy-Report-Only` and "item"
- from response's header
- list.load events to
+ true.pending".traversal", then:
-
+
+ canceled", and url is url.report-to"] exists, then set policy's endpoint to
- parsedItem[1]["report-to"].Embedder policy checks
+ javascript", then:
-
+
+ javascript: URL given navigable,
+ url, historyHandling, initiatorOriginSnapshot, and
+ cspNavigationType.navigation", parentPolicy's report only reporting endpoint,
- "reporting", and target's container document's relevant settings
- object.
+
+ navigation", parentPolicy's reporting endpoint,
- "enforce", and target's
- container document's relevant settings
- object.
+
+
- canceled", and url is url.WorkerGlobalScope
- workerGlobalScope, an environment settings object owner, and
- a response response:
-
+ DedicatedWorkerGlobalScope object,
- then return true.
+
worker
- initialization", owner's policy's report only reporting endpoint,
- "reporting", and owner.worker initialization", owner's policy's
- reporting endpoint,
- "enforce", and owner.about:blank, then set documentState's origin to documentState's initiator origin.about:srcdoc, then set
+ documentState's origin to
+ navigable's parent's active document's origin.
-
+
+
+
-
-
-
+
-
-
-
- key
- value
-
-
- type
- type
-
-
- blockedURL
- serialized
-
-
-
- disposition
- disposition
-
+
+ coep" report type for endpoint on settings.
- Policy containers
+
+
+ Document, a WorkerGlobalScope, or a WorkletGlobalScope.
- It has the following items:
-
+
-
navigate"navigate", sourceSnapshotParams,
+ targetSnapshotParams, navigationId, navigationParams,
+ cspNavigationType, with allowPOST
+ set to true and completionSteps set to the following
+ step:
+
+
-
- blob", then return false.Ending navigation
-
- Document, all navigations that don't get aborted will ultimately end up calling into
+ one of the below algorithms.The usual cross-document navigation case
+
+
-
+ blob", then return a clone of response's URL's blob URL
- entry's environment's policy
- container.load
+ events to false.unsafe-none".Referrer-Policy` header given response.
+
+
+ replace", otherwise
+ null.
-
-
- about:srcdoc, then:
-
WorkerGlobalScope workerGlobalScope, a response response, and an environment
- environment:
-
+ blob":The
- javascript: URL special case
-
- javascript: URLs have a dedicated label
+ on the issue tracker documenting various problems with their specification.javascript: URL, given a navigable
+ targetNavigable, a URL url, a history handling
+ behavior historyHandling, an origin initiatorOrigin,
+ and a string cspNavigationType:
+
- replace".Session history and navigation
+ Browsing sessions
+ Cross-Origin-Opener-Policy` header or navigation.Blocked", then return. javascript: URL given targetNavigable,
+ url, and initiatorOrigin.
-
+ Window.Document was created, so we will not perform a navigation.The session history of browsing contexts
+ Documents in a browsing context is its session
- history. Each browsing context, including child browsing contexts, has a distinct session history. A browsing
- context's session history consists of a flat list of session history entries.
+
+ Document object in a browsing context's session
- history is associated with a unique History object which must all model the
- same underlying session history.history getter steps
- are to return this's associated
- Document's History instance.
+
-
Document or null
+
- Document for its document. However, when a Document is not active, it's possible for it to be discarded to free resources. The URL and other
- data in the session history entry is then used to bring a new Document
- into being to take the place of the original, in the case where the user agent finds itself
- having to navigate to the entry.Document for the
- destination session history entry is not null (i.e., the predicate in step 1
- of traversing the history is false), that means
- the browser has cached that Document. This cache is often called a
- back-forward cache, or bfcache (or perhaps
- "blazingly fast" cache).javascript: URL that
+ the navigate algorithm was called with. This means javascript: URLs are never stored in session history, and so can never be
+ traversed to.javascript: URL given a navigable
+ targetNavigable, a URL url, and an origin
+ newDocumentOrigin:auto"
+
- javascript:" from urlString.dir
- attribute). This prevents values from being displayed incorrectly after a history traversal when
- the user had originally entered the values with an explicit, non-default directionality.Document instance and it would have to be reconstructed if a new
- Document were opened.div was made to animate, so that if the user goes back, it can be made
- to animate to the same location. Or alternatively, it could be used to keep a pointer into a
- cache of data that would be fetched from the server based on the information in the
- URL, so that when going back and forward, the information doesn't have to be fetched
- again.
-
+ auto"manual"
+ history.pushState(). Or it can occur via navigation to a fragment.
+
Content-Type`, `text/html;charset=utf-8`) »
-
+ Document objects which are referenced from
- script.Document will
- set the corresponding document item of any session history entries to null. Subsequent navigations to
- those entries will result in the creation of a new Document object, and set the document item to it.
+
+
+ Document in a browsing context can also have a latest
- entry. This is the entry for that Document to which the browsing
- context's session history was most recently traversed. When a
- Document is created, it initially has no latest entry.
+
The
+ History interfaceDocument
+ to be null; is that correct?
+ enum ScrollRestoration { "auto", "manual" };
+
-
+ window.history.lengthwindow.history.scrollRestoration [ = value ]window.history.statenavigate"window.history.go([ delta ])window.history.back()Fragment navigations
-
+
- window.history.forward()
+
+ window.history.pushState(data, "")replace", otherwise
+ null.window.history.pushState(data, "", url)Document cannot have
- its URL rewritten to url, a "SecurityError"
- DOMException will be thrown.window.history.replaceState(data, "")push", then:
+
+
- window.history.replaceState(data, "", url)Document cannot have
- its URL rewritten to url, a "SecurityError"
- DOMException will be thrown.Document objects that share that top-level browsing context, with all
- the entries that are current entries in their respective session histories removed except for the current entry of
- the joint session history.history.state
+ is nulled out, and various events are fired; and once asynchronously, where the final values for
+ index and length are set, history.state remains
+ untouched, and no events are fired.Document is new and the
+ relevant ID has not yet been parsed, then the second
+ asynchronous call to update document for history step application will take
+ care of scrolling.Document in a browsing context might have a
- different event loop, the actual state of the joint session history can
- be somewhat nebulous. For example, two sibling iframe elements could both traverse from one unique origin to another at the same time,
- so their precise order might not be well-defined; similarly, since they might only find out about
- each other later, they might disagree about the length of the joint session
- history.
+
+
+
- complete".History object has state,
- initially null.length getter
- steps are:
-
+ Document is not fully active,
- then throw a "SecurityError" DOMException.scrollRestoration getter steps are:
-
+ Document is not fully active,
- then throw a "SecurityError" DOMException.
+
- scrollRestoration setter steps
- are:
-
+ Document is not fully active,
- then throw a "SecurityError" DOMException.state getter
- steps are:
-
- Document is not fully active,
- then throw a "SecurityError" DOMException.
+
+
+
+ replace" navigations,
+ as it resolves race conditions across multiple synchronous navigations.go(delta)
- method steps are:
-
+ Document.Non-fetch schemes and external software
- SecurityError" DOMException.location.reload() method was called, and return.
+
back() method steps
- are:
-
- Document.SecurityError" DOMException.
+
+
+
+ forward() method
- steps are:
-
+ Document.SecurityError" DOMException.
+
-
+
-
- iframe only when one of allow-popups, allow-top-navigation, allow-top-navigation-by-user-activation,
+ or allow-top-navigation-to-custom-protocols
+ is specified.example.com to shop.example), transitions would
- otherwise have to involve cross-event-loop synchronization.
+ Preventing navigation
-
-
-
+
-
-
+
- Document the active document), then cancel that
- attempt to navigate the browsing context.Document as the Document of the specified
- entry, then run these substeps:
-
refuse", then abort these steps.
+
-
+ Document document,
- a URL newURL, an optional serialized state-or-null serializedData (default null), and an optional
- boolean isPush (default false), are:
-
- about:blank
- Document, then set isPush to false.pushState() on an
- initial about:blank
- Document behaves as a replaceState()
- call.
-
BeforeUnloadEvent.Document objects in the
- top-level browsing context's document family.type attribute to
+ beforeunload and its cancelable attribute true.
-
+
+ returnValue attribute of event
+ is not the empty string; and
+
beforeunload", and "".returnValue attribute is ignored.
-
- Reloading and traversing
-
+
+
+
+
parent.location.reload().Document
+ sourceDocument:
+
-
+
hashchange event to be fired.
-
History instance's state to state.pushState(data,
- unused, url) method steps are to run the shared history
- push/replace state steps given this, data, url, and
- true.replaceState(data, unused,
- url) method steps are to run the shared history push/replace state
- steps given this, data, url, and false.Non-fragment synchronous "navigations"
- History
- history, a value data, a scalar value string-or-null
- url, and a boolean isPush, are:history.replaceState() and history.pushState() APIs, but various other parts of the
+ standard also need to perform updates to the active
+ history entry, and they use these steps to do so.Document
+ document, a URL newURL, an optional serialized
+ state-or-null serializedData (default
+ null), and an optional history handling behavior historyHandling (default "replace"), are:
+
-
Document.
+
SecurityError" DOMException.about:blank is true, then set
+ historyHandling to "replace".
-
pushState() on an
+ initial about:blank
+ Document behaves as a replaceState() call.SecurityError"
- DOMException.replace", otherwise null.push", then:SecurityError"
- DOMException.
+
+
+ Document object in the session history
- after having added the new entry. (Thus the state history acts as a FIFO buffer for eviction, but
- as a LIFO buffer for navigation.)hashchange event to be fired.Document document can have its URL rewritten to a
- URL targetURL if the following algorithm returns true:
-
- http: and https: URLs.)file", and targetURL and documentURL differ in their
- path component, then return false. (Differences in query and fragment
- are allowed for file: URLs.)
+
+
+ popstate events
+ fire for fragment navigations, but not for history.pushState() calls.
-
-
+
-
- document's URL
- targetURL
- can have its URL rewritten
-
- https://example.com/home
- https://example.com/home#about
- ✅
-
- https://example.com/home
- https://example.com/home?page=shop
- ✅
-
- https://example.com/home
- https://example.com/shop
- ✅
-
- https://example.com/home
- https://user:pass@example.com/home
- ❌
-
- https://example.com/home
- http://example.com/home
- ❌
-
- file:///path/to/x
- file:///path/to/x#hash
- ✅
-
- file:///path/to/x
- file:///path/to/x?search
- ✅
-
- file:///path/to/x
- file:///path/to/y
- ❌
-
- about:blank
- about:blank#hash
- ✅
-
- about:blank
- about:blank?search
- ❌
-
- about:blank
- about:srcdoc
- ❌
-
- data:text/html,foo
- data:text/html,foo#hash
- ✅
-
- data:text/html,foo
- data:text/html,foo?search
- ❌
-
- data:text/html,foo
- data:text/html,bar
- ❌
-
- data:text/html,foo
- data:bar
- ❌
-
- blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43
- blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43#hash
- ✅
-
- blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43
- blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43?search
- ❌
-
- blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43
- blob:https://example.com/anything
- ❌
-
- blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43
- blob:path
- ❌
- Populating a session history entry
- Document
- matters, and not its origin. They can mismatch in
- cases like about:blank Documents with inherited origins, in sandboxed
- iframes, or when the document.domain
- setter has been used.Document) or can result in populating the
+ session history entry with an error
+ document.NavigationTimingType navTimingType, a source snapshot params
+ sourceSnapshotParams, a target snapshot params
+ targetSnapshotParams, an optional navigation ID-or-null
+ navigationId (default null), an optional navigation params-or-null
+ navigationParams (default null), an optional string cspNavigationType
+ (default "other"), an optional boolean allowPOST (default false), and optional
+ algorithm steps completionSteps (default an empty
+ algorithm):
+
+ <!DOCTYPE HTML>
-<!-- this is https://example.com/line?x=5 -->
-<html lang="en">
-<title>Line Game - 5</title>
-<p>You are at coordinate 5 on the line.</p>
-<p>
- <a href="?x=6">Advance to 6</a> or
- <a href="?x=4">retreat to 4</a>?
-</p>
+ <!DOCTYPE HTML>
-<!-- this starts off as https://example.com/line?x=5 -->
-<html lang="en">
-<title>Line Game - 5</title>
-<p>You are at coordinate <span id="coord">5</span> on the line.</p>
-<p>
- <a href="?x=6" onclick="go(1); return false;">Advance to 6</a> or
- <a href="?x=4" onclick="go(-1); return false;">retreat to 4</a>?
-</p>
-<script>
- var currentPage = 5; // prefilled by server
- function go(d) {
- setupPage(currentPage + d);
- history.pushState(currentPage, "", '?x=' + currentPage);
- }
- onpopstate = function(event) {
- setupPage(event.state);
- }
- function setupPage(page) {
- currentPage = page;
- document.title = 'Line Game - ' + currentPage;
- document.getElementById('coord').textContent = currentPage;
- document.links[0].href = '?x=' + (currentPage+1);
- document.links[0].textContent = 'Advance to ' + (currentPage+1);
- document.links[1].href = '?x=' + (currentPage-1);
- document.links[1].textContent = 'retreat to ' + (currentPage-1);
- }
-</script>pushState() method is the same information as would be sent
- to the server, but in a more convenient form, so that the script doesn't have to parse the URL
- each time the user navigates.
+
scrollRestoration attribute as soon as possible
- (e.g., in the first script element in the document's head element) to
- ensure that any entry added to the history session gets the desired scroll restoration mode.
+
- <head>
- <script>
- if ('scrollRestoration' in history)
- history.scrollRestoration = 'manual';
- </script>
-</head>
- Implementation notes for session history
-
+
+
+ History interface is not meant to place restrictions on how implementations
- represent the session history to the user.
+
history object are derived from the actual session history as
- seen from the user's perspective.iframes has a history object distinct from the iframes' history objects, despite the fact that typical web browsers present the
- user with just one "Back" button, with a session history that interleaves the navigation of the
- two inner frames and the outer page.pushState(),
- the UA provide the user with a way to jump back to the previous page (rather than just going back
- to the previous state). For example, the back button could have a drop down showing just the pages
- in the session history, and not showing any of the states. Similarly, an aural browser could have
- two "back" commands, one that goes back to the previous state, and one that jumps straight back to
- the previous page.pushState() and replaceState(), user agents are encouraged to prevent
- abuse of these APIs via too-frequent calls or over-large state objects. As detailed above, the
- algorithm explicitly allows user agents to ignore any such calls when appropriate.Blocked", then set failure to true. X-Frame-Options` given navigationParams's response, navigable,
+ navigationParams's policy
+ container's CSP list, and
+ navigationParams's origin is false,
+ then set failure to true.The
+ Location interface
+
+ Window object is associated with a unique instance of a Location
- object, allocated when the Window object is created.Location exotic object is defined through a mishmash of IDL,
- invocation of JavaScript internal methods post-creation, and overridden JavaScript internal
- methods. Coupled with its scary security policy, please take extra care while implementing
- this excrescence.
+
+ canceled", and url is navigationParams's response's URL.Location object, run these steps:
-
Location platform
- object.
+
+ valueOf", {
- [[Value]]: valueOf,
- [[Writable]]: false,
- [[Enumerable]]: false,
- [[Configurable]]: false }).
+
+ valueOf and @@toPrimitive own
- data properties, as well as the fact that all of Location's IDL attributes are marked
- [LegacyUnforgeable], is required by legacy code that consulted
- the Location interface, or stringified it, to determine the document URL, and then used it in a security-sensitive way.
- In particular, the valueOf, @@toPrimitive, and [LegacyUnforgeable] stringifier mitigations ensure that code such as
- foo[location] = bar or location + "" cannot be
- misdirected.complete", and url is navigationParams's response's URL.
-
document.location [ = value ]window.location [ = value ]Location object with the current page's location.
+
Document object's location getter steps are to return
- this's relevant global object's Location object, if
- this is fully active, and null otherwise.Window object's location getter steps are to return this's
- Location object.Location objects provide a representation of the URL of the active document of their
- Document's browsing context, and allow the
- current entry of the browsing context's session history to be changed,
- by adding or replacing entries in the history object.client", then set it to request's referrer.
+ [Exposed=Window]
-interface Location { // but see also additional creation steps and overridden internal methods
- [LegacyUnforgeable] stringifier attribute USVString href;
- [LegacyUnforgeable] readonly attribute USVString origin;
- [LegacyUnforgeable] attribute USVString protocol;
- [LegacyUnforgeable] attribute USVString host;
- [LegacyUnforgeable] attribute USVString hostname;
- [LegacyUnforgeable] attribute USVString port;
- [LegacyUnforgeable] attribute USVString pathname;
- [LegacyUnforgeable] attribute USVString search;
- [LegacyUnforgeable] attribute USVString hash;
+ NavigationTimingType navTimingType:
-
location.toString()location.hrefLocation object's URL.
+
location.originLocation object's URL's origin.
+
+ about:srcdoclocation.protocolLocation object's URL's scheme.Content-Type`, `text/html`) »location.hostLocation object's URL's host and port (if different from the default
- port for the scheme).location.hostnameLocation object's URL's host.
+
+
+
- location.portLocation object's URL's port.location.pathnameLocation object's URL's path.location.searchLocation object's URL's query (includes leading "?" if non-empty).?").location.hashLocation object's URL's fragment (includes leading "#" if non-empty).#").location.assign(url)location.replace(url)location.reload()location.ancestorOriginsDOMStringList object listing the origins of the ancestor browsing contexts, from the parent browsing
- context to the top-level browsing context.Location object has an associated relevant Document,
- which is this Location object's relevant global object's browsing context's active document, if this
- Location object's relevant global object's browsing context is non-null, and null otherwise.
+
+ Location object has an associated url,
- which is this Location object's relevant Document's URL, if this Location object's relevant
- Document is non-null, and about:blank otherwise.Location object has an associated ancestor origins list. When a
- Location object is created, its ancestor origins list must be set to a
- DOMStringList object whose associated list is the list of strings that
- the following steps would produce:
-
+
+
Document with which this Location object is associated.document"include"manual"Location-object navigate, given a URL url
- and an optional history handling behavior historyHandling (default "default"):
-
Location object's relevant
- global object's browsing context.navigate"Location object's relevant Document is not
- yet completely loaded, and the incumbent
- global object does not have transient activation, then set
- historyHandling to "replace".href getter
- steps are:
+
+ POST`.
-
+ Document is non-null and its
- origin is not same origin-domain with
- the entry settings object's origin, then throw a
- "SecurityError" DOMException.Content-Type`
+ to documentResource's request
+ content-type in request's header
+ list.href setter steps are:
-
+ Document is null, then
- return.TypeError exception.Location-object navigate given the resulting URL
- record.href setter intentionally has no
- security check.
+
+ origin
- getter steps are:
-
+ Document is non-null and its
- origin is not same origin-domain with
- the entry settings object's origin, then throw a
- "SecurityError" DOMException.protocol
- getter steps are:
-
+ Document is non-null and its
- origin is not same origin-domain with
- the entry settings object's origin, then throw a
- "SecurityError" DOMException.
+
+ :".protocol setter steps are:
-
+ Document is null, then
- return.Document's origin is not same origin-domain with the
- entry settings object's origin, then throw a
- "SecurityError" DOMException.:", with copyURL
- as url and scheme start state as
- state override.https:" (or even "https::::") is the same as
- providing a value of "https".
+
+
- SyntaxError" DOMException.
+
+ Location-object navigate to copyURL.host getter
- steps are:
-
+ Document is non-null and its
- origin is not same origin-domain with
- the entry settings object's origin, then throw a
- "SecurityError" DOMException.
+
+ :" and url's port, serialized.
+
+
- host setter steps are:
-
+
- Document is null, then
- return.Document's origin is not same origin-domain with the
- entry settings object's origin, then throw a
- "SecurityError" DOMException.Blocked", then set response to a network error and
+ break. Location-object navigate to copyURL.hostname
- getter steps are:
-
+ Document is non-null and its
- origin is not same origin-domain with
- the entry settings object's origin, then throw a
- "SecurityError" DOMException.
+
-
+
+ hostname setter steps are:
-
Document is null, then
- return.Document's origin is not same origin-domain with the
- entry settings object's origin, then throw a
- "SecurityError" DOMException.mailto: URLs
+ and such.Location-object navigate to copyURL.port getter
- steps are:
-
+ Document is non-null and its
- origin is not same origin-domain with
- the entry settings object's origin, then throw a
- "SecurityError" DOMException.port setter steps are:
-
Document is null, then
- return.
+
+ Document's origin is not same origin-domain with the
- entry settings object's origin, then throw a
- "SecurityError" DOMException.unsafe-none", then set response to an
+ appropriate network error and break.Location-object navigate to copyURL.pathname
- getter steps are:
-
+ Document is non-null and its
- origin is not same origin-domain with
- the entry settings object's origin, then throw a
- "SecurityError" DOMException.Location object's url.pathname setter steps are:
+
-
-
Document is null, then
- return.Document's origin is not same origin-domain with the
- entry settings object's origin, then throw a
- "SecurityError" DOMException.Location-object navigate to copyURL.search
- getter steps are:
-
+ Document is non-null and its
- origin is not same origin-domain with
- the entry settings object's origin, then throw a
- "SecurityError" DOMException.
- 0 1 2 3 top/a /a#foo /a#bar /b ?", followed by this's url's query./a, the server responds with a `Location`
+ header pointing to /c. That is, locationURL points to
+ /c and so we have reached this step instead of breaking out of the loop.search setter steps are:
-
Document is null, then
- return.
- 0 1 2 3 top/a /a#foo /c#bar /b Document's origin is not same origin-domain with the
- entry settings object's origin, then throw a
- "SecurityError" DOMException./c itself had a `Location` header pointing to /a. Such a case would
+ end up like so:
+ 0 1 2 3 top/a /a#foo /a#bar /b
+
-
+ ?" removed, if any.Location-object navigate to copyURL.hash getter
- steps are:
+
+ Location` header.
-
Document is non-null and its
- origin is not same origin-domain with
- the entry settings object's origin, then throw a
- "SecurityError" DOMException.Location` header.#", followed by this's url's fragment.hash setter steps are:
+
-
-
Document is null, then
- return.Document's origin is not same origin-domain with the
- entry settings object's origin, then throw a
- "SecurityError" DOMException.
+
- #"
- removed, if any.location.hash on scroll. It does not apply to other
- mechanisms of fragment navigation, such as the location.href setter or location.assign().
+
Location-object navigate to copyURL.a and area elements,
- the hash setter does not special case the empty string, to
- remain compatible with deployed scripts.
+ assign(url) method steps are:
-
+ Document is null, then
- return.Document's origin is not same origin-domain with the
- entry settings object's origin, then throw a
- "SecurityError" DOMException.SyntaxError"
- DOMException.Location-object navigate given the resulting URL
- record.replace(url) method steps are:
-
- Document is null, then
- return.SyntaxError"
- DOMException.Location-object navigate given the resulting URL
- record and "replace".replace() method intentionally has
- no security check.Document's
+ node navigable is a top-level traversable or if all of its
+ Document's ancestor navigables all have active documents whose origins are the same origin as the element's
+ node document's origin. If an element
+ has a browsing context scope origin, then its value is the origin of the element's node document.reload() method
- steps are to run the appropriate steps from the following list:
-
- Document is nullDocument or null.Document's origin is not same origin-domain with the
- entry settings object's originSecurityError" DOMException.resize event in response to the user resizing the
- browsing context
+
iframe srcdoc documentiframe
- attributes of the browsing context's container.Document's URL, with exceptionsEnabled set to
- true, historyHandling set to "reload", and the source browsing context set to the
- browsing context being navigated.
+
+ text/css"text/plain"text/vtt"Document, with historyHandling set to "reload". In the case of non-idempotent methods (e.g., HTTP POST), the
- user agent should prompt the user to confirm the operation first, since otherwise transactions
- (e.g., purchases or database modifications) could be repeated. User agents may allow the user to
- explicitly override any caches when reloading.multipart/x-mixed-replace"multipart/x-mixed-replace document, given navigationParams,
+ sourceSnapshotParams, and initiatorOrigin.
+ ancestorOrigins getter steps are:application/pdf"text/pdf"
-
- Document is null, then return
- an empty list.Document's origin is not same origin-domain with the
- entry settings object's origin, then throw a
- "SecurityError" DOMException.application/atom+xml MIME
+ type.ancestorOrigins attribute works are still
- controversial and might change. See issue
- #1918 for more information.
+ Applying the history step
- Location exotic object
- requires additional logic beyond IDL for security purposes. The Location object must
- use the ordinary internal methods except where it is explicitly specified otherwise below.Document. For navigations, this work generally
+ occurs toward the end of the process; for traversals, it is the beginning.Location object has a [[DefaultProperties]] internal slot
- representing its own properties at time of its creation.Updating the traversable
- [[GetPrototypeOf]] ( )
+
-
+
+
- Document[[SetPrototypeOf]] ( V )
+
-
+ [[IsExtensible]] ( )
+
-
+ [[PreventExtensions]] ( )
+
-
+ [[GetOwnProperty]] ( P )
+
+
-
[[DefineOwnProperty]] ( P, Desc )
+
+
-
traversal".SecurityError" DOMException.[[Get]] ( P, Receiver )
+
-
+ [[Set]] ( P, V, Receiver )
+
-
+
+
[[Delete]] ( P )
+
+
+
-
+ SecurityError" DOMException.
+
+ [[OwnPropertyKeys]] ( )
+
-
- Browsing the web
+
+
back_forward" if
+ targetEntry's document is null; otherwise
+ "reload".Navigating across documents
+ window.open() and location.assign() methods can all cause a browsing context to
- navigate.iframe srcdoc document needs to know the data it is to use.Document, which ultimately happens in the create and initialize a Document object
- algorithm. The parameters to this algorithm are tracked via a navigation params
- struct, which has the following items:
-
+
+
+
+
+
- DocumentDocumentDocumentDocument
+
- DocumentDocument, once it has been createdDocument creation, the session history gets updated. A
- history handling behavior is used to track the desired type of session history update
- throughout the navigation process. It is one of the following:
+
-
default"
+
+
+ replace"default"), an optional policy container-or-null historyPolicyContainer (default null), an
- optional string navigationType (default
- "other"), an optional navigation id
- navigationId (default null), and an
- optional processResponseEndOfBody,
- which is an algorithm receiving a response (default an
- algorithm that does nothing):
-
- reload", then set
- resource's reload-navigation
- flag.
-
SecurityError" DOMException.canceled", and url is resource's url, and return.
-
+ about:blank
- Document
+
+
javascript"replace".
-
+
- Document object, abort that
- Document also. (Navigation attempts that have matured already have session history entries, and are
- therefore handled during the update the session history with the new page algorithm,
- later.)
+
refuse", then return a new
- WebDriver BiDi navigation status whose id is navigationId and status is "canceled".load events mode.load events mode when this navigation algorithm later matures, or when it terminates (whether due to having
- run all the steps, or being canceled, or being aborted), whichever happens first.
+
about:blank is false, i.e., we never traverse back to the initial about:blank Document because it
+ always gets replaced when we navigate away from
+ it.pending".
+
-
-
-
+
-
+ javascript"
-
javascript: URL request given resource,
- browsingContext, and incumbentNavigationOrigin.
+
+ javascript: URL in an href attribute of an a element would only be
- evaluated when the link was followed, while such a
- URL in the src attribute of an iframe
- element would be evaluated in the context of the iframe's nested browsing
- context when the iframe is being set up. Once evaluated, its return value
- (if it was a string) would replace that browsing context's active
- document, thus also changing the corresponding Window object.javascript" nor a fetch
- scheme
+
-
- document", mode to "navigate", credentials
- mode to "include", use-URL-credentials flag, redirect mode to "manual",
- and replaces client id to
- browsingContext's active document's relevant settings
- object's id.
-
+
+
+
-
- 0 1 2 3 top/t /t#foo frames[0]/i-0-a /i-0-b top navigable
+ is the /t entry, whose step is 0, while the target history entry for the frames[0] navigable is the /i-0-b entry, whose step is 1:
- 0 1 2 3 top/t /t#foo frames[0]/i-0-a /i-0-b top entry whose step is 3, and the frames[0] entry whose step is 1:
+ 0 1 2 3 top/t /t#foo frames[0]/i-0-a /i-0-b
-
-
-
+
+
-
+
Document, so accessing
+ navigable's document is reliable.
-
-
-
+ Updating the document
- Document
+ document, a session history entry entry, a boolean
+ doNotReactivate, and integers scriptHistoryLength and
+ scriptHistoryIndex:
+
+
- Blocked", then set response to a network error and
- break.
-
-
+
-
+
- unsafe-none", then set response to an
- appropriate network error and break.popstate at document's
+ relevant global object, using PopStateEvent, with the state attribute initialized to document's
+ history object's state.mailto:
- URLs and such.hashchange at document's relevant global
+ object, using HashChangeEvent, with the oldURL attribute initialized to the serialization of oldURL and the newURL attribute initialized to the serialization of entry's URL.
-
+
+ Location` header.Location` header.Document
+ document and session history entry entry:javascript", then set response to a network
- error.
+
- Document document:
-
- WindowProxy's [[Window]] internal
+ slot value to window.Blocked",
- then set failure to true. Document
+ document:X-Frame-Options` given response, browsingContext,
- and navigationParams's origin is
- false, then set failure to true.
+
+
+ off", invoke the reset algorithm for formControl.
-
-
- canceled", and url is response's URL.Content-Disposition` header specifying the attachment disposition type, then:complete", and document's page showing flag is false,
+ then:
-
+
+
complete", and url is response's URL.visible".pageshow at document's relevant global
+ object with true.Document document,
+ perform the following steps in parallel:
+
-
-
+
+ text/css"text/plain"text/vtt"multipart/x-mixed-replace"Scrolling to a fragment
- application/pdf"text/pdf"Document document:
+
application/atom+xml MIME type), or one for which the user agent has a dedicated
- handler.
+
+
+
-
- Document's viewport as the fallback target.Document's indicated part is
+ the one that its URL's fragment identifies, or null if the fragment does not
+ identify anything. The semantics of the fragment in
+ terms of mapping it to a node is defined by the specification that defines the MIME
+ type used by the Document (for example, the processing of fragments for XML MIME
+ types is the responsibility of RFC7303). Document, which is used in
+ defining the :target pseudo-class and is updated by the
+ above algorithm. It is initially null.
-
-
-
+ iframe only when one of allow-popups, allow-top-navigation, allow-top-navigation-by-user-activation,
- or allow-top-navigation-to-custom-protocols
- is specified.top, then return the top of the document.javascript: URL request,
- given a request request, a browsing
- context browsingContext, and an origin
- initiatorOrigin:Document
+ document and a string fragment, run these steps:
-
- 204.
+
- a element in the document
+ tree whose root is document that has a name attribute whose value is equal to fragment, then
+ return the first such element in tree order.
-
Allowed". Persisted history entry state
-
-
-
+ javascript:" from urlString.
+
-
+
+
- auto", then the user agent may
+ use entry's scroll position data to restore
+ the scroll positions of entry's document's
+ restorable scrollable regions.dir attribute
+ of textarea elements or input elements whose type attribute is in either the Text state or the Search state, if the persisted state includes the
+ directionality of user input in such controls.input or change events, but
+ can trigger the formStateRestoreCallback of form-associated custom elements.
- Document document are
+ document's viewport, and all of document's scrollable regions
+ excepting any navigable containers.Content-Type`,
- `text/html;charset=utf-8`) », and whose body is the result of UTF-8
- encoding result.Documents.javascript: URLs have a dedicated label
- on the issue tracker documenting various problems with their specification.Document lifecycle
-
+ Shared document creation infrastructure
- Document object,
given a type type, content type contentType, and
navigation params navigationParams:Document objects are also created when creating a new browsing
+ context and document; such initial
+ about:blank Document are never created by this algorithm. Also,
+ browsing context-less Document objects can
+ be created via various APIs, such as document.implementation.createHTMLDocument().
-
@@ -89675,41 +93159,63 @@ interface Location { // but see also timing info's
- start time.
+ navigation start time set to navigationParams's response's timing info's start time.
Window, Document, and
+ agent will not end up being used; because the created Document's
+ origin is opaque, we will end up creating a new agent
+ and Window later in this algorithm to
+ go along with the new Document.document.domain has
- been used for browsingContext's container document, then its navigationParams's navigable's container document, then its origin cannot be same origin-domain with
the passed origin, because these steps run before the document is created, so it
cannot itself yet have used document.domain. Note
@@ -89596,27 +93074,29 @@ interface Location { // but see also request's current URL.about:blank
- Document, and navigationParams's history handling is "replace", and browsingContext's active
+ about:blank is true, and browsingContext's active
document's origin is same
origin-domain with navigationParams's origin, then do nothing.about:blank Document, and the new Document that is
- about to be created, will share the same Window object.about:blank Document, and the new Document that
+ is about to be created, will share the same Window object.
Origin-Agent-Cluster` and "item" from
- response's header list.
-
Document, whose type is type, content type is contentType, origin is navigationParams's origin, policy container is
- navigationParams's policy
- container, permissions policy
- is permissionsPolicy, active sandboxing flag set is
- navigationParams's final sandboxing flag
- set, and cross-origin opener policy is
- navigationParams's cross-origin opener
- policy, load timing info is loadTimingInfo, and
- navigation id is
- navigationParams's id.Window's associated Document is set to
- document later, when the caller of this algorithm updates the session history with the new page. That algorithm
- sets the active document as part of its larger
- role of synchronizing the Window, Document, browsing
- context, and session history.Document, with
+
loading".loading"Document to document.Document given
document.
-
+ default"replace"navigate"reload"reload"entry update"back_forward"
+
- <!-- https://example.com/b.html -->
-<!doctype html>
-<script>
-new PaymentRequest(…); // Allowed to use
-</script>Document newDocument. When
- a user agent is required to do this, it must queue a global task on the
- networking task source, given the relevant global object of the
- Document object of the current entry (not the new one), to run the
- following steps:
-
-
-
-
- entry update"reload"
-
- replace"
-
- replace".default"
-
- Document document,
- perform the following steps in parallel:
-
-
-
-
-
- Page load processing model for HTML files
-
-
-
-
-
-
- Document
- object given "html", "text/html", and
- navigationParams.media", after
- the task has been procesed by the HTML parser.Document's relevant
- global object to run the following steps:
-
-
- load event to be fired.Document object, but before any script execution, certainly
- before the parser stops, the user agent must update the
- session history with the new page given navigationParams and the newly-created
- Document.Page load processing model for XML files
-
- Document object
- document, given "xml", type, and
- navigationParams. They must also create a corresponding XML parser.
- media", after
- the task has been procesed by the XML parser.Document.Page load processing model for text files
-
-
-
-
- Document
- object given "html", type, and
- navigationParams.no-quirks".media", after
- the task has been procesed by the HTML parser.Document's relevant
- global object to run the following steps:
-
-
- load event to be fired.Document object, but potentially before the page has finished
- parsing, the user agent must update the session history with the new page given
- navigationParams and the newly-created Document.head element of the Document,
- e.g., linking to a style sheet, providing script, or giving the document a title.Format=Flowed
- feature of RFC 3676 then the user agent would need to apply extra styling to cause the text to
- wrap correctly and to handle the quoting feature. This could be performed using, e.g., a CSS
- extension.Page load processing model for
-
- multipart/x-mixed-replace resourcesmultipart/x-mixed-replace is to be loaded in a
- browsing context, the user agent must parse the resource using the rules for
- multipart types. replace" if a previous body part from the same resource resulted in a
- creating and initializing a Document
- object, and otherwise using the same setup as the navigate attempt that caused
- this section to be invoked in the first place.load events (and for that matter unload events) do fire for each body part loaded.Page load processing model for media
-
-
-
-
- Document
- object given "html", type, and
- navigationParams.no-quirks".html element to document.head element to the html element.body element to the html element.body element.media".
-
-
-
-
-
-
- Type of media
- Element for the media
- Appropriate attribute
- Image
- img
- src
- Video
- video
- src
- Audio
- audio
- src
- Document object, but potentially before the page has finished
- fully loading, the user agent must update the session history with the new page given
- navigationParams and the newly-created Document.head element of the Document, or
- attributes to the element host element, e.g., to link to a style sheet, to provide a
- script, to give the document a title, or to make the media autoplay.Document's
- relevant global object to call navigationParams's process response end of body with
- navigationParams's response.Page load processing model for content that uses plugins
-
-
-
-
- Document
- object given "html", type, and
- navigationParams.no-quirks".html element to document.head element to the html element.body element to the html element.embed to the body element.src attribute of the embed
- element to the address of the resource.media".iframes
- can't be used to evade plugin-types directives. Document object, but potentially before the page has finished
- fully loading, the user agent must update the session history with the new page given
- navigationParams and the newly-created Document.head element of the Document, or
- attributes to the embed element, e.g. to link to a style sheet or to give the
- document a title.Page load processing model for inline
- content that doesn't have a DOM
-
-
-
-
-
-
- Document
- object given "html", "text/html", and
- navigationParams.no-quirks".Document rendering rules, or mutate document until it
- represents the content the user agent wants to render.Document object, but potentially before the page has been
- completely set up, the user agent must update the session history with the new page
- given navigationParams and the newly-created Document.Navigating to a fragment
-
-
-
-
- replace", then remove
- all the entries in browsingContext's session history after the
- current entry. (If the current entry is the last entry in the session
- history, then no entries are removed.)Document objects in
- browsingContext's top-level browsing context's document
- family.complete".
-
-
-
-
- Document's target element to null.
-
- Document's target element to
- target.Document's viewport as the fallback target.Document (for
- example, the processing of fragments for XML MIME types is the responsibility of RFC7303). Document, which is used in
- defining the :target pseudo-class and is updated by the
- above algorithm. It is initially null.
-
-
- top, then the indicated part of the document is the
- top of the document; return.
-
-
- a element in the document
- tree that has a name attribute whose value is equal to
- fragment, then return the first such element in tree order.
To traverse the history to a session history entry entry,
- with an optional history handling behavior historyHandling (default "default"), and an optional boolean
- explicitHistoryNavigation (default false):
This algorithm is not just invoked when explicitly going back or forwards in the session history — it is also invoked - in other situations, for example when navigating a browsing context, - as part of updating the session history - with the new page.
- -If entry's document is null, then:
- -Assert: historyHandling is "default".
Let request be a new request whose - URL is entry's URL.
If explicitHistoryNavigation is true, then set request's history-navigation flag.
Navigate the browsing
- context to request with historyHandling
- set to "entry update" and with historyPolicyContainer set to
- entry's policy container. The navigation
- must be done using the same source browsing context as was used the first time
- entry was created.
The "navigate" algorithm reinvokes this "traverse" algorithm to - complete the traversal, at which point entry's document is non-null.
- -If the resource was obtained using a non-idempotent action, for example a POST - form submission, or if the resource is no longer available, for example because the computer - is now offline and the page wasn't cached, navigating to it again might not be possible. In - this case, the navigation will result in a different page than previously; for example, it - might be an error message explaining the problem or offering to resubmit the form.
-Return.
Save persisted state to the current entry.
Let newDocument be entry's document.
Assert: newDocument's is initial
- about:blank is false, i.e., we never traverse back to the initial about:blank Document because it
- always gets replaced when we navigate away from
- it.
<!-- https://example.com/b.html -->
+<!doctype html>
+<script>
+new PaymentRequest(…); // Allowed to use
+</script>If newDocument is different than the current entry's document, or historyHandling is "entry update" or "reload",
- then:
If newDocument's suspended timer handles is not - empty:
+Assert: newDocument's suspension time is not - zero.
To load an HTML document, given navigation + params navigationParams:
-Let suspendDuration be the current high resolution time minus - newDocument's suspension time.
Let document be the result of creating and initializing a Document
+ object given "html", "text/html", and
+ navigationParams.
Let activeTimers be newDocument's - relevant global object's map of active timers.
Create an HTML parser and associate it with the document. Each + task that the networking task source places on + the task queue while fetching runs must then fill the parser's input byte + stream with the fetched bytes and cause the HTML parser to perform the + appropriate processing of the input stream.
-For each handle in newDocument's suspended timer - handles, if activeTimers[handle] exists, then increase activeTimers[handle] by - suspendDuration.
The first task that the networking task
+ source places on the task queue while fetching runs must process link
+ headers given document, navigationParams's response, and "media", after
+ the task has been processed by the HTML parser.
Remove any tasks queued by the history traversal
- task source that are associated with any Document objects in the
- top-level browsing context's document family.
Before any script execution occurs, the user agent must wait for scripts may run for + the newly-created document to be true for document.
-If newDocument's origin is not - same origin with the current entry's document's origin, - then:
+The input byte stream converts bytes into characters for use in the + tokenizer. This process relies, in part, on character encoding + information found in the real Content-Type metadata of the + resource; the computed type is not used for this purpose.
-Let entriesToUpdate be all entries in the session history whose document's origin - is same origin as the active document and that are - contiguous with the current entry.
For each entryToUpdate of - entriesToUpdate, set entryToUpdate's browsing context name to the current browsing context - name.
If the browsing context is a top-level browsing context, - but not an auxiliary browsing context whose disowned is false, then - set the browsing context's name to the empty - string.
When no more bytes are available, the user agent must queue a global task on
+ the networking task source given document's relevant global
+ object to have the parser to process the implied EOF character, which eventually causes
+ a load event to be fired.
Set the active document of the browsing context to - newDocument.
Return document.
If entry's browsing context name is not null, - then:
-Set the browsing context's name to - entry's browsing context name.
Let entriesToUpdate be all entries in the session history whose document's origin - is same origin as the new active document's origin and that are contiguous with - entry.
For each entryToUpdate of - entriesToUpdate, set entryToUpdate's browsing context name to null.
If newDocument has any form controls whose
- autofill field name is "off",
- invoke the reset algorithm of each of those
- elements.
When faced with displaying an XML file inline, provided navigation params
+ navigationParams and a string type, user agents must follow the
+ requirements defined in XML and Namespaces in XML, XML Media
+ Types, DOM, and other relevant specifications to create and initialize a Document object
+ document, given "xml", type, and
+ navigationParams, and return that Document. They must also create a
+ corresponding XML parser.
If newDocument's current document readiness "complete", then queue a global task on the DOM
- manipulation task source given newDocument's relevant global
- object to run the following steps:
At the time of writing, the XML specification community had not actually yet + specified how XML and the DOM interact.
-If newDocument's page showing flag is true, then abort these - steps.
The first task that the networking task source
+ places on the task queue while fetching runs must process link headers
+ given document, navigationParams's response, and "media", after
+ the task has been processed by the XML parser.
Set newDocument's page showing flag to true.
The actual HTTP headers and other metadata, not the headers as mutated or implied by the + algorithms given in this specification, are the ones that must be used when determining the + character encoding according to the rules given in the above specifications. Once the character + encoding is established, the document's character encoding must be set to that + character encoding.
-Update the visibility state of newDocument to
- "hidden".
Before any script execution occurs, the user agent must wait for scripts may run for the
+ newly-created document to be true for the newly-created Document.
Fire a page transition event named pageshow at newDocument's relevant global
- object with true.
Once parsing is complete, the user agent must set document's navigation id to null.
- -For HTML documents this is reset when parsing is complete, after firing the load + event.
-Set newDocument's URL to - entry's URL.
Error messages from the parse process (e.g., XML namespace well-formedness errors) may be
+ reported inline by mutating the Document.
Let hashChanged be false, and let oldURL and newURL be - null.
If entry's URL's fragment is not identical to the current - entry's URL's fragment, and entry's document equals the current entry's document, then set hashChanged to true, set - oldURL to the current entry's URL, and set - newURL to entry's URL.
If historyHandling is "replace", then remove
- the entry immediately before entry in the session history.
To load a text document, given a navigation + params navigationParams and a string type:
-If entry's persisted user state is null, and - its URL's fragment is - non-null, then scroll to the fragment.
Let document be the result of creating and initializing a Document
+ object given "html", type, and
+ navigationParams.
Set the current entry to entry.
Set document's parser cannot change the mode flag to + true.
Let targetRealm be the current realm.
Set document's mode
+ to "no-quirks".
Let state be null.
Create an HTML parser and associate it with the document. Act as + if the tokenizer had emitted a start tag token with the tag name "pre" followed by a single + U+000A LINE FEED (LF) character, and switch the HTML parser's tokenizer to the + PLAINTEXT state. Each task that the + networking task source places on the task queue while fetching runs + must then fill the parser's input byte stream with the fetched bytes and cause the + HTML parser to perform the appropriate processing of the input stream.
-If entry's serialized state is not - null, then set state to StructuredDeserialize(entry's serialized state, targetRealm). If this throws an - exception, catch it and ignore the exception.
document's encoding must be + set to the character encoding used to decode the document during parsing.
-Set newDocument's History object's state to state.
The first task that the networking task
+ source places on the task queue while fetching runs must process link
+ headers given document, navigationParams's response, and "media", after
+ the task has been processed by the HTML parser.
Let stateChanged be true if newDocument has a latest - entry, and that entry is not entry; otherwise let it be false.
+Before any script execution occurs, the user agent must wait for scripts may run for + the newly-created document to be true for document.
-Set newDocument's latest entry to entry.
When no more bytes are available, the user agent must queue a global task on
+ the networking task source given document's relevant global
+ object to have the parser to process the implied EOF character, which eventually causes
+ a load event to be fired.
If stateChanged is true, then fire an
- event named popstate at newDocument's
- relevant global object, using PopStateEvent, with the state attribute initialized to
- state.
User agents may add content to the head element of document, e.g.,
+ linking to a style sheet, providing script, or giving the document a title.
Restore persisted state from entry.
In particular, if the user agent supports the Format=Flowed feature of RFC 3676 then the user agent would need to apply
+ extra styling to cause the text to wrap correctly and to handle the quoting feature. This could
+ be performed using, e.g., a CSS extension.
If hashChanged is true, then queue a global task on the DOM
- manipulation task source given newDocument's relevant global
- object to fire an event named hashchange at newDocument's relevant global
- object, using HashChangeEvent, with the oldURL attribute initialized to oldURL and
- the newURL attribute initialized to
- newURL.
Return document.
The rules for how to convert the bytes of the plain text document into actual characters, and + the rules for actually rendering the text to the user, are defined by the specifications for the + computed MIME type of the resource (i.e., + type).
-multipart/x-mixed-replace
+ documentsTo save persisted state to a session history entry - entry:
+To load a
+ multipart/x-mixed-replace document, given navigation params
+ navigationParams, source snapshot params sourceSnapshotParams,
+ and origin initiatorOrigin:
Set the scroll position data of entry - to contain the scroll positions for all of entry's document's restorable scrollable regions.
Parse navigationParams's response's body using the rules for multipart types.
Optionally, update entry's persisted user state - to reflect any state that the user agent wishes to persist, such as the values of form - fields.
Let firstPartNavigationParams be a copy of + navigationParams.
To restore persisted state from a session - history entry entry:
+Set firstPartNavigationParams's response to a new response representing the first part of + navigationParams's response's body's multipart stream.
If entry's scroll restoration
- mode is "auto", then the user agent may
- use entry's scroll position data to restore
- the scroll positions of entry's document's
- restorable scrollable regions.
Let document be the result of loading a document given + firstPartNavigationParams, sourceSnapshotParams, and + initiatorOrigin.
-The user agent not restoring scroll positions does not imply that scroll - positions will be left at any particular value (e.g., (0,0)). The actual scroll position depends - on the navigation type and the user agent's particular caching strategy. So web applications - cannot assume any particular scroll position but rather are urged to set it to what they want it - to be.
+For each additional body part obtained from navigationParams's response, the user agent must navigate
+ document's node navigable to navigationParams's request's URL, using document, with response set to navigationParams's response and historyHandling set to "replace".
Optionally, update other aspects of entry's document and its rendering, for instance values of form fields, - that the user agent had previously recorded in entry's persisted user state.
- -This can even include updating the dir attribute
- of textarea elements or input elements whose type attribute is in either the Text state or the Search state, if the persisted state includes the
- directionality of user input in such controls.
Restoring the value of form controls as part of this process does not fire any
- input or change events, but
- can trigger the formStateRestoreCallback of form-associated custom elements.
Return document.
The restorable scrollable regions of a Document document are
- document's viewport, and all of document's scrollable regions
- excepting any child browsing contexts of
- document.
Child browsing context scroll restoration is handled by the history
- entry for those browsing contexts' Documents.
For the purposes of algorithms processing these body parts as if they were complete + stand-alone resources, the user agent must act as if there were no more bytes for those resources + whenever the boundary following the body part is reached.
+Thus, load events (and for that matter unload events) do fire for each body part loaded.
PopStateEvent interface[Exposed=Window]
-interface PopStateEvent : Event {
- constructor(DOMString type, optional PopStateEventInit eventInitDict = {});
+ Loading media documents
- readonly attribute any state;
-};
+ To load a media document, given navigationParams
+ and a string type:
-dictionary PopStateEventInit : EventInit {
- any state = null;
-};Let document be the result of creating and initializing a Document
+ object given "html", type, and
+ navigationParams.
event.stateSet document's mode
+ to "no-quirks".
Returns a copy of the information that was provided to pushState() or replaceState().
Append an html element to document.
Append a head element to the html element.
The state attribute must return the value it was
- initialized to. It represents the context information for the event, or null, if the state
- represented is the initial state of the Document.
Append a body element to the html element.
Append an element host element for the media, as described below, to the
+ body element.
Set the appropriate attribute of the element host element, as described below, + to the address of the image, video, or audio resource.
HashChangeEvent interfaceUser agents may add content to the head element of document, or
+ attributes to host element, e.g., to link to a style sheet, to provide a script, to
+ give the document a title, or to make the media autoplay.
[Exposed=Window]
-interface HashChangeEvent : Event {
- constructor(DOMString type, optional HashChangeEventInit eventInitDict = {});
+ Process link headers given document,
+ navigationParams's response, and
+ "media".
Act as if the user agent had stopped parsing
+ document.
Return document.
event.oldURLThe element host element to create for the media is the element given in + the table below in the second cell of the row whose first cell describes the media. The + appropriate attribute to set is the one given by the third cell in that same row.
-Returns the URL of the session history entry that was previously - current.
-| Type of media + | Element for the media + | Appropriate attribute + |
|---|---|---|
| Image + | img
+ | src
+ |
| Video + | video
+ | src
+ |
| Audio + | audio
+ | src
+ |
Before any script execution occurs, the user agent must wait for scripts may run for the
+ newly-created document to be true for the Document.
event.newURLReturns the URL of the session history entry that is now - current.
-When the user agent is to create a document to display a user agent page or PDF viewer inline,
+ provided a navigable navigable, a navigation ID
+ navigationId, a NavigationTimingType navTimingType, the
+ user agent should:
The oldURL attribute must return the value it was
- initialized to. It represents context information for the event, specifically the URL of the
- session history entry that was traversed from.
Let navigationParams be a new navigation params with
-The newURL attribute must return the value it was
- initialized to. It represents context information for the event, specifically the URL of the
- session history entry that was traversed to.
PageTransitionEvent interface[Exposed=Window]
-interface PageTransitionEvent : Event {
- constructor(DOMString type, optional PageTransitionEventInit eventInitDict = {});
+ policy container
+ a new policy container
- readonly attribute boolean persisted;
-};
+ final sandboxing flag set
+ an empty set
-dictionary PageTransitionEventInit : EventInit {
- boolean persisted = false;
-};event.persistedFor the pageshow event, returns false if the page is
- newly being loaded (and the load event will fire). Otherwise,
- returns true.
For the pagehide event, returns false if the page is
- going away for the last time. Otherwise, returns true, meaning that the page might be reused if
- the user navigates back to this page (if the Document's salvageable state stays true).
Things that can cause the page to be unsalvageable include:
+Document alive in a session
- history entry after unloadiframes that are not salvageableWebSocket objectsLet document be the result of creating and initializing a Document
+ object given "html", "text/html", and
+ navigationParams.
DocumentEither associate document with a custom rendering that is not rendered using
+ the normal Document rendering rules, or mutate document until it
+ represents the content the user agent wants to render.
Return document.
The persisted attribute must return the value
- it was initialized to. It represents the context information for the event.
Because we ensure the resulting Document's origin is opaque, and the resulting Document cannot run
+ script with access to the DOM, the existence and properties of this Document are not
+ observable to web developer code. This means that most of the above values, e.g., the
+ text/html type, do not matter.
+ Similarly, most of the items in navigationParams don't have any observable effect,
+ besides preventing the Document-creation
+ algorithm from getting confused, and so are set to default values.
To fire a page transition event named eventName at a Window
- window with a boolean persisted, fire
- an event named eventName at window, using
- PageTransitionEvent, with the persisted attribute initialized to
- persisted, the cancelable attribute
- initialized to true, the bubbles attribute initialized to
- true, and legacy target override flag set.
Once the page has been set up, the user agent must act as if it had stopped parsing.
-The values for cancelable and bubbles don't make any sense, since canceling the event does
- nothing and it's not possible to bubble past the Window object. They are set to true
- for historical reasons.
A Document has a completely loaded time (a time or null), which is
initially null.
Let container be document's browsing context's container.
+Let container be document's node navigable's container.
This will be null in the case where document is the initial about:blank Document in a
frame or iframe, since at the point of browsing context creation which calls this algorithm, the container
- relationship has not yet been established. (That happens in a subsequent step of create
- a new nested browsing context.)
The consequence of this is that the following steps do nothing, i.e., we do not fire an
asynchronous load event on the container element for such
cases. Instead, a synchronous load event is fired in a special
- initial-insertion case in the shared attribute processing steps for iframe
- and frame elements.
iframe attributes.
A Document has a salvageable state, which must initially be
true, and a page showing flag, which must initially be false. The page
@@ -91074,193 +93764,114 @@ dictionary PageTransitionEventInit : EventInit, which is used to ignore certain operations while the below algorithms run.
Initially, the counter must be set to zero.
To prompt to unload, given a Document
- object document and optionally a recursiveFlag, run these steps:
To unload a Document
+ oldDocument, given an optional Document newDocument:
Increase the event loop's termination nesting level by - 1.
Increase the document's unload counter by 1.
Assert: this is running as part of a task + queued on oldDocument's event loop.
Let event be the result of creating an event using
- BeforeUnloadEvent.
Initialize event's type attribute to beforeunload and its cancelable attribute true.
Dispatch event at - document's relevant global object.
Decrease the event loop's termination nesting level by - 1.
Let result be "no-prompt".
Let unloadTimingInfo be a new document unload timing + info.
If all of the following are true:
- -document's active sandboxing flag set does not have its - sandboxed modals flag set
document's relevant global object has sticky - activation
event's canceled flag is set, or the returnValue attribute of event is
- not the empty string
then the user agent may ask the user to confirm that they wish to unload the document.
+If newDocument is not given, then set unloadTimingInfo to null.
-The message shown to the user is not customizable, but instead determined by
- the user agent. In particular, the actual value of the returnValue attribute is ignored.
The user agent is encouraged to avoid asking the user for confirmation if it judges that - doing so would be annoying, deceptive, or pointless.
- -If the user agent asks the user for confirmation, it must:
- -Invoke WebDriver BiDi user prompt opened with document's
- relevant global object, "beforeunload", and "".
Pause while waiting for the user's response.
- -If the user confirmed the page navigation, then set result to "confirm"; otherwise to "refuse".
Invoke WebDriver BiDi user prompt closed with document's
- relevant global object and true if result is "confirm" or false otherwise.
In this case there is no new document that needs to know about how long it took + oldDocument to unload.
If the recursiveFlag is not set, then:
+Otherwise, if newDocument's event loop is not + oldDocument's event loop, then the user agent may be unloading oldDocument in parallel. In + that case, the user agent should set unloadTimingInfo to null.
-Let descendants be the list of the descendant browsing contexts - of document.
For each browsingContext in descendants:
- -Let internalResult be the result of calling prompt to unload - for browsingContext's active document with the - recursiveFlag set.
If internalResult is "refuse", then return
- internalResult.
Otherwise, if internalResult is "confirm", set
- result to internalResult.
In this case newDocument's loading is not impacted by how long it + takes to unload oldDocument, so it would be meaningless to communicate that timing + info.
Decrease the document's unload counter by 1.
Let intendToStoreInBfcache be true if the user agent intends to keep + oldDocument alive in a session history entry, such that it can later be + used for history traversal.
-Return result.
This must be false if oldDocument is not salvageable, or if there are any descendants of + oldDocument which the user agent does not intend to keep alive in the same way + (including due to their lack of salvageability).
+ -To unload a
- Document document, given an optional recursiveFlag, a
- document unload timing info-or-null unloadTimingInfo (default null),
- and an optional global object newGlobal:
Let eventLoop be oldDocument's relevant agent's event loop.
Increase the event loop's termination nesting level by - one.
Increase eventLoop's termination nesting level by 1.
Increase document's unload counter by 1.
Increase oldDocument's unload counter by 1.
If the user agent does not intend to keep document alive - in a session history entry (such that it can be reused later on history traversal), set document's - salvageable state to false.
If intendToKeepInBfcache is false, then set oldDocument's salvageable state to false.
If document's page showing flag is true:
+If oldDocument's page showing is true:
Set document's page showing flag to false.
Set oldDocument's page showing to false.
Fire a page transition event named pagehide at document's relevant global
- object with document's pagehide at oldDocument's relevant global
+ object with oldDocument's salvageable state.
Update the visibility state of newDocument to +
Update the visibility state of oldDocument to
"hidden".
If unloadTimingInfo is not null, then set unloadTimingInfo's unload event start time to the current high resolution time given - newGlobal, coarsened given document's - relevant settings object's cross-origin isolated + newDocument's relevant global object, coarsened given oldDocument's relevant settings object's + cross-origin isolated capability.
If document's salvageable state is
- false, then fire an event named
- unload at document's
- relevant global object, with legacy target override flag set.
If oldDocument's salvageable
+ state is false, then fire an event named unload at oldDocument's relevant global
+ object, with legacy target override flag set.
If unloadTimingInfo is not null, then set unloadTimingInfo's unload event end time to the current high resolution time given - newGlobal, coarsened given document's - relevant settings object's cross-origin isolated + newDocument's relevant global object, coarsened given oldDocument's relevant settings object's + cross-origin isolated capability.
Decrease the event loop's termination nesting level by - one.
Decrease eventLoop's termination nesting level by 1.
Set document's suspension time to the - current high resolution time given document's - relevant global object.
Set oldDocument's suspension time to the current high + resolution time given document's relevant global object.
Set document's suspended timer handles to the result of +
Set oldDocument's suspended timer handles to the result of getting the keys for the map of active timers.
Run any unloading document cleanup steps for document that are +
Run any unloading document cleanup steps for oldDocument that are defined by this specification and other applicable specifications.
If the recursiveFlag is not set, then:
- -Let descendants be the list of the descendant browsing - contexts of document.
For each browsingContext in descendants:
- -Unload the active document of - browsingContext with the recursiveFlag set.
If the salvageable state of the - active document of browsingContext is false, then set the - salvageable state of document to - false also.
If oldDocument's salvageable state + is false, then destroy oldDocument.
If document's salvageable state - is false, then discard document.
Decrease oldDocument's unload counter by 1.
Decrease document's unload counter by 1.
If newDocument is given, newDocument's was created via + cross-origin redirects is false, and newDocument's origin is the same as + oldDocument's origin, then set + newDocument's previous document unload timing to + unloadTimingInfo.
This specification defines the following unloading document cleanup steps. @@ -91294,54 +93905,61 @@ dictionary PageTransitionEventInit : EventInit -
To destroy a
+ Document document:
BeforeUnloadEvent interfaceDestroy the active documents of each of document's descendant + navigables. In what order?
[Exposed=Window]
-interface BeforeUnloadEvent : Event {
- attribute DOMString returnValue;
-};Set document's salvageable state + to false.
There are no BeforeUnloadEvent-specific initialization methods.
Run any unloading document cleanup steps for document that + are defined by this specification and other applicable specifications.
The BeforeUnloadEvent interface is a legacy interface which allows prompting to unload to be controlled not only by canceling the
- event, but by setting the returnValue
- attribute to a value besides the empty string. Authors should use the preventDefault() method, or other means of canceling
- events, instead of using returnValue.
Abort document.
Remove any tasks whose document is document from any task + queue (without running those tasks).
The returnValue attribute controls the process
- of prompting to unload. When the event is created, the
- attribute must be set to the empty string. On getting, it must return the last value it was set
- to. On setting, the attribute must be set to the new value.
Set document's browsing context to + null.
This attribute is a DOMString only for historical reasons.
- Any value besides the empty string will be treated as a request to ask the user for
- confirmation.
Set document's node navigable's active session history entry's document state's document to null.
Remove document from the
+ owner set of each WorkerGlobalScope object whose set contains document.
For each workletGlobalScope in + document's worklet global + scopes, terminate + workletGlobalScope.
Even after destruction, the Document object itself might still be
+ accessible to script, in the case where we are destroying a nested navigable.
To abort a Document document:
Abort the active
- documents of every child browsing context. If this results in any of those
- Document objects having their salvageable state set to false, then set
- document's salvageable state to false
- also.
Abort the active
+ documents of each of document's descendant navigables. In what order? If this results in any of those Document
+ objects having their salvageable state set to false,
+ then set document's salvageable state to
+ false also.
Cancel any instances of the fetch algorithm in the context of document, discarding any tasks @@ -91384,33 +94002,39 @@ interface BeforeUnloadEvent : Event {
User agents may allow users to explicitly invoke the stop document loading for a
- Document.
To stop document loading given a Document object document,
- run these steps:
To stop loading a + navigable navigable:
Let browsingContext be document's browsing context.
Let document be navigable's active + document.
If browsingContext's active document is not document, - then return.
If document's unload counter is 0, and navigable's + ongoing navigation is a navigation ID, then set + navigable's ongoing navigation to null.
-If there is an existing attempt to navigate browsingContext and - document's unload counter is 0, then cancel that navigation.
This will have the effect of aborting any ongoing navigations of + navigable, since at certain points during navigation, changes to the ongoing + navigation will cause further work to be abandoned.
+Abort document.
Through their user interface, user agents also
+ allow stopping traversals, i.e. cases where the ongoing navigation is "traversal". The above algorithm does not account for this. (On the other hand,
+ user agents do not allow window.stop() to stop traversals,
+ so the above algorithm is correct for that caller.) See issue #6905.
X-Frame-Options` headerX-Frame-Options` headerThe ` To check a navigation response's adherence to ` If browsingContext is not a child browsing context, then return
- true. If navigable is not a child navigable, then return true. For each policy of
- navigationParams's policy
- container's CSP list: For each policy of cspList: If policy's disposition is not " Let rawXFrameOptions be the result of getting, decoding, and splitting
- ` Let xFrameOptions be a new set. If xFrameOptions[0] is " Let containerDocument be browsingContext's container document. Let containerDocument be navigable's container document. While containerDocument is not null: Let containerBC be containerDocument's browsing context. Set containerDocument to containerBC's container document, if containerBC is
- non-null; otherwise, null. Set containerDocument to containerDocument's container document. The ` Browser user agents should provide the ability to navigate, reload,
+ and stop loading any top-level traversable in their
+ top-level traversable set. For example, via a location bar and reload/stop button UI. Browser user agents should provide the ability to traverse by a delta any top-level traversable in their top-level
+ traversable set. For example, via back and forward buttons, possibly including long-press
+ abilities to change the delta. It is suggested that such user agents allow traversal by deltas greater than one, to avoid
+ letting a page "trap" the user by stuffing the session history with spurious entries. (For
+ example, via repeated calls to Some user agents have heuristics for translating a single "back" or "forward"
+ button press into a larger delta, specifically to overcome such abuses. We are contemplating
+ specifying these heuristics in issue
+ #7832. Browser user agents should offer users the ability to create a fresh top-level
+ traversable, given a user-provided or user agent-determined initial URL. For example, via a "new tab" or "new window" button. Browser user agents should offer users the ability to arbitrarily close any top-level traversable in their
+ top-level traversable set. For example, by clicking a "close tab" button. Browser user agents may provide ways for the user to explicitly cause any
+ navigable (not just a top-level traversable) to navigate,
+ reload, or stop loading. For example, via a context menu. Browser user agents may provide the ability for users to destroy a top-level
+ traversable. For example, by force-closing a window containing one or more such top-level traversables. When a user requests a reload of a navigable whose active session history entry's document state's resource is a POST resource, the user agent
+ should prompt the user to confirm the operation first, since otherwise transactions (e.g.,
+ purchases or database modifications) could be repeated. When a user requests a reload of a navigable, user agents may provide
+ a mechanism for ignoring any caches when reloading. The above recommendations, and the data structures in this specification, are not meant to
+ place restrictions on how user agents represent the session history to the user. For example, although a top-level traversable's session history entries are stored and maintained as a
+ list, and the user agent is recommended to give an interface for traversing that list by a delta, a novel user agent could instead or
+ in addition present a tree-like view, with each page having multiple "forward" pages that the user
+ can choose between. Similarly, although session history for all descendant navigables is stored in their traversable navigable, user
+ agents could present the user with a more nuanced per-navigable view of the session
+ history. Browser user agents may use a top-level browsing context's is
+ popup boolean for the following purposes:
+
+ Deciding whether or not to provide a minimal web browser user interface for the
+ corresponding top-level traversable. Performing the optional steps in set up browsing context features. In both cases user agents might additionally incorporate user preferences, or present a choice
+ as to whether to go down the popup route. User agents that provides a minimal user interface for such popups are encouraged to not hide
+ the browser's location bar.X-Frame-Options` HTTP response header is a legacy way
of controlling whether and how a Document may be loaded inside of a child
- browsing context. It is obsoleted by the frame-ancestors CSP directive, which provides more granular control over the
same situations. It was originally defined in HTTP Header Field X-Frame-Options, but
the definition and processing model here supersedes that document. BeforeUnloadEvent : Event {
X-Frame-Options`, given
- navigationParams navigationParams, a
- browsing context browsingContext, and an origin
- destinationOrigin:
-
@@ -91625,17 +94241,116 @@ interface BeforeUnloadEvent : Event {
BeforeUnloadEvent : Event {
` from response's header list.X-Frame-Options` from navigationParams's response's X-Frame-Optionssameorigin", then:
-
The `
+ Refresh` headerThe `
Refresh` headerRefresh` HTTP response header is the HTTP-equivalent
to a meta element with an http-equiv
attribute in the Refresh state. It takes the same value and works largely the same.
- Its processing model is detailed in create and
- initialize a Document object.
+ href="#conformance-attr-meta-http-equiv-refresh">the same value and works largely the
+ same. Its processing model is detailed in create and initialize a Document
+ object.Browser user interface
+ considerations
+
+ history.pushState() or
+ fragment navigations.)
+
+
+
+
+
+
+
+
+
+
+ Web application APIs
@@ -91953,10 +94668,8 @@ interface BeforeUnloadEvent : Event {
iframe element that A created that cannot be same
origin-domain with A.
- Window objects whose browsing
- contexts do not have a non-null opener or
- ancestor relationship. This holds even if the
- two Window objects are same origin.Window objects with no opener or ancestor relationship. This holds
+ even if the two Window objects are same origin.
Note that this means that even though it is the Set request's client to
settings object. Set request's initiator
+ type to Set up the classic script request given request and
options.iframe inside a.html that navigates, it is a.html itself that is used
- as the source browsing context, which determines among other things the Document, which determines among other things the request client. This is perhaps the only justifiable use
of the incumbent concept on the web platform; in all other cases the consequences of using it
@@ -93093,6 +95806,9 @@ document.querySelector("button").addEventListener("click", bound);
script".
Finalize and report timing with response, settings
- object's global object, and "script".
Set response to response's unsafe response.
same-origin", initiator type is "other",
+ mode is "same-origin", credentials mode is "same-origin", parser
metadata is "not parser-inserted", and whose
@@ -93195,10 +95908,6 @@ document.querySelector("button").addEventListener("click", bound);
sequence bodyBytes be the following algorithm:
Finalize and report timing with response, fetch client
- settings object's global object, and
- "other".
Set response to response's unsafe response.
Let request be a new request whose URL is url, client is settings object, destination is "script", parser metadata is "not
- parser-inserted", and whose use-URL-credentials flag is set.
script",
+ initiator type is "other", parser metadata
+ is "not parser-inserted", and whose use-URL-credentials flag
+ is set.If performFetch was given, run performFetch with request, @@ -93289,10 +96000,6 @@ document.querySelector("button").addEventListener("click", bound); here.
Finalize and report timing with response, settings
- object's global object, and "other".
Set response to response's unsafe response.
same-origin".Set request's initiator
+ type to script".
Set up the module script request given request and options.
response is always CORS-same-origin.
Finalize and report timing with response, fetch client
- settings object's global object, and
- "other".
If either of the following conditions are met:
@@ -96652,10 +99358,27 @@ import "https://example.com/foo/../module2.mjs";Let top-level browsing contexts be an empty set.
For each environment settings object settings of - oldestTask's script evaluation environment settings object set, append setting's top-level browsing context - to top-level browsing contexts.
For each environment settings object settings of + oldestTask's script evaluation environment settings object set:
+ +Let global be settings's global object.
If global is not a Window object, then
+ continue.
If global's browsing context is null, then + continue.
Let tlbc be global's browsing + context's top-level browsing context.
If tlbc is not null, then append it to + top-level browsing contexts.
Report long tasks, passing in taskStartTime, now (the end time of the task), top-level browsing contexts, and @@ -96675,16 +99398,13 @@ import "https://example.com/foo/../module2.mjs";
Any Document B whose browsing context's container document is A must be listed after
- A in the list.
If there are two documents A and B whose browsing contexts are both child browsing contexts whose container
- documents are another Document C, then the order of
- A and B in the list must match the shadow-including tree
- order of their respective browsing context
+ data-x="doc-container-document">container document is A must be listed
+ after A in the list.
If there are two documents A and B that both have the same + non-null container document C, then + the order of A and B in the list must match the shadow-including + tree order of their respective navigable containers in C's node tree.
Rendering opportunities: Remove from docs all Document
- objects whose browsing context do not have a
+ objects whose node navigables do not have a
rendering opportunity.
A browsing context has a rendering opportunity if the user agent is - currently able to present the contents of the browsing context to the user, - accounting for hardware refresh rate constraints and user agent throttling for performance - reasons, but considering content presentable even if it's outside the viewport.
+A navigable has a rendering opportunity if the user agent is + currently able to present the contents of the navigable to the user, accounting + for hardware refresh rate constraints and user agent throttling for performance reasons, but + considering content presentable even if it's outside the viewport.
-A browsing context has no rendering
- opportunities if its active document is render-blocked;
- otherwise, rendering opportunities are determined
- based on hardware constraints such as display refresh rates and other factors such as page
- performance or whether the document's visibility state is "visible". Rendering opportunities typically occur at regular intervals.
A navigable has no rendering
+ opportunities if its active document is
+ render-blocked; otherwise, rendering
+ opportunities are determined based on hardware constraints such as display refresh
+ rates and other factors such as page performance or whether the document's visibility
+ state is "visible". Rendering opportunities typically occur at
+ regular intervals.
This specification does not mandate any particular model for selecting rendering opportunities. But for example, if the browser is attempting to achieve a 60Hz - refresh rate, then rendering opportunities occur at a maximum of every 60th of a second (about - 16.7ms). If the browser finds that a browsing context is not able to sustain this - rate, it might drop to a more sustainable 30 rendering opportunities per second for that - browsing context, rather than occasionally dropping frames. Similarly, if a - browsing context is not visible, the user agent might decide to drop that page to - a much slower 4 rendering opportunities per second, or even less.
+ refresh rate, then rendering opportunities occur at a maximum of every 60th of a second + (about 16.7ms). If the browser finds that a navigable is not able to sustain + this rate, it might drop to a more sustainable 30 rendering opportunities per second for that + navigable, rather than occasionally dropping frames. Similarly, if a + navigable is not visible, the user agent might decide to drop that page to a + much slower 4 rendering opportunities per second, or even less.If docs is not empty, then set hasARenderingOpportunity to @@ -96728,9 +99449,10 @@ import "https://example.com/foo/../module2.mjs"; which meet both of the following conditions:
Document's browsing context would have no visible effect, andDocument's map of animation frame callbacks is empty.Document's
+ node navigable would have no visible effect, andDocument's map of animation frame callbacks is empty.For each fully active Document in docs, flush
- autofocus candidates for that Document if its
- browsing context is a
- top-level browsing context.
Document if its node navigable
+ is a top-level traversable.
For each fully active Document in docs, run
the resize steps for that Document.
For each fully active Document in docs, update the
- rendering or user interface of that Document and its browsing context to reflect the current state.
Document and its node navigable
+ to reflect the current state.
If necessary, update the rendering or user interface of any Document or
- browsing context to reflect the current state.
Wait until the condition goal is met. While a user agent has a paused task, the corresponding event loop must not run @@ -97312,11 +100033,12 @@ import "https://example.com/foo/../module2.mjs"; activity.
-This task source is used to queue calls to history.back() and similar APIs.
This task source is used to queue tasks involved in navigation and history + traversal.
If document's browsing context is - non-null and there is an existing attempt to navigate document's browsing context, then stop document loading - given document.
- -Issue #3447 looks into - the distinction between an ongoing instance of the navigate algorithm versus tasks - to navigate that are still queued. For the purpose of implementing this step, both - an ongoing instance of the navigate algorithm and tasks queued to - navigate should be counted towards "an existing attempt to navigate," - at least until that issue is resolved.
-If document's node navigable is non-null and + document's node navigable's ongoing navigation is a + navigation ID, then stop loading + document's node navigable.
For each shadow-including inclusive descendant node of document, erase all event listeners and handlers given @@ -98975,7 +101688,7 @@ document.body.appendChild(frame) name, features) method must run these steps:
If this is not an active document, then throw an +
If this is not fully active, then throw an
"InvalidAccessError" DOMException exception.
Return the result of running the window open steps with url, @@ -100014,8 +102727,11 @@ function sendData(data) {
The user agent must fire an event named beforeprint at the relevant global object of
- document, as well as any child browsing contexts in it.
Firing in children only doesn't seem right here, and some tasks likely need to + be queued. See issue #5096.
The beforeprint event can be used to
annotate the printed copy, for instance adding the time at which the document was printed.
The user agent must fire an event named afterprint at the relevant global object of
- document, as well as any child browsing
- contexts in it.
Firing in children only doesn't seem right here, and some tasks likely need to + be queued. See issue #5096.
The afterprint event can be used to
revert annotations added in the earlier event, as well as showing post-printing UI. For
@@ -100519,7 +103238,7 @@ interface Navigator {
Let resultURL be the result of parsing handlerURLString.
Navigate an appropriate browsing context to +
Navigate an appropriate navigable to resultURL.
Set request's cache mode to
"no-store".
Set request's initiator
+ type to "other".
Set ev's request to request.
Let finalizeEventSourceFetch given response res be to finalize and report
- timing with res, settings's global object, and "other".
Let processEventSourceEndOfBody given response res be the following step: if - res is not a network error, then finalizeEventSourceFetch - with res, and reestablish the connection.
Fetch request with Fetch request, with processResponseEndOfBody set to - processEventSourceEndOfBody and processResponse set + processEventSourceEndOfBody and processResponse set to the following steps given response res:
@@ -102123,10 +104839,9 @@ dictionary EventSourceInit {If res is an aborted network error, then fail the connection.
Otherwise, if res is a network error, then call - finalizeEventSourceFetch given res, and reestablish the - connection, unless the user agent knows that to be futile, in which case the user agent - may fail the connection.
Otherwise, if res is a network error, then reestablish + the connection, unless the user agent knows that to be futile, in which case the user + agent may fail the connection.
Otherwise, if res's status is
not 200, or if res's `Content-Type` is not
@@ -103980,8 +106695,8 @@ function showLogout() {
Finally, the example is extended to show how two pages can connect to the same worker; in this
case, the second page is merely in an iframe on the first page, but the same
- principle would apply to an entirely separate page in a separate top-level browsing
- context.
Here is the outer HTML page:
@@ -104569,9 +107284,9 @@ interface SharedWorkerGlobalScope : WorkerGlobalScopeWorkers communicate with other workers and with browsing
- contexts through message channels and their
- MessagePort objects.
Workers communicate with other workers and with Windows through message channels and their MessagePort
+ objects.
Each WorkerGlobalScope object worker global scope has a list of
the worker's ports, which consists of all the MessagePort objects
@@ -104600,8 +107315,8 @@ interface SharedWorkerGlobalScope : WorkerGlobalScope
than a short implementation-defined timeout value,
WorkerGlobalScope object is a SharedWorkerGlobalScope object
(i.e., the worker is a shared worker), andDocument object is not
- completely loaded.The second part of this definition allows a shared worker to survive for a short @@ -104753,8 +107468,8 @@ interface SharedWorkerGlobalScope : WorkerGlobalScope policy container given worker global scope, response, and inside settings.
-If the Run CSP initialization for a global object algorithm returns "Blocked" when executed upon worker global scope, set
+
If the Run CSP initialization for a global object algorithm returns
+ "Blocked" when executed upon worker global scope, set
response to a network error.
This really ought to be set when the agent cluster is created, which requires a - redesign of this section.
+This really ought to be set when the agent cluster is created, which requires + a redesign of this section.
If the result of checking a @@ -105423,7 +108138,7 @@ interface SharedWorker : EventTarget { scope to null.
For example, a user agent could have a development mode that isolates a - particular top-level browsing context from all other pages, and scripts in that + particular top-level traversable from all other pages, and scripts in that development mode could be blocked from connecting to shared workers running in the normal browser mode.
The lifetime of a WorkletGlobalScope is, at a minimum, tied to the
Document whose worklet global
- scopes contain it. In particular, discarding the
+ scopes contain it. In particular, destroying the
Document will terminate the
corresponding WorkletGlobalScope and allow it to be garbage-collected.
Each site has its own separate storage area.
The localStorage getter provides access
- to shared state. This specification does not define the interaction with other browsing contexts
+ to shared state. This specification does not define the interaction with other agent clusters
in a multiprocess user agent, and authors are encouraged to assume that there is no locking
mechanism. A site could, for instance, try to read the value of a key, increment its value, then
write it back out, using the new value as a unique identifier for the session; if the site does
@@ -106778,9 +109493,9 @@ interface Storage {
these steps:
Let url be storage's relevant global object's associated Document's URL.
Let thisDocument be storage's relevant global object's associated Document.
Let url be thisDocument's URL.
Let remoteStorages be all Storage objects excluding
@@ -106795,9 +109510,10 @@ interface Storage {
and, if type is "session",
- whose relevant settings object's browsing session is storage's relevant settings object's
- browsing session.
Document's node navigable's traversable navigable is thisDocument's node
+ navigable's traversable navigable.
Return storage.
While creating a new auxiliary browsing context, the session storage - is copied over.
+After creating a new auxiliary browsing context and document, the + session storage is copied over.
User agents may restrict access to the localStorage
- objects to scripts originating at the domain of the active document of the top-level browsing
- context, for instance denying access to the API for pages from other domains running in
- iframes.
iframes.
For example, a user agent could be configured to treat third-party local storage areas as - session-only storage, deleting the data once the user had closed all the browsing contexts that could access it.
+ session-only storage, deleting the data once the user had closed all the navigables that could access it.This can restrict the ability of a site to track a user, as the site would then only be able to track the user across multiple sessions when they authenticate with the site itself (e.g. by @@ -109000,13 +111716,12 @@ dictionary StorageEventInit : EventInit {
If the HTML parser for which this algorithm is being run is associated with a
- Document d whose browsing
- context is non-null and a child browsing context, then:
Document d whose container
+ document is non-null, then:
Let parentDocument be d's browsing context's container document.
If parentDocument's origin is same origin with d's StorageEventInit : EventInit { used to convert the input stream to the new encoding, set the confidence to certain, and return.
Otherwise, navigate to the document again, with historyHandling set to " Otherwise, restart the navigate algorithm, with historyHandling set to "replace",
- and using the same source browsing context, but this time skip the encoding
- sniffing algorithm and instead just set the encoding to the new encoding and the confidence to certain. Whenever possible, this
- should be done without actually contacting the network layer (the bytes should be re-parsed from
- memory), even if, e.g., the document is marked as not being cacheable. If this is not possible
- and contacting the network layer would involve repeating a request that uses a method other than
- `GET`, then instead set the replace" and
+ other inputs kept the same, but this time skip the encoding sniffing algorithm and
+ instead just set the encoding to the new encoding and the confidence to certain. Whenever possible,
+ this should be done without actually contacting the network layer (the bytes should be re-parsed
+ from memory), even if, e.g., the document is marked as not being cacheable. If this is not
+ possible and contacting the network layer would involve repeating a request that uses a method
+ other than `GET`, then instead set the confidence to certain and ignore the new
encoding. The resource will be misinterpreted. User agents may notify the user of the situation,
to aid in application development.
This could happen if, e.g., while the spin the event loop
- algorithm is running, the browsing context gets closed, or the document.open() method gets invoked on the
- Document.
Document gets destroyed, or the document.open()
+ method gets invoked on the Document.
Stop the speculative HTML parser for this instance of the HTML @@ -118708,12 +121423,11 @@ html, body { display: block; }
body element's container frame element's marginwidth attribute
- If the body element's node document's browsing context is a child browsing context,
- and the container of that browsing context is a
- frame or iframe element, then the container frame element of
- the body element is that frame or iframe element.
- Otherwise, there is no container frame element.
If the body element's node document's node navigable is
+ a child navigable, and the container of that
+ navigable is a frame or iframe element, then the
+ container frame element of the body element is that frame or
+ iframe element. Otherwise, there is no container frame element.
The above requirements imply that a page can change the margins of another page
(including one from another origin) using, for example, an iframe. This
@@ -118723,22 +121437,22 @@ html, body { display: block; }
If a Document's browsing context is a
- child browsing context, then it is expected to be positioned and sized to fit inside
- the content box of the container of that
- browsing context. If the container is not
- being rendered, the browsing context is expected to have a
- viewport with zero width and zero height.
If a If a If a Document's browsing context is a
- child browsing context, the container of that
- browsing context is a frame or iframe element, that element
- has a scrolling attribute, and that attribute's value is an ASCII
+ Document's node navigable is a child navigable,
+ then it is expected to be positioned and sized to fit inside the content box of the
+ container of that navigable. If the container is not being rendered, the
+ navigable is expected to have a viewport with zero width and zero
+ height.Document's node navigable is a child navigable,
+ the container of that navigable is a
+ frame or iframe element, that element has a scrolling attribute, and that attribute's value is an ASCII
case-insensitive match for the string "off", "noscroll", or "no", then the user agent is expected to
prevent any scrollbars from being shown for the viewport of the
- Document's browsing context, regardless of
- the 'overflow' property that applies to that viewport.Document's node navigable, regardless of the 'overflow'
+ property that applies to that viewport.
An object element that represents an image, plugin, or its
- nested browsing context is expected to be treated as a replaced element.
+ nested navigable is expected to be treated as a replaced element.
Other object elements are expected to be treated as ordinary elements in the
rendering model.
frameset element, with the rectangle as the
surface.
- Otherwise, it is a frame element; render its nested browsing
- context, positioned and sized to fit the rectangle.
Otherwise, it is a frame element; render its nested navigable,
+ positioned and sized to fit the rectangle.
The contents of a frame element that does not have a frameset parent
are expected to be rendered as transparent black; the user agent is expected to not
- render its nested browsing context in this case, and its nested browsing
- context is expected to have a viewport with zero width and zero height.
User agents are expected to allow the user to control aspects of hyperlink - activation and form submission, such as which browsing context is to be - used for the subsequent navigation.
+ activation and form submission, such as which navigable is to be used + for the subsequent navigation.User agents are expected to allow users to discover the destination of hyperlinks and of forms before triggering their @@ -121353,9 +124067,9 @@ progress { appearance: auto; } hyperlink auditing, and to let them know at a minimum which domains will be contacted as part of such auditing.
-User agents may allow users to navigate browsing contexts to the URLs indicated by the
- cite attributes on q, blockquote,
+
User agents may allow users to navigate navigables to the URLs indicated by
+ the cite attributes on q, blockquote,
ins, and del elements.
User agents may surface hyperlinks created by link
@@ -122284,9 +124998,8 @@ interface HTMLFrameSetElement : HTMLElement {
The frame element has a nested browsing context
- similar to the iframe element, but rendered within a frameset
- element.
The frame element has a nested navigable similar
+ to the iframe element, but rendered within a frameset element.
Create a new nested browsing context for element.
Create a new nested navigable for element.
Process the frame attributes for element, with initialInsertion set to true.
When a frame element stops being an active frame
- element, the user agent must discard
- the element's nested browsing context, and then set the element's nested
- browsing context to null.
Whenever a frame element with a non-null nested browsing context has
- its src attribute set, changed, or removed, the
- user agent must process the frame attributes.
To process the frame attributes for an element element, with
@@ -122321,10 +125032,26 @@ interface HTMLFrameSetElement : HTMLElement {
data-x="process-frame-initial-insertion">initialInsertion:
If element has a src attribute
- specified, or initialInsertion is false, then run the shared attribute
- processing steps for iframe and frame elements given
- element and initialInsertion.
Let url be the result of running the shared attribute processing steps
+ for iframe and frame elements given element and
+ initialInsertion.
If url is null, then return.
If url matches about:blank and
+ initialInsertion is true, then:
Fire an event named load at element.
Return.
Navigate an iframe or frame given
+ element, url, and the empty string.
The frame element potentially delays the load event.
noresize content attribute.
- The contentDocument IDL attribute, on getting, must
- return the frame element's content
- document.
The contentWindow IDL attribute must return the
- WindowProxy object of the frame element's nested browsing
- context, if the element's nested browsing context is non-null, or return null
- otherwise.
The marginHeight IDL attribute of the frame
element must reflect the element's HTMLFrameElement : HTMLElement {
element must reflect the element's marginwidth content attribute.
The contentDocument getter steps are to return
+ this's content document.
The contentWindow getter steps are to return
+ this's content window.
Fragments used with text/html resources
- either refer to the indicated part of the document or provide state information for
- in-page scripts.
Document, or
+ provide state information for in-page scripts.
@@ -123921,7 +126644,7 @@ interface External {
baseheadiframeobjectformtarget
button;
input
- headers
td;
@@ -126412,8 +129135,8 @@ interface External {
name
iframe;
object
- name
map
@@ -126681,18 +129404,18 @@ interface External {
target
a;
area
- target
base
- target
form
- title
pagehide
PageTransitionEvent
Window
- Window when the page's entry in the session history stops being the current entry
+ Window when the page's session history entry stops
+ being the active entry
pageshow
PageTransitionEvent
Window
- Window when the page's entry in the session history becomes the current entry
+ Window when the page's session history entry
+ becomes the active entry
pointercancel
@@ -127999,7 +130724,7 @@ INSERT INTERFACES HERE
popstate
PopStateEvent
Window
- Window when the user navigates the session history
+ Window when in some cases of session history traversal
readystatechange
@@ -128552,9 +131277,6 @@ INSERT INTERFACES HERE