The internal slot value is updated when navigations occur.

Nested browsing contexts

1. Let list be an empty list.
2. For each child browsing context of d that is nested through an element that is in the Document d, in the tree order of the elements nesting those browsing contexts, run these substeps:
   1. Append that child browsing context to the list list.
   2. Append the list of the descendant browsing contexts of the active document of that child browsing context to the list list.
3. Return the constructed list.

Navigating nested browsing contexts in the DOM

window . top

Returns the WindowProxy for the top-level browsing context.

window . parent

Returns the WindowProxy for the parent browsing context.

window . frameElement

Returns the {{Element}} for the browsing context container. Returns null if there isn't one, and in cross-origin situations.

Auxiliary browsing contexts

Navigating auxiliary browsing contexts in the DOM

Security

• Either the [=concept/origin=] of the active document of A is the same as the [=concept/origin=] of the active document of B, or
• The browsing context A is a nested browsing context with a top-level browsing context, and its top-level browsing context is B, or
• The browsing context B is an auxiliary browsing context and A is familiar with B's opener browsing context, or
• The browsing context B is not a top-level browsing context, but there exists an ancestor browsing context of B whose active document has the same origin as the active document of A (possibly in fact being A itself).

The relationship "familiar with" may be used to decide the value of a browsing context name, see the table in the following browsing context names section for details.

1. If A is not the same browsing context as B, and A is not one of the ancestor browsing contexts of B, and B is not a top-level browsing context, and A's active document's active sandboxing flag set has its sandboxed navigation browsing context flag set, then abort these steps negatively.
2. Otherwise, if B is a top-level browsing context, and is one of the ancestor browsing contexts of A, and A's active document's active sandboxing flag set has its sandboxed top-level navigation browsing context flag set, then abort these steps negatively.
3. Otherwise, if B is a top-level browsing context, and is neither A nor one of the ancestor browsing contexts of A, and A's {{Document}}'s active sandboxing flag set has its sandboxed navigation browsing context flag set, and A is not the one permitted sandboxed navigator of B, then abort these steps negatively.
4. Otherwise, terminate positively!

Groupings of browsing contexts

There is also at most one event loop per unit of related similar-origin browsing contexts (though several units of related similar-origin browsing contexts can have a shared event loop).

Browsing context names

• The task in which the algorithm is running is currently processing an activation behavior whose click event was trusted.
• The task in which the algorithm is running is currently running the event listener for a trusted event whose type is in the following list:
  • change
  • click
  • dblclick
  • mouseup
  • reset
  • submit
• The task in which the algorithm is running was queued by an algorithm that was allowed to show a popup, and the chain of such algorithms started within a user-agent defined timeframe.

  For example, if a user clicked a button, it might be acceptable for a popup to result from that after 4 seconds, but it would likely not be acceptable for a popup to result from that after 4 hours.

1. If name is the empty string or _self, then the chosen browsing context must be the current one.
2. If name is _parent, then the chosen browsing context must be the parent browsing context of the current one, unless there isn't one, in which case the chosen browsing context must be the current browsing context.
3. If name is _top, then the chosen browsing context must be the top-level browsing context of the current one, if there is one, or else the current browsing context.
4. If name is not _blank and there exists a browsing context whose name is the same as name, within the unit of related browsing contexts, then that browsing context must be the chosen one. If there are multiple matching browsing contexts, the user agent should select one in some arbitrary consistent manner, such as the most recently opened, most recently focused, or more closely related.

This non-deterministic approach is likely to change in a future version of HTML.

