multipart/x-mixed-replace documentsX-Frame-Options` headerRefresh` headerWelcome 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.
The basic concept may not seem so difficult:
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.
The browser looks at the URL stored in that session history entry, and uses it to re-fetch and populate that entry's document.
The browser again updates the navigable's active session history entry.
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:
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 event 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.
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.
A session history entry is a struct with the following items:
step, a non-negative integer or "pending", initially "pending".
URL, a URL
document state, a document state.
serialized state, which is serialized state or null, initially null..
scroll restoration mode, a scroll
restoration mode, initially "auto".
scroll position data, which is scroll position data for the document's restorable scrollable regions.
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.
To get a session history entry's document, return its document state's document.
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.
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.
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.
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.
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:
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 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".
A request referrer policy, which is a referrer policy, initially the default referrer policy.
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.
An origin, which is an origin or null, initially null.
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.
Nested histories, a list of nested histories, initially an empty list.
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.
A reload pending boolean, initially false.
An ever populated boolean, initially false.
A navigable target name string, initially the empty string.
User agents may destroy the documents of document
states with non-null documents, as long as
the Document is not fully active.
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.
A POST resource has:
A request body, a byte sequence or failure.
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.
A request content-type, which is
`application/x-www-form-urlencoded`, `multipart/form-data`, or
`text/plain`.
A nested history has:
An id, a unique internal value.
This is used to associate the nested history with a navigable.
Entries, a list of session history entries.
This will later contain ways to identify a nested navigable across reloads.
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.
All entries that share the same document state (and that are therefore merely different states of one particular document) are contiguous by construction.
A Document has a latest entry, a session history entry or
null.
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.
Run the following steps in parallel:
While true:
If sessionHistoryTraversalQueue's algorithm set is empty, then continue.
Let steps be sessionHistoryTraversalQueue's algorithm set[0].
Remove sessionHistoryTraversalQueue's algorithm set[0].
Run steps.
Return sessionHistoryTraversalQueue.
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 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.
For each docState of docStates:
For each nestedHistory of docState's nested histories:
Assert: This step is not reached.
To clear the forward session history of a traversable navigable navigable:
Assert: This is running within navigable's session history traversal queue.
Let step be the navigable's current session history step.
Let entryLists be the ordered set « navigable's session history entries ».
For each entryList of entryLists:
Remove every session history entry from entryList that has a step greater than step.
For each entry of entryList:
For each nestedHistory of entry's document state's nested histories, append nestedHistory's entries list to entryLists.
To get all used history steps that are part of traversable navigable traversable:
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 ».
For each entryList of entryLists:
For each entry of entryList:
For each nestedHistory of entry's document state's nested histories, append nestedHistory's entries list to entryLists.
Return steps, sorted.
To apply pending history changes to a traversable navigable traversable with optional boolean checkForUserCancelation (default false) and an optional number unsafeNavigationStartTime:
Let targetStep be traversable's current session history step.
Apply the history step targetStep to traversable with checkForUserCancelation set to checkForUserCancelation and unsafeNavigationStartTime set to unsafeNavigationStartTime if it was given.
Certain actions cause a navigable 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.
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, the URL and history update steps are often used during so-called "single-page app navigations" or "same-document navigations". And although fragment navigations are always done through the navigation 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:
To snapshot source snapshot params
given a Document sourceDocument, return a new source snapshot
params with
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:
To snapshot target snapshot params given a navigable targetNavigable, return a new target snapshot params with sandboxing flags set to targetNavigable's active browsing context's sandboxing flags.
Much of the navigation process is concerned with determining how to create a new
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:
DocumentDocumentDocumentDocumentDocumentNavigationTimingType used for creating the navigation timing entry for the new DocumentDocument has been createdOnce a navigation params struct is created, this standard does not mutate any of its items. They are only passed onward to other algorithms.
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. [WEBDRIVERBIDI]
DOMENIC-TODO: this could probably move somewhere more general since it isn't only for navigation, I think?
After 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:
push"replace"Each navigable has an ongoing navigation, which is a
navigation ID, "traversal", or null, initially null. It is
used to track navigation aborting and to prevent any navigations from taking place during
traversal.
To navigate a navigable navigable to a
URL url using a Document sourceDocument, with an
optional POST resource or string documentResource (default null), an optional response response (default null), an optional boolean exceptionsEnabled (default false), an optional
history handling behavior historyHandling (default "push"), an optional string cspNavigationType (default "other"), an optional referrer policy referrerPolicy (default the empty string),
and an optional processResponseEndOfBody, which is an
algorithm receiving a response (default an algorithm that
does nothing):
Let sourceSnapshotParams be the result of snapshotting source snapshot params given sourceDocument.
Let unsafeNavigationStartTime be the unsafe shared current time.
If sourceDocument's node navigable is not allowed by sandboxing to navigate navigable given and sourceSnapshotParams, then:
If exceptionsEnabled is true, then throw a
"SecurityError" DOMException.
Return.
Let navigationId be the result of generating a random UUID. [UUID]
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 "canceled", and url is url, and return.
If navigable's parent is non-null, then set
navigable's is delaying load events to
true.
Let targetBrowsingContext be navigable's active browsing context.
Let targetSnapshotParams be the result of snapshotting target snapshot params given navigable.
Let activeDocumentAtNavigationStartTime be navigable's active document.
Invoke WebDriver BiDi navigation started with
targetBrowsingContext, and a new WebDriver BiDi navigation status whose
id is navigationId, url is url, and status is "pending".
In parallel, run these steps:
If navigable's ongoing navigation is "traversal", then:
Invoke WebDriver BiDi navigation failed with
targetBrowsingContext and a new WebDriver BiDi navigation status
whose id is navigationId, status is "canceled", and url is url.
Abort these steps.
Any attempts to navigate a navigable that is currently traversing are ignored.
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.
Let unloadPromptResult be the result of checking if unloading is user-canceled for navigable's active document's inclusive descendant navigables.
If unloadPromptResult is "refuse", or
navigable's ongoing navigation is no longer navigationId,
then:
Invoke WebDriver BiDi navigation failed with
targetBrowsingContext and a new WebDriver BiDi navigation status
whose id is navigationId, status is "canceled", and url is url.
Abort these steps.
If unloadPromptResult is "confirm", then set
unsafeNavigationStartTime to the unsafe shared current time.
Queue a global task on the navigation and traversal task source given navigable's active window to abort navigable's active document.
Let documentState be a new document state with
The navigable target name can get cleared under various conditions later in the navigation process, before the document state is finalized.
If url is about:blank, then set documentState's origin to
sourceSnapshotParams's origin.
Otherwise, if url is about:srcdoc, then set
documentState's origin to
navigable's parent's active document's origin.
Let historyEntry be a new session history entry, with its URL set to url and its document state set to documentState.
If url's scheme is "javascript", then queue a global task on the
DOM manipulation task source given navigable's active window to run these steps:
Populate a history entry's document by evaluating
a javascript: URL for historyEntry, given
navigable, unsafeNavigationStartTime, sourceSnapshotParams,
cspNavigationType, and url.
Queue a task on the navigable's traversable's session history traversal queue to finalize a cross-document navigation with navigable, historyHandling, and historyEntry.
Return.
So for example a 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
navigable's active window when the
iframe is being set up. Once evaluated, its return value (if it was a string)
would replace that navigable's active
document, thus also changing the corresponding Window object.
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, targetBrowsingContext's parent browsing context's active 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, sourceSnapshotParams's 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.
Set navigationParams to a new navigation params, with
navigate"Attempt to populate the history entry's document for historyEntry,
given navigable, "navigate",
unsafeNavigationStartTime, sourceSnapshotParams,
targetSnapshotParams, navigationId, navigationParams,
cspNavigationType, with allowPOST
set to true, processResponseEndOfBody set to
processResponseEndOfBody, and completionSteps set to the following
steps:
If navigable's active document is not activeDocumentAtNavigationStartTime, then abort these steps.
Queue a task on the navigable's traversable's session history traversal queue to finalize a cross-document navigation given navigable, historyHandling, and historyEntry.
Although a cross-document navigation will first foray into populating a session history entry with a
Document, all navigations that don't get aborted will ultimately end up calling into
one of the below algorithms.
To finalize a cross-document navigation given a navigable navigable, history handling behavior historyHandling, and session history entry historyEntry:
Set navigable's is delaying load
events to false.
If historyEntry's document is null, then return.
This means that attempting to populate the history entry's document ended up not creating a document, e.g. due to a 204 No Content response.
Assert: This algorithm is running on navigable's traversable navigable's session history traversal queue.
Set the historyEntry's document state's ever populated to true.
DOMFAROLINO-TODO: Should the above happen elsewhere? When the document is actually populated?
If all of the following are true:
navigable's parent is null;
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 "replace", otherwise null.
Let traversable be navigable's traversable navigable.
Let targetStep be null.
Let targetEntries be the result of getting session history entries for navigable.
If entryToReplace is null, then:
Clear the forward session history of traversable.
Set targetStep to traversable's current session history step + 1.
Set historyEntry's step to targetStep.
Append historyEntry to targetEntries.
Otherwise:
Replace entryToReplace with historyEntry in targetEntries.
Set targetStep to traversable's current session history step.
Apply the history step targetStep to traversable.
To navigate to a fragment given a navigable navigable, a URL url, a history handling behavior historyHandling, and a navigation ID navigationId:
Let historyEntry be a new session history entry, with
Let entryToReplace be navigable's active session history entry if
historyHandling is "replace", otherwise
null.
Let history be navigable's active document's history object.
Let scriptHistoryIndex be history's index.
Let scriptHistoryLength be history's length.
If historyHandling is "push", then:
Set history's state to null.
Increment scriptHistoryIndex.
Set scriptHistoryLength to scriptHistoryIndex + 1.
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.
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, 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.
Scroll to the fragment given navigable's active document.
If the scrolling fails because the 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.
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 browsingContext,
and a new WebDriver BiDi navigation status whose id is navigationId, url is resource's url, and status is "complete".
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:
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.
Assert: this algorithm is running on traversable's session history traversal queue.
If targetNavigable's active session history entry is not targetEntry, then return.
Let targetStep be null.
Let targetEntries be the result of getting session history entries for targetNavigable.
If entryToReplace is null, then:
Clear the forward session history of traversable.
Set targetStep to traversable's current session history step + 1.
Set targetEntry's step to targetStep.
Append targetEntry to targetEntries.
Otherwise:
Replace entryToReplace with targetEntry in targetEntries.
Set targetStep to traversable's current session history step.
Apply the history step targetStep to traversable.
This is done even for "replace" navigations,
as it resolves race conditions across multiple synchronous navigations.
To attempt to create a URL scheme document, given a URL
url, a browsing context browsingContext, a sandboxing
flag set sandboxFlags, a navigation ID navigationId, a
NavigationTimingType navTimingType, and a source snapshot
params sourceSnapshotParams:
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 sourceSnapshotParams.
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 browsingContext, navigationId, and navTimingType.
In the case of a registered handler being used, navigate will be invoked with a new URL.
To hand-off to external software given a URL or response resource, a browsing context browsingContext, a sandboxing flag set sandboxFlags, and a source snapshot params sourceSnapshotParams, user agents should:
If all of the following conditions hold:
browsingContext is not a top-level browsing context;
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 sourceSnapshotParams's has transient activation is false
then return without invoking the external software package.
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
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.
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 sourceSnapshotParams's origin is to be allowed to invoke the external software in question. In particular, if sourceSnapshotParams's has transient activation is false, then the user agent should not invoke the external software package without prior user confirmation.
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.
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 source is target, then return true.
If source is an ancestor of target, then return true.
If target is an ancestor of source, then:
If target is not a top-level traversable, then return true.
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.
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.
Return true.
If target is a top-level traversable:
If source is the one permitted sandboxed navigator of target, then return true.
If sourceSnapshotParams's sandboxing flags's sandboxed navigation browsing context flag is set, then return false.
Return true.
If sourceSnapshotParams's sandboxing flags's sandboxed navigation browsing context flag is set, then return false.
Return true.
To check if unloading is user-canceled for list of navigables navigables:
Let documents be the active document of each item in navigables.
Let unloadPromptShown be false.
Let unloadPromptCanceled be false.
Let totalTasks be the size of documents.
Let completedTasks be 0.
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:
Increase the document's unload counter by 1.
Increase the event loop's termination nesting level by 1.
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.
If all of the following are true:
unloadPromptShown is false;
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; and
showing an unload prompt is unlikely to be annoying, deceptive, or pointless
then:
Set unloadPromptShown to true.
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 returnValue attribute is ignored.
If the user did not confirm the page navigation, set unloadPromptCanceled to true.
Decrease the document's unload counter by 1.
Increment completedTasks.
Wait for completedTasks to be totalTasks.
If unloadPromptCanceled is true, then return "refuse".
If unloadPromptShown is true, then return "confirm".
Return "no-prompt".
To reload a navigable navigable:
Let unsafeNavigationStartTime be the unsafe shared current time.
Set navigable's active session history entry's document state's reload pending to true.
Let traversable be navigable's traversable navigable.
Append the following session history traversal steps to traversable:
Apply pending history changes to traversable with true and unsafeNavigationStartTime.
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 parent.location.reload().
To traverse the history by a delta given a traversable navigable
traversable, an integer delta, and an optional Document
sourceDocument:
Let unsafeNavigationStartTime be the unsafe shared current time.
Let sourceSnapshotParams and initiatorToCheck be null.
If sourceDocument is given, then:
Set sourceSnapshotParams to the result of snapshotting source snapshot params given sourceDocument.
Set initiatorToCheck to sourceDocument's node navigable.
Append the following session history traversal steps to traversable:
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.
Apply the history step allSteps[targetStepIndex] to traversable, with checkForUserCancelation set to true, unsafeNavigationStartTime set to unsafeNavigationStartTime, sourceSnapshotParams set to sourceSnapshotParams, and initiatorToCheck set to initiatorToCheck.
When the user navigates through a top-level traversable, e.g. using a browser's back and forward buttons, the user agent must traverse the history by a delta with the top-level traversable being operated on and a delta equivalent to the action specified by the user.
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 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.
The URL and history update steps, given a Document
document, a URL newURL, an optional serialized
state-or-null serializedData (default
null), and an optional history handling behavior historyHandling (default "replace"), are:
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
If document's is initial about:blank is true, then set
historyHandling to "replace".
This means that pushState() on an
initial about:blank
Document behaves as a replaceState() call.
Let entryToReplace be activeEntry if historyHandling is
"replace", otherwise null.
If historyHandling is "push", then:
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.
If serializedData is not null, then restore the history object state given document and newEntry.
Set document's URL to newURL.
Since this is neither a navigation nor a history traversal, it does not cause a hashchange event to be fired.
Set document's latest entry to newEntry.
Set navigable's active session history entry to newEntry.
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, newEntry, and entryToReplace.
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 popstate events
fire for fragment navigations, but not for history.pushState() calls.
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 process breaks down into two high-level cases: the usual
case, and the javascript: URL special
case. The usual case involves either using an
already-given response, using the srcdoc
resource stored in the session history entry, or fetching. The javascript: case bypasses most of the usual machinery and instead assembles
enough information to immediately load an HTML document. Both
cases have several failure modes, which can either result in doing nothing (leaving the
navigable on its currently-active
Document) or can result in populating the session history entry with an
error document.
To attempt to populate the history entry's document for a session history
entry entry, given a navigable
navigable, a NavigationTimingType navTimingType,
a number unsafeNavigationStartTime, 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), optional
algorithm steps processResponseEndOfBody
(default an empty algorithm), and optional algorithm steps completionSteps (default an empty
algorithm):
Assert: if navigationParams is non-null, then navigationParams's response is non-null.
Let currentBrowsingContext be navigable's active browsing context.
Let documentResource be entry's document state's resource.
If navigationParams is null, then:
If documentResource is a string, then set navigationParams to the result of creating navigation params from a srcdoc resource given entry, navigable, sourceSnapshotParams, targetSnapshotParams, cspNavigationType, navigationId, navTimingType, processResponseEndOfBody, and unsafeNavigationStartTime.
Otherwise, if both of the following are true:
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, navTimingType, processResponseEndOfBody, and unsafeNavigationStartTime.
If navigationParams is "aborted", then run
completionSteps and return.
Queue a global task on the networking task source, given currentBrowsingContext's active window to run these steps:
Let failure be false.
If navigationParams is null and entry's URL is not a fetch scheme, then set entry's document state's document to the result of running attempt to create a URL scheme document given entry's URL, currentBrowsingContext, sandboxFlags, navigationId, navTimingType, and sourceSnapshotParams.
The entry's URL might have been changed within the previous step of this algorithm following an HTTP redirect.
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 "Blocked", then set failure to true. [CSP]
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, currentBrowsingContext, 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
`X-Frame-Options` given navigationParams's response, currentBrowsingContext, and
navigationParams's origin is false,
then set failure to true.
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 currentBrowsingContext, null, and navTimingType. The inline content should indicate to the user the sort of error that occurred.
Set entry's document state's document's salvageable to false.
If navigationParams is not null, then:
Run processResponseEndOfBody given navigationParams's response.
Run the environment discarding steps for navigationParams's reserved environment.
Invoke WebDriver BiDi navigation failed with
browsingContext and a new WebDriver BiDi navigation status whose
id is navigationId, status is "canceled", and url is navigationParams's response's URL.
Otherwise, if navigationParams's response's status is 204 or 205, then:
Run processResponseEndOfBody given navigationParams's response.
Run completionSteps.
Return.
Otherwise:
Let document be the result of loading a document given navigationParams and sourceSnapshotParams.
If document is null, then run completionSteps and return.
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 "client", then set it to request's referrer.
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.
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, a NavigationTimingType navTimingType, an
algorithm processResponseEndOfBody, and a number
unsafeNavigationStartTime:
Let documentResource be entry's document state's resource.
Let response be a new response whose
URL list consists of about:srcdoc,
header list consists of
(`Content-Type`, `text/html`), and body is documentResource.
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.
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.
Let policyContainer be the result of determining navigation params policy container given response's URL, entry's document state's history policy container, null, currentBrowsingContext's parent browsing context's active document's policy container, and null.
Return a new navigation params, with
To create navigation params by fetching given a session history entry
entry, a navigable navigable, a source snapshot
params sourceSnapshotParams, a target snapshot params
targetSnapshotParams, a string cspNavigationType, a navigation
ID-or-null navigationId, a NavigationTimingType
navTimingType, an algorithm processResponseEndOfBody, and a number
unsafeNavigationStartTime:
This algorithm mutates entry.
Let url be entry's URL.
Let documentResource be entry's document state's resource.
Let request be a new request, with
document"include"manual"navigate"If documentResource is a POST resource, then:
Set request's method to `POST`.
Set request's body to documentResource's request body.
Set `Content-Type`
to documentResource's request
content-type in request's header
list.
If entry's document state's reload pending is true, then set request's reload-navigation flag.
Otherwise, if entry's document state's ever populated is true, then set request's history-navigation flag.
If sourceSnapshotParams's has transient activation is true, then set request's user-activation to true.
If navigable's container is non-null:
If the navigable's container has a browsing context scope origin, then set request's origin to that browsing context scope origin.
Set request's destination to navigable's container's local name.
Let response be null.
Let responseOrigin be null.
Let coopEnforcementResult be a new cross-origin opener policy enforcement result, with
Let finalSandboxFlags be an empty sandboxing flag set.
Let responsePolicyContainer be null.
Let responseCOOP be a new cross-origin opener policy.
Let locationURL be null.
Let currentURL be request's current URL.
Let hasCrossOriginRedirects be false.
Let uncommittedPreloads be null.
While true:
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:
Run the environment discarding steps for request's reserved client.
Set request's reserved client to null.
Set uncommittedPreloads to null.
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 request's reserved client is null, then:
Let topLevelCreationURL be currentURL.
Let topLevelOrigin be null.
If navigable is not a top-level traversable, then:
Let parentEnvironment be navigable's parent's active document's relevant settings object.
Set topLevelCreationURL to parentEnvironment's top-level creation URL.
Set 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 navigable's active browsing context, creation URL is currentURL, top-level creation URL is topLevelCreationURL, and top-level origin is topLevelOrigin.
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. [SW]
If the result of should navigation request of type be blocked by Content Security
Policy? given request and cspNavigationType is "Blocked", then set response to a network error and
break. [CSP]
If response is null, fetch request, with processEarlyHintsResponse set to the following step given a response earlyResponse: If uncommittedPreloads is null, then set uncommittedPreloads to the result of processing early hint headers given earlyResponse and request's reserved client.
Otherwise, perform HTTP-redirect fetch using request and response.
If request's body is null, then set entry's document state's resource to null.
Fetch unsets the body for particular redirects.
Wait for the task on the networking task source to process response and set response to the result.
If navigationId is not null, then, while waiting, if
navigable's ongoing navigation changes to no longer equal
navigationId, terminate the ongoing
fetch with the aborted flag set, and return "aborted".
Set responsePolicyContainer to the result of creating a policy container from a fetch response given response and request's reserved client.
Set finalSandboxFlags to the union of targetSnapshotParams's sandboxing flags and responsePolicyContainer's CSP list's CSP-derived sandboxing flags.
Let sourceOrigin be entry's document state's origin if request's current URL matches
about:blank, and sourceSnapshotParams's origin otherwise.
Set responseOrigin to the result of determining the origin given response's URL, finalSandboxFlags, sourceOrigin, and null.
If navigable is a top-level traversable, 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 navigable's active browsing context, request's URL, responseOrigin, responseCOOP, coopEnforcementResult and request's referrer.
If sandboxFlags is not empty and responseCOOP's value is not "unsafe-none", then set response to an
appropriate network error and break.
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 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.
Set locationURL to response's location URL given currentURL's fragment.
If locationURL is failure or null, then break.
Set entry's URL to locationURL.
Set entry's serialized state to null.
Let oldDocState be entry's document state.
Set entry's document state to a new document state, with request referrer, request referrer policy, resource, ever populated, and navigable target name copied from oldDocState, and the history policy container set to a clone of the oldDocState's history policy container.
For the navigation case, only entry referenced oldDocState, so 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.
Consider a session history which contains... TODO-DOMENIC: fill out the full example of the traversal case, maybe.
If locationURL is not a URL whose scheme is an HTTP(S) scheme, then:
Set entry's document state's resource to null.
Navigation handles redirects manually as navigation is the only place in the
web platform that cares for redirects to mailto: URLs
and such.
If locationURL's origin is not the same as currentURL's origin, then set hasCrossOriginRedirects to true.
Set currentURL to locationURL.
By the end of this loop we will be in one of these scenarios:
response is a network error.
locationURL is failure, because of an unparseable `Location` header.
locationURL is null, because we successfully fetched a non-network
error HTTP(S) response with no `Location` header.
If locationURL is not null or response is a network error, then return null.
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.
Return a new navigation params, with
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.
This definition is broken and needs investigation to see what it was intended to express: see issue #4703.
To load a document given navigation params
navigationParams and source snapshot params
sourceSnapshotParams, perform the following steps. They return a Document
or null.
Let type be the computed type of navigationParams's response.
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:
text/css"text/plain"text/vtt"multipart/x-mixed-replace"multipart/x-mixed-replace document, given navigationParams and sourceSnapshotParams.application/pdf"text/pdf"Otherwise, proceed onward.
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 application/atom+xml MIME
type.
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 browsing context, 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 browsing context, 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 browsing context, navigationParams's final sandboxing flag set, and sourceSnapshotParams.
Return null.
javascript: URL special casejavascript: URLs have a dedicated label
on the issue tracker documenting various problems with their specification.
To populate a history entry's document by evaluating a
javascript: URL for session history entry
historyEntry, given a navigable targetNavigable, a number
unsafeNavigationStartTime, a source snapshot params
sourceSnapshotParams, a string cspNavigationType, and a URL
url:
Let request be a new request whose URL is url.
This is a synthetic request solely for plumbing into other algorithms. It will never hit the network.
If both of the following are true:
sourceSnapshotParams's origin is same origin-domain with targetNavigable's active document's origin; and
the result of should navigation request of type be blocked by Content Security
Policy? given request and cspNavigationType is "Allowed" [CSP]
then:
Let urlString be the result of running the URL serializer on url.
Let encodedScriptSource be the result of removing the leading "javascript:" from urlString.
Let scriptSource be the UTF-8 decoding of the percent-decoding of encodedScriptSource.
Append targetNavigable's active document's URL to request's URL list.
Let settings be targetNavigable's active document's relevant settings object.
Let baseURL be settings's API base URL.
Let script be the result of creating a classic script given scriptSource, settings, baseURL, and the default classic script fetch options.
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.
If Type(result) is String, then set
response to a response whose header list is « (`Content-Type`,
`text/html;charset=utf-8`) », and whose body is the result of UTF-8
encoding result.
The encoding to UTF-8 means that unpaired surrogates will not roundtrip, once the HTML parser decodes the response body.
Let policyContainer be targetNavigable's active document's policy container.
Let finalSandboxFlags be policyContainer's CSP list's CSP-derived sandboxing flags.
Let coop be targetNavigable's active document's cross-origin opener policy.
Let coopEnforcementResult be a new cross-origin opener policy enforcement result with
Let navigationParams be a new navigation params, with
navigate"Set historyEntry's document state's document to the result loading an HTML document given navigationParams.
javascript: URL
documents go through a special path wherein we never actually call into attempt to
populate the history entry's document, but instead we synchronously populate its document right here.
A changing navigable continuation state is a struct with:
DocumentTo apply the history step non-negative integer step to a traversable navigable traversable, with optional boolean checkForUserCancelation (default false), optional number unsafeNavigationStartTime, 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.)
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 initiatorToCheck is given, then:
Assert: sourceSnapshotParams is not null.
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 navigablesCrossingDocuments be the result of getting all navigables that might experience a cross-document traversal given traversable and targetStep.
If checkForUserCancelation is true, and the result of checking if unloading
is user-canceled given navigablesCrossingDocuments given
traversable and targetStep is "refuse", then
return.
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.
For each navigable of changingNavigables:
Let targetEntry be the result of getting the target history entry given navigable and targetStep.
Set navigable's current session history entry to targetEntry.
Set navigable's ongoing navigation to "traversal".
Let changeJobs be the size of changingNavigables.
Let completedChangeJobs be 0.
Let changingNavigableContinuations be an empty queue of changing navigable continuation states.
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:
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.
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 displayedEntry is targetEntry and targetEntry's document state's reload pending is false, then:
Set changingNavigableContinuation's update-only to true.
Enqueue changingNavigableContinuation on changingNavigableContinuations.
Abort these steps.
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:
Assert: unsafeNavigationStartTime is given.
Let navTimingType be "back_forward" if
targetEntry's document is null; otherwise
"reload".
Let targetSnapshotParams be the result of snapshotting target snapshot params given navigable.
Let potentiallyTargetSpecificSourceSnapshotParams be sourceSnapshotParams.
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.
Attempt to populate the history entry's document for targetEntry, given navigable, unsafeNavigationStartTime, potentiallyTargetSpecificSourceSnapshotParams, targetSnapshotParams, with allowPOST set to targetEntry's document state's reload pending, and completionSteps set to queue a global task on the navigation and traversal task source given navigable's active document's relevant global object to continue these steps.
Set targetEntry's document state's reload pending to false.
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 is true:
navigable's parent is null.
targetEntry's document's browsing context is not an auxiliary browsing context whose disowned is false.
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.
While completedChangeJobs does not equal totalChangeJobs:
If traversable's running nested apply history step is false, then:
Let changingNavigableContinuation be the result of dequeuing from changingNavigableContinuations.
If changingNavigableContinuation is nothing, then continue.
Let displayedDocument be changingNavigableContinuation's displayed document.
Let targetEntry be changingNavigableContinuation's target entry.
Let navigable be changingNavigableContinuation's navigable.
Set navigable's ongoing navigation to null.
This allows new navigations of navigable to start, whereas during the traversal they were blocked.
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.
Append navigable to navigablesThatMustWaitBeforeHandlingSyncNavigation.
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 of navigable's active window to run the steps:
If changingNavigableContinuation's update-only is false, then:
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.
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.
Update document for history step application given targetEntry's document, targetEntry, changingNavigableContinuation's update-only, scriptHistoryLength, and scriptHistoryIndex.
Increment completedChangeJobs.
Let totalNonchangingJobs be the size of nonchangingNavigablesThatStillNeedUpdates.
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.
Let completedNonchangingJobs be 0.
Let (scriptHistoryLength, scriptHistoryIndex) be the result of getting the history object length and index given traversable and targetStep.
For each navigable of nonchangingNavigablesThatStillNeedUpdates, queue a global task on the navigation and traversal task source of navigable's active window to run the steps:
Let document be navigable's active document.
Set document's history object's index to scriptHistoryIndex.
Set document's history object's length to scriptHistoryLength.
Increment completedNonchangingJobs.
Wait for completedNonchangingJobs to equal totalNonchangingJobs.
Set traversable's current session history step to targetStep.
To activate history entry session history entry entry for navigable navigable:
Save persisted state to the navigable's active session history 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.
Set navigable's active session history entry to entry.
Make active newDocument.
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.
Let steps be the result of getting all used history steps within traversable.
Return the greatest item in steps that is less than or equal to step.
This caters for situations where there's no session history entry with step step, due to the removal of a navigable.
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 steps be the result of getting all used history steps within traversable.
Let scriptHistoryLength be the size of steps.
Assert: steps contains step.
It is assumed that step has been adjusted by getting the used step.
Let scriptHistoryIndex be the index of step in sessionSteps.
Return (scriptHistoryLength, scriptHistoryIndex).
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 results be an empty list.
Let navigablesToCheck be « traversable ».
This list is extended in the loop below.
For each navigable of navigablesToCheck:
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 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 results be an empty list.
Let navigablesToCheck be « traversable ».
This list is extended in the loop below.
For each navigable of navigablesToCheck:
Let targetEntry be the result of getting the target history entry given navigable and targetStep.
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.
Return results.
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 entries be the result of getting the history entries for navigable.
Return the item in entries that has the greatest step less than or equal to step.
JAKE-TODO: Create a timeline diagram to explain why it's "greatest step less than or equal to step".
DOMENIC-TODO: the below algorithm is only called once, but there is a very similar getting session history entries, which seems very suspicious and demands a rename at least.
To get the history entries for a navigable navigable:
Let traversable be navigable's traversable navigable.
Assert: This is running within traversable's session history traversal queue.
If traversable is navigable, then return traversable's session history entries.
Let entryLists be the ordered set « traversable's session history entries ».
For each entryList of entryLists:
For each entry of entryList:
For each nestedHistory of entry's document state's nested histories:
If nestedHistory's id is navigable's id, then return nestedHistory's entries list.
Append nestedHistory's entries list to entryLists.
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.
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.
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.
Let results be an empty list.
Let navigablesToCheck be « traversable ».
This list is extended in the loop below.
For each navigable of navigablesToCheck:
Let targetEntry be the result of getting the target history entry given navigable and targetStep.
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 Document, so accessing navigable's document is reliable.
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.
Return results.
To update document for history step application given a Document
document, a session history entry entry, a boolean
doNotReactivate, and integers scriptHistoryLength and
scriptHistoryIndex:
Let documentIsNew be true if document's latest entry is null; otherwise false.
Let documentsEntryChanged be true if document's latest entry is not entry; otherwise false.
Set document's history object's index to scriptHistoryIndex.
Set document's history object's length to scriptHistoryLength.
If documentsEntryChanged is true, then:
Let oldURL be document's latest entry's URL.
Set document's latest entry to entry.
Restore the history object state given document and entry.
If documentIsNew is false, then fire an
event named popstate at document's
relevant global object, using PopStateEvent, with the state attribute initialized to document's
history object's state.
Restore persisted state given entry.
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 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.
If documentIsNew is true, then:
Try to scroll to the fragment for document.
At this point scripts may run for the newly-created document document. DOMENIC-TODO: reference this appropriately.
Otherwise, if documentsEntryChanged is false and doNotReactivate is false, then reactivate document.
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.
To restore the history object state given Document
document and session history entry entry:
Let targetRealm be document's relevant Realm.
Let state be null.
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.
Set document's history object's state to state.
To make active a Document document:
Let window be document's relevant global object.
Set document's browsing context's
WindowProxy's [[Window]] internal
slot value to window.
Set document's visibility state to document's node navigable's traversable navigable's system visibility state.
Set window's relevant settings object's execution ready flag.
To reactivate a Document
document:
This algorithm updates document after it has come out of bfcache, i.e., after it has been made fully active again.
For each
formControl of form controls in document with an autofill field
name of "off", invoke the reset algorithm for formControl.
If document's suspended timer handles is not empty:
Assert: document's suspension time is not zero.
Let suspendDuration be the current high resolution time minus document's suspension time.
Let activeTimers be document's relevant global object's map of active timers.
For each handle in document's suspended timer handles, if activeTimers[handle] exists, then increase activeTimers[handle] by suspendDuration.
If document's current document readiness is "complete", and document's page showing flag is false,
then:
Set document's page showing flag to true.
Update the visibility state of document to "visible".
Fire a page transition event named pageshow at document's relevant global
object with true.
To try to scroll to the fragment for a Document document,
perform the following steps in parallel:
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 document.
If document's indicated part is still null, then try to scroll to the fragment for document.
To scroll to the fragment given a
Document document:
If document's indicated part is null, then set document's target element to null.
Otherwise, if document's indicated part is top of the document, then:
Set document's target element to null.
Scroll to the beginning of the document for document. [CSSOMVIEW]
Return.
Otherwise:
Assert: document's indicated part is an element.
Let target be document's indicated part.
Set document's target element to target.
Run the ancestor details revealing algorithm on target.
Run the on target.
Scroll target into view, with behavior set to "auto", block set to "start", and inline set to "nearest". [CSSOMVIEW]
Run the focusing steps for target, with the
Document's viewport as the fallback target.
Move the sequential focus navigation starting point to target.
A 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). [RFC7303]
There is also a target element for each Document, which is used in
defining the :target pseudo-class and is updated by the
above algorithm. It is initially null.
For an HTML document document, the following processing model must be followed to determine its indicated part:
If fragment is the empty string, then return the special value top of the document.
Let potentialIndicatedElement be the result of finding a potential indicated element given document and fragment.
If potentialIndicatedElement is not null, then return potentialIndicatedElement.
Let fragmentBytes be the result of percent-decoding fragment.
Let decodedFragment be the result of running UTF-8 decode without BOM on fragmentBytes.
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 top, then return the top of the document.
Return null.
To find a potential indicated element given a Document
document and a string fragment, run these steps:
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 there is an 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.
Return null.
To save persisted state to a session history entry entry:
Set the scroll position data of entry to contain the scroll positions for all of entry's document's restorable scrollable regions.
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 "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.
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.
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.
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.
JAKE-TODO: review this section
This section is non-normative.
The History interface is not meant to place restrictions on how implementations
represent the session history to the user.
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
history object are derived from the actual session history as
seen from the user's perspective.
Similarly, a page containing two 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.
Security: It is suggested that to avoid letting a page "hijack" the history
navigation facilities of a UA by abusing 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.
For both 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.
When loading a document using one of the below algorithms, we use the
following steps to create and initialize a 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().
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.
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 browsing context. In such a case, the
created 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.
Let permissionsPolicy be the result of creating a permissions policy from a response given browsingContext, navigationParams's origin, and navigationParams's response. [PERMISSIONSPOLICY]
The creating a permissions policy from a response algorithm makes use of the
passed origin. If document.domain has
been used for browsingContext'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
that this means that Permissions Policy checks are less permissive compared to doing a
same origin check instead.
See below for some examples of this in action.
If navigationParams's request is non-null, then set creationURL to navigationParams's request's current URL.
Let window be null.
If browsingContext's active document's is initial
about:blank is true, and browsingContext's active
document's origin is same
origin-domain with navigationParams's origin, then set window to
browsingContext's active window.
This means that both the initial
about:blank Document, and the new Document that
is about to be created, will share the same Window object.
Otherwise:
Let oacHeader be the result of getting a structured field value
given `Origin-Agent-Cluster` and "item" from
navigationParams's response's
header list.
Let requestsOAC be true if oacHeader is not null and oacHeader[0] is the boolean true; otherwise false.
If navigationParams's reserved environment is a non-secure context, then set requestsOAC to false.
Let agent be the result of obtaining a similar-origin window agent given navigationParams's origin, browsingContext's group, and requestsOAC.
Let realmExecutionContext be the result of creating a new JavaScript realm given agent and the following customizations:
For the global object, create a new Window object.
For the global this binding, use browsingContext's
WindowProxy object.
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:
Let parentEnvironment be browsingContext's container's relevant settings object.
Set topLevelCreationURL to parentEnvironment's top-level creation URL.
Set topLevelOrigin to parentEnvironment's top-level origin.
Set up a window environment settings object with creationURL, realmExecutionContext, navigationParams's reserved environment, topLevelCreationURL, and topLevelOrigin.
This is the usual case, where the new Document we're about to
create gets a new Window to go along with it.
Let loadTimingInfo be a new document load timing info with its navigation start time set to the result of calling coarsen time with navigationParams's unsafe start time and document's relevant settings object's cross-origin isolated capability.
Let document be a new Document, with
loading"Set window's associated
Document to document.
Run CSP initialization for a Document given
document. [CSP]
If navigationParams's request is non-null, then:
Set document's referrer to the empty string.
If referrer is a URL record, then set document's referrer to the serialization of referrer.
Per Fetch, referrer will be either a URL
record or "no-referrer" at this point.
Let redirectCount be 0 if navigationParams'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, navigationParams's navigation timing type, and navigationParams's response's service worker timing info.
If navigationParams's response
has a `Refresh` header, then:
Let value be the isomorphic decoding of the value of the header.
Run the shared declarative refresh steps with document and value.
We do not currently have a spec for how to handle multiple `Refresh`
headers. This is tracked as issue #2900.
If navigationParams's uncommitted preloads is not null, then for each commitEarlyPreload of navigationParams's uncommitted preloads, call commitEarlyPreload given document.
Process link headers given document,
navigationParams's response, and
"pre-media".
Return document.
In this example, the child document is not allowed to use PaymentRequest,
despite being same origin-domain at the time the child document tries to use
it. At the time the child document is initialized, only the parent document has set document.domain, and the child document has not.
<!-- https://foo.example.com/a.html -->
<!doctype html>
<script>
document.domain = 'example.com';
</script>
<iframe src=b.html></iframe><!-- https://bar.example.com/b.html -->
<!doctype html>
<script>
document.domain = 'example.com'; // This happens after the document is initialized
new PaymentRequest(…); // Not allowed to use
</script>In this example, the child document is allowed to use
PaymentRequest, despite not being same origin-domain at the time
the child document tries to use it. At the time the child document is initialized, none of
the documents have set document.domain yet so
same origin-domain falls back to a normal same origin check.
<!-- https://example.com/a.html -->
<!doctype html>
<iframe src=b.html></iframe>
<!-- The child document is now initialized, before the script below is run. -->
<script>
document.domain = 'example.com';
</script><!-- https://example.com/b.html -->
<!doctype html>
<script>
new PaymentRequest(…); // Allowed to use
</script>To load an HTML document, given navigation params navigationParams:
Let document be the result of creating and initializing a Document
object given "html", "text/html", and
navigationParams.
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 "media", after
the task has been procesed by the HTML parser.
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 document's relevant global object to run the following steps:
Call navigationParams's process response end of body with navigationParams's response.
Have the parser to process the implied EOF character, which eventually causes a load event to be fired.
Return document.
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.
[XML] [XMLNS] [RFC7303] [DOM]
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 procesed by the XML parser.
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.
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 Document.
To load a text document, given a navigation params navigationParams and a string type:
Let document be the result of creating and initializing a Document
object given "html", type, and
navigationParams.
Set document's parser cannot change the mode flag to true.
Set document's mode
to "no-quirks".
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 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 procesed by the HTML parser.
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 run the following steps:
Call navigationParams's process response end of body with navigationParams's response.
Have the parser to process the implied EOF character, which eventually causes a load event to be fired.
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).
The document's character encoding must be set to the character encoding used to decode the document.
User agents may add content to the head element of the Document,
e.g., linking to a style sheet, providing script, or giving the document a title.
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.
multipart/x-mixed-replace documentsTo load a multipart/x-mixed-replace document, given navigation params navigationParams and source snapshot params sourceSnapshotParams:
Parse navigationParams's response's body using the rules for multipart types. [RFC2046]
Let firstPartNavigationParams be a copy of navigationParams.
Set firstPartNavigationParams response to a new response representing the first part of navigationParams's response's body's multipart stream.
Let document be the result of loading a document given firstPartNavigationParams and sourceSnapshotParams.
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".
Return document.
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.
To load a media document, given navigationParams and a string type:
Let document be the result of creating and initializing a Document
object given "html", type, and
navigationParams.
Set document's mode
to "no-quirks".
Append an html element to document.
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.
Process link headers given document,
navigationParams's response, and
"media".
Return document.
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.
| Type of media | Element for the media | Appropriate attribute |
|---|---|---|
| Image | img
| src
|
| Video | video
| src
|
| Audio | audio
| src
|
Then, the user agent must act as if it had stopped parsing.
User agents may add content to the 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.
When no more bytes are available, the user agent must queue a global task on the
networking task source given the newly-created Document's
relevant global object to call navigationParams's process response end of body with
navigationParams's response.
When the user agent is to create a document to display a user agent page or PDF viewer inline,
provided a browsing context browsingContext, a navigation ID
navigationId, a NavigationTimingType navTimingType, the
user agent should:
Let navigationParams be a new navigation params with
Let document be the result of creating and initializing a Document
object given "html", "text/html", and
navigationParams.
Either 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.
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.
Once the page has been set up, the user agent must act as if it had stopped parsing.
A Document has a completely loaded time (a time or null), which is
initially null.
A Document is considered completely loaded if its completely
loaded time is non-null.
To completely finish loading a Document document:
Assert: document's browsing context is non-null.
Set document's completely loaded time to the current time.
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 navigable.)
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.
If container is an iframe element, then queue an element
task on the DOM manipulation task source given container to run
the iframe load event steps given container.
Otherwise, if container is non-null, then queue an element task on
the DOM manipulation task source given container to fire an event named load at
container.
A Document has a salvageable state, which must initially be
true, and a page showing flag, which must initially be false. The page
showing flag is used to ensure that scripts receive pageshow and pagehide events
in a consistent manner (e.g. that they never receive two pagehide events in a row without an intervening pageshow, or vice versa).
A Document has a DOMHighResTimeStamp suspension time,
initially 0.
A Document has a list of suspended timer handles,
initially empty.
Event loops have a termination nesting level counter, which must initially be 0.
Document objects have an unload
counter, which is used to ignore certain operations while the below algorithms run.
Initially, the counter must be set to zero.
To unload a Document
oldDocument, given an optional Document newDocument:
Assert: this algorithm is running as part of a task queued on oldDocument's event loop.
Let unloadTimingInfo be a new document unload timing info.
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.
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).
Let eventLoop be oldDocument's relevant agent's event loop.
Increase eventLoop's termination nesting level by 1.
Increase oldDocument's unload counter by 1.
If intendToKeepInBfcache is false, then set oldDocument's salvageable state to false.
If oldDocument's page showing is true:
Set oldDocument's page showing to false.
Fire a page transition event named pagehide at oldDocument's relevant global
object with oldDocument's salvageable state.
Update the visibility state of oldDocument to
"hidden".
If unloadTimingInfo is given, then set unloadTimingInfo's unload event start time to the current high resolution time given oldDocument's relevant global object.
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 given, then set unloadTimingInfo's unload event end time to the current high resolution time given oldDocument's relevant global object.
Decrease eventLoop's termination nesting level by 1.
Set oldDocument's suspension time to the current high resolution time given document's relevant global object.
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 oldDocument that are defined by this specification and other applicable specifications.
If oldDocument's salvageable state is false, then destroy oldDocument.
Decrease oldDocument'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.
Other specifications can define more. Given a Document document:
Let window be document's relevant global object.
For each WebSocket object webSocket whose relevant global
object is window, make disappear webSocket.
If this affected any WebSocket objects, then set document's salvageable state to false.
If document's salvageable state is false, then:
For each EventSource object eventSource whose relevant
global object is equal to window, forcibly close
eventSource.
Clear window's map of active timers.
To destroy a
Document document:
Destroy the active documents of each of document's descendant navigables. In what order?
Set document's salvageable state to false.
Run any unloading document cleanup steps for document that are defined by this specification and other applicable specifications.
Abort document.
Remove any tasks whose document is document from any task queue (without running those tasks).
Set document's browsing context to null.
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 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 queued for them, and discarding any further data received from the network for them. If this resulted in any instances of the fetch algorithm being canceled or any queued tasks or any network data getting discarded, then set document's salvageable state to false.
If document's navigation id is non-null, then:
Invoke WebDriver BiDi navigation aborted with document's browsing context, and new WebDriver BiDi navigation
status whose whose id is
document's navigation id, status is "canceled", and url is
document's URL.
Set document's navigation id to null.
If document has an active parser, then:
Set document's active parser was aborted to true.
Set document's salvageable state to false.
To stop document loading given a Document document:
Let navigable be document's node navigable.
If navigable is null, 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.
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.
User agents may allow users to explicitly invoke the stop document loading for a
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` headerThe `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. [CSP] [RFC7034]
In particular, HTTP Header Field X-Frame-Options specified an `ALLOW-FROM` variant of the header, but that is not to be implemented.
Per the below processing model, if both
a CSP frame-ancestors directive and an
`X-Frame-Options` header are used in the same response, then `X-Frame-Options` is ignored.
For web developers and conformance checkers, its value ABNF is:
X-Frame-Options = "DENY" / "SAMEORIGIN"To check a navigation response's adherence to `X-Frame-Options`, given
navigation params navigationParams, a browsing context
browsingContext, and an origin destinationOrigin:
If browsingContext is not a child browsing context, then return true.
For each policy of navigationParams's policy container's CSP list:
If policy's disposition is not "enforce", then continue.
If policy's directive set contains a frame-ancestors directive, then return true.
Let rawXFrameOptions be the result of getting, decoding, and splitting
`X-Frame-Options` from navigationParams's response's header list.
Let xFrameOptions be a new set.
For each value of rawXFrameOptions, append value, converted to ASCII lowercase, to xFrameOptions.
If xFrameOptions's size is greater than 1, and
xFrameOptions contains any of "deny", "allowall", or "sameorigin", then return false.
The intention here is to block any attempts at applying
`X-Frame-Options` which were trying to do something valid, but appear confused.
This is the only impact of the legacy `ALLOWALL` value
on the processing model.
If xFrameOptions's size is greater than 1, then return true.
This means it contains multiple invalid values, which we treat the same way as if the header was omitted entirely.
If xFrameOptions[0] is "deny", then return
false.
If xFrameOptions[0] is "sameorigin", then:
Let containerDocument be browsingContext's container document.
While containerDocument is not null:
If containerDocument's origin is not same origin with destinationOrigin, then return false.
Let containerBC be containerDocument's browsing context.
Set containerDocument to containerBC's container document, if containerBC is non-null; otherwise, null.
Return true.
If we've reached this point then we have a lone invalid value (which could
potentially be one the legacy `ALLOWALL` or `ALLOW-FROM` forms). These are treated as if the header were omitted
entirely.
The following table illustrates the processing of various values for the header, including non-conformant ones:
`X-Frame-Options` | Valid | Result |
|---|---|---|
`DENY` | ✅ | embedding disallowed |
`SAMEORIGIN` | ✅ | same-origin embedding allowed |
`INVALID` | ❌ | embedding allowed |
`ALLOWALL` | ❌ | embedding allowed |
`ALLOW-FROM=https://example.com/` | ❌ | embedding allowed (from anywhere) |
The following table illustrates how various non-conformant cases involving multiple values are processed:
`X-Frame-Options` | Result |
|---|---|
`SAMEORIGIN, SAMEORIGIN` | same-origin embedding allowed |
`SAMEORIGIN, DENY` | embedding disallowed |
`SAMEORIGIN,` | embedding disallowed |
`SAMEORIGIN, ALLOWALL` | embedding disallowed |
`SAMEORIGIN, INVALID` | embedding disallowed |
`ALLOWALL, INVALID` | embedding disallowed |
`ALLOWALL,` | embedding disallowed |
`INVALID, INVALID` | embedding allowed |
The same results are obtained whether the values are delivered in a single header whose value is comma-delimited, or in multiple headers.
Refresh` headerThe `Refresh` 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.