5. Otherwise, a new browsing context is being requested, and what happens depends on the user agent's configuration and abilities — it is determined by the rules given for the first applicable option from the following list:

   If the algorithm is not allowed to show a popup and the user agent has been configured to not show popups (i.e., the user agent has a "popup blocker" enabled)

   There is no chosen browsing context. The user agent may inform the user that a popup has been blocked.

   If the current browsing context's active document's active sandboxing flag set has the sandboxed auxiliary navigation browsing context flag set.

   Typically, there is no chosen browsing context. The user agent may offer to create a new top-level browsing context or reuse an existing top-level browsing context. If the user picks one of those options, then the designated browsing context must be the chosen one (the browsing context's name isn't set to the given browsing context name). The default behavior (if the user agent doesn't offer the option to the user, or if the user declines to allow a browsing context to be used) must be that there must not be a chosen browsing context.

   If this case occurs, it means that an author has explicitly sandboxed the document that is trying to open a link.

   If the user agent has been configured such that in this instance it will create a new browsing context, and the browsing context is being requested as part of following a hyperlink whose link types include the <{link/noreferrer}> keyword

   A new top-level browsing context must be created. If the given browsing context name is not _blank, then the new top-level browsing context's name must be the given browsing context name (otherwise, it has no name). The chosen browsing context must be this new browsing context. The creation of such a browsing context is a new start for session storage.

   If it is immediately navigated, then the navigation will be done with replacement enabled.

   If the user agent has been configured such that in this instance it will create a new browsing context, and the <{link/noreferrer}> keyword doesn't apply

   A new auxiliary browsing context must be created, with the opener browsing context being the current one. If the given browsing context name is not _blank, then the new auxiliary browsing context's name must be the given browsing context name (otherwise, it has no name). The chosen browsing context must be this new browsing context.

   If it is immediately navigated, then the navigation will be done with replacement enabled.

   If the user agent has been configured such that in this instance it will reuse the current browsing context

   The chosen browsing context is the current browsing context.

   If the user agent has been configured such that in this instance it will not find a browsing context

   There must not be a chosen browsing context.

   User agent implementors are encouraged to provide a way for users to configure the user agent to always reuse the current browsing context.

   If the chosen browsing context picked above, if any, is a new browsing context, then:

   1. Let flagSet be the current browsing context's active document's active sandboxing flag set.

   2. If flagSet's sandboxed navigation browsing context flag is set, then the current browsing context must be set as the new browsing context's one permitted sandboxed navigator.

   3. If flagSet's sandbox propagates to auxiliary browsing contexts flag is set, then all the flags that are set in flagSet must be set in the new browsing context's popup sandboxing flag set.

Script settings for browsing contexts

Security infrastructure for Window, WindowProxy, and {{Location}} objects

Integration with IDL

Shared internal slot: \[[CrossOriginPropertyDescriptorMap]]

The [[CrossOriginPropertyDescriptorMap]] internal slot contains a map with entries whose keys are (currentOrigin, objectOrigin, propertyKey)-tuples and values are property descriptors, as a memoization of what is visible to scripts when currentOrigin inspects a {{Window}} or {{Location}} object from objectOrigin. It is filled lazily by CrossOriginGetOwnPropertyHelper, which consults it on future lookups.

const href = Object.getOwnPropertyDescriptor(crossOriginLocation, "href").set

Shared abstract operations

CrossOriginProperties ( O )

      « {
          [[Property]]: "href",
          [[NeedsGet]]: false,
          [[NeedsSet]]: true
        },
        {
          [[Property]]: "replace"
        } »

      « {
          [[Property]]: "window",
          [[NeedsGet]]: true,
          [[NeedsSet]]: false
        },
        {
          [[Property]]: "self",
          [[NeedsGet]]: true,
          [[NeedsSet]]: false
        },
        {
          [[Property]]: "location",
          [[NeedsGet]]: true,
          [[NeedsSet]]: true
        },
        {
          [[Property]]: "close"
        },
        {
          [[Property]]: "closed",
          [[NeedsGet]]: true,
          [[NeedsSet]]: false
        },
        {
          [[Property]]: "focus"
        },
        {
          [[Property]]: "blur"
        },
        {
          [[Property]]: "frames",
          [[NeedsGet]]: true,
          [[NeedsSet]]: false
        },
        {
          [[Property]]: "length",
          [[NeedsGet]]: true,
          [[NeedsSet]]: false
        },
        {
          [[Property]]: "top",
          [[NeedsGet]]: true,
          [[NeedsSet]]: false
        },
        {
          [[Property]]: "opener",
          [[NeedsGet]]: true,
          [[NeedsSet]]: false
        },
        {
          [[Property]]: "parent",
          [[NeedsGet]]: true,
          [[NeedsSet]]: false
        },
        {
          [[Property]]: "postMessage"
        } »

Indexed properties do not need to be safelisted as they are handled directly by the {{WindowProxy}} object.

IsPlatformObjectSameOrigin ( O )

CrossOriginGetOwnPropertyHelper ( O, P )

If this abstract operation returns undefined and there is no custom behavior, the caller needs to throw a "{{SecurityError}}" {{DOMException}}.

CrossOriginPropertyDescriptor ( crossOriginProperty, originalDesc )

CrossOriginFunctionWrapper ( needsWrapping, functionToWrap )

Due to this being invoked from a different [=concept/origin=], a cross-origin wrapper function will have a different value for Function.prototype from the function being wrapped. This follows from how JavaScript creates anonymous built-in functions.

CrossOriginGet ( O, P, Receiver )

CrossOriginSet ( O, P, V, Receiver )

CrossOriginOwnPropertyKeys ( O )

The Window object

    [PrimaryGlobal, LegacyUnenumerableNamedProperties]
    /*sealed*/ interface Window : EventTarget {
    // the current browsing context
    [Unforgeable] readonly attribute WindowProxy window;
    [Replaceable] readonly attribute WindowProxy self;
    [Unforgeable] readonly attribute Document document;
    attribute DOMString name;
    [PutForwards=href, Unforgeable] readonly attribute Location location;
    readonly attribute History history;
    readonly attribute CustomElementRegistry customElements;
    [Replaceable] readonly attribute BarProp locationbar;
    [Replaceable] readonly attribute BarProp menubar;
    [Replaceable] readonly attribute BarProp personalbar;
    [Replaceable] readonly attribute BarProp scrollbars;
    [Replaceable] readonly attribute BarProp statusbar;
    [Replaceable] readonly attribute BarProp toolbar;
    attribute DOMString status;
    void close();
    readonly attribute boolean closed;
    void stop();
    void focus();
    void blur();

    // other browsing contexts
    [Replaceable] readonly attribute WindowProxy frames;
    [Replaceable] readonly attribute unsigned long length;
    [Unforgeable] readonly attribute WindowProxy top;
    attribute any opener;
    [Replaceable] readonly attribute WindowProxy parent;
    readonly attribute Element? frameElement;
    WindowProxy open(optional DOMString url = "about:blank", optional DOMString target = "_blank", [TreatNullAs=EmptyString] optional DOMString features = "", optional boolean replace = false);
    getter WindowProxy (unsigned long index);
    getter object (DOMString name);
    // Since this is the global object, the IDL named getter adds a NamedPropertiesObject exotic
    // object on the prototype chain. Indeed, this does not make the global object an exotic object.
    // Indexed access is taken care of by the WindowProxy exotic object.

    // the user agent
    readonly attribute Navigator navigator;

    // user prompts
    void alert();
    void alert(DOMString message);
    boolean confirm(optional DOMString message = "");
    DOMString? prompt(optional DOMString message = "", optional DOMString default = "");
    void print();

    unsigned long requestAnimationFrame(FrameRequestCallback callback);
    void cancelAnimationFrame(unsigned long handle);

    void postMessage(any message, USVString targetOrigin, optional sequence<object> transfer = []);
    };
    Window implements GlobalEventHandlers;
    Window implements WindowEventHandlers;

    callback FrameRequestCallback = void (DOMHighResTimeStamp time);
  

window . window

window . frames

window . self

These attributes all return window.

window . document

Returns the {{Document}} associated with window.

document . defaultView

Returns the {{Window}} object of the active document.

The {{Document}} object associated with a Window object can change in exactly one case: when the navigate algorithm initializes a new {{Document}} object for the first page loaded in a browsing context. In that specific case, the {{Window}} object of the original about:blank page is reused and gets a new {{Document}} object.

APIs for creating and navigating browsing contexts by name

window = window . open( [ url [, target [, features [, replace ] ] ] ] )

Opens a window to show url (defaults to about:blank), and returns it. The target argument gives the name of the new window. If a window exists with that name already, it is reused. The replace attribute, if true, means that whatever page is currently open in that window will be removed from the window's session history. The features argument can be used to influence the rendering of the new window.

window . name [ = value ]

Returns the name of the window. Can be set, to change the name.

window . close()

Closes the window.

window . closed

Returns true if the window has been closed, false otherwise.

window . stop()

Cancels the document load.

1. Let entry settings be the entry settings object when the method was invoked.
2. Let url be the first argument.
3. Let target be the second argument.
4. Let features be the third argument.
5. Let replace be the fourth argument.
6. Let source browsing context be the responsible browsing context specified by entry settings.
7. If target is the empty string, let it be the string "_blank" instead.
8. If the user has indicated a preference for which browsing context to navigate, follow these substeps:
   1. Let target browsing context be the browsing context indicated by the user.
   2. If target browsing context is a new top-level browsing context, let the source browsing context be set as target browsing context's one permitted sandboxed navigator.

   For example, suppose there is a user agent that supports control-clicking a link to open it in a new tab. If a user clicks in that user agent on an element whose onclick handler uses the window.open() API to open a page in an iframe, but, while doing so, holds the control key down, the user agent could override the selection of the target browsing context to instead target a new tab.

   Otherwise, apply the rules for choosing a browsing context with the name target source browsing context as the context in which the algorithm is executed. If this does not result in a chosen browsing context, then throw an {{InvalidAccessError}} exception and abort these steps. Otherwise, let target browsing context be the browsing context so obtained.
9. If target browsing context was just created, either as part of the rules for choosing a browsing context given a browsing context name or due to the user indicating a preference for navigating a new top-level browsing context, then let new be true. Otherwise, let it be false.
10. Interpret features as defined in the CSSOM View specification. [[!CSSOM-VIEW]]
11. If url is the empty string, run the appropriate steps from the following list:

    If new is false

    Jump to the step labeled end.

    If new is true

    Let resource be the [=url/URL=] "about:blank".

    Otherwise, parse url relative to entry settings, and let resource be the resulting URL record, if any. If the parse a URL algorithm failed, then run one of the following two steps instead:
    • Let resource be a resource representing an inline error page.
    • If new is false, jump to the step labeled end, otherwise, let resource be the [=url/URL=] "about:blank".
12. If resource is "about:blank" and new is true, queue a task to fire a simple event named load at target browsing context's Window object, with target override set to target browsing context's Window object's {{Document}} object. Otherwise, navigate target browsing context to resource, with the exceptions enabled flag set. If new is true, then replacement must be enabled also. The source browsing context is source browsing context.
13. End:
    1. If the result of splitting |features| on commas contains the token "`noopener`", then disown |target browsing context|'s opener and return null.
    2. Otherwise, return the {{WindowProxy}} object of |target browsing context|.

The name gets reset when the browsing context is navigated to another domain.

• The corresponding browsing context A is script-closable.
• The responsible browsing context specified by the incumbent settings object is familiar with the browsing context A.
• The responsible browsing context specified by the incumbent settings object is allowed to navigate the browsing context A.

Accessing other browsing contexts

window . {{Window/length}}

Returns the number of child browsing contexts.

window[index]

Returns the indicated child browsing context.

Indexed access to child browsing contexts is defined through the \[[GetOwnProperty]] internal method of the {{WindowProxy}} object.

Named access on the Window object

window[name]

Returns the indicated element or collection of elements. As a general rule, relying on this will lead to brittle code. Which IDs end up mapping to this API can vary over time, as new features are added to the Web platform, for example. Instead of this, use {{NonElementParentNode/getElementById()|document.getElementById()}} or document.querySelector().

1. Let objects be the list of named objects with the name name in the active document.

   There will be at least one such object, by definition.

2. If objects contains a nested browsing context, then return the WindowProxy object of the nested browsing context corresponding to the first browsing context container in tree order whose browsing context is in objects, and abort these steps.
3. Otherwise, if objects has only one element, return that element and abort these steps.
4. Otherwise return an HTMLCollection rooted at the {{Document}} node, whose filter matches only named objects with the name name. (By definition, these will all be elements.)

• child browsing contexts of the active document whose name is name,
• <{a}>, <{area}>, <{embed}>, <{form}>, <{frameset}>, <{img}>, or <{object}> elements that have a name content attribute whose value is name, or
• HTML elements that have an <{global/id}> content attribute whose value is name and are in a document tree with the active document as their root.

Garbage collection and browsing contexts

A Window object has a strong reference to its {{Document}} object through its document attribute. Thus, references from other scripts to either of those objects will keep both alive. Similarly, both {{Document}} and Window objects have implied strong references to the WindowProxy object.

1. Set the {{Document}}'s salvageable state to false.
2. Run any unloading document cleanup steps for the {{Document}} that are defined by this specification and [=other applicable specifications=].
3. Abort the Document.
4. Remove any tasks associated with the {{Document}} in any task source, without running those tasks.
5. Discard all the child browsing contexts of the {{Document}}.
6. Lose the strong reference from the {{Document}}'s browsing context to the {{Document}}.

Whenever a {{Document}} object is discarded, it is also removed from the list of the worker's Documents of each worker whose list contains that {{Document}}.

Closing browsing contexts

1. Let specified browsing context be the browsing context being closed.
2. Prompt to unload the active document of the specified browsing context. If the user refused to allow the document to be unloaded, then abort these steps.
3. Unload the active document of the specified browsing context with the recycle parameter set to false.
4. Remove the specified browsing context from the user interface (e.g., close or hide its tab in a tabbed browser).
5. Discard the specified browsing context.

Browser interface elements

    interface BarProp {
      readonly attribute boolean visible;
    };
  

window . locationbar . visible

Returns true if the location bar is visible; otherwise, returns false.

window . menubar . visible

Returns true if the menu bar is visible; otherwise, returns false.

window . personalbar . visible

Returns true if the personal bar is visible; otherwise, returns false.

window . scrollbars . visible

Returns true if the scroll bars are visible; otherwise, returns false.

window . statusbar . visible

Returns true if the status bar is visible; otherwise, returns false.

window . toolbar . visible

Returns true if the toolbar is visible; otherwise, returns false.

The location bar BarProp object

Represents the user interface element that contains a control that displays the [=url/URL=] of the active document, or some similar interface concept.

The menu bar BarProp object

Represents the user interface element that contains a list of commands in menu form, or some similar interface concept.

The personal bar BarProp object

Represents the user interface element that contains links to the user's favorite pages, or some similar interface concept.

The scrollbar BarProp object

Represents the user interface element that contains a scrolling mechanism, or some similar interface concept.

The status bar BarProp object

Represents a user interface element found immediately below or after the document, as appropriate for the user's media, which typically provides information about ongoing network activity or information about elements that the user's pointing device is current indicating. If the user agent has no such user interface element, then the object may act as if the corresponding user interface element was absent (i.e., its visible attribute may return false).

The toolbar BarProp object

Represents the user interface element found immediately above or before the document, as appropriate for the user's media, which typically provides session history traversal controls (back and forward buttons, reload buttons, etc). If the user agent has no such user interface element, then the object may act as if the corresponding user interface element was absent (i.e., its visible attribute may return false).

The WindowProxy object

Although {{WindowProxy}} is named as a "proxy", it does not do polymorphic dispatch on its target's internal methods as a real proxy would, due to a desire to reuse machinery between {{WindowProxy}} and {{Location}} objects. As long as the {{Window}} object remains an ordinary object this is unobservable and can be implemented either way.

      var x = window;
      x instanceof Window; // true
      x === this; // true
    

The WindowProxy internal methods

[[GetPrototypeOf]] ( )

[[SetPrototypeOf]] ( V )

[[IsExtensible]] ( )

[[PreventExtensions]] ( )

[[GetOwnProperty]] ( P )

This violates JavaScript's internal method invariants.

[[DefineOwnProperty]] ( P, Desc )

See above about how this violates JavaScript's internal method invariants.

[[Get]] ( P, Receiver )

[[Set]] ( P, V, Receiver )

[[Delete]] ( P )

[[OwnPropertyKeys]] ( )

Origin

For example, if Example Bank's Web site, hosted at bank.example.com, tries to examine the DOM of Example Charity's Web site, hosted at charity.example.org, a "{{SecurityError}}" {{DOMException}} will be raised.

Origins can be shared, e.g., among multiple {{Document}} objects. Furthermore, origins are generally immutable. Only the domain of a tuple origin can be changed, and only through the {{Document/domain|document.domain}} API.

If the {{Document}}'s active sandboxing flag set has its sandboxed origin browsing context flag set or the {{Document}} was generated from a data: URL

A unique opaque origin is assigned when the {{Document}} is created.

If the {{Document}}'s [=url/URL=]'s [=url/scheme=] is a network scheme

A copy of the {{Document}}'s [=url/URL=]'s origin assigned when the {{Document}} is created.

The {{Document/open()|document.open(type, replace)}} method can change the {{Document}}'s [=url/URL=] to "about:blank". Therefore the [=concept/origin=] is assigned when the {{Document}} is created.

If the {{Document}} is the initial "about:blank" document

The one it was assigned when its browsing context was created.

If the {{Document}} is a non-initial "about:blank" document

The [=concept/origin=] of the incumbent settings object when the navigate algorithm was invoked, or, if no [=concept/script=] was involved, of the node document of the element that initiated the navigation to that [=url/URL=].

If the {{Document}} was created as part of the processing for javascript: URLs

The [=concept/origin=] of the active document of the browsing context being navigated when the navigate algorithm was invoked.

If the {{Document}} is an `iframe` `srcdoc` document

The [=concept/origin=] of the {{Document}}'s browsing context's browsing context container's node document.

If the {{Document}} was obtained in some other manner (e.g., a {{Document}} created using the {{DOMImplementation/createDocument()}} API, etc)

The default behavior as defined in the DOM specification applies. [[!DOM]].

The [=concept/origin=] is a unique opaque origin assigned when the {{Document}} is created.

If the image data is CORS-cross-origin

A unique opaque origin assigned when the image is created.

If the image data is CORS-same-origin

The <{img}> element's node document's [=concept/origin=].

If the media data is CORS-cross-origin

A unique opaque origin assigned when the media data is fetched.

If the media data is CORS-same-origin

The media element's node document's [=concept/origin=].

The name ASCII serialization of an origin is misleading, as it merely serialises an origin, which are all ASCII by default due to the URL parser.

Relaxing the same-origin restriction

document . {{Document/domain}} [ = domain ]

Returns the current domain used for security checks. Can be set to a value that removes subdomains, to change the [=concept/origin=]'s domain to allow pages on other subdomains of the same domain (if they do the same thing) to access each other. (Can't be set in sandboxed <{iframe}>s.)

I.e exclude IPv4 and IPv6 addresses as hosts.

Suffixes must be compared after applying the host parser algorithm.

The {{Document/domain|document.domain}} attribute is used to enable pages on different hosts of a domain to access each others' DOMs.

Do not use the {{Document/domain|document.domain}} attribute when using shared hosting. If an untrusted third party is able to host an HTTP server at the same IP address but on a different port, then the same-origin protection that normally protects two different sites on the same host will fail, as the ports are ignored when comparing origins after the {{Document/domain|document.domain}} attribute has been used.

Sandboxing

The sandboxed navigation browsing context flag

This flag prevents content from navigating browsing contexts other than the sandboxed browsing context itself (or browsing contexts further nested inside it), auxiliary browsing contexts (which are protected by the sandboxed auxiliary navigation browsing context flag defined next), and the top-level browsing context (which is protected by the sandboxed top-level navigation browsing context flag defined below). If the sandboxed auxiliary navigation browsing context flag is not set, then in certain cases the restrictions nonetheless allow popups (new top-level browsing contexts) to be opened. These browsing contexts always have one permitted sandboxed navigator, set when the browsing context is created, which allows the browsing context that created them to actually navigate them. (Otherwise, the sandboxed navigation browsing context flag would prevent them from being navigated even if they were opened.)

The sandboxed auxiliary navigation browsing context flag

This flag prevents content from creating new auxiliary browsing contexts, e.g., using the target attribute, the window.open() method.

The sandboxed top-level navigation browsing context flag

This flag prevents content from navigating their top-level browsing context and prevents content from closing their top-level browsing context. When the sandboxed top-level navigation browsing context flag is not set, content can navigate its top-level browsing context, but other browsing contexts are still protected by the sandboxed navigation browsing context flag and possibly the sandboxed auxiliary navigation browsing context flag.

The sandboxed plugins browsing context flag

This flag prevents content from instantiating plugins, whether using the <{embed}> element, the <{object}> element, or through navigation of a nested browsing context, unless those plugins can be secured.

The sandboxed origin browsing context flag

This flag forces content into a unique origin, thus preventing it from accessing other content from the same [=concept/origin=]. This flag also prevents script from reading from or writing to the document.cookie IDL attribute, and blocks access to localStorage. [[!WEBSTORAGE]]

The sandboxed forms browsing context flag

This flag blocks form submission.

The sandboxed pointer lock browsing context flag

This flag disables the Pointer Lock API. [[!POINTERLOCK]]

The sandboxed scripts browsing context flag

This flag blocks script execution.

The sandboxed automatic features browsing context flag

This flag blocks features that trigger automatically, such as automatically playing a video or automatically focusing a form control.

The sandboxed storage area URLs flag

This flag prevents URL schemes that use storage areas from being able to access the origin's data.

The sandboxed fullscreen browsing context flag

This flag prevents content from using the requestFullscreen() method.

The sandboxed document.domain browsing context flag

This flag prevents content from using the {{Document/domain|document.domain}} setter.

The sandbox propagates to auxiliary browsing contexts flag

This flag prevents content from escaping the sandbox by ensuring that any auxiliary browsing context it creates inherits the content's active sandboxing flag set.

The sandboxed modals flag

This flag prevents content from using any of the following features to produce modal dialogs:

• window.alert()
• window.confirm()
• window.print()
• window.prompt()
• the beforeunload event

The sandboxed orientation lock browsing context flag

This flag blocks the ability to lock screen orientation. [[!SCREEN-ORIENTATION]]

The sandboxed presentation browsing context flag

This flag disables the Presentation API. [[!PRESENTATION-API]]

1. Split input on spaces, to obtain tokens.
2. Let output be empty.
3. Add the following flags to output:
   • The sandboxed navigation browsing context flag.
   • The sandboxed auxiliary navigation browsing context flag, unless tokens contains the allow-popups keyword.
   • The sandboxed top-level navigation browsing context flag, unless tokens contains the allow-top-navigation keyword.
   • The sandboxed plugins browsing context flag.
   • The sandboxed origin browsing context flag, unless the tokens contains the allow-same-origin keyword.
     The allow-same-origin keyword is intended for two cases. First, it can be used to allow content from the same site to be sandboxed to disable scripting, while still allowing access to the DOM of the sandboxed content. Second, it can be used to embed content from a third-party site, sandboxed to prevent that site from opening pop-up windows, etc, without preventing the embedded page from communicating back to its originating site, using the database APIs to store data, etc.
   • The sandboxed forms browsing context flag, unless tokens contains the allow-forms keyword.
   • The sandboxed pointer lock browsing context flag, unless tokens contains the allow-pointer-lock keyword.
   • The sandboxed scripts browsing context flag, unless tokens contains the allow-scripts keyword.
   • The sandboxed automatic features browsing context flag, unless tokens contains the allow-scripts keyword (defined above).

     This flag is relaxed by the same keyword as scripts, because when scripts are enabled these features are trivially possible anyway, and it would be unfortunate to force authors to use script to do them, when sandboxed, rather than allowing them to use the declarative features.

   • The sandboxed storage area URLs flag.
   • The sandboxed fullscreen browsing context flag, unless the allow fullscreen flag was passed to the parse a sandboxing directive flag.
   • The sandboxed document.domain browsing context flag.
   • The sandbox propagates to auxiliary browsing contexts flag, unless tokens contains the allow-popups-to-escape-sandbox keyword.
   • The sandboxed modals flag, unless tokens contains the allow-modals keyword.
   • The sandboxed presentation browsing context flag, unless tokens contains the allow-presentation keyword.

     There is only one known native implementation of the allow-presentation token (Chrome/Blink). Therefore this feature should not be relied upon until it becomes interoperable.

   • The sandboxed orientation lock browsing context flag, unless tokens contains the allow-orientation-lock keyword.

In particular, the forced sandboxing flag set is used by the Content Security Policy specification. [[!CSP3]]

• If the {{Document}}'s browsing context is a top-level browsing context, then: the flags set on the browsing context's popup sandboxing flag set.
• If the {{Document}}'s browsing context is a nested browsing context, then: the flags set on the browsing context's iframe sandboxing flag set.
• If the {{Document}}'s browsing context is a nested browsing context, then: the flags set on the browsing context's parent browsing context's active document's active sandboxing flag set.
• The flags set on the {{Document}}'s resource's forced sandboxing flag set, if it has one.

Session history and navigation

The session history of browsing contexts

Each entry, when first created, has a {{Document}}. However, when a {{Document}} is not active, it's possible for it to be discarded to free resources. The [=url/URL=] and other data in a session history entry is then used to bring a new {{Document}} into being to take the place of the original, should the user agent find itself having to reactivate that {{Document}}.

Titles associated with session history entries need not have any relation with the current <{title}> of the {{Document}}. The title of a session history entry is intended to explain the state of the document at that point, so that the user can navigate the document's history.

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.

The current entry is usually an entry for the [=Document/URL=] of the {{Document}}. However, it can also be one of the entries for serialized state added to the history by that document.

For example, some user agents might want to persist the scroll position, or 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 <{global/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.

"auto"

The user agent is responsible for restoring the scroll position upon navigation.

"manual"

The page is responsible for restoring the scroll position and the user agent does not attempt to do so automatically

All entries that share the same {{Document}} (and that are therefore merely different states of one particular document) are contiguous by definition.

The History interface

    enum ScrollRestoration { "auto", "manual" };
  

    interface History {
      readonly attribute unsigned long length;
      attribute ScrollRestoration scrollRestoration;
      readonly attribute any state;
      void go(optional long delta = 0);
      void back();
      void forward();
      void pushState(any data, DOMString title, optional DOMString? url = null);
      void replaceState(any data, DOMString title, optional DOMString? url = null);
    };
  

window . history . length

Returns the number of entries in the joint session history.

window . history . scrollRestoration [ = value ]

Returns the scroll restoration mode of the current entry in the session history. Can be set, to change the scroll restoration mode of the current entry in the session history.

window . history . state

Returns the current serialized state, deserialized into an object.

window . history . go( [ delta ] )

Goes back or forward the specified number of steps in the joint session history. A zero delta will reload the current page. If the delta is out of range, does nothing.

window . history . back()

Goes back one step in the joint session history. If there is no previous page, does nothing.

window . history . forward()

Goes forward one step in the joint session history. If there is no next page, does nothing.

window . history . pushState(data, title [, url ] )

Pushes the given data onto the session history, with the given title, and, if provided and not null, the given URL.

window . history . replaceState(data, title [, url ] )

Updates the current entry in the session history to have the given data, title, and, if provided and not null, URL.

Since each {{Document}} in a browsing context might have a different event loop, the actual state of the joint session history can be somewhat nebulous. For example, two sibling <{iframe}> elements could both traverse from one unique origin to another at the same time, so their precise order might not be well-defined; similarly, since they might only find out about each other later, they might disagree about the length of the joint session history.

1. Wait until this top-level browsing context's session history traversal queue is not empty.
2. Pull the first task from this top-level browsing context's session history traversal queue, and execute it.
3. Return to the first step of this algorithm.

1. If the index of the current entry of the joint session history plus delta is less than zero or greater than or equal to the number of items in the joint session history, then abort these steps.
2. Let specified entry be the entry in the joint session history whose index is the sum of delta and the index of the current entry of the joint session history.
3. Let specified browsing context be the browsing context of the specified entry.
4. If the specified browsing context's active document's unload a document algorithm is currently running, abort these steps.
5. Queue a task that consists of running the following substeps. The relevant event loop is that of the specified browsing context's active document. The task source for the queued task is the history traversal task source.
   1. If there is an ongoing attempt to navigate specified browsing context that has not yet matured (i.e., it has not passed the point of making its {{Document}} the active document), then cancel that attempt to navigate the browsing context.
   2. If the specified browsing context's active document is not the same {{Document}} as the {{Document}} of the specified entry, then run these substeps:
      1. Prompt to unload the active document of the specified browsing context. If the user refused to allow the document to be unloaded, then abort these steps.
      2. Unload the active document of the specified browsing context with the recycle parameter set to false.
   3. Traverse the history of the specified browsing context to the specified entry.

This doesn't necessarily have to affect the user agent's user interface.

Since this is neither a navigation of the browsing context nor a history traversal, it does not cause a hashchange event to be fired.

The title is purely advisory. User agents might use the title in the user interface.

Implementation notes for session history

The Location interface

document . {{Document/location}} [ = value ]

window . {{Window/location}} [ = value ]

Returns a {{Location}} object with the current page's location. Can be set, to navigate to another page.

    interface Location {
      [Unforgeable] stringifier attribute USVString href;
      [Unforgeable] readonly attribute USVString origin;
      [Unforgeable] attribute USVString protocol;
      [Unforgeable] attribute USVString host;
      [Unforgeable] attribute USVString hostname;
      [Unforgeable] attribute USVString port;
      [Unforgeable] attribute USVString pathname;
      [Unforgeable] attribute USVString search;
      [Unforgeable] attribute USVString hash;

      [Unforgeable] void assign(USVString url);
      [Unforgeable] void replace(USVString url);
      [Unforgeable] void reload();

      [Unforgeable, SameObject] readonly attribute USVString[] ancestorOrigins;
    };
  

location . toString()

location . {{Location/href}}

Returns the {{Location}} object's URL. Can be set, to navigate to the given URL.

location . {{Location/origin}}

Returns the {{Location}} object's URL's origin.

location . {{Location/protocol}}

Returns the {{Location}} object's URL's scheme. Can be set, to navigate to the same URL with a changed scheme.

location . {{Location/host}}

Returns the {{Location}} object's URL's host and port (if different from the default port for the scheme). Can be set, to navigate to the same URL with a changed host and port.

location . {{Location/hostname}}

Returns the {{Location}} object's URL's host. Can be set, to navigate to the same URL with a changed host.

location . {{Location/port}}

Returns the {{Location}} object's URL's port. Can be set, to navigate to the same URL with a changed port.

location . {{Location/pathname}}

Returns the {{Location}} object's URL's path. Can be set, to navigate to the same URL with a changed path.

location . {{Location/search}}

Returns the {{Location}} object's URL's query (includes leading "?" if non-empty). Can be set, to navigate to the same URL with a changed query (ignores leading "?").

location . {{Location/hash}}

Returns the {{Location}} object's URL's fragment (includes leading "#" if non-empty). Can be set, to navigate to the same URL with a changed fragment (ignores leading "#").

location . {{Location/assign()|assign}}(url)

Navigates to the given URL.

location . {{Location/replace()|replace}}(url)

Removes the current page from the session history and navigates to the given URL.

location . {{Location/reload()}}

Reloads the current page.

location . {{Location/ancestorOrigins}}

Returns an array whose values are the origins of the ancestor browsing contexts, from the parent browsing context to the top-level browsing context.

The {{Location/href}} attribute setter intentionally has no security check.

It returns the Unicode rather than the ASCII serialization for compatibility with MessageEvent.

Unlike the equivalent API for the <{a}> and <{area}> elements, the {{Location/hash}} attribute's setter does not special case the empty string to remain compatible with deployed scripts.

The {{Location/replace()}} method intentionally has no security check.

If this {{Location}} object's relevant Document's [=concept/origin=] is not same origin with entry settings object's [=concept/origin=]

Throw a "{{SecurityError}}" {{DOMException}}.

If the currently executing task is the dispatch of a resize event in response to the user resizing the browsing context

Repaint the browsing context and abort these steps.

If the browsing context's active document is an `iframe` `srcdoc` document

Reprocess the iframe attributes of the browsing context's browsing context container.

If the browsing context's active document has its reload override flag set

Perform an overridden reload, with the browsing context being navigated as the responsible browsing context.

Otherwise

Navigate the browsing context to the document's [=document url|URL=] with the exceptions enabled flag set and replacement enabled. The source browsing context must be the browsing context being navigated. This is a reload-triggered navigation. Rethrow any exceptions.

The Location internal methods

[[GetPrototypeOf]] ( )

[[SetPrototypeOf]] ( V )

[[IsExtensible]] ( )

[[PreventExtensions]] ( )

[[GetOwnProperty]] ( P )

[[DefineOwnProperty]] ( P, Desc )

[[Get]] ( P, Receiver )

[[Set]] ( P, V, Receiver )

[[Delete]] ( P )

[[OwnPropertyKeys]] ( )

Browsing the Web

Navigating across documents

For example, following a hyperlink, [[#forms-form-submission]], and the window.open() and location.assign() methods can all cause a browsing context to navigate.

A resource has a URL, but that might not be the only information necessary to identify it. For example, a form submission that uses HTTP POST would also have the HTTP method and payload. Similarly, an `iframe` `srcdoc` document needs to know the data it is to use.

1. If the source browsing context is not allowed to navigate the browsing context being navigated, then abort these steps. If these steps are aborted here, the user agent may instead offer to open the new resource in a new top-level browsing context or in the top-level browsing context of the source browsing context, at the user's option, in which case the user agent must navigate that designated top-level browsing context to the new resource as if the user had requested it independently.

   Doing so, however, can be dangerous, as it means that the user is overriding the author's explicit request to sandbox the content.

   If the navigate algorithm was invoked optionally with an exceptions enabled flag, and it is aborted on this step, then in addition to aborting this algorithm, the user agent must also throw a "{{SecurityError}}" {{DOMException}}.
2. If there is a preexisting attempt to navigate the browsing context, and the source browsing context is the same as the browsing context being navigated, and that attempt is currently running the unload a document algorithm, and the [=concept/origin=] of the [=url/URL=] of the resource being loaded in that navigation is not the same origin as the [=concept/origin=] of the [=url/URL=] of the resource being loaded in this navigation, then abort these steps without affecting the preexisting attempt to navigate the browsing context.
3. If a task queued by the traverse the history by a delta algorithm is running the unload a document algorithm for the active document of the browsing context being navigated, then abort these steps without affecting the unload a document algorithm or the aforementioned history traversal task.
4. If the prompt to unload a document algorithm is being run for the active document of the browsing context being navigated, then abort these steps without affecting the prompt to unload a document algorithm.
5. Let gone async be false.

   The handle redirects step later in this algorithm can in certain cases jump back to the step labeled Fragments. Since, between those two steps, this algorithm goes from operating immediately in the context of the calling task to operating in parallel independent of the event loop, some of the intervening steps need to be able to handle both being run as part of a task and running in parallel. The gone async flag is thus used to make these steps aware of which mode they are operating in.

6. Fragments: If this is not a reload-triggered navigation: apply the URL parser algorithm to the absolute URL of the new resource and the [=Document/URL=] of the active document of the browsing context being navigated; if all the components of the resulting parsed URLs, ignoring any fragment components, are identical, and the new resource is to be fetched using GET, and the URL record of the new resource has a fragment component that is not null (even if it is empty), then navigate to that fragment and abort these steps.
7. If gone async is false, cancel any preexisting but not yet mature attempt to navigate the browsing context, including canceling any instances of the fetch algorithm started by those attempts. If one of those attempts has already created and initialized a new {{Document}} object, abort that {{Document}} also. (Navigation attempts that have matured already have session history entries, and are therefore handled during the update the session history with the new page algorithm, later.)
8. If the new resource is to be handled using a mechanism that does not affect the browsing context, e.g., ignoring the navigation request altogether because the specified scheme is not one of the supported protocols, then abort these steps and proceed with that mechanism instead.
9. If gone async is false, prompt to unload the {{Document}} object. If the user refused to allow the document to be unloaded, then abort these steps. If this instance of the navigation algorithm gets canceled while this step is running, the prompt to unload a document algorithm must nonetheless be run to completion.
10. If gone async is false, abort the active document of the browsing context.
11. If the new resource is to be handled by displaying some sort of inline content, e.g., an error message because the specified scheme is not one of the supported protocols, or an inline prompt to allow the user to select a registered handler for the given scheme, then display the inline content and abort these steps.

    In the case of a registered handler being used, the algorithm will be reinvoked with a new URL to handle the request.

12. If the browsing context being navigated is a nested browsing context, then put it in the delaying load events mode. The user agent must take this nested browsing context out of the delaying load events mode when this navigation algorithm later matures, or when it terminates (whether due to having run all the steps, or being canceled, or being aborted), whichever happens first.
13. This is the step that attempts to obtain the resource, if necessary. Jump to the first appropriate substep:

    If the resource has already been obtained (e.g., because it is being used to populate an <{object}> element's new child browsing context)

    Skip this step. The data is already available.

    If the new resource is a [=url/URL=] whose [=url/scheme=] is javascript

    Queue a task to run these "javascript: URL" steps, associated with the active document of the browsing context being navigated: 1. If the [=concept/origin=] of the source browsing context is not the same origin as the [=concept/origin=] of the active document of the browsing context being navigated, then let result be undefined, and jump to the step labeled process results below. 2. Let urlRecord be the result of running the URL parser on the [=url/URL=] of the new resource. 3. Let script source be the empty string. 4. Append the first string of urlRecord's path component to script source. 5. If urlRecord's query component is not null, then first append a U+003F QUESTION MARK character (?) to script source, and then append urlRecord's query component to script source. 6. If urlRecord's fragment component is not null, then first append a U+0023 NUMBER SIGN character (#) to script source, and then append urlRecord's fragment component to script source. 7. Replace script source with the result of applying the percent decode algorithm to script source. 8. Replace script source with the result of applying the UTF-8 decode algorithm to script source. 9. Let address be the [=Document/URL=] of the active document of the browsing context being navigated. 10. Let settings be the relevant settings object of the browsing context being navigated. 11. Let script be the result of creating a classic script given script source and settings. 12. Let result be the result of running the classic script script. If evaluation was unsuccessful, let result be undefined instead. (The result will also be undefined if scripting is disabled.) 13. Process results: If Type(result) is not String, then the result of obtaining the resource for the URL is a response whose status is 204. Otherwise, the result of obtaining the resource for the URL is a response whose [=response/header list=] consists of Content-Type/[[#text-html|text/html]] and whose [=response/body=] is result, and whose [=response/HTTPS state=] is settings's HTTPS state. When it comes time to set the document's address in the navigation algorithm, use address as the override URL. The task source for this task is the DOM manipulation task source.

    So for example a javascript: URL in an <{links/href}> attribute of an <{a}> element would only be evaluated when the link was followed, while such a URL in the <{iframe/src}> attribute of an <{iframe}> element would be evaluated in the context of the iframe's own nested browsing context when the iframe is being set up; once evaluated, its return value (if it was not void) would replace that browsing context's {{Document}}, thus also changing the Window object of that browsing context.

    Otherwise

    1. Let request be the new resource.
    2. If request is a URL, set request to a new request whose [=url/URL=] is request.
    3. Set request's client to the source browsing context's active document's Window object's environment settings object, target browsing context to the browsing context being navigated, destination to "document", mode to "navigate", credentials mode to "include", use-URL-credentials flag, and redirect mode to "manual".
    4. Set request's omit-Origin-header flag.
    5. If request's method is not GET, or, if the navigation algorithm was invoked as a result of the form submission algorithm, then if there is an [=concept/origin=] of the active document of the source browsing context, unset request's omit-Origin-header flag.
    6. Otherwise, if the browsing context being navigated is a child browsing context, and the browsing context container of the browsing context being navigated has a browsing context scope origin, set request's origin to that browsing context scope origin and unset request's omit-Origin-header flag.
    7. Fetch request.

14. If gone async is false, return to whatever algorithm invoked the navigation steps and continue running these steps in parallel.
15. Let gone async be true.
16. Wait for one or more bytes to be available or for the user agent to establish that the resource in question is empty. During this time, the user agent may allow the user to cancel this navigation attempt or start other navigation attempts.
17. Handle redirects: If fetching the resource results in a redirect, and either the [=url/URL=] of the target of the redirect has the same origin as the original resource, or the resource is being obtained using the POST method or a safe method (in HTTP terms), return to the step labeled Fragments with the new resource, except that if the [=url/URL=] of the target of the redirect does not have a fragment and the [=url/URL=] of the resource that led to the redirect does, then the fragment of the resource that led to the redirect must be propagated to the [=url/URL=] of the target of the redirect.

    So for instance, if the original URL was "https://example.com/#!sample" and "https://example.com/" is found to redirect to "https://example.com/", the URL of the new resource will be "https://example.com/#!sample".

    Otherwise, if fetching the resource results in a redirect but the [=url/URL=] of the target of the redirect does not have the same origin as the original resource and the resource is being obtained using a method that is neither the POST method nor a safe method (in HTTP terms), then abort these steps. The user agent may indicate to the user that the navigation has been aborted for security reasons.
18. Resource handling: If the resource's out-of-band metadata (e.g., HTTP headers), not counting any type information (such as the Content-Type HTTP header), requires some sort of processing that will not affect the browsing context, then perform that processing and abort these steps.
    Such processing might be triggered by, amongst other things, the following:

    • HTTP status codes (e.g., 204 No Content or 205 Reset Content)
    • Network errors (e.g., the network interface being unavailable)
    • Cryptographic protocol failures (e.g., an incorrect TLS certificate)
    Responses with HTTP Content-Disposition headers specifying the attachment disposition type must be handled as a download. HTTP 401 responses that do not include a challenge recognized by the user agent must be processed as if they had no challenge, e.g., rendering the entity body as if the response had been 200 OK. User agents may show the entity body of an HTTP 401 response even when the response does include a recognized challenge, with the option to login being included in a non-modal fashion, to enable the information provided by the server to be used by the user before authenticating. Similarly, user agents should allow the user to authenticate (in a non-modal fashion) against authentication challenges included in other responses such as HTTP 200 OK responses, effectively allowing resources to present HTTP login forms without requiring their use.
19. Let type be the computed type of the resource.
20. If the user agent has been configured to process resources of the given type using some mechanism other than rendering the content in a browsing context, then skip this step. Otherwise, if the type is one of the following types, jump to the appropriate entry in the following list, and process the resource as described there:

    an HTML MIME type

    Follow the steps given in the HTML document section, and then, once they have completed, abort this navigate algorithm.

    an XML MIME type that is not an explicitly supported XML type

    Follow the steps given in the XML document section. If that section determines that the content is not to be displayed as a generic XML document, then proceed to the next step in this overall set of steps. Otherwise, once the steps given in the XML document section have completed, abort this navigate algorithm.

    a JavaScript MIME type

    a JSON MIME type that is not an explicitly supported JSON type

    "text/css"

    "text/plain"

    "text/vtt"

    Follow the steps given in the plain text file section, and then, once they have completed, abort this navigate algorithm.

    "multipart/x-mixed-replace"

    Follow the steps given in the [[#multipart-x-mixed-replace]] section, and then, once they have completed, abort this navigate algorithm.

    A supported image, video, or audio type

    Follow the steps given in the media section, and then, once they have completed, abort this navigate algorithm.

    A type that will use an external application to render the content in the browsing context

    Follow the steps given in the plugin section, and then, once they have completed, abort this navigate algorithm.

    An explicitly supported XML type is one for which the user agent is configured to use an external application to render the content (either a plugin rendering directly in the browsing context, or a separate application), or one for which the user agent has dedicated processing rules (e.g., a Web browser with a built-in Atom feed viewer would be said to explicitly support the application/atom+xml MIME type), or one for which the user agent has a dedicated handler. The term JSON MIME type is used to refer to the MIME types application/json, text/json, and any MIME type whose subtype ends with the five characters "+json". An explicitly supported JSON type is one for which the user agent is configured to use an external application to render the content (either a plugin rendering directly in the browsing context, or a separate application), or one for which the user agent has dedicated processing rules, or one for which the user agent has a dedicated handler. Setting the document's address: If there is no override URL, then any {{Document}} created by these steps must have its [=Document/URL=] set to the [=url/URL=] that was originally to be fetched, ignoring any other data that was used to obtain the resource. However, if there is an override URL, then any {{Document}} created by these steps must have its [=Document/URL=] set to that [=url/URL=] instead.

    An override URL is set when dereferencing a javascript: URL and when performing an overridden reload.

    Initializing a new Document object: when a {{Document}} is created as part of the above steps, the user agent will be required to additionally run the following algorithm after creating the new object: 1. If browsingContext's only entry in its session history is the about:blank {{Document}} that was added when browsingContext was created, and navigation is occurring with replacement enabled, and that {{Document}} has the same origin as the new {{Document}}, then 1. Let window be the {{Window}} object of that {{Document}}. 2. Change the {{Window/document}} attribute of window to point to the new {{Document}}. 2. Otherwise, 1. Call the JavaScript InitializeHostDefinedRealm() abstract operation with the following customizations: * For the global object, create a new {{Window}} object window. * For the global this value, use browsingContext's {{WindowProxy}} object. * Let realm execution context be the created JavaScript execution context. * Do not obtain any source texts for scripts or modules. 2. Set up a browsing context environment settings object with realm execution context, and let settings object be the result. 3. Set window's associated Document to the new {{Document}}. 3. Set browsingContext's {{WindowProxy}} object's \[[Window]] internal slot value to window. 4. Set the {{Document}}'s HTTPS state to the [=response/HTTPS state=] of the resource used to generate the document. 5. Set the {{Document}}'s referrer policy to the result of parsing the Referrer-Policy header of the response used to generate the document. [[!REFERRERPOLICY]] 6. Execute the Initialize a Document's CSP list algorithm on the {{Document}} object and the resource used to generate the document. [[CSP3]] 7. Set [=the document's referrer=] to the address of the resource from which Request-URIs are obtained as determined when the fetch algorithm obtained the resource, if that algorithm was used and determined such a value; otherwise, set it to the empty string. 8. Implement the sandboxing for the {{Document}}. 9. If the active sandboxing flag set of the {{Document}}'s browsing context or any of its ancestor browsing contexts (if any) have the sandboxed fullscreen browsing context flag set, then skip this step. If the {{Document}}'s browsing context has a browsing context container and either it is not an <{iframe}> element, or it does not have the <{iframe/allowfullscreen}> attribute specified, or its {{Document}} does not have the fullscreen enabled flag set, then also skip this step. Otherwise, set the {{Document}}'s fullscreen enabled flag.
21. Non-document content: If, given type, the new resource is to be handled by displaying some sort of inline content, e.g., a native rendering of the content, an error message because the specified type is not supported, or an inline prompt to allow the user to select a registered handler for the given type, then display the inline content, and then abort these steps.

    In the case of a registered handler being used, the algorithm will be reinvoked with a new URL to handle the request.

22. Otherwise, the document's type is such that the resource will not affect the 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. Process the resource appropriately.

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.

1. Unload the {{Document}} object of the current entry, with the recycle parameter set to false. If this instance of the navigation algorithm is canceled while this step is running the unload a document algorithm, then the unload a document algorithm must be allowed to run to completion, but this instance of the navigation algorithm must not run beyond this step. (In particular, for instance, the cancelation of this algorithm does not abort any event dispatch or script execution occurring as part of unloading the document or its descendants.)

2. If the navigation was initiated for entry update of an entry

   1. Replace the {{Document}} of the entry being updated, and any other entries that referenced the same document as that entry, with the new {{Document}}.
   2. Traverse the history to the new entry.

   This can only happen if the entry being updated is not the current entry, and can never happen with replacement enabled. (It happens when the user tried to traverse to a session history entry that no longer had a {{Document}} object.)

   Otherwise

   1. Remove all the entries in the browsing context's session history after the current entry. If the current entry is the last entry in the session history, then no entries are removed.

      This doesn't necessarily have to affect the user agent's user interface.

   2. Append a new entry at the end of the History object representing the new resource and its {{Document}} object, related state, and the default scroll restoration mode of "auto".
   3. Traverse the history to the new entry. If the navigation was initiated with replacement enabled, then the traversal must itself be initiated with replacement enabled.

3. The navigation algorithm has now matured.
4. fragment loop: Spin the event loop for a user-agent-defined amount of time, as desired by the user agent implementor. (This is intended to allow the user agent to optimize the user experience in the face of performance concerns.)
5. If the {{Document}} object has no parser, or its parser has [=stop parsing|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.
6. Scroll to the fragment given in the document's [=Document/URL=]. If this fails to find an indicated part of the document, then return to the fragment loop step.

Page load processing model for HTML files

The input byte stream converts bytes into characters for use in the [[#tokenization|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.

Page load processing model for XML files

At the time of writing, the XML specification community had not actually yet specified how XML and the DOM interact.

Page load processing model for text files

In particular, if the user agent supports the Format=Flowed feature of RFC3676 then the user agent would need to apply extra styling to cause the text to wrap correctly and to handle the quoting feature. [[RFC3676]]

Page load processing model for multipart/x-mixed-replace resources

Thus, load events (and for that matter unload events) do fire for each body part loaded.

Page load processing model for media

Page load processing model for content that uses plugins

The term plugin document is used by Content Security Policy as part of the mechanism that ensures <{iframe}>s can't be used to evade plugin-types directives. [[!CSP3]]

If the {{Document}}'s active sandboxing flag set has its sandboxed plugins browsing context flag set, the synthesized <{embed}> element will fail to render the content if the relevant plugin cannot be secured.

Page load processing model for inline content that doesn't have a DOM

Navigating to a fragment

1. Remove all the entries in the browsing context's session history after the current entry. If the current entry is the last entry in the session history, then no entries are removed.

   This doesn't necessarily have to affect the user agent's user interface.

2. Remove any tasks queued by the history traversal task source that are associated with any {{Document}} objects in the top-level browsing context's document family.
3. Append a new entry at the end of the History object representing the new resource and its {{Document}} object, related state, and current history scroll restoration preference. Its [=url/URL=] must be set to the address to which the user agent was navigating. The title must be left unset.
4. Traverse the history to the new entry, with the non-blocking events flag set. This will scroll to the fragment given in what is now the document's [=Document/URL=].

If the scrolling fails because the relevant ID has not yet been parsed, then the original navigation algorithm will take care of the scrolling instead, as the last few steps of its update the session history with the new page algorithm.

1. Let target be the indicated part of the document, as defined below.
2. If target is the top of the document, then scroll to the beginning of the document for the {{Document}}, and abort these steps. [[!CSSOM-VIEW]]
3. Use the scroll an element into view algorithm to scroll target into view, with the align to top flag set. [[!CSSOM-VIEW]]
4. Run the focusing steps for that element, with the {{Document}}'s viewport as the fallback target.
5. Move the sequential focus navigation starting point to target.

1. Apply the URL parser algorithm to the [=url/URL=], and let fragid be the fragment component of the resulting URL record.
2. If fragid is the empty string, then the indicated part of the document is the top of the document; stop the algorithm here.
3. Let fragid bytes be the result of percent decoding fragid.
4. Let decoded fragid be the result of running UTF-8 decode without BOM or fail on fragid bytes. If decoded fragid is failure, jump to the step labeled no decoded fragid.
5. If there is an element in the DOM that has an ID exactly equal to decoded fragid, then the first such element in tree order is the indicated part of the document; stop the algorithm here.
6. No decoded fragid: If there is an <{a}> element in the DOM that has a <{a/name}> attribute whose value is exactly equal to fragid (not decoded fragid), then the first such element in tree order is the indicated part of the document; stop the algorithm here.
7. If fragid is an ASCII case-insensitive match for the string top, then the indicated part of the document is the top of the document; stop the algorithm here.
8. Otherwise, there is no indicated part of the document.

History traversal

This algorithm is not just invoked when explicitly going back or forwards in the session history — it is also invoked in other situations, for example when navigating a browsing context, as part of updating the session history with the new page.

1. If there is no longer a {{Document}} object for the entry in question, navigate the browsing context to the resource for that entry to perform an entry update of that entry, and abort these steps. The "navigate" algorithm reinvokes this "traverse" algorithm to complete the traversal, at which point there is a {{Document}} object and so this step gets skipped. The navigation must be done using the same source browsing context as was used the first time this entry was created. (This can never happen with replacement enabled.)

   If the resource was obtained using a non-idempotent action, for example a POST form submission, or if the resource is no longer available, for example because the computer is now offline and the page wasn't cached, navigating to it again might not be possible. In this case, the navigation will result in a different page than previously; for example, it might be an error message explaining the problem or offering to resubmit the form.

2. If the current entry's title was not set by the pushState() or replaceState() methods, then set its title to the value returned by the document.title IDL attribute.
3. If appropriate, update the current entry in the browsing context's {{Document}} object's History object to reflect any state that the user agent wishes to persist. The entry is then said to be an entry with persisted user state.
4. If the specified entry has a different {{Document}} object than the current entry, then run the following substeps:
   1. Remove any tasks queued by the history traversal task source that are associated with any {{Document}} objects in the top-level browsing context's document family.
   2. If the [=concept/origin=] of the {{Document}} of the specified entry is not the same as the [=concept/origin=] of the {{Document}} of the current entry, then run the following sub-sub-steps:
      1. The current browsing context name must be stored with all the entries in the history that are associated with {{Document}} objects with the same origin as the active document and that are contiguous with the current entry.
      2. If the browsing context is a top-level browsing context, but not an auxiliary browsing context, then the browsing context's browsing context name must be unset.
   3. Make the specified entry's {{Document}} object the active document of the browsing context.
   4. If the specified entry has a browsing context name stored with it, then run the following sub-sub-steps:
      1. Set the browsing context's browsing context name to the name stored with the specified entry.
      2. Clear any browsing context names stored with all entries in the history that are associated with {{Document}} objects with the same origin as the new active document and that are contiguous with the specified entry.
   5. If the specified entry's {{Document}} has any form controls whose autofill field name is "off", invoke the reset algorithm of each of those elements.
   6. If the current document readiness of the specified entry's {{Document}} is "complete", queue a task to run the following sub-sub-steps:
      1. If the {{Document}}'s page showing flag is true, then abort this task (i.e., don't fire the event below).
      2. Set the {{Document}}'s page showing flag to true.
      3. Run any session history document visibility change steps for {{Document}} that are defined by [=other applicable specifications=].

         This is specifically intended for use by the Page Visibility specification. [[PAGE-VISIBILITY]]

      4. Fire a trusted event with the name pageshow at the Window object of that {{Document}}, with target override set to the {{Document}} object, using the PageTransitionEvent interface, with the {{PageTransitionEvent/persisted}} attribute initialized to true. This event must not bubble, must not be cancelable, and has no default action.
5. Set the document's [=Document/URL=] to the URL of the specified entry.
6. If the specified entry has a URL whose fragment differs from that of the current entry's when compared in a case-sensitive manner, and the two share the same {{Document}} object, then let hash changed be true, and let old URL be the URL of the current entry and new URL be the URL of the specified entry. Otherwise, let hash changed be false.
7. If the traversal was initiated with replacement enabled, remove the entry immediately before the specified entry in the session history.
8. If the specified entry is not an entry with persisted user state, but its URL has a fragment, scroll to the fragment.
9. If the entry is an entry with persisted user state, the user agent may restore persisted user state and update aspects of the document and its rendering.
10. Let targetRealm be the current Realm Record.
11. If the entry is a serialized state entry, let state be StructuredDeserialize(entry's serialized state, targetRealm). If this throws an exception, ignore the exception and let state be null.
12. Set history.state to state.
13. Let state changed be true if the {{Document}} of the specified entry has a latest entry, and that entry is not the specified entry; otherwise let it be false.
14. Let the latest entry of the {{Document}} of the specified entry be the specified entry.
15. If the non-blocking events flag is not set, then run the following steps immediately. Otherwise, the non-blocking events flag is set; queue a task to run the following substeps instead.
    1. If state changed is true, fire a trusted event with the name popstate at the Window object of the {{Document}}, using the PopStateEvent interface, with the state attribute initialized to the value of state. This event must bubble but not be cancelable and has no default action.
    2. If hash changed is true, then fire a trusted event with the name hashchange at the browsing context's {{Window}} object, using the {{HashChangeEvent}} interface, with the oldURL attribute initialized to old URL and the newURL attribute initialized to new URL. This event must bubble but not be cancelable and has no default action.
16. The current entry is now the specified entry.

Persisted user state restoration

When the user agent is to restore persisted user state from a history entry, it must run the following steps immediately:

1. If the entry has a scroll restoration mode, let scrollRestoration be that. Otherwise let scrollRestoration be "auto"
2. If scrollRestoration is "manual" the user agent should not restore the scroll position for the document, otherwise, it may do so.
3. Optionally, update other aspects of the document and its rendering, for instance values of form fields, that the user agent had previously recorded.

This can even include updating the <{global/dir}> attribute of <{textarea}> elements or <{input}> elements whose <{input/type}> attribute is in either the <{input/Text}> state or the <{input/Search}> state, if the persisted state includes the directionality of user input in such controls.

The PopStateEvent interface

    [Constructor(DOMString type, optional PopStateEventInit eventInitDict), Exposed=(Window,Worker)]
    interface PopStateEvent : Event {
      readonly attribute any state;
    };
  

    dictionary PopStateEventInit : EventInit {
      any state = null;
    };
  

event . state

Returns a copy of the information that was provided to pushState() or replaceState().

The HashChangeEvent interface

    [Constructor(DOMString type, optional HashChangeEventInit eventInitDict), Exposed=(Window,Worker)]
    interface HashChangeEvent : Event {
      readonly attribute USVString oldURL;
      readonly attribute USVString newURL;
    };
  

    dictionary HashChangeEventInit : EventInit {
      USVString oldURL = "";
      USVString newURL = "";
    };
  

event . oldURL

Returns the [=url/URL=] of the session history entry that was previously current.

event . newURL

Returns the [=url/URL=] of the session history entry that is now current.

The PageTransitionEvent interface

    [Constructor(DOMString type, optional PageTransitionEventInit eventInitDict), Exposed=(Window,Worker)]
    interface PageTransitionEvent : Event {
      readonly attribute boolean persisted;
    };
  

    dictionary PageTransitionEventInit : EventInit {
      boolean persisted = false;
    };
  

event . {{PageTransitionEvent/persisted}}

For the pageshow event, returns false if the page is newly being loaded (and the load event will fire). Otherwise, returns true. For the pagehide event, returns false if the page is going away for the last time. Otherwise, returns true, meaning that (if nothing conspires to make the page unsalvageable) the page might be reused if the user navigates back to this page. Things that can cause the page to be unsalvageable include:

• document.open()
• Listening for beforeunload events
• Listening for unload events
• Having iframes that are not salvageable
• Active WebSocket objects
• Aborting a Document

Unloading documents

1. Increase the event loop's termination nesting level by one.
2. Increase the {{Document}}'s ignore-opens-during-unload counter by one.
3. Let event be a new trusted BeforeUnloadEvent event object with the name beforeunload, which does not bubble but is cancelable.
4. Dispatch: Dispatch event at the {{Document}}'s Window object.
5. Decrease the event loop's termination nesting level by one.
6. If any event listeners were triggered by the earlier dispatch step, then set the {{Document}}'s salvageable state to false.
7. If the {{Document}}'s active sandboxing flag set does not have its sandboxed modals flag set, and the {{BeforeUnloadEvent/returnValue}} attribute of the event object is not the empty string, or if the event was canceled, then the user agent should ask the user to confirm that they wish to unload the document. The prompt shown by the user agent may include the string of the {{BeforeUnloadEvent/returnValue}} attribute, or optionally truncated. The user agent must pause while waiting for the user's response. If the user did not confirm the page navigation, then the user agent refused to allow the document to be unloaded.
8. If this algorithm was invoked by another instance of the "prompt to unload a document" algorithm (i.e., through the steps below that invoke this algorithm for all descendant browsing contexts), then jump to the step labeled end.
9. Let descendants be the list of the descendant browsing contexts of the {{Document}}.
10. If descendants is not an empty list, then for each browsing context b in descendants run the following substeps:
    1. Prompt to unload the active document of the browsing context b. If the user refused to allow the document to be unloaded, then the user implicitly also refused to allow this document to be unloaded; jump to the step labeled end.
    2. If the salvageable state of the active document of the browsing context b is false, then set the salvageable state of this document to false also.
11. End: Decrease the {{Document}}'s ignore-opens-during-unload counter by one.

1. Increase the event loop's termination nesting level by one.
2. Increase the {{Document}}'s ignore-opens-during-unload counter by one.
3. If the {{Document}}'s page showing flag is false, then jump to the step labeled unload event below (i.e., skip firing the pagehide event and don't rerun the unloading document visibility change steps).
4. Set the {{Document}}'s page showing flag to false.
5. Fire a trusted event with the name pagehide at the Window object of the {{Document}}, with target override set to the {{Document}} object, using the PageTransitionEvent interface, with the {{PageTransitionEvent/persisted}} attribute initialized to true if the {{Document}} object's salvageable state is true, and false otherwise. This event must not bubble, must not be cancelable, and has no default action.
6. Run any unloading document visibility change steps for {{Document}} that are defined by [=other applicable specifications=].

   This is specifically intended for use by the Page Visibility specification. [[PAGE-VISIBILITY]]

7. Unload event: If the {{Document}}'s fired unload flag is false, fire a simple event named unload at the {{Document}}'s Window object, with target override set to the {{Document}} object.
8. Decrease the event loop's termination nesting level by one.
9. If any event listeners were triggered by the earlier unload event step, then set the {{Document}} object's salvageable state to false and set the {{Document}}'s fired unload flag to true.
10. Run any unloading document cleanup steps for {{Document}} that are defined by this specification and [=other applicable specifications=].
11. If this algorithm was invoked by another instance of the "unload a document" algorithm (i.e., by the steps below that invoke this algorithm for all descendant browsing contexts), then jump to the step labeled end.
12. Let descendants be the list of the descendant browsing contexts of the {{Document}}.
13. If descendants is not an empty list, then for each browsing context b in descendants run the following substeps:
    1. Unload the active document of the browsing context b with the recycle parameter set to false.
    2. If the salvageable state of the active document of the browsing context b is false, then set the salvageable state of this document to false as well.
14. If both the {{Document}}'s salvageable state and recycle are false, then the {{Document}}'s browsing context must discard the Document.
15. End: Decrease the {{Document}}'s ignore-opens-during-unload counter by one.

1. Make disappear any WebSocket objects that were created by the WebSocket() constructor from the {{Document}}'s Window object. If this affected any WebSocket objects, then set {{Document}}'s salvageable state to false.
2. If the {{Document}}'s salvageable state is false, forcibly close any EventSource objects that whose constructor was invoked from the {{Document}}'s Window object.
3. If the {{Document}}'s salvageable state is false, empty the {{Document}}'s Window's list of active timers.

The BeforeUnloadEvent interface

    interface BeforeUnloadEvent : Event {
      attribute DOMString returnValue;
    };
  

event . {{BeforeUnloadEvent/returnValue}} [ = value ]

Returns the current return value of the event (the message to show the user). Can be set, to update the message.

There are no BeforeUnloadEvent-specific initialization methods.

Aborting a document load

1. Abort the active documents of every child browsing context. If this results in any of those {{Document}} objects having their salvageable state set to false, then set this {{Document}}'s salvageable state to false also.
2. Cancel any instances of the fetch algorithm in the context of this {{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 the {{Document}}'s salvageable state to false.
3. If the {{Document}} has an active parser, then abort that parser and set the {{Document}}'s salvageable state to false.

Browser state

    [NoInterfaceObject, Exposed=(Window, Worker)]
    interface NavigatorOnLine {
      readonly attribute boolean onLine;
    };
  

window . navigator . onLine

Returns false if the user agent is definitely offline (disconnected from the network). Returns true if the user agent might be online. The events online and offline are fired when the value of this attribute changes.

This attribute is inherently unreliable. A computer can be connected to a network without having Internet access.