## 7 Loading Web pages

This section describes features that apply most directly to Web browsers. Having said that, except where specified otherwise, the requirements defined in this section do apply to all user agents, whether they are Web browsers or not.

### 7.1 Browsing contexts

A browsing context is an environment in which `Document` objects are presented to the user.

A tab or window in a Web browser typically contains a browsing context, as does an `iframe` or `frame`s in a `frameset`.

Each browsing context has a corresponding `WindowProxy` object.

A browsing context has a session history, which lists the `Document` objects that that browsing context has presented, is presenting, or will present. At any time, one `Document` in each browsing context is designated the active document. A `Document`'s browsing context is that browsing context whose session history contains the `Document`, if any. (A `Document` created using an API such as `createDocument()` has no browsing context.)

Each `Document` in a browsing context is associated with a `Window` object. A browsing context's `WindowProxy` object forwards everything to the browsing context's active document's `Window` object.

In general, there is a 1-to-1 mapping from the `Window` object to the `Document` object. There are two exceptions. First, a `Window` can be reused for the presentation of a second `Document` in the same browsing context, such that the mapping is then 1-to-2. This occurs when a browsing context is navigated from the initial `about:blank` `Document` to another, with replacement enabled. Second, a `Document` can end up being reused for several `Window` objects when the `document.open()` method is used, such that the mapping is then many-to-1.

A `Document` does not necessarily have a browsing context associated with it. In particular, data mining tools are likely to never instantiate browsing contexts.

A browsing context can have a creator browsing context, the browsing context that was responsible for its creation. If a browsing context has a parent browsing context, then that is its creator browsing context. Otherwise, if the browsing context has an opener browsing context, then that is its creator browsing context. Otherwise, the browsing context has no creator browsing context.

If a browsing context A has a creator browsing context, then the `Document` that was the active document of that creator browsing context at the time A was created is the creator `Document`.

Creating a browsing context: When a browsing context is first created, it must be created with a single `Document` in its session history, whose address is `about:blank`, which is marked as being an HTML document, whose character encoding is UTF-8, and which is both ready for post-load tasks and completely loaded immediately, along with a new `Window` object that the `Document` is associated with. The `Document` must have a single child `html` node, which itself has two empty child nodes: a `head` element, and a `body` element. As soon as this `Document` is created, the user agent must implement the sandboxing for it. If the browsing context has a creator `Document`, then the browsing context's `Document`'s referrer must be set to the address of that creator `Document` at the time of the browsing context's creation.

If the browsing context is created specifically to be immediately navigated, then that initial navigation will have replacement enabled.

The origin and effective script origin of the `about:blank` `Document` are set when the `Document` is created. If the new browsing context has a creator browsing context, then the origin of the `about:blank` `Document` is an alias to the origin of the creator `Document` and the effective script origin of the `about:blank` `Document` is initially an alias to the effective script origin of the creator `Document`. Otherwise, the origin of the `about:blank` `Document` is a globally unique identifier assigned when the new browsing context is created and the effective script origin of the `about:blank` `Document` is initially an alias to its origin.

#### 7.1.1 Nested browsing contexts

Certain elements (for example, `iframe` elements) can instantiate further browsing contexts. These are called nested browsing contexts. If a browsing context P has a `Document` D with an element E that nests another browsing context C inside it, then C is said to be nested through D, and E is said to be the browsing context container of C. If the browsing context container element E is in the `Document` D, then P is said to be the parent browsing context of C and C is said to be a child browsing context of P. Otherwise, the nested browsing context C has no parent browsing context.

A browsing context A is said to be an ancestor of a browsing context B if there exists a browsing context A' that is a child browsing context of A and that is itself an ancestor of B, or if the browsing context A is the parent browsing context of B.

A browsing context that is not a nested browsing context has no parent browsing context, and is the top-level browsing context of all the browsing contexts for which it is an ancestor browsing context.

The transitive closure of parent browsing contexts for a nested browsing context gives the list of ancestor browsing contexts.

The list of the descendant browsing contexts of a `Document` d is the (ordered) list returned by the following algorithm:

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.

A `Document` is said to be fully active when it is the active document of its browsing context, and either its browsing context is a top-level browsing context, or it has a parent browsing context and the `Document` through which it is nested is itself fully active.

Because they are nested through an element, child browsing contexts are always tied to a specific `Document` in their parent browsing context. User agents must not allow the user to interact with child browsing contexts of elements that are in `Document`s that are not themselves fully active.

A nested browsing context can have a seamless browsing context flag set, if it is embedded through an `iframe` element with a `seamless` attribute.

A nested browsing context can be put into a delaying `load` events mode. This is used when it is navigated, to delay the load event of the browsing context container before the new `Document` is created.

The document family of a browsing context consists of the union of all the `Document` objects in that browsing context's session history and the document families of all those `Document` objects. The document family of a `Document` object consists of the union of all the document families of the browsing contexts that are nested through the `Document` object.

##### 7.1.1.1 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.

  Throws a `SecurityError` exception in cross-origin situations.

The `top` IDL attribute on the `Window` object of a `Document` in a browsing context b must return the `WindowProxy` object of its top-level browsing context (which would be its own `WindowProxy` object if it was a top-level browsing context itself), if it has one, or its own `WindowProxy` object otherwise (e.g. if it was a detached nested browsing context).

The `parent` IDL attribute on the `Window` object of a `Document` in a browsing context b must return the `WindowProxy` object of the parent browsing context, if there is one (i.e. if b is a child browsing context), or the `WindowProxy` object of the browsing context b itself, otherwise (i.e. if it is a top-level browsing context or a detached nested browsing context).

The `frameElement` IDL attribute on the `Window` object of a `Document` d, on getting, must run the following algorithm:

1. If d is not a `Document` in a nested browsing context, return null and abort these steps.

2. If the browsing context container's node document does not have the same effective script origin as the effective script origin specified by the entry settings object, then throw a `SecurityError` exception and abort these steps.

3. Return the browsing context container for b.

#### 7.1.2 Auxiliary browsing contexts

It is possible to create new browsing contexts that are related to a top-level browsing context without being nested through an element. Such browsing contexts are called auxiliary browsing contexts. Auxiliary browsing contexts are always top-level browsing contexts.

An auxiliary browsing context has an opener browsing context, which is the browsing context from which the auxiliary browsing context was created.

##### 7.1.2.1 Navigating auxiliary browsing contexts in the DOM

The `opener` IDL attribute on the `Window` object, on getting, must return the `WindowProxy` object of the browsing context from which the current browsing context was created (its opener browsing context), if there is one, if it is still available, and if the current browsing context has not disowned its opener; otherwise, it must return null. On setting, if the new value is null then the current browsing context must disown its opener; if the new value is anything else then the user agent must call the [[DefineOwnProperty]] internal method of the `Window` object, passing the property name "`opener`" as the property key, and the Property Descriptor { [[Value]]: value, [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true } as the property descriptor, where value is the new value.

#### 7.1.3 Secondary browsing contexts

User agents may support secondary browsing contexts, which are browsing contexts that form part of the user agent's interface, apart from the main content area.

The `sidebar` link type uses secondary browsing contexts.

#### 7.1.4 Security

A browsing context A is familiar with a second browsing context B if one of the following conditions is true:

- Either the origin of the active document of A is the same as the 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).

A browsing context A is allowed to navigate a second browsing context B if the following algorithm terminates positively:

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 node 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!

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 origin 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.

#### 7.1.5 Groupings of browsing contexts

Each browsing context is defined as having a list of one or more directly reachable browsing contexts. These are:

- The browsing context itself.
- All the browsing context's child browsing contexts.
- The browsing context's parent browsing context.
- All the browsing contexts that have the browsing context as their opener browsing context.
- The browsing context's opener browsing context.

The transitive closure of all the browsing contexts that are directly reachable browsing contexts forms a unit of related browsing contexts.

Each unit of related browsing contexts is then further divided into the smallest number of groups such that every member of each group has an active document with an effective script origin that, through appropriate manipulation of the `document.domain` attribute, could be made to be the same as other members of the group, but could not be made the same as members of any other group. Each such group is a unit of related similar-origin 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).

#### 7.1.6 Browsing context names

Browsing contexts can have a browsing context name. By default, a browsing context has no name (its name is not set).

A valid browsing context name is any string with at least one character that does not start with a U+005F LOW LINE character. (Names starting with an underscore are reserved for special keywords.)

A valid browsing context name or keyword is any string that is either a valid browsing context name or that is an ASCII case-insensitive match for one of: `_blank`, `_self`, `_parent`, or `_top`.

These values have different meanings based on whether the page is sandboxed or not, as summarised in the following (non-normative) table. In this table, "current" means the browsing context that the link or script is in, "parent" means the parent browsing context of the one the link or script is in, "master" means the nearest ancestor browsing context of the one the link or script is in that is not itself in a seamless iframe, "top" means the top-level browsing context of the one the link or script is in, "new" means a new top-level browsing context or auxiliary browsing context is to be created, subject to various user preferences and user agent policies, "none" means that nothing will happen, and "maybe new" means the same as "new" if the "`allow-popups`" keyword is also specified on the `sandbox` attribute (or if the user overrode the sandboxing), and the same as "none" otherwise.

Keyword | Ordinary effect | Effect in an `iframe` with...
--- | --- | ---
`seamless=""` | `sandbox=""` | `sandbox="" seamless=""` | `sandbox="allow-top-navigation"` | `sandbox="allow-top-navigation" seamless=""`
none specified, for links and form submissions | current | master | current | master | current | master
empty string | current | master | current | master | current | master
`_blank` | new | new | maybe new | maybe new | maybe new | maybe new
`_self` | current | current | current | current | current | current
`_parent` if there isn't a parent | current | current | current | current | current | current
`_parent` if parent is also top | parent/top | parent/top | none | none | parent/top | parent/top
`_parent` if there is one and it's not top | parent | parent | none | none | none | none
`_top` if top is current | current | current | current | current | current | current
`_top` if top is not current | top | top | none | none | top | top
name that doesn't exist | new | new | maybe new | maybe new | maybe new | maybe new
name that exists and is a descendant | specified descendant | specified descendant | specified descendant | specified descendant | specified descendant | specified descendant
name that exists and is current | current | current | current | current | current | current
name that exists and is an ancestor that is top | specified ancestor | specified ancestor | none | none | specified ancestor/top | specified ancestor/top
name that exists and is an ancestor that is not top | specified ancestor | specified ancestor | none | none | none | none
other name that exists with common top | specified | specified | none | none | none | none
name that exists with different top, if familiar and one permitted sandboxed navigator | specified | specified | specified | specified | specified | specified
name that exists with different top, if familiar but not one permitted sandboxed navigator | specified | specified | none | none | none | none
name that exists with different top, not familiar | new | new | maybe new | maybe new | maybe new | maybe new

Most of the restrictions on sandboxed browsing contexts are applied by other algorithms, e.g. the navigation algorithm, not the rules for choosing a browsing context given a browsing context name given below.

An algorithm is allowed to show a popup if any of the following conditions is true:

- The task in which the algorithm is running is currently processing an activation behaviour 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.

The rules for choosing a browsing context given a browsing context name are as follows. The rules assume that they are being applied in the context of a browsing context, as part of the execution of a task.

1. If the given browsing context name is the empty string or `_self`, then the chosen browsing context must be the current one.

   If the given browsing context name is `_self`, then this is an explicit self-navigation override, which overrides the behaviour of the seamless browsing context flag set by the `seamless` attribute on `iframe` elements.

2. If the given browsing context 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 the given browsing context 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 the given browsing context name is not `_blank` and there exists a browsing context whose name is the same as the given browsing context name, and the current browsing context is familiar with that browsing context, and the user agent determines that the two browsing contexts are related enough that it is ok if they reach each other, 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.

   If the browsing context is chosen by this step to be the current browsing context, then this is also an explicit self-navigation override.

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 behaviour (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 `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 `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 current browsing context's active document's active sandboxing flag set has the sandboxed navigation browsing context flag set and the chosen browsing context picked above, if any, is a new browsing context (whether top-level or auxiliary), then all the flags that are set in the current browsing context's active document's active sandboxing flag set when the new browsing context is created must be set in the new browsing context's popup sandboxing flag set, and the current browsing context must be set as the new browsing context's one permitted sandboxed navigator.

### 7.2 The `Window` object

    [PrimaryGlobal]
    /*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;
      [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);

      // the user agent
      readonly attribute Navigator navigator;
      [Replaceable, SameObject] readonly attribute External external;
      readonly attribute ApplicationCache applicationCache;

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

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

      void postMessage(any message, DOMString targetOrigin, optional sequence<Transferable> transfer);
    };
    Window implements GlobalEventHandlers;
    Window implements WindowEventHandlers;

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 `window`, `frames`, and `self` IDL attributes must all return the `Window` object's browsing context's `WindowProxy` object.

The `document` IDL attribute must return the `Window` object's newest `Document` object.

The `Document` object associated with a `Window` object can change in exactly one case: when the navigate algorithm initialises 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.

The `defaultView` IDL attribute of the `Document` interface must return the `Document`'s browsing context's `WindowProxy` object, if there is one, or null otherwise.

For historical reasons, `Window` objects must also have a writable, configurable, non-enumerable property named `HTMLDocument` whose value is the `Document` interface object.

#### 7.2.1 Security

This section describes a security model that is underdefined, imperfect, and does not match implementations. Work is ongoing to attempt to resolve this, but in the meantime, please do not rely on this section for precision. Implementors are urged to send their feedback on how cross-origin cross-global access to `Window` and `Location` objects should work. See bug 20701.

User agents must throw a `SecurityError` exception whenever any properties of a `Window` object are accessed when the incumbent settings object specifies an effective script origin that is not the same as the `Window` object's `Document`'s effective script origin, with the following exceptions:

- The `location` attribute
- The `postMessage()` method
- The `window` attribute
- The `frames` attribute
- The `self` attribute
- The `top` attribute
- The `parent` attribute
- The `opener` attribute
- The `closed` attribute
- The `close()` method
- The `blur()` method
- The `focus()` method
- The dynamic nested browsing context properties

When the incumbent settings object specifies an effective script origin that is different than a `Window` object's `Document`'s effective script origin, the user agent must act as if any changes to that `Window` object's properties, getters, setters, etc, were not present, and as if all the properties of that `Window` object had their [[Enumerable]] attribute set to false.

For members that return objects (including function objects), each distinct effective script origin that is not the same as the `Window` object's `Document`'s effective script origin must be provided with a separate set of objects. These objects must have the prototype chain appropriate for the script for which the objects are created (not those that would be appropriate for scripts whose global object, as specified by their settings object, is the `Window` object in question).

For instance, if two frames containing `Document`s from different origins access the same `Window` object's `postMessage()` method, they will get distinct objects that are not equal.

#### 7.2.2 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.

The `open()` method on `Window` objects provides a mechanism for navigating an existing browsing context or opening and navigating an auxiliary browsing context.

When the method is invoked, the user agent must run the following steps:

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 given a browsing context name using target as the name and source browsing context as the context in which the algorithm is executed. If this results in there not being 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. [CSSOMVIEW]

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 "`about:blank`".

    Otherwise, resolve url relative to the API base URL specified by entry settings, and let resource be the resulting absolute URL, if any. If the resolve 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 "`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 exceptions enabled. If new is true, then replacement must be enabled also. The source browsing context is source browsing context.

13. End: Return the `WindowProxy` object of target browsing context.

The `name` attribute of the `Window` object must, on getting, return the current name of the browsing context, if one is set, or the empty string otherwise; and, on setting, set the name of the browsing context to the new value.

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

The `close()` method on `Window` objects should, if all the following conditions are met, close the browsing context A:

- 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.

A browsing context is script-closable if it is an auxiliary browsing context that was created by a script (as opposed to by an action of the user), or if it is a top-level browsing context whose session history contains only one `Document`.

The `closed` attribute on `Window` objects must return true if the `Window` object's browsing context has been discarded, and false otherwise.

The `stop()` method on `Window` objects should, if there is an existing attempt to navigate the browsing context and that attempt is not currently running the unload a document algorithm, cancel that navigation; then, it must abort the active document of the browsing context of the `Window` object on which it was invoked.

#### 7.2.3 Accessing other browsing contexts

window . `length`

  Returns the number of child browsing contexts.

window[index]

  Returns the indicated child browsing context.

The `length` IDL attribute on the `Window` interface must return the number of child browsing contexts that are nested through elements that are in the `Document` that is the active document of that `Window` object, if that `Window`'s browsing context shares the same event loop as the responsible document specified by the entry settings object accessing the IDL attribute; otherwise, it must return zero.

The supported property indices on the `Window` object at any instant are the numbers in the range 0 .. n-1, where n is the number returned by the `length` IDL attribute. If n is zero then there are no supported property indices.

To determine the value of an indexed property index of a `Window` object, the user agent must return the `WindowProxy` object of the indexth child browsing context of the `Document` that is nested through an element that is in the `Document`, sorted in the order that the elements nesting those browsing contexts were most recently inserted into the `Document`, the `WindowProxy` object of the most recently inserted browsing context container's nested browsing context being last.

These properties are the dynamic nested browsing context properties.

#### 7.2.4 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 `document.getElementById()` or `document.querySelector()`.

The `Window` interface supports named properties. The supported property names at any moment consist of the following, in tree order, ignoring later duplicates:

- the browsing context name of any child browsing context of the active document whose name is not the empty string,
- the value of the `name` content attribute for all `a`, `applet`, `area`, `embed`, `form`, `frameset`, `img`, and `object` elements in the active document that have a non-empty `name` content attribute, and
- the value of the `id` content attribute of any HTML element in the active document with a non-empty `id` content attribute.

To determine the value of a named property name when the `Window` object is indexed for property retrieval, the user agent must return the value obtained using the following steps:

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.)

Named objects with the name name, for the purposes of the above algorithm, are those that are either:

- child browsing contexts of the active document whose name is name,
- `a`, `applet`, `area`, `embed`, `form`, `frameset`, `img`, or `object` elements that have a `name` content attribute whose value is name, or
- HTML elements that have an `id` content attribute whose value is name.

#### 7.2.5 Garbage collection and browsing contexts

A browsing context has a strong reference to each of its `Document`s and its `WindowProxy` object, and the user agent itself has a strong reference to its top-level browsing contexts.

A `Document` has a strong reference to its `Window` object.

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.

Each script has a strong reference to its settings object, and each environment settings object has strong references to its global object, responsible browsing context, and responsible document (if any).

When a browsing context is to discard a `Document`, the user agent must run the following steps:

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 `Document`s of each worker whose list contains that `Document`.

When a browsing context is discarded, the strong reference from the user agent itself to the browsing context must be severed, and all the `Document` objects for all the entries in the browsing context's session history must be discarded as well.

User agents may discard top-level browsing contexts at any time (typically, in response to user requests, e.g. when a user force-closes a window containing one or more top-level browsing contexts). Other browsing contexts must be discarded once their `WindowProxy` object is eligible for garbage collection.

#### 7.2.6 Closing browsing contexts

When the user agent is required to close a browsing context, it must run the following steps:

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.

User agents should offer users the ability to arbitrarily close any top-level browsing context.

#### 7.2.7 Browser interface elements

To allow Web pages to integrate with Web browsers, certain Web browser interface elements are exposed in a limited way to scripts in Web pages.

Each interface element is represented by a `BarProp` object:

    interface BarProp {
      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 visible attribute, on getting, must return either true or a value determined by the user agent to most accurately represent the visibility state of the user interface element that the object represents, as described below. On setting, the new value must be discarded.

The following `BarProp` objects exist for each `Document` object in a browsing context. Some of the user interface elements represented by these objects might have no equivalent in some user agents; for those user agents, except when otherwise specified, the object must act as if it was present and visible (i.e. its `visible` attribute must return true).

The location bar `BarProp` object
  Represents the user interface element that contains a control that displays the 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 `locationbar` attribute must return the location bar `BarProp` object.

The `menubar` attribute must return the menu bar `BarProp` object.

The `personalbar` attribute must return the personal bar `BarProp` object.

The `scrollbars` attribute must return the scrollbar `BarProp` object.

The `statusbar` attribute must return the status bar `BarProp` object.

The `toolbar` attribute must return the toolbar `BarProp` object.

For historical reasons, the `status` attribute on the `Window` object must, on getting, return the last string it was set to, and on setting, must set itself to the new value. When the `Window` object is created, the attribute must be set to the empty string. It does not do anything else.

#### 7.2.8 The `WindowProxy` object

As mentioned earlier, each browsing context has a `WindowProxy` object. This object is unusual in that all operations that would be performed on it must be performed on the `Window` object of the browsing context's active document instead. It is thus indistinguishable from that `Window` object in every way until the browsing context is navigated.

There is no `WindowProxy` interface object.

The `WindowProxy` object allows scripts to act as if each browsing context had a single `Window` object, while still keeping separate `Window` objects for each `Document`.

In the following example, the variable x is set to the `WindowProxy` object returned by the `window` accessor on the global object. All of the expressions following the assignment return true, because in every respect, the `WindowProxy` object acts like the underlying `Window` object.

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

### 7.3 Origin

Origins are the fundamental currency of the Web's security model. Two actors in the Web platform that share an origin are assumed to trust each other and to have the same authority. Actors with differing origins are considered potentially hostile versus each other, and are isolated from each other to varying degrees.

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` exception will be raised.

The origin of a resource and the effective script origin of a resource are each one of the following:

Opaque identifiers

  Internal values, with no serialisation, for which the only meaningful operation is testing for equality.

Tuples

  Tuples consisting of a scheme component, a host component, a port component, and optionally extra data.

  The extra data could include the certificate of the site when using encrypted connections, to ensure that if the site's secure certificate changes, the origin is considered to change as well.

Aliases

  A reference to another origin or effective script origin.

An origin or effective script origin can be defined as an alias to another origin or effective script origin. The value of the origin or effective script origin is then the value of the origin or effective script origin to which it is an alias.

These characteristics are defined as follows:

For URLs

  The origin and effective script origin of the URL are the URL origin defined in the WHATWG URL standard. [URL]

For `Document` objects
  If a `Document`'s active sandboxing flag set has its sandboxed origin browsing context flag set

    The origin is a globally unique identifier assigned when the `Document` is created.

    The effective script origin is initially an alias to the origin of the `Document`.

  If a `Document` was served over the network and has an address that uses a URL scheme with a server-based naming authority

    The origin is an alias to the origin of the `Document`'s address.

    The effective script origin is initially an alias to the origin of the `Document`.

  If a `Document` was generated from a `data:` URL found in another `Document` or in a script

    The origin is an alias to the origin specified by the incumbent settings object when the navigate algorithm was invoked, or, if no script was involved, of the node document of the element that initiated the navigation to that URL.

    The effective script origin is initially an alias to the effective script origin of that same environment settings object or `Document`.

  If a `Document` is the initial "`about:blank`" document

    The origin and effective script origin of the `Document` are those it was assigned when its browsing context was created.

  If a `Document` was created as part of the processing for `javascript:` URLs

    The origin is an alias to the origin of the active document of the browsing context being navigated when the navigate algorithm was invoked.

    The effective script origin is initially an alias to the effective script origin of that same `Document`.

  If a `Document` is an `iframe` `srcdoc` document

    The origin of the `Document` is an alias to the origin of the `Document`'s browsing context's browsing context container's node document.

    The effective script origin is initially an alias to the effective script origin of the `Document`'s browsing context's browsing context container's node document.

  If a `Document` was obtained in some other manner (e.g. a `data:` URL typed in by the user or that was returned as the location of an HTTP redirect (or equivalent in other protocols), a `Document` created using the `createDocument()` API, etc)

    The default behaviour as defined in the DOM standard applies. [DOM].

    The origin is a globally unique identifier assigned when the `Document` is created, and the effective script origin is initially an alias to the origin of the `Document`.

  The effective script origin of a `Document` can be manipulated using the `document.domain` IDL attribute.

For images of `img` elements
  If the image data is CORS-cross-origin
    The origin is a globally unique identifier assigned when the image is created.
  If the image data is CORS-same-origin
    The origin is an alias to the origin of the `img` element's node document.

  Images do not have an effective script origin.

For `audio` and `video` elements
  If the media data is CORS-cross-origin
    The origin is a globally unique identifier assigned when the media data is fetched.
  If the media data is CORS-same-origin
    The origin is an alias to the origin of the media element's node document.

  Media elements do not have an effective script origin.

For fonts

  The origin of a downloadable Web font is an alias to the origin of the absolute URL used to obtain the font (after any redirects). [CSSFONTS] [CSSFONTLOAD]

  The origin of a locally installed system font is an alias to the origin of the `Document` in which that font is being used.

  Fonts do not have an effective script origin.

Other specifications can override the above definitions by themselves specifying the origin of a particular URL, `Document`, image, media element, or font.

The Unicode serialisation of an origin is the string obtained by applying the following algorithm to the given origin:

1. If the origin in question is not a scheme/host/port tuple, then return the literal string "`null`" and abort these steps.

2. Otherwise, let result be the scheme part of the origin tuple.

3. Append the string "`://`" to result.

4. Apply the domain to Unicode algorithm to each component of the host part of the origin tuple, and append the results — each component, in the same order, separated by U+002E FULL STOP characters (.) — to result. [URL]

5. If the port part of the origin tuple gives a port that is different from the default port for the protocol given by the scheme part of the origin tuple, then append a U+003A COLON character (:) and the given port, in base ten, to result.

6. Return result.

The ASCII serialisation of an origin is the string obtained by applying the following algorithm to the given origin:

1. If the origin in question is not a scheme/host/port tuple, then return the literal string "`null`" and abort these steps.

2. Otherwise, let result be the scheme part of the origin tuple.

3. Append the string "`://`" to result.

4. Apply the domain to ASCII algorithm to each component of the host part of the origin tuple, and append the results — each component, in the same order, separated by U+002E FULL STOP characters (.) — to result. [URL]

   If the domain to ASCII algorithm returns failure, e.g. because a component is too long or because it contains invalid characters, then throw a `SecurityError` exception and abort these steps.

5. If the port part of the origin tuple gives a port that is different from the default port for the protocol given by the scheme part of the origin tuple, then append a U+003A COLON character (:) and the given port, in base ten, to result.

6. Return result.

Two origins are said to be the same origin if the following algorithm returns true:

1. Let A be the first origin being compared, and B be the second origin being compared.

2. If A and B are both opaque identifiers, and their value is equal, then return true.

3. Otherwise, if either A or B or both are opaque identifiers, return false.

4. If A and B have scheme components that are not identical, return false.

5. If A and B have host components that are not identical, return false.

6. If A and B have port components that are not identical, return false.

7. If either A or B have additional data, but that data is not identical for both, return false.

8. Return true.

#### 7.3.1 Relaxing the same-origin restriction

document . `domain` [ = domain ]

  Returns the current domain used for security checks.

  Can be set to a value that removes subdomains, to change the effective script origin 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.)

The `domain` attribute on `Document` objects must be initialised to the document's domain, if it has one, and the empty string otherwise. If the document's domain starts with a U+005B LEFT SQUARE BRACKET character ([) and ends with a U+005D RIGHT SQUARE BRACKET character (]), it is an IPv6 address; these square brackets must be omitted when initialising the attribute's value.

On getting, the attribute must return its current value, unless the `Document` has no browsing context, in which case it must return the empty string.

On setting, the user agent must run the following algorithm:

1. If the `Document` has no browsing context, throw a `SecurityError` exception and abort these steps.

2. If the `Document`'s active sandboxing flag set has its sandboxed `document.domain` browsing context flag set, throw a `SecurityError` exception and abort these steps.

3. If the new value is an IPv4 or IPv6 address, let new value be the new value.

   Otherwise, strictly split the new value on U+002E FULL STOP characters (.), apply the domain to ASCII algorithm to each returned token, and let new value be the result of concatenating the results of applying that algorithm to each token, in the same order, separated by U+002E FULL STOP characters (.). [URL]

   If the domain to ASCII algorithm returns failure, e.g. because a component is too long or because it contains invalid characters, then throw a `SecurityError` exception and abort these steps.

4. If new value is not exactly equal to the current value of the `document.domain` attribute, then run these substeps:

   1. If the current value is an IPv4 or IPv6 address, throw a `SecurityError` exception and abort these steps.

   2. If new value, prefixed by a U+002E FULL STOP (.), does not exactly match the end of the current value, throw a `SecurityError` exception and abort these steps.

      If the new value is an IPv4 or IPv6 address, it cannot match the new value in this way and thus an exception will be thrown here.

   3. If new value matches a suffix in the Public Suffix List, or, if new value, prefixed by a U+002E FULL STOP (.), matches the end of a suffix in the Public Suffix List, then throw a `SecurityError` exception and abort these steps. [PSL]

      Suffixes must be compared in an ASCII case-insensitive manner, after applying the domain to ASCII algorithm to their individual components, . [URL]

5. Release the storage mutex.

6. Set the attribute's value to new value.

7. If the effective script origin of the `Document` is an alias, set it to the value of the effective script origin (essentially de-aliasing the effective script origin).

8. If new value is not the empty string, then run these substeps:

   1. Set the host part of the effective script origin tuple of the `Document` to new value.

   2. Set the port part of the effective script origin tuple of the `Document` to "manual override" (a value that, for the purposes of comparing origins, is identical to "manual override" but not identical to any other value).

The domain of a `Document` is the host part of the document's origin, if the value of that origin is a scheme/host/port tuple. If it isn't, then the document does not have a domain.

The `domain` attribute is used to enable pages on different hosts of a domain to access each others' DOMs.

Do not use the `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` attribute has been used.

### 7.4 Sandboxing

A sandboxing flag set is a set of zero or more of the following flags, which are used to restrict the abilities that potentially untrusted resources have:

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, or the `showModalDialog()` 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, the `applet` element, or through navigation of a nested browsing context, unless those plugins can be secured.

The sandboxed seamless iframes flag

  This flag prevents content from using the `seamless` attribute on descendant `iframe` elements.

  This prevents a page inserted using the `allow-same-origin` keyword from using a CSS-selector-based method of probing the DOM of other pages on the same site (in particular, pages that contain user-sensitive information).

The sandboxed origin browsing context flag

  This flag forces content into a unique origin, thus preventing it from accessing other content from the same origin.

  This flag also prevents script from reading from or writing to the `document.cookie` IDL attribute, and blocks access to `localStorage`.

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` feature to change the effective script origin.

When the user agent is to parse a sandboxing directive, given a string input, a sandboxing flag set output, and optionally an allow fullscreen flag, it must run the following steps:

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 seamless iframes 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.

Every top-level browsing context has a popup sandboxing flag set, which is a sandboxing flag set. When a browsing context is created, its popup sandboxing flag set must be empty. It is populated by the rules for choosing a browsing context given a browsing context name.

Every nested browsing context has an `iframe` sandboxing flag set, which is a sandboxing flag set. Which flags in a nested browsing context's `iframe` sandboxing flag set are set at any particular time is determined by the `iframe` element's `sandbox` attribute.

Every `Document` has an active sandboxing flag set, which is a sandboxing flag set. When the `Document` is created, its active sandboxing flag set must be empty. It is populated by the navigation algorithm.

Every resource that is obtained by the navigation algorithm has a forced sandboxing flag set, which is a sandboxing flag set. A resource by default has no flags set in its forced sandboxing flag set, but other specifications can define that certain flags are set.

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

When a user agent is to implement the sandboxing for a `Document`, it must populate `Document`'s active sandboxing flag set with the union of the flags that are present in the following sandboxing flag sets at the time the `Document` object is created:

- 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.

### 7.5 Session history and navigation

#### 7.5.1 The session history of browsing contexts

The sequence of `Document`s in a browsing context is its session history. Each browsing context, including nested browsing contexts, has a distinct session history. A browsing context's session history consists of a flat list of session history entries. Each session history entry consists, at a minimum, of a URL, and each entry may in addition have a state object, a title, a `Document` object, form data, a scroll position, and other information associated with it.

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 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.

URLs without associated state objects are added to the session history as the user (or script) navigates from page to page.

Each `Document` object in a browsing context's session history is associated with a unique `History` object which must all model the same underlying session history.

The `history` attribute of the `Window` interface must return the object implementing the `History` interface for that `Window` object's newest `Document`.

A state object is an object representing a user interface state.

Pages can add state objects to the session history. These are then 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.

State objects are 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), and 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 pop-up `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.

At any point, one of the entries in the session history is the current entry. This is the entry representing the active document of the browsing context. Which entry is the current entry is changed by the algorithms defined in this specification, e.g. during session history traversal.

The current entry is usually an entry for the address of the `Document`. However, it can also be one of the entries for state objects added to the history by that document.

An entry with persisted user state is one that also has user-agent defined state. This specification does not specify what kind of state can be stored.

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 `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.

Entries that consist of state objects share the same `Document` as the entry for the page that was active when they were added.

Contiguous entries that differ just by fragment identifier also share the same `Document`.

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

Each `Document` in a browsing context can also have a latest entry. This is the entry for that `Document` to which the browsing context's session history was most recently traversed. When a `Document` is created, it initially has no latest entry.

User agents may discard the `Document` objects of entries other than the current entry that are not referenced from any script, reloading the pages afresh when the user or script navigates back to such pages. This specification does not specify when user agents should discard `Document` objects and when they should cache them.

Entries that have had their `Document` objects discarded must, for the purposes of the algorithms given below, act as if they had not. When the user or script navigates back or forwards to a page which has no in-memory DOM objects, any other entries that shared the same `Document` object with it must share the new object as well.

#### 7.5.2 The `History` interface

    interface History {
      readonly attribute long length;
      readonly attribute any state;
      void go(optional long delta);
      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` . `state`

  Returns the current state 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.

The joint session history of a top-level browsing context is the union of all the session histories of all browsing contexts of all the fully active `Document` objects that share that top-level browsing context, with all the entries that are current entries in their respective session histories removed except for the current entry of the joint session history.

The current entry of the joint session history is the entry that most recently became a current entry in its session history.

Entries in the joint session history are ordered chronologically by the time they were added to their respective session histories. Each entry has an index; the earliest entry has index 0, and the subsequent entries are numbered with consecutively increasing integers (1, 2, 3, etc).

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.

All the getters and setters for attributes, and all the methods, defined on the `History` interface, when invoked on a `History` object associated with a `Document` that is not fully active, must throw a `SecurityError` exception instead of operating as described below.

The `length` attribute of the `History` interface must return the number of entries in the top-level browsing context's joint session history.

The actual entries are not accessible from script.

The `state` attribute of the `History` interface must return the last value it was set to by the user agent. Initially, its value must be null.

When the `go(delta)` method is invoked, if the argument to the method was omitted or has the value zero, the user agent must act as if the `location.reload()` method was called instead. Otherwise, the user agent must traverse the history by a delta whose value is the value of the method's argument.

When the `back()` method is invoked, the user agent must traverse the history by a delta −1.

When the `forward()`method is invoked, the user agent must traverse the history by a delta +1.

Each top-level browsing context has a session history traversal queue, initially empty, to which tasks can be added.

Each top-level browsing context, when created, must begin running the following algorithm, known as the session history event loop for that top-level browsing context, in parallel:

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.

The session history event loop helps coordinate cross-browsing-context transitions of the joint session history: since each browsing context might, at any particular time, have a different event loop (this can happen if the user agent has more than one event loop per unit of related browsing contexts), transitions would otherwise have to involve cross-event-loop synchronisation.

To traverse the history by a delta delta, the user agent must append a task to this top-level browsing context's session history traversal queue, the task consisting of running the following steps:

1. Let delta be the argument to the method.

2. 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.

3. 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.

4. Let specified browsing context be the browsing context of the specified entry.

5. If the specified browsing context's active document's unload a document algorithm is currently running, abort these steps.

6. 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. Fully exit fullscreen.

      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.

   3. Traverse the history of the specified browsing context to the specified entry.

When the user navigates through a browsing context, e.g. using a browser's back and forward buttons, the user agent must traverse the history by a delta equivalent to the action specified by the user.

The `pushState(data, title, url)` method adds a state object entry to the history.

The `replaceState(data, title, url)` method updates the state object, title, and optionally the URL of the current entry in the history.

When either of these methods is invoked, the user agent must run the following steps:

1. Let cloned data be a structured clone of the specified data. If this throws an exception, then rethrow that exception and abort these steps.

2. If the third argument is not null, run these substeps:

   1. Resolve the value of the third argument, relative to the API base URL specified by the entry settings object.
   2. If that fails, throw a `SecurityError` exception and abort these steps.
   3. Compare the resulting parsed URL to the result of applying the URL parser algorithm to the document's address. If any component of these two URLs differ other than the path, query, and fragment components, then throw a `SecurityError` exception and abort these steps.
   4. If the origin of the resulting absolute URL is not the same as the origin of the responsible document specified by the entry settings object, and either the path or query components of the two parsed URLs compared in the previous step differ, throw a `SecurityError` exception and abort these steps. (This prevents sandboxed content from spoofing other pages on the same origin.)

   5. Let new URL be the resulting absolute URL.

   For the purposes of the comparisons in the above substeps, the path and query components can only be the same if the scheme component of both parsed URLs are relative schemes.

3. If the third argument is null, then let new URL be the URL of the current entry.

4. If the method invoked was the `pushState()` method:

   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. If appropriate, update the current entry 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. Add a state object entry to the session history, after the current entry, with cloned data as the state object, the given title as the title, and new URL as the URL of the entry.

   5. Update the current entry to be this newly added entry.

   Otherwise, if the method invoked was the `replaceState()` method:

   1. Update the current entry in the session history so that cloned data is the entry's new state object, the given title is the new title, and new URL is the entry's new URL.

5. If the current entry in the session history represents a non-GET request (e.g. it was the result of a POST submission) then update it to instead represent a GET request (or equivalent).

6. Set the document's address to new URL.

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

7. Set `history.state` to a structured clone of cloned data.

8. Let the latest entry of the `Document` of the current entry be the current entry.

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

User agents may limit the number of state objects added to the session history per page. If a page hits the UA-defined limit, user agents must remove the entry immediately after the first entry for that `Document` object in the session history after having added the new entry. (Thus the state history acts as a FIFO buffer for eviction, but as a LIFO buffer for navigation.)

Consider a game where the user can navigate along a line, such that the user is always at some coordinate, and such that the user can bookmark the page corresponding to a particular coordinate, to return to it later.

A static page implementing the x=5 position in such a game could look like the following:

    <!DOCTYPE HTML>
    <!-- this is http://example.com/line?x=5 -->
    <title>Line Game - 5</title>
    <p>You are at coordinate 5 on the line.</p>
    <p>
     <a href="?x=6">Advance to 6</a> or
     <a href="?x=4">retreat to 4</a>?
    </p>

The problem with such a system is that each time the user clicks, the whole page has to be reloaded. Here instead is another way of doing it, using script:

    <!DOCTYPE HTML>
    <!-- this starts off as http://example.com/line?x=5 -->
    <title>Line Game - 5</title>
    <p>You are at coordinate <span id="coord">5</span> on the line.</p>
    <p>
     <a href="?x=6" onclick="go(1); return false;">Advance to 6</a> or
     <a href="?x=4" onclick="go(-1); return false;">retreat to 4</a>?
    </p>
    <script>
     var currentPage = 5; // prefilled by server
     function go(d) {
       setupPage(currentPage + d);
       history.pushState(currentPage, document.title, '?x=' + currentPage);
     }
     onpopstate = function(event) {
       setupPage(event.state);
     }
     function setupPage(page) {
       currentPage = page;
       document.title = 'Line Game - ' + currentPage;
       document.getElementById('coord').textContent = currentPage;
       document.links[0].href = '?x=' + (currentPage+1);
       document.links[0].textContent = 'Advance to ' + (currentPage+1);
       document.links[1].href = '?x=' + (currentPage-1);
       document.links[1].textContent = 'retreat to ' + (currentPage-1);
     }
    </script>

In systems without script, this still works like the previous example. However, users that do have script support can now navigate much faster, since there is no network access for the same experience. Furthermore, contrary to the experience the user would have with just a naïve script-based approach, bookmarking and navigating the session history still work.

In the example above, the data argument to the `pushState()` method is the same information as would be sent to the server, but in a more convenient form, so that the script doesn't have to parse the URL each time the user navigates.

Applications might not use the same title for a session history entry as the value of the document's `title` element at that time. For example, here is a simple page that shows a block in the `title` element. Clearly, when navigating backwards to a previous state the user does not go back in time, and therefore it would be inappropriate to put the time in the session history title.

    <!DOCTYPE HTML>
    <TITLE>Line</TITLE>
    <SCRIPT>
     setInterval(function () { document.title = 'Line - ' + new Date(); }, 1000);
     var i = 1;
     function inc() {
       set(i+1);
       history.pushState(i, 'Line - ' + i);
     }
     function set(newI) {
       i = newI;
       document.forms.F.I.value = newI;
     }
    </SCRIPT>
    <BODY ONPOPSTATE="set(event.state)">
    <FORM NAME=F>
    State: <OUTPUT NAME=I>1</OUTPUT> <INPUT VALUE="Increment" TYPE=BUTTON ONCLICK="inc()">
    </FORM>

#### 7.5.3 The `Location` interface

Each `Document` object in a browsing context's session history is associated with a unique instance of a `Location` object.

document . `location` [ = value ]
window . `location` [ = value ]

  Returns a `Location` object with the current page's location.

  Can be set, to navigate to another page.

The `location` attribute of the `Document` interface must return the `Location` object for that `Document` object, if it is in a browsing context, and null otherwise.

The `location` attribute of the `Window` interface must return the `Location` object for that `Window` object's `Document`.

`Location` objects provide a representation of the address of the active document of their `Document`'s browsing context, and allow the current entry of the browsing context's session history to be changed, by adding or replacing entries in the `history` object.

    [Unforgeable] interface Location {
      void assign(DOMString url);
      void replace(DOMString url);
      void reload();

      [SameObject] readonly attribute DOMString[] ancestorOrigins;
    };
    Location implements URLUtils;

location . `assign`(url)

  Navigates to the given page.

location . `replace`(url)

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

location . `reload`()

  Reloads the current page.

location . `ancestorOrigins`

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

The relevant `Document` is the `Location` object's associated `Document` object's browsing context's active document.

When the `assign(url)` method is invoked, the UA must resolve the argument, relative to the API base URL specified by the entry settings object, and if that is successful, must navigate the browsing context to the specified url, with exceptions enabled. If the browsing context's session history contains only one `Document`, and that was the `about:blank` `Document` created when the browsing context was created, then the navigation must be done with replacement enabled.

When the `replace(url)` method is invoked, the UA must resolve the argument, relative to the API base URL specified by the entry settings object, and if that is successful, navigate the browsing context to the specified url with replacement enabled and exceptions enabled.

Navigation for the `assign()` and `replace()` methods must be done with the responsible browsing context specified by the incumbent settings object as the source browsing context.

If the resolving step of the `assign()` and `replace()` methods is not successful, then the user agent must instead throw a `SyntaxError` exception.

When the `reload()` method is invoked, the user agent must run the appropriate steps from the following list:

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 address with replacement enabled and exceptions enabled. The source browsing context must be the browsing context being navigated. This is a reload-triggered navigation.

When a user requests that the active document of a browsing context be reloaded through a user interface element, the user agent should navigate the browsing context to the same resource as that `Document`, with replacement enabled. In the case of non-idempotent methods (e.g. HTTP POST), the user agent should prompt the user to confirm the operation first, since otherwise transactions (e.g. purchases or database modifications) could be repeated. User agents may allow the user to explicitly override any caches when reloading. If browsing context's active document's reload override flag is set, then the user agent may instead perform an overridden reload rather than the navigation described in this paragraph (with the browsing context being reloaded as the source browsing context).

The `Location` interface also supports the `URLUtils` interface. [URL]

When the object is created, and whenever the the address of the relevant `Document` changes, the user agent must invoke the object's `URLUtils` interface's set the input algorithm with the address of the relevant `Document` as the given value.

The object's `URLUtils` interface's get the base algorithm must return the API base URL specified by the entry settings object, if there is one, or null otherwise.

The object's `URLUtils` interface's query encoding is the document's character encoding.

When the object's `URLUtils` interface invokes its update steps with the string value, the user agent must run the following steps:

1. If any of the following conditions are met, let mode be normal navigation; otherwise, let it be replace navigation:

   - The `Location` object's relevant `Document` has completely loaded, or
   - In the task in which the algorithm is running, an activation behaviour is currently being processed whose `click` event was trusted, or
   - In the task in which the algorithm is running, the event listener for a trusted `click` event is being handled.

2. If mode is normal navigation, then act as if the `assign()` method had been called with value as its argument. Otherwise, act as if the `replace()` method had been called with value as its argument.

The `ancestorOrigins` attribute, on getting, must return a read only array whose values are determined as follows. The same object must be returned each time the attribute's value is obtained for any particular `Location` object.

1. Let output be an empty ordered list of strings.

2. Let current be the browsing context of the `Document` with which the `Location` object is associated.

3. Loop: If current has no parent browsing context, jump to the step labeled end.

4. Let current be current's parent browsing context.

5. Append the Unicode serialisation of current's active document's origin to output as a new value.

6. Return to the step labeled loop.

7. End: Let output be the values of the array, in the same order.

##### 7.5.3.1 Security

This section describes a security model that is underdefined, imperfect, and does not match implementations. Work is ongoing to attempt to resolve this, but in the meantime, please do not rely on this section for precision. Implementors are urged to send their feedback on how cross-origin cross-global access to `Window` and `Location` objects should work. See bug 20701.

User agents must throw a `SecurityError` exception whenever any properties of a `Location` object are accessed when the entry settings object specifies an effective script origin that is not the same as the `Location` object's associated `Document`'s browsing context's active document's effective script origin, with the following exceptions:

- The `href` setter, if the responsible browsing context specified by the entry settings object is familiar with the browsing context with which the `Location` object is associated
- The `replace()` method, if the responsible browsing context specified by the entry settings object is familiar with the browsing context with which the `Location` object is associated
- Any properties not defined in the IDL for the `Location` object or indirectly via one of those properties (e.g. `toString()`, which is defined via the `stringifier` keyword), if the effective script origin specified by the entry settings object is the same origin as the `Location` object's associated `Document`'s effective script origin

When the effective script origin specified by the entry settings object is different than a `Location` object's associated `Document`'s effective script origin, the user agent must act as if any changes to that `Location` object's properties, getters, setters, etc, were not present, and as if all the properties of that `Location` object had their [[Enumerable]] attribute set to false.

For members that return objects (including function objects), each distinct effective script origin that is not the same origin as the `Location` object's `Document`'s effective script origin must be provided with a separate set of objects. These objects must have the prototype chain appropriate for the script for which the objects are created (not those that would be appropriate for scripts whose settings object specifies a global object that is the `Location` object's `Document`'s `Window` object).

#### 7.5.4 Implementation notes for session history

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 `iframe`s has a `history` object distinct from the `iframe`s' `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.

In addition, a user agent could ignore calls to `pushState()` that are invoked on a timer, or from event listeners that are not triggered in response to a clear user action, or that are invoked in rapid succession.

### 7.6 Browsing the Web

#### 7.6.1 Navigating across documents

Certain actions cause the browsing context to navigate to a new resource. A user agent may provide various ways for the user to explicitly cause a browsing context to navigate, in addition to those defined in this specification.

For example, following a hyperlink, 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.

Navigation always involves source browsing context, which is the browsing context which was responsible for starting the navigation.

When a browsing context is navigated to a new resource, the user agent must run the following steps:

1. Release the storage mutex.

2. 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 with exceptions enabled, and it is aborted on this step, then in addition to aborting this algorithm, the user agent must also throw a `SecurityError` exception.

3. If the source browsing context is the same as the browsing context being navigated, and this browsing context has its seamless browsing context flag set, and the browsing context being navigated was not chosen using an explicit self-navigation override, then find the nearest ancestor browsing context that does not have its seamless browsing context flag set, and continue these steps as if that browsing context was the one that was going to be navigated instead.

4. 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 origin of the URL of the resource being loaded in that navigation is not the same origin as the origin of the URL of the resource being loaded in this navigation, then abort these steps without affecting the preexisting attempt to navigate the browsing context.

5. 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.

6. 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.

7. Let gone async be false.

   The handle redirects step later in this algorithm can in certain cases jump back to the step labeled fragment identifiers. Since, between those two steps, this algorithm goes from operating synchronously 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.

8. Fragment identifiers: If this is not a reload-triggered navigation: apply the URL parser algorithm to the absolute URL of the new resource and the address 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 HTTP GET or equivalent, and the parsed URL of the new resource has a fragment component that is not null (even if it is empty), then navigate to that fragment identifier and abort these steps.

9. 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 initialised 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.)

10. 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.

11. 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.

12. If gone async is false, abort the active document of the browsing context.

13. 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.

14. 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.

15. 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 whose 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 origin of the source browsing context is not the same origin as the origin of the active document of the browsing context being navigated, then act as if the result of evaluating the script was the void value, and jump to the step labeled process results below.

      2. Apply the URL parser to the URL being navigated.

      3. Let parsed URL be the result of the URL parser.

      4. Let script source be the empty string.

      5. Append parsed URL's scheme data component to script source.

      6. If parsed URL's query component is not null, then first append a U+003F QUESTION MARK character (?) to script source, and then append parsed URL's query component to script source.

      7. If parsed URL's fragment component is not null, then first append a U+0023 NUMBER SIGN character (#) to script source, and then append parsed URL's fragment component to script source.

      8. Replace script source with the result of applying the percent decode algorithm to script source.

      9. Replace script source with the result of applying the UTF-8 decode algorithm to script source.

      10. Let address be the address of the active document of the browsing context being navigated.

      11. Create a script, using script source as the script source, address as the script source URL, JavaScript as the scripting language, and the environment settings object of the `Window` object of the active document of the browsing context being navigated.

          Let result be the return value of the code entry-point of this script. If an exception was thrown, let result be void instead. (The result will be void also if scripting is disabled.)

      12. Process results: If the result of executing the script is void (there is no return value), then the result of obtaining the resource for the URL is equivalent to an HTTP resource with an HTTP 204 No Content response.

          Otherwise, the result of obtaining the resource for the URL is equivalent to an HTTP resource with a 200 OK response whose Content-Type metadata is `text/html` and whose response body is the return value converted to a string value.

          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 `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 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.

    If the new resource is to be fetched using HTTP GET or equivalent, and there are relevant application caches that are identified by a URL with the same origin as the URL in question, and that have this URL as one of their entries, excluding entries marked as foreign, and whose mode is fast, and the user agent is not in a mode where it will avoid using application caches

      Fetch the resource from the most appropriate application cache of those that match.

      For example, imagine an HTML page with an associated application cache displaying an image and a form, where the image is also used by several other application caches. If the user right-clicks on the image and chooses "View Image", then the user agent could decide to show the image from any of those caches, but it is likely that the most useful cache for the user would be the one that was used for the aforementioned HTML page. On the other hand, if the user submits the form, and the form does a POST submission, then the user agent will not use an application cache at all; the submission will be made to the network.

    Otherwise

      Fetch the new resource, with the manual redirect flag set.

    If the steps above invoked the fetch algorithm, the following requirements also apply:

    If the resource is being fetched using a method other than one equivalent to HTTP's GET, or, if the navigation algorithm was invoked as a result of the form submission algorithm, then the fetching algorithm must be invoked from the origin of the active document of the source browsing context, if any.

    Otherwise, if the browsing context being navigated is a child browsing context, then the fetching algorithm must be invoked from the browsing context scope origin of the browsing context container of the browsing context being navigated, if it has one.

16. If gone async is false, return to whatever algorithm invoked the navigation steps and continue running these steps asynchronously.

17. Let gone async be true.

18. 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.

19. Handle redirects: If fetching the resource results in a redirect, and either the 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 fragment identifiers with the new resource, except that if the URL of the target of the redirect does not have a fragment identifier and the URL of the resource that led to the redirect does, then the fragment identifier of the resource that led to the redirect must be propagated to the URL of the target of the redirect.

    So for instance, if the original URL was "`http://example.com/#!sample`" and "`http://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 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.

20. Fallback in prefer-online mode: If the resource was not fetched from an application cache, and was to be fetched using HTTP GET or equivalent, and there are relevant application caches that are identified by a URL with the same origin as the URL in question, and that have this URL as one of their entries, excluding entries marked as foreign, and whose mode is prefer-online, and the user didn't cancel the navigation attempt during the earlier step, and the navigation attempt failed (e.g. the server returned a 4xx or 5xx status code or equivalent, or there was a DNS error), then:

    Let candidate be the resource identified by the URL in question from the most appropriate application cache of those that match.

    If candidate is not marked as foreign, then the user agent must discard the failed load and instead continue along these steps using candidate as the resource. The user agent may indicate to the user that the original page load failed, and that the page used was a previously cached resource.

    This does not affect the address of the resource from which Request-URIs are obtained, as used to set the document's referrer in the initialise the `Document` object steps below; they still use the value as computed by the original fetch algorithm.

21. Fallback for fallback entries: If the resource was not fetched from an application cache, and was to be fetched using HTTP GET or equivalent, and its URL matches the fallback namespace of one or more relevant application caches, and the most appropriate application cache of those that match does not have an entry in its online whitelist that has the same origin as the resource's URL and that is a prefix match for the resource's URL, and the user didn't cancel the navigation attempt during the earlier step, and the navigation attempt failed (e.g. the server returned a 4xx or 5xx status code or equivalent, or there was a DNS error), then:

    Let candidate be the fallback resource specified for the fallback namespace in question. If multiple application caches match, the user agent must use the fallback of the most appropriate application cache of those that match.

    If candidate is not marked as foreign, then the user agent must discard the failed load and instead continue along these steps using candidate as the resource. The document's address, if appropriate, will still be the originally requested URL, not the fallback URL, but the user agent may indicate to the user that the original page load failed, that the page used was a fallback resource, and what the URL of the fallback resource actually is.

    This does not affect the address of the resource from which Request-URIs are obtained, as used to set the document's referrer in the initialise the `Document` object steps below; they still use the value as computed by the original fetch algorithm.

22. 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 recognised 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 recognised 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.

23. Let type be the sniffed type of the resource.

24. 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:

    "`text/html`"
      Follow the steps given in the HTML document section, and then, once they have completed, abort this navigate algorithm.
    "`application/xml`"
    "`text/xml`"
    "`image/svg+xml`"
    "`application/xhtml+xml`"
    Any other type ending in "`+xml`" 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.
    "`text/plain`"
      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 (e.g. one registered using `registerContentHandler()`).

    Setting the document's address: If there is no override URL, then any `Document` created by these steps must have its address set to the URL that was originally to be fetched, ignoring any other data that was used to obtain the resource (e.g. the entity body in the case of a POST submission is not part of the document's address, nor is the URL of the fallback resource in the case of the original load having failed and that URL having been found to match a fallback namespace). However, if there is an override URL, then any `Document` created by these steps must have its address set to that URL instead.

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

    Initialising 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. Create a new `Window` object, and associate it with the `Document`, with one exception: if the browsing context's only entry in its session history is the `about:blank` `Document` that was added when the browsing context was created, and navigation is occurring with replacement enabled, and that `Document` has the same origin as the new `Document`, then use the `Window` object of that `Document` instead, and change the `document` attribute of the `Window` object to point to the new `Document`.

    2. 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.

    3. Implement the sandboxing for the `Document`.

    4. 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 `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.

25. 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.

26. 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.

When a resource is handled by passing its URL or data to an external software package separate from the user agent (e.g. handing a `mailto:` URL to a mail client, or a Word document to a word processor), user agents should attempt to mitigate the risk that this is an attempt to exploit the target software, e.g. by prompting the user to confirm that the source browsing context's active document's origin is to be allowed to invoke the specified software. In particular, if the navigate algorithm, when it was invoked, was not allowed to show a popup, 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.

Some of the sections below, to which the above algorithm defers in certain cases, require the user agent to update the session history with the new page. When a user agent is required to do this, it must queue a task (associated with the `Document` object of the current entry, not the new one) to run the following steps:

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 and related state.

     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 identifier 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 optimise the user experience in the face of performance concerns.)

5. If the `Document` object 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 identifier, then abort these steps.

6. Scroll to the fragment identifier given in the document's address. If this fails to find an indicated part of the document, then return to the fragment identifier loop step.

The task source for this task is the networking task source.

#### 7.6.2 Page load processing model for HTML files

When an HTML document is to be loaded in a browsing context, the user agent must queue a task to create a `Document` object, mark it as being an HTML document, set its content type to "`text/html`", initialise the `Document` object, and finally create an HTML parser and associate it with the `Document`. Each task that the networking task source places on the task queue while the fetching algorithm 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 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 "sniffed type" is not used for this purpose.

When no more bytes are available, the user agent must queue a task for the parser to process the implied EOF character, which eventually causes a `load` event to be fired.

After creating the `Document` object, but before any script execution, certainly before the parser stops, the user agent must update the session history with the new page.

Application cache selection happens in the HTML parser.

The task source for the two tasks mentioned in this section must be the networking task source.

#### 7.6.3 Page load processing model for XML files

When faced with displaying an XML file inline, user agents must follow the requirements defined in the XML and Namespaces in XML recommendations, RFC 7303, DOM, and other relevant specifications to create a `Document` object and a corresponding XML parser. [XML] [XMLNS] [RFC7303] [DOM]

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

After the `Document` is created, the user agent must initialise the `Document` object.

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.

If the root element, as parsed according to the XML specifications cited above, is found to be an `html` element with an attribute `manifest` whose value is not the empty string, then, as soon as the element is inserted into the document, the user agent must resolve the value of that attribute relative to that element, and if that is successful, must apply the URL serialiser algorithm to the resulting parsed URL with the exclude fragment flag set to obtain manifest URL, and then run the application cache selection algorithm with manifest URL as the manifest URL, passing in the newly-created `Document`. Otherwise, if the attribute is absent, its value is the empty string, or resolving its value fails, then as soon as the root element is inserted into the document, the user agent must run the application cache selection algorithm with no manifest, and passing in the `Document`.

Because the processing of the `manifest` attribute happens only once the root element is parsed, any URLs referenced by processing instructions before the root element (such as `<?xml-stylesheet?>` PIs) will be fetched from the network and cannot be cached.

User agents may examine the namespace of the root `Element` node of this `Document` object to perform namespace-based dispatch to alternative processing tools, e.g. determining that the content is actually a syndication feed and passing it to a feed handler. If such processing is to take place, abort the steps in this section, and jump to the next step (labeled non-document content) in the navigate steps above.

Otherwise, then, with the newly created `Document`, the user agent must update the session history with the new page. User agents may do this before the complete document has been parsed (thus achieving incremental rendering), and must do this before any scripts are to be executed.

Error messages from the parse process (e.g. XML namespace well-formedness errors) may be reported inline by mutating the `Document`.

#### 7.6.4 Page load processing model for text files

When a plain text document is to be loaded in a browsing context, the user agent must queue a task to create a `Document` object, mark it as being an HTML document, set its content type to "`text/plain`", initialise the `Document` object, create an HTML parser, 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 the fetching algorithm runs must then fill the parser's input byte stream with the fetched bytes and cause the HTML parser to perform the appropriate processing of the input stream.

The rules for how to convert the bytes of the plain text document into actual characters, and the rules for actually rendering the text to the user, are defined in RFC 2046, RFC 3676, and subsequent versions thereof. [RFC2046] [RFC3676]

The document's character encoding must be set to the character encoding used to decode the document.

Upon creation of the `Document` object, the user agent must run the application cache selection algorithm with no manifest, and passing in the newly-created `Document`.

When no more bytes are available, the user agent must queue a task for the parser to process the implied EOF character, which eventually causes a `load` event to be fired.

After creating the `Document` object, but potentially before the page has finished parsing, the user agent must update the session history with the new page.

User agents may add content to the `head` element of the `Document`, e.g. linking to a style sheet or a binding, providing script, giving the document a `title`, etc.

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 binding or a CSS extension.

The task source for the two tasks mentioned in this section must be the networking task source.

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

When a resource with the type `multipart/x-mixed-replace` is to be loaded in a browsing context, the user agent must parse the resource using the rules for multipart types. [RFC2046]

For each body part obtained from the resource, the user agent must run a new instance of the navigate algorithm, starting from the resource handling step, using the new body part as the resource being navigated, with replacement enabled if a previous body part from the same resource resulted in a `Document` object being created and initialised, and otherwise using the same setup as the navigate attempt that caused this section to be invoked in the first place.

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.

#### 7.6.6 Page load processing model for media

When an image, video, or audio resource is to be loaded in a browsing context, the user agent should create a `Document` object, mark it as being an HTML document, set its content type to the sniffed MIME type of the resource (type in the navigate algorithm), initialise the `Document` object, append an `html` element to the `Document`, append a `head` element and a `body` element to the `html` element, append an element host element for the media, as described below, to the `body` element, and set the appropriate attribute of the element host element, as described below, to the address of the image, video, or audio resource.

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.

Upon creation of the `Document` object, the user agent must run the application cache selection algorithm with no manifest, and passing in the newly-created `Document`.

After creating the `Document` object, but potentially before the page has finished fully loading, the user agent must update the session history with the new page.

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 or a binding, to provide a script, to give the document a `title`, to make the media autoplay, etc.

#### 7.6.7 Page load processing model for content that uses plugins

When a resource that requires an external resource to be rendered is to be loaded in a browsing context, the user agent should create a `Document` object, mark it as being an HTML document and mark it as being a plugin document, set its content type to the sniffed MIME type of the resource (type in the navigate algorithm), initialise the `Document` object, append an `html` element to the `Document`, append a `head` element and a `body` element to the `html` element, append an `embed` to the `body` element, and set the `src` attribute of the `embed` element to the address of the resource.

The term plugin document is used by the Content Security Policy specification as part of the mechanism that ensures `iframe`s can't be used to evade `plugin-types` directives. [CSP]

Then, the user agent must act as if it had stopped parsing.

Upon creation of the `Document` object, the user agent must run the application cache selection algorithm with no manifest, and passing in the newly-created `Document`.

After creating the `Document` object, but potentially before the page has finished fully loading, the user agent must update the session history with the new page.

User agents may add content to the `head` element of the `Document`, or attributes to the `embed` element, e.g. to link to a style sheet or a binding, or to give the document a `title`.

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.

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

When the user agent is to display a user agent page inline in a browsing context, the user agent should create a `Document` object, mark it as being an HTML document, set its content type to "`text/html`", initialise the `Document` object, and then either associate that `Document` with a custom rendering that is not rendered using the normal `Document` rendering rules, or mutate that `Document` until it represents the content the user agent wants to render.

Once the page has been set up, the user agent must act as if it had stopped parsing.

Upon creation of the `Document` object, the user agent must run the application cache selection algorithm with no manifest, passing in the newly-created `Document`.

After creating the `Document` object, but potentially before the page has been completely set up, the user agent must update the session history with the new page.

#### 7.6.9 Navigating to a fragment identifier

When a user agent is supposed to navigate to a fragment identifier, then the user agent must run the following steps:

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 and related state. Its 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 identifier given in what is now the document's address.

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

When the user agent is required to scroll to the fragment identifier and the indicated part of the document, if any, is being rendered, the user agent must either change the scrolling position of the document using the following algorithm, or perform some other action such that the indicated part of the document is brought to the user's attention. If there is no indicated part, or if the indicated part is not being rendered, then the user agent must do nothing. The aforementioned algorithm is as follows:

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. [CSSOMVIEW]

3. Use the scroll an element into view algorithm to scroll target into view, with the align to top flag set. [CSSOMVIEW]

4. Run the focusing steps for that element, with the `Document`'s viewport as the fallback target.

5. Optionally, move the sequential focus navigation starting point to target.

The indicated part of the document is the one that the fragment identifier, if any, identifies. The semantics of the fragment identifier in terms of mapping it to a specific DOM Node is defined by the specification that defines the MIME type used by the `Document` (for example, the processing of fragment identifiers for XML MIME types is the responsibility of RFC7303). [RFC7303]

For HTML documents (and HTML MIME types), the following processing model must be followed to determine what the indicated part of the document is.

1. Apply the URL parser algorithm to the URL, and let fragid be the fragment component of the resulting parsed URL.

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 applying the UTF-8 decoder algorithm to fragid bytes. If the UTF-8 decoder emits a decoder error, abort the decoder and instead 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 `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.

For the purposes of the interaction of HTML with Selectors' `:target` pseudo-class, the target element is the indicated part of the document, if that is an element; otherwise there is no target element. [SELECTORS]

The task source for the task mentioned in this section must be the DOM manipulation task source.

#### 7.6.10 History traversal

When a user agent is required to traverse the history to a specified entry, optionally with replacement enabled, and optionally with the non-blocking events flag set, the user agent must act as follows.

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 usign 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 origin of the `Document` of the specified entry is not the same as the 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. [PAGEVIS]

      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 `persisted` attribute initialised to true. This event must not bubble, must not be cancelable, and has no default action.

5. Set the document's address to the URL of the specified entry.

6. If the specified entry has a URL whose fragment identifier 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 identifier, scroll to the fragment identifier.

9. If the entry is an entry with persisted user state, the user agent may update aspects of the document and its rendering, for instance the scroll position or values of form fields, that it had previously recorded.

   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.

10. If the entry is a state object entry, let state be a structured clone of that state object. Otherwise, let state be null.

11. Set `history.state` to state.

12. 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.

13. Let the latest entry of the `Document` of the specified entry be the specified entry.

14. 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 initialised 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 initialised to old URL and the `newURL` attribute initialised to new URL. This event must bubble but not be cancelable and has no default action.

15. The current entry is now the specified entry.

The task source for the tasks mentioned above is the DOM manipulation task source.

##### 7.6.10.1 The `PopStateEvent` interface

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

    dictionary PopStateEventInit : EventInit {
      any state;
    };

event . `state`

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

The `state` attribute must return the value it was initialised to. When the object is created, this attribute must be initialised to null. It represents the context information for the event, or null, if the state represented is the initial state of the `Document`.

##### 7.6.10.2 The `HashChangeEvent` interface

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

    dictionary HashChangeEventInit : EventInit {
      DOMString oldURL;
      DOMString newURL;
    };

event . `oldURL`

  Returns the URL of the session history entry that was previously current.

event . `newURL`

  Returns the URL of the session history entry that is now current.

The `oldURL` attribute must return the value it was initialised to. When the object is created, this attribute must be initialised to null. It represents context information for the event, specifically the URL of the session history entry that was traversed from.

The `newURL` attribute must return the value it was initialised to. When the object is created, this attribute must be initialised to null. It represents context information for the event, specifically the URL of the session history entry that was traversed to.

##### 7.6.10.3 The `PageTransitionEvent` interface

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

    dictionary PageTransitionEventInit : EventInit {
      boolean persisted;
    };

event . `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 `iframe`s that are not salvageable
  - Active `WebSocket` objects
  - Aborting a `Document`

The `persisted` attribute must return the value it was initialised to. When the object is created, this attribute must be initialised to false. It represents the context information for the event.

#### 7.6.11 Unloading documents

A `Document` has a salvageable state, which must initially be true, a fired unload flag, which must initially be false, 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).

Event loops have a termination nesting level counter, which must initially be zero.

When a user agent is to prompt to unload a document, it must run the following steps.

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. Release the storage mutex.

7. If any event listeners were triggered by the earlier dispatch step, then set the `Document`'s salvageable state to false.

8. If the `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 `returnValue` attribute, or some leading subset thereof. (A user agent may want to truncate the string to 1024 characters for display, for instance.)

   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.

9. 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.

10. Let descendants be the list of the descendant browsing contexts of the `Document`.

11. 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.

12. End: Decrease the `Document`'s ignore-opens-during-unload counter by one.

When a user agent is to unload a document, it must run the following steps. These steps are passed an argument, recycle, which is either true or false, indicating whether the `Document` object is going to be re-used. (This is set by the `document.open()` method.)

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 `persisted` attribute initialised 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. [PAGEVIS]

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. Release the storage mutex.

10. 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.

11. Run any unloading document cleanup steps for `Document` that are defined by this specification and other applicable specifications.

12. 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.

13. Let descendants be the list of the descendant browsing contexts of the `Document`.

14. 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 also.

15. If both the `Document`'s salvageable state and recycle are false, then the `Document`'s browsing context must discard the `Document`.

16. End: Decrease the `Document`'s ignore-opens-during-unload counter by one.

This specification defines the following unloading document cleanup steps. Other specifications can define more.

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.

##### 7.6.11.1 The `BeforeUnloadEvent` interface

    interface BeforeUnloadEvent : Event {
      attribute DOMString returnValue;
    };

event . `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 initialisation methods.

The `returnValue` attribute represents the message to show the user. When the event is created, the attribute must be set to the empty string. On getting, it must return the last value it was set to. On setting, the attribute must be set to the new value.

#### 7.6.12 Aborting a document load

If a `Document` is aborted, the user agent must run the following steps:

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.

User agents may allow users to explicitly invoke the abort a document algorithm for a `Document`. If the user does so, then, if that `Document` is an active document, the user agent should queue a task to fire a simple event named `abort` at that `Document`'s `Window` object before invoking the abort algorithm.

### 7.7 Offline Web applications

#### 7.7.1 Introduction

This section is non-normative.

In order to enable users to continue interacting with Web applications and documents even when their network connection is unavailable — for instance, because they are traveling outside of their ISP's coverage area — authors can provide a manifest which lists the files that are needed for the Web application to work offline and which causes the user's browser to keep a copy of the files for use offline.

To illustrate this, consider a simple clock applet consisting of an HTML page "`clock.html`", a CSS style sheet "`clock.css`", and a JavaScript script "`clock.js`".

Before adding the manifest, these three files might look like this:

    <!-- clock.html -->
    <!DOCTYPE HTML>
    <html>
     <head>
      <title>Clock</title>
      <script src="clock.js"></script>
      <link rel="stylesheet" href="clock.css">
     </head>
     <body>
      <p>The time is: <output id="clock"></output></p>
     </body>
    </html>

    /* clock.css */
    output { font: 2em sans-serif; }

    /* clock.js */
    setInterval(function () {
        document.getElementById('clock').value = new Date();
    }, 1000);

If the user tries to open the "`clock.html`" page while offline, though, the user agent (unless it happens to have it still in the local cache) will fail with an error.

The author can instead provide a manifest of the three files, say "`clock.appcache`":

    CACHE MANIFEST
    clock.html
    clock.css
    clock.js

With a small change to the HTML file, the manifest (served as `text/cache-manifest`) is linked to the application:

    <!-- clock.html -->
    <!DOCTYPE HTML>
    <html manifest="clock.appcache">
     <head>
      <title>Clock</title>
      <script src="clock.js"></script>
      <link rel="stylesheet" href="clock.css">
     </head>
     <body>
      <p>The time is: <output id="clock"></output></p>
     </body>
    </html>

Now, if the user goes to the page, the browser will cache the files and make them available even when the user is offline.

Authors are encouraged to include the main page in the manifest also, but in practice the page that referenced the manifest is automatically cached even if it isn't explicitly mentioned.

With the exception of "no-store" directive, HTTP cache headers and restrictions on caching pages served over TLS (encrypted, using `https:`) are overridden by manifests. Thus, pages will not expire from an application cache before the user agent has updated it, and even applications served over TLS can be made to work offline.

View this example online.

##### 7.7.1.1 Supporting offline caching for legacy applications

This section is non-normative.

The application cache feature works best if the application logic is separate from the application and user data, with the logic (markup, scripts, style sheets, images, etc) listed in the manifest and stored in the application cache, with a finite number of static HTML pages for the application, and with the application and user data stored in Web Storage or a client-side Indexed Database, updated dynamically using Web Sockets, `XMLHttpRequest`, server-sent events, or some other similar mechanism.

This model results in a fast experience for the user: the application immediately loads, and fresh data is obtained as fast as the network will allow it (possibly while stale data shows).

Legacy applications, however, tend to be designed so that the user data and the logic are mixed together in the HTML, with each operation resulting in a new HTML page from the server.

For example, consider a news application. The typical architecture of such an application, when not using the application cache feature, is that the user fetches the main page, and the server returns a dynamically-generated page with the current headlines and the user interface logic mixed together.

A news application designed for the application cache feature, however, would instead have the main page just consist of the logic, and would then have the main page fetch the data separately from the server, e.g. using `XMLHttpRequest`.

The mixed-content model does not work well with the application cache feature: since the content is cached, it would result in the user always seeing the stale data from the previous time the cache was updated.

While there is no way to make the legacy model work as fast as the separated model, it can at least be retrofitted for offline use using the prefer-online application cache mode. To do so, list all the static resources used by the HTML page you want to have work offline in an application cache manifest, use the `manifest` attribute to select that manifest from the HTML file, and then add the following line at the bottom of the manifest:

    SETTINGS:
    prefer-online
    NETWORK:
    *

This causes the application cache to only be used for master entries when the user is offline, and causes the application cache to be used as an atomic HTTP cache (essentially pinning resources listed in the manifest), while allowing all resources not listed in the manifest to be accessed normally when the user is online.

##### 7.7.1.2 Event summary

This section is non-normative.

When the user visits a page that declares a manifest, the browser will try to update the cache. It does this by fetching a copy of the manifest and, if the manifest has changed since the user agent last saw it, redownloading all the resources it mentions and caching them anew.

As this is going on, a number of events get fired on the `ApplicationCache` object to keep the script updated as to the state of the cache update, so that the user can be notified appropriately. The events are as follows:

Event name | Interface | Fired when... | Next events
--- | --- | --- | ---
`checking` | `Event` | The user agent is checking for an update, or attempting to download the manifest for the first time. This is always the first event in the sequence. | `noupdate`, `downloading`, `obsolete`, `error`
`noupdate` | `Event` | The manifest hadn't changed. | Last event in sequence.
`downloading` | `Event` | The user agent has found an update and is fetching it, or is downloading the resources listed by the manifest for the first time. | `progress`, `error`, `cached`, `updateready`
`progress` | `ProgressEvent` | The user agent is downloading resources listed by the manifest. The event object's `total` attribute returns the total number of files to be downloaded. The event object's `loaded` attribute returns the number of files processed so far. | `progress`, `error`, `cached`, `updateready`
`cached` | `Event` | The resources listed in the manifest have been downloaded, and the application is now cached. | Last event in sequence.
`updateready` | `Event` | The resources listed in the manifest have been newly redownloaded, and the script can use `swapCache()` to switch to the new cache. | Last event in sequence.
`obsolete` | `Event` | The manifest was found to have become a 404 or 410 page, so the application cache is being deleted. | Last event in sequence.
`error` | `Event` | The manifest was a 404 or 410 page, so the attempt to cache the application has been aborted. | Last event in sequence.
The manifest hadn't changed, but the page referencing the manifest failed to download properly.
A fatal error occurred while fetching the resources listed in the manifest.
The manifest changed while the update was being run. | The user agent will try fetching the files again momentarily.

These events are cancelable; their default action is for the user agent to show download progress information. If the page shows its own update UI, canceling the events will prevent the user agent from showing redundant progress information.

#### 7.7.2 Application caches

An application cache is a set of cached resources consisting of:

- One or more resources (including their out-of-band metadata, such as HTTP headers, if any), identified by URLs, each falling into one (or more) of the following categories:

  Master entries

    These are documents that were added to the cache because a browsing context was navigated to that document and the document indicated that this was its cache, using the `manifest` attribute.

  The manifest

    This is the resource corresponding to the URL that was given in a master entry's `html` element's `manifest` attribute. The manifest is fetched and processed during the application cache download process. All the master entries have the same origin as the manifest.

  Explicit entries

    These are the resources that were listed in the cache's manifest in an explicit section.

  Fallback entries

    These are the resources that were listed in the cache's manifest in a fallback section.

  Explicit entries and Fallback entries can be marked as foreign, which means that they have a `manifest` attribute but that it doesn't point at this cache's manifest.

  A URL in the list can be flagged with multiple different types, and thus an entry can end up being categorised as multiple entries. For example, an entry can be a manifest entry and an explicit entry at the same time, if the manifest is listed within the manifest.

- Zero or more fallback namespaces, each of which is mapped to a fallback entry.

  These are URLs used as prefix match patterns for resources that are to be fetched from the network if possible, or to be replaced by the corresponding fallback entry if not. Each namespace URL has the same origin as the manifest.

- Zero or more URLs that form the online whitelist namespaces.

  These are used as prefix match patterns, and declare URLs for which the user agent will ignore the application cache, instead fetching them normally (i.e. from the network or local HTTP cache as appropriate).

- An online whitelist wildcard flag, which is either open or blocking.

  The open state indicates that any URL not listed as cached is to be implicitly treated as being in the online whitelist namespaces; the blocking state indicates that URLs not listed explicitly in the manifest are to be treated as unavailable.

- A cache mode flag, which is either in the fast state or the prefer-online state.

Each application cache has a completeness flag, which is either complete or incomplete.

An application cache group is a group of application caches, identified by the absolute URL of a resource manifest which is used to populate the caches in the group.

An application cache is newer than another if it was created after the other (in other words, application caches in an application cache group have a chronological order).

Only the newest application cache in an application cache group can have its completeness flag set to incomplete; the others are always all complete.

Each application cache group has an update status, which is one of the following: idle, checking, downloading.

A relevant application cache is an application cache that is the newest in its group to be complete.

Each application cache group has a list of pending master entries. Each entry in this list consists of a resource and a corresponding `Document` object. It is used during the application cache download process to ensure that new master entries are cached even if the application cache download process was already running for their application cache group when they were loaded.

An application cache group can be marked as obsolete, meaning that it must be ignored when looking at what application cache groups exist.

A cache host is a `Document` or a `SharedWorkerGlobalScope` object. A cache host can be associated with an application cache.

A `Document` initially is not associated with an application cache, but can become associated with one early during the page load process, when steps in the parser and in the navigation sections cause cache selection to occur.

A `SharedWorkerGlobalScope` can be associated with an application cache when it is created.

Each cache host has an associated `ApplicationCache` object.

Multiple application caches in different application cache groups can contain the same resource, e.g. if the manifests all reference that resource. If the user agent is to select an application cache from a list of relevant application caches that contain a resource, the user agent must use the application cache that the user most likely wants to see the resource from, taking into account the following:

- which application cache was most recently updated,
- which application cache was being used to display the resource from which the user decided to look at the new resource, and
- which application cache the user prefers.

A URL matches a fallback namespace if there exists a relevant application cache whose manifest's URL has the same origin as the URL in question, and that has a fallback namespace that is a prefix match for the URL being examined. If multiple fallback namespaces match the same URL, the longest one is the one that matches. A URL looking for a fallback namespace can match more than one application cache at a time, but only matches one namespace in each cache.

If a manifest `http://example.com/app1/manifest` declares that `http://example.com/resources/images` is a fallback namespace, and the user navigates to `HTTP://EXAMPLE.COM:80/resources/images/cat.png`, then the user agent will decide that the application cache identified by `http://example.com/app1/manifest` contains a namespace with a match for that URL.

#### 7.7.3 The cache manifest syntax

##### 7.7.3.1 Some sample manifests

This section is non-normative.

This example manifest requires two images and a style sheet to be cached and whitelists a CGI script.

    CACHE MANIFEST
    # the above line is required

    # this is a comment
    # there can be as many of these anywhere in the file
    # they are all ignored
      # comments can have spaces before them
      # but must be alone on the line

    # blank lines are ignored too

    # these are files that need to be cached they can either be listed
    # first, or a "CACHE:" header could be put before them, as is done
    # lower down.
    images/sound-icon.png
    images/background.png
    # note that each file has to be put on its own line

    # here is a file for the online whitelist -- it isn't cached, and
    # references to this file will bypass the cache, always hitting the
    # network (or trying to, if the user is offline).
    NETWORK:
    comm.cgi

    # here is another set of files to cache, this time just the CSS file.
    CACHE:
    style/default.css

It could equally well be written as follows:

    CACHE MANIFEST
    NETWORK:
    comm.cgi
    CACHE:
    style/default.css
    images/sound-icon.png
    images/background.png

Offline application cache manifests can use absolute paths or even absolute URLs:

    CACHE MANIFEST

    /main/home
    /main/app.js
    /settings/home
    /settings/app.js
    http://img.example.com/logo.png
    http://img.example.com/check.png
    http://img.example.com/cross.png

The following manifest defines a catch-all error page that is displayed for any page on the site while the user is offline. It also specifies that the online whitelist wildcard flag is open, meaning that accesses to resources on other sites will not be blocked. (Resources on the same site are already not blocked because of the catch-all fallback namespace.)

So long as all pages on the site reference this manifest, they will get cached locally as they are fetched, so that subsequent hits to the same page will load the page immediately from the cache. Until the manifest is changed, those pages will not be fetched from the server again. When the manifest changes, then all the files will be redownloaded.

Subresources, such as style sheets, images, etc, would only be cached using the regular HTTP caching semantics, however.

    CACHE MANIFEST
    FALLBACK:
    / /offline.html
    NETWORK:
    *

##### 7.7.3.2 Writing cache manifests

Manifests must be served using the `text/cache-manifest` MIME type. All resources served using the `text/cache-manifest` MIME type must follow the syntax of application cache manifests, as described in this section.

An application cache manifest is a text file, whose text is encoded using UTF-8. Data in application cache manifests is line-based. Newlines must be represented by U+000A LINE FEED (LF) characters, U+000D CARRIAGE RETURN (CR) characters, or U+000D CARRIAGE RETURN (CR) U+000A LINE FEED (LF) pairs. [ENCODING]

This is a willful violation of RFC 2046, which requires all `text/*` types to only allow CRLF line breaks. This requirement, however, is outdated; the use of CR, LF, and CRLF line breaks is commonly supported and indeed sometimes CRLF is not supported by text editors. [RFC2046]

The first line of an application cache manifest must consist of the string "CACHE", a single U+0020 SPACE character, the string "MANIFEST", and either a U+0020 SPACE character, a U+0009 CHARACTER TABULATION (tab) character, a U+000A LINE FEED (LF) character, or a U+000D CARRIAGE RETURN (CR) character. The first line may optionally be preceded by a U+FEFF BYTE ORDER MARK (BOM) character. If any other text is found on the first line, it is ignored.

Subsequent lines, if any, must all be one of the following:

A blank line

  Blank lines must consist of zero or more U+0020 SPACE and U+0009 CHARACTER TABULATION (tab) characters only.

A comment

  Comment lines must consist of zero or more U+0020 SPACE and U+0009 CHARACTER TABULATION (tab) characters, followed by a single U+0023 NUMBER SIGN character (#), followed by zero or more characters other than U+000A LINE FEED (LF) and U+000D CARRIAGE RETURN (CR) characters.

  Comments must be on a line on their own. If they were to be included on a line with a URL, the "#" would be mistaken for part of a fragment identifier.

A section header

  Section headers change the current section. There are four possible section headers:

  `CACHE:`
    Switches to the explicit section.
  `FALLBACK:`
    Switches to the fallback section.
  `NETWORK:`
    Switches to the online whitelist section.
  `SETTINGS:`
    Switches to the settings section.

  Section header lines must consist of zero or more U+0020 SPACE and U+0009 CHARACTER TABULATION (tab) characters, followed by one of the names above (including the U+003A COLON character (:)) followed by zero or more U+0020 SPACE and U+0009 CHARACTER TABULATION (tab) characters.

  Ironically, by default, the current section is the explicit section.

Data for the current section

  The format that data lines must take depends on the current section.

  When the current section is the explicit section, data lines must consist of zero or more U+0020 SPACE and U+0009 CHARACTER TABULATION (tab) characters, a valid URL identifying a resource other than the manifest itself, and then zero or more U+0020 SPACE and U+0009 CHARACTER TABULATION (tab) characters.

  When the current section is the fallback section, data lines must consist of zero or more U+0020 SPACE and U+0009 CHARACTER TABULATION (tab) characters, a valid URL identifying a resource other than the manifest itself, one or more U+0020 SPACE and U+0009 CHARACTER TABULATION (tab) characters, another valid URL identifying a resource other than the manifest itself, and then zero or more U+0020 SPACE and U+0009 CHARACTER TABULATION (tab) characters.

  When the current section is the online whitelist section, data lines must consist of zero or more U+0020 SPACE and U+0009 CHARACTER TABULATION (tab) characters, either a single U+002A ASTERISK character (*) or a valid URL identifying a resource other than the manifest itself, and then zero or more U+0020 SPACE and U+0009 CHARACTER TABULATION (tab) characters.

  When the current section is the settings section, data lines must consist of zero or more U+0020 SPACE and U+0009 CHARACTER TABULATION (tab) characters, a setting, and then zero or more U+0020 SPACE and U+0009 CHARACTER TABULATION (tab) characters.

  Currently only one setting is defined:

  The cache mode setting
    This consists of the string "`prefer-online`". It sets the cache mode to prefer-online. (The cache mode defaults to fast.)

  Within a settings section, each setting must occur no more than once.

Manifests may contain sections more than once. Sections may be empty.

URLs that are to be fallback pages associated with fallback namespaces, and those namespaces themselves, must be given in fallback sections, with the namespace being the first URL of the data line, and the corresponding fallback page being the second URL. All the other pages to be cached must be listed in explicit sections.

Fallback namespaces and fallback entries must have the same origin as the manifest itself. Fallback namespaces must also be in the same path as the manifest's URL.

A fallback namespace must not be listed more than once.

Namespaces that the user agent is to put into the online whitelist must all be specified in online whitelist sections. (This is needed for any URL that the page is intending to use to communicate back to the server.) To specify that all URLs are automatically whitelisted in this way, a U+002A ASTERISK character (*) may be specified as one of the URLs.

Authors should not include namespaces in the online whitelist for which another namespace in the online whitelist is a prefix match.

Relative URLs must be given relative to the manifest's own URL. All URLs in the manifest must have the same scheme as the manifest itself (either explicitly or implicitly, through the use of relative URLs). [URL]

URLs in manifests must not have fragment identifiers (i.e. the U+0023 NUMBER SIGN character isn't allowed in URLs in manifests).

Fallback namespaces and namespaces in the online whitelist are matched by prefix match.

##### 7.7.3.3 Parsing cache manifests

When a user agent is to parse a manifest, it means that the user agent must run the following steps:

1. UTF-8 decode the byte stream corresponding with the manifest to be parsed.

   The UTF-8 decode algorithm strips a leading BOM, if any.

2. Let base URL be the absolute URL representing the manifest.

3. Apply the URL parser to base URL, and let manifest path be the path component thus obtained.

4. Remove all the characters in manifest path after the last U+002F SOLIDUS character (/), if any. (The first character and the last character in manifest path after this step will both be slashes, the URL path separator character.)

5. Apply the URL parser steps to the base URL, so that the components from its parsed URL can be used by the subseqent steps of this algorithm.

6. Let explicit URLs be an initially empty list of absolute URLs for explicit entries.

7. Let fallback URLs be an initially empty mapping of fallback namespaces to absolute URLs for fallback entries.

8. Let online whitelist namespaces be an initially empty list of absolute URLs for an online whitelist.

9. Let online whitelist wildcard flag be blocking.

10. Let cache mode flag be fast.

11. Let input be the decoded text of the manifest's byte stream.

12. Let position be a pointer into input, initially pointing at the first character.

13. If the characters starting from position are "CACHE", followed by a U+0020 SPACE character, followed by "MANIFEST", then advance position to the next character after those. Otherwise, this isn't a cache manifest; abort this algorithm with a failure while checking for the magic signature.

14. If the character at position is neither a U+0020 SPACE character, a U+0009 CHARACTER TABULATION (tab) character, U+000A LINE FEED (LF) character, nor a U+000D CARRIAGE RETURN (CR) character, then this isn't a cache manifest; abort this algorithm with a failure while checking for the magic signature.

15. This is a cache manifest. The algorithm cannot fail beyond this point (though bogus lines can get ignored).

16. Collect a sequence of characters that are not U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters, and ignore those characters. (Extra text on the first line, after the signature, is ignored.)

17. Let mode be "explicit".

18. Start of line: If position is past the end of input, then jump to the last step. Otherwise, collect a sequence of characters that are U+000A LINE FEED (LF), U+000D CARRIAGE RETURN (CR), U+0020 SPACE, or U+0009 CHARACTER TABULATION (tab) characters.

19. Now, collect a sequence of characters that are not U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters, and let the result be line.

20. Drop any trailing U+0020 SPACE and U+0009 CHARACTER TABULATION (tab) characters at the end of line.

21. If line is the empty string, then jump back to the step labeled start of line.

22. If the first character in line is a U+0023 NUMBER SIGN character (#), then jump back to the step labeled start of line.

23. If line equals "CACHE:" (the word "CACHE" followed by a U+003A COLON character (:)), then set mode to "explicit" and jump back to the step labeled start of line.

24. If line equals "FALLBACK:" (the word "FALLBACK" followed by a U+003A COLON character (:)), then set mode to "fallback" and jump back to the step labeled start of line.

25. If line equals "NETWORK:" (the word "NETWORK" followed by a U+003A COLON character (:)), then set mode to "online whitelist" and jump back to the step labeled start of line.

26. If line equals "SETTINGS:" (the word "SETTINGS" followed by a U+003A COLON character (:)), then set mode to "settings" and jump back to the step labeled start of line.

27. If line ends with a U+003A COLON character (:), then set mode to "unknown" and jump back to the step labeled start of line.

28. This is either a data line or it is syntactically incorrect.

29. Let position be a pointer into line, initially pointing at the start of the string.

30. Let tokens be a list of strings, initially empty.

31. While position doesn't point past the end of line:

    1. Let current token be an empty string.

    2. While position doesn't point past the end of line and the character at position is neither a U+0020 SPACE nor a U+0009 CHARACTER TABULATION (tab) character, add the character at position to current token and advance position to the next character in input.

    3. Add current token to the tokens list.

    4. While position doesn't point past the end of line and the character at position is either a U+0020 SPACE or a U+0009 CHARACTER TABULATION (tab) character, advance position to the next character in input.

32. Process tokens as follows:

    If mode is "explicit"

      Resolve the first item in tokens, relative to base URL, with the URL character encoding set to UTF-8; ignore the rest.

      If this fails, then jump back to the step labeled start of line.

      If the resulting parsed URL has a different scheme component than base URL (the manifest's URL), then jump back to the step labeled start of line.

      Let new URL be the result of applying the URL serialiser algorithm to the resulting parsed URL, with the exclude fragment flag set.

      Add new URL to the explicit URLs.

    If mode is "fallback"

      Let part one be the first token in tokens, and let part two be the second token in tokens.

      Resolve part one and part two, relative to base URL, with the URL character encoding set to UTF-8.

      If either fails, then jump back to the step labeled start of line.

      If the absolute URL corresponding to either part one or part two does not have the same origin as the manifest's URL, then jump back to the step labeled start of line.

      Let part one path be the path component of the resulting parsed URL for part one.

      If manifest path is not a prefix match for part one path, then jump back to the step labeled start of line.

      Let part one be the result of applying the URL serialiser algorithm to the first resulting parsed URL, with the exclude fragment flag set.

      Let part two be the result of applying the URL serialiser algorithm to the second resulting parsed URL, with the exclude fragment flag set.

      If part one is already in the fallback URLs mapping as a fallback namespace, then jump back to the step labeled start of line.

      Otherwise, add part one to the fallback URLs mapping as a fallback namespace, mapped to part two as the fallback entry.

    If mode is "online whitelist"

      If the first item in tokens is a U+002A ASTERISK character (*), then set online whitelist wildcard flag to open and jump back to the step labeled start of line.

      Otherwise, resolve the first item in tokens, relative to base URL, with the URL character encoding set to UTF-8; ignore the rest.

      If this fails, then jump back to the step labeled start of line.

      If the resulting parsed URL has a different scheme component than base URL (the manifest's URL), then jump back to the step labeled start of line.

      Let new URL be the result of applying the URL serialiser algorithm to the resulting parsed URL, with the exclude fragment flag set.

      Add new URL to the online whitelist namespaces.

    If mode is "settings"

      If tokens contains a single token, and that token is a case-sensitive match for the string "`prefer-online`", then set cache mode flag to prefer-online and jump back to the step labeled start of line.

      Otherwise, the line is an unsupported setting: do nothing; the line is ignored.

    If mode is "unknown"

      Do nothing. The line is ignored.

33. Jump back to the step labeled start of line. (That step jumps to the next, and last, step when the end of the file is reached.)

34. Return the explicit URLs list, the fallback URLs mapping, the online whitelist namespaces, the online whitelist wildcard flag, and the cache mode flag.

The resource that declares the manifest (with the `manifest` attribute) will always get taken from the cache, whether it is listed in the cache or not, even if it is listed in an online whitelist namespace.

If a resource is listed in the explicit section or as a fallback entry in the fallback section, the resource will always be taken from the cache, regardless of any other matching entries in the fallback namespaces or online whitelist namespaces.

When a fallback namespace and an online whitelist namespace overlap, the online whitelist namespace has priority.

The online whitelist wildcard flag is applied last, only for URLs that match neither the online whitelist namespace nor the fallback namespace and that are not listed in the explicit section.

#### 7.7.4 Downloading or updating an application cache

When the user agent is required (by other parts of this specification) to start the application cache download process for an absolute URL purported to identify a manifest, or for an application cache group, potentially given a particular cache host, and potentially given a master resource, the user agent must run the steps below. These steps are always run in parallel with the event loop tasks.

Some of these steps have requirements that only apply if the user agent shows caching progress. Support for this is optional. Caching progress UI could consist of a progress bar or message panel in the user agent's interface, or an overlay, or something else. Certain events fired during the application cache download process allow the script to override the display of such an interface. (Such events are delayed until after the `load` event has fired.) The goal of this is to allow Web applications to provide more seamless update mechanisms, hiding from the user the mechanics of the application cache mechanism. User agents may display user interfaces independent of this, but are encouraged to not show prominent update progress notifications for applications that cancel the relevant events.

The application cache download process steps are as follows:

1. Optionally, wait until the permission to start the application cache download process has been obtained from the user and until the user agent is confident that the network is available. This could include doing nothing until the user explicitly opts-in to caching the site, or could involve prompting the user for permission. The algorithm might never get past this point. (This step is particularly intended to be used by user agents running on severely space-constrained devices or in highly privacy-sensitive environments).

2. Atomically, so as to avoid race conditions, perform the following substeps:

   1. Pick the appropriate substeps:

      If these steps were invoked with an absolute URL purported to identify a manifest

        Let manifest URL be that absolute URL.

        If there is no application cache group identified by manifest URL, then create a new application cache group identified by manifest URL. Initially, it has no application caches. One will be created later in this algorithm.

      If these steps were invoked with an application cache group

        Let manifest URL be the absolute URL of the manifest used to identify the application cache group to be updated.

        If that application cache group is obsolete, then abort this instance of the application cache download process. This can happen if another instance of this algorithm found the manifest to be 404 or 410 while this algorithm was waiting in the first step above.

   2. Let cache group be the application cache group identified by manifest URL.

   3. If these steps were invoked with a master resource, then add the resource, along with the resource's `Document`, to cache group's list of pending master entries.

   4. If these steps were invoked with a cache host, and the status of cache group is checking or downloading, then queue a post-load task to fire a simple event named `checking` that is cancelable at the `ApplicationCache` singleton of that cache host. The default action of this event must be, if the user agent shows caching progress, the display of some sort of user interface indicating to the user that the user agent is checking to see if it can download the application.

   5. If these steps were invoked with a cache host, and the status of cache group is downloading, then also queue a post-load task to fire a simple event named `downloading` that is cancelable at the `ApplicationCache` singleton of that cache host. The default action of this event must be, if the user agent shows caching progress, the display of some sort of user interface indicating to the user the application is being downloaded.

   6. If the status of the cache group is either checking or downloading, then abort this instance of the application cache download process, as an update is already in progress.

   7. Set the status of cache group to checking.

   8. For each cache host associated with an application cache in cache group, queue a post-load task to fire a simple event that is cancelable named `checking` at the `ApplicationCache` singleton of the cache host. The default action of these events must be, if the user agent shows caching progress, the display of some sort of user interface indicating to the user that the user agent is checking for the availability of updates.

   The remainder of the steps run in parallel.

   If cache group already has an application cache in it, then this is an upgrade attempt. Otherwise, this is a cache attempt.

3. If this is a cache attempt, then this algorithm was invoked with a cache host; queue a post-load task to fire a simple event named `checking` that is cancelable at the `ApplicationCache` singleton of that cache host. The default action of this event must be, if the user agent shows caching progress, the display of some sort of user interface indicating to the user that the user agent is checking for the availability of updates.

4. Fetching the manifest: Fetch the resource from manifest URL with the blocking flag set, and let manifest be that resource. HTTP caching semantics should be honored for this request. The override referrer source must be null.

   Parse manifest according to the rules for parsing manifests, obtaining a list of explicit entries, fallback entries and the fallback namespaces that map to them, entries for the online whitelist, and values for the online whitelist wildcard flag and the cache mode flag.

   The MIME type of the resource is ignored — it is assumed to be `text/cache-manifest`. In the future, if new manifest formats are supported, the different types will probably be distinguished on the basis of the file signatures (for the current format, that is the "`CACHE MANIFEST`" string at the top of the file).

5. If fetching the manifest fails due to a 404 or 410 response or equivalent, then run these substeps:

   1. Mark cache group as obsolete. This cache group no longer exists for any purpose other than the processing of `Document` objects already associated with an application cache in the cache group.

   2. Let task list be an empty list of tasks.

   3. For each cache host associated with an application cache in cache group, create a task to fire a simple event named `obsolete` that is cancelable at the `ApplicationCache` singleton of the cache host, and append it to task list. The default action of these events must be, if the user agent shows caching progress, the display of some sort of user interface indicating to the user that the application is no longer available for offline use.

   4. For each entry in cache group's list of pending master entries, create a task to fire a simple event that is cancelable named `error` (not `obsolete`!) at the `ApplicationCache` singleton of the `Document` for this entry, if there still is one, and append it to task list. The default action of this event must be, if the user agent shows caching progress, the display of some sort of user interface indicating to the user that the user agent failed to save the application for offline use.

   5. If cache group has an application cache whose completeness flag is incomplete, then discard that application cache.

   6. If appropriate, remove any user interface indicating that an update for this cache is in progress.

   7. Let the status of cache group be idle.

   8. For each task in task list, queue that task as a post-load task.

   9. Abort the application cache download process.

6. Otherwise, if fetching the manifest fails in some other way (e.g. the server returns another 4xx or 5xx response or equivalent, or there is a DNS error, or the connection times out, or the user cancels the download, or the parser for manifests fails when checking the magic signature), or if the server returned a redirect, then run the cache failure steps. [HTTP]

7. If this is an upgrade attempt and the newly downloaded manifest is byte-for-byte identical to the manifest found in the newest application cache in cache group, or the server reported it as "304 Not Modified" or equivalent, then run these substeps:

   1. Let cache be the newest application cache in cache group.

   2. Let task list be an empty list of tasks.

   3. For each entry in cache group's list of pending master entries, wait for the resource for this entry to have either completely downloaded or failed.

      If the download failed (e.g. the server returns a 4xx or 5xx response or equivalent, or there is a DNS error, the connection times out, or the user cancels the download), or if the resource is labeled with the "no-store" cache directive, then create a task to fire a simple event that is cancelable named `error` at the `ApplicationCache` singleton of the `Document` for this entry, if there still is one, and append it to task list. The default action of this event must be, if the user agent shows caching progress, the display of some sort of user interface indicating to the user that the user agent failed to save the application for offline use.

      Otherwise, associate the `Document` for this entry with cache; store the resource for this entry in cache, if it isn't already there, and categorise its entry as a master entry. If applying the URL parser algorithm to the resource's URL results in a parsed URL that has a non-null fragment component, the URL used for the entry in cache must instead be the absolute URL obtained from applying the URL serialiser algorithm to the parsed URL with the exclude fragment flag set (application caches never include fragment identifiers).

   4. For each cache host associated with an application cache in cache group, create a task to fire a simple event that is cancelable named `noupdate` at the `ApplicationCache` singleton of the cache host, and append it to task list. The default action of these events must be, if the user agent shows caching progress, the display of some sort of user interface indicating to the user that the application is up to date.

   5. Empty cache group's list of pending master entries.

   6. If appropriate, remove any user interface indicating that an update for this cache is in progress.

   7. Let the status of cache group be idle.

   8. For each task in task list, queue that task as a post-load task.

   9. Abort the application cache download process.

8. Let new cache be a newly created application cache in cache group. Set its completeness flag to incomplete.

9. For each entry in cache group's list of pending master entries, associate the `Document` for this entry with new cache.

10. Set the status of cache group to downloading.

11. For each cache host associated with an application cache in cache group, queue a post-load task to fire a simple event that is cancelable named `downloading` at the `ApplicationCache` singleton of the cache host. The default action of these events must be, if the user agent shows caching progress, the display of some sort of user interface indicating to the user that a new version is being downloaded.

12. Let file list be an empty list of URLs with flags.

13. Add all the URLs in the list of explicit entries obtained by parsing manifest to file list, each flagged with "explicit entry".

14. Add all the URLs in the list of fallback entries obtained by parsing manifest to file list, each flagged with "fallback entry".

15. If this is an upgrade attempt, then add all the URLs of master entries in the newest application cache in cache group whose completeness flag is complete to file list, each flagged with "master entry".

16. If any URL is in file list more than once, then merge the entries into one entry for that URL, that entry having all the flags that the original entries had.

17. For each URL in file list, run the following steps. These steps may be run in parallel for two or more of the URLs at a time. If, while running these steps, the `ApplicationCache` object's `abort()` method sends a signal to this instance of the application cache download process algorithm, then run the cache failure steps instead.

    1. If the resource URL being processed was flagged as neither an "explicit entry" nor or a "fallback entry", then the user agent may skip this URL.

       This is intended to allow user agents to expire resources not listed in the manifest from the cache. Generally, implementors are urged to use an approach that expires lesser-used resources first.

    2. For each cache host associated with an application cache in cache group, queue a progress post-load task to fire a trusted event with the name `progress`, which does not bubble, which is cancelable, and which uses the `ProgressEvent` interface, at the `ApplicationCache` singleton of the cache host. The `lengthComputable` attribute must be set to true, the `total` attribute must be set to the number of files in file list, and the `loaded` attribute must be set to the number of files in file list that have been either downloaded or skipped so far. The default action of these events must be, if the user agent shows caching progress, the display of some sort of user interface indicating to the user that a file is being downloaded in preparation for updating the application. [XHR]

    3. Fetch the resource, from the origin of the URL manifest URL, with the blocking flag set and the manual redirect flag set. If this is an upgrade attempt, then use the newest application cache in cache group as an HTTP cache, and honor HTTP caching semantics (such as expiration, ETags, and so forth) with respect to that cache. User agents may also have other caches in place that are also honored. The override referrer source must be null.

       If the resource in question is already being downloaded for other reasons then the existing download process can sometimes be used for the purposes of this step, as defined by the fetching algorithm.

       An example of a resource that might already be being downloaded is a large image on a Web page that is being seen for the first time. The image would get downloaded to satisfy the `img` element on the page, as well as being listed in the cache manifest. According to the rules for fetching that image only need be downloaded once, and it can be used both for the cache and for the rendered Web page.

    4. If the previous step fails (e.g. the server returns a 4xx or 5xx response or equivalent, or there is a DNS error, or the connection times out, or the user cancels the download), or if the server returned a redirect, or if the resource is labeled with the "no-store" cache directive, then run the first appropriate step from the following list: [HTTP]

       If the URL being processed was flagged as an "explicit entry" or a "fallback entry"

         If these steps are being run in parallel for any other URLs in file list, then abort these steps for those other URLs. Run the cache failure steps.

         Redirects are fatal because they are either indicative of a network problem (e.g. a captive portal); or would allow resources to be added to the cache under URLs that differ from any URL that the networking model will allow access to, leaving orphan entries; or would allow resources to be stored under URLs different than their true URLs. All of these situations are bad.

       If the error was a 404 or 410 HTTP response or equivalent
       If the resource was labeled with the "no-store" cache directive

         Skip this resource. It is dropped from the cache.

       Otherwise

         Copy the resource and its metadata from the newest application cache in cache group whose completeness flag is complete, and act as if that was the fetched resource, ignoring the resource obtained from the network.

       User agents may warn the user of these errors as an aid to development.

       These rules make errors for resources listed in the manifest fatal, while making it possible for other resources to be removed from caches when they are removed from the server, without errors, and making non-manifest resources survive server-side errors.

       Except for the "no-store" directive, HTTP caching rules that would cause a file to be expired or otherwise not cached are ignored for the purposes of the application cache download process.

    5. Otherwise, the fetching succeeded. Store the resource in the new cache.

       If the user agent is not able to store the resource (e.g. because of quota restrictions), the user agent may prompt the user or try to resolve the problem in some other manner (e.g. automatically pruning content in other caches). If the problem cannot be resolved, the user agent must run the cache failure steps.

    6. If the URL being processed was flagged as an "explicit entry" in file list, then categorise the entry as an explicit entry.

    7. If the URL being processed was flagged as a "fallback entry" in file list, then categorise the entry as a fallback entry.

    8. If the URL being processed was flagged as an "master entry" in file list, then categorise the entry as a master entry.

    9. As an optimization, if the resource is an HTML or XML file whose root element is an `html` element with a `manifest` attribute whose value doesn't match the manifest URL of the application cache being processed, then the user agent should mark the entry as being foreign.

18. For each cache host associated with an application cache in cache group, queue a progress post-load task to fire a trusted event with the name `progress`, which does not bubble, which is cancelable, and which uses the `ProgressEvent` interface, at the `ApplicationCache` singleton of the cache host. The `lengthComputable` attribute must be set to true, the `total` and the `loaded` attributes must be set to the number of files in file list. The default action of these events must be, if the user agent shows caching progress, the display of some sort of user interface indicating to the user that all the files have been downloaded. [XHR]

19. Store the list of fallback namespaces, and the URLs of the fallback entries that they map to, in new cache.

20. Store the URLs that form the new online whitelist in new cache.

21. Store the value of the new online whitelist wildcard flag in new cache.

22. Store the value of the new cache mode flag in new cache.

23. For each entry in cache group's list of pending master entries, wait for the resource for this entry to have either completely downloaded or failed.

    If the download failed (e.g. the server returns a 4xx or 5xx response or equivalent, or there is a DNS error, the connection times out, or the user cancels the download), or if the resource is labeled with the "no-store" cache directive, then run these substeps:

    1. Unassociate the `Document` for this entry from new cache.

    2. Queue a post-load task to fire a simple event that is cancelable named `error` at the `ApplicationCache` singleton of the `Document` for this entry, if there still is one. The default action of this event must be, if the user agent shows caching progress, the display of some sort of user interface indicating to the user that the user agent failed to save the application for offline use.

    3. If this is a cache attempt and this entry is the last entry in cache group's list of pending master entries, then run these further substeps:

       1. Discard cache group and its only application cache, new cache.

       2. If appropriate, remove any user interface indicating that an update for this cache is in progress.

       3. Abort the application cache download process.

    4. Otherwise, remove this entry from cache group's list of pending master entries.

    Otherwise, store the resource for this entry in new cache, if it isn't already there, and categorise its entry as a master entry.

24. Fetch the resource from manifest URL again, with the blocking flag set, and let second manifest be that resource. HTTP caching semantics should again be honored for this request. The override referrer source must be null.

    Since caching can be honored, authors are encouraged to avoid setting the cache headers on the manifest in such a way that the user agent would simply not contact the network for this second request; otherwise, the user agent would not notice if the cache had changed during the cache update process.

25. If the previous step failed for any reason, or if the fetching attempt involved a redirect, or if second manifest and manifest are not byte-for-byte identical, then schedule a rerun of the entire algorithm with the same parameters after a short delay, and run the cache failure steps.

26. Otherwise, store manifest in new cache, if it's not there already, and categorise its entry as the manifest.

27. Set the completeness flag of new cache to complete.

28. Let task list be an empty list of tasks.

29. If this is a cache attempt, then for each cache host associated with an application cache in cache group, create a task to fire a simple event that is cancelable named `cached` at the `ApplicationCache` singleton of the cache host, and append it to task list. The default action of these events must be, if the user agent shows caching progress, the display of some sort of user interface indicating to the user that the application has been cached and that they can now use it offline.

    Otherwise, it is an upgrade attempt. For each cache host associated with an application cache in cache group, create a task to fire a simple event that is cancelable named `updateready` at the `ApplicationCache` singleton of the cache host, and append it to task list. The default action of these events must be, if the user agent shows caching progress, the display of some sort of user interface indicating to the user that a new version is available and that they can activate it by reloading the page.

30. If appropriate, remove any user interface indicating that an update for this cache is in progress.

31. Set the update status of cache group to idle.

32. For each task in task list, queue that task as a post-load task.

The cache failure steps are as follows:

1. Let task list be an empty list of tasks.

2. For each entry in cache group's list of pending master entries, run the following further substeps. These steps may be run in parallel for two or more entries at a time.

   1. Wait for the resource for this entry to have either completely downloaded or failed.

   2. Unassociate the `Document` for this entry from its application cache, if it has one.

   3. Create a task to fire a simple event that is cancelable named `error` at the `ApplicationCache` singleton of the `Document` for this entry, if there still is one, and append it to task list. The default action of these events must be, if the user agent shows caching progress, the display of some sort of user interface indicating to the user that the user agent failed to save the application for offline use.

3. For each cache host still associated with an application cache in cache group, create a task to fire a simple event that is cancelable named `error` at the `ApplicationCache` singleton of the cache host, and append it to task list. The default action of these events must be, if the user agent shows caching progress, the display of some sort of user interface indicating to the user that the user agent failed to save the application for offline use.

4. Empty cache group's list of pending master entries.

5. If cache group has an application cache whose completeness flag is incomplete, then discard that application cache.

6. If appropriate, remove any user interface indicating that an update for this cache is in progress.

7. Let the status of cache group be idle.

8. If this was a cache attempt, discard cache group altogether.

9. For each task in task list, queue that task as a post-load task.

10. Abort the application cache download process.

Attempts to fetch resources as part of the application cache download process may be done with cache-defeating semantics, to avoid problems with stale or inconsistent intermediary caches.

User agents may invoke the application cache download process, in the background, for any application cache group, at any time (with no cache host). This allows user agents to keep caches primed and to update caches even before the user visits a site.

Each `Document` has a list of pending application cache download process tasks that is used to delay events fired by the algorithm above until the document's `load` event has fired. When the `Document` is created, the list must be empty.

When the steps above say to queue a post-load task task, where task is a task that dispatches an event on a target `ApplicationCache` object target, the user agent must run the appropriate steps from the following list:

If target's node document is ready for post-load tasks

  Queue the task task.

Otherwise

  Add task to target's node document's list of pending application cache download process tasks.

When the steps above say to queue a progress post-load task task, where task is a task that dispatches an event on a target `ApplicationCache` object target, the user agent must run the following steps:

1. If there is a task in target's node document's list of pending application cache download process tasks that is labeled as a progress task, then remove that task from the list.

2. Label task as a progress task.

3. Queue a post-load task task.

The task source for these tasks is the networking task source.

#### 7.7.5 The application cache selection algorithm

When the application cache selection algorithm algorithm is invoked with a `Document` document and optionally a manifest URL manifest URL, the user agent must run the first applicable set of steps from the following list:

If there is a manifest URL, and document was loaded from an application cache, and the URL of the manifest of that cache's application cache group is not the same as manifest URL

  Mark the entry for the resource from which document was taken in the application cache from which it was loaded as foreign.

  Restart the current navigation from the top of the navigation algorithm, undoing any changes that were made as part of the initial load (changes can be avoided by ensuring that the step to update the session history with the new page is only ever completed after this application cache selection algorithm is run, though this is not required).

  The navigation will not result in the same resource being loaded, because "foreign" entries are never picked during navigation.

  User agents may notify the user of the inconsistency between the cache manifest and the document's own metadata, to aid in application development.

If document was loaded from an application cache, and that application cache still exists (it is not now obsolete)

  Associate document with the application cache from which it was loaded. Invoke, in the background, the application cache download process for that application cache's application cache group, with document as the cache host.

If document was loaded using HTTP GET or equivalent, and, there is a manifest URL, and manifest URL has the same origin as document

  Invoke, in the background, the application cache download process for manifest URL, with document as the cache host and with the resource from which document was parsed as the master resource.

  If there are relevant application caches that are identified by a URL with the same origin as the URL of document, and that have this URL as one of their entries, excluding entries marked as foreign, then the user agent should use the most appropriate application cache of those that match as an HTTP cache for any subresource loads. User agents may also have other caches in place that are also honored.

Otherwise

  The `Document` is not associated with any application cache.

  If there was a manifest URL, the user agent may report to the user that it was ignored, to aid in application development.

#### 7.7.6 Changes to the networking model

When a cache host is associated with an application cache whose completeness flag is complete, any and all loads for resources related to that cache host other than those for child browsing contexts must go through the following steps instead of immediately invoking the mechanisms appropriate to that resource's scheme:

1. If the resource is not to be fetched using the HTTP GET mechanism or equivalent, or if applying the URL parser algorithm to both its URL and the application cache's manifest's URL results in two parsed URLs with different scheme components, then fetch the resource normally and abort these steps.

2. If the resource's URL is a master entry, the manifest, an explicit entry, or a fallback entry in the application cache, then get the resource from the cache (instead of fetching it), and abort these steps.

3. If there is an entry in the application cache's online whitelist that has the same origin as the resource's URL and that is a prefix match for the resource's URL, then fetch the resource normally and abort these steps.

4. If the resource's URL has the same origin as the manifest's URL, and there is a fallback namespace f in the application cache that is a prefix match for the resource's URL, then:

   Fetch the resource normally. If this results in a redirect to a resource with another origin (indicative of a captive portal), or a 4xx or 5xx status code or equivalent, or if there were network errors (but not if the user canceled the download), then instead get, from the cache, the resource of the fallback entry corresponding to the fallback namespace f. Abort these steps.

5. If the application cache's online whitelist wildcard flag is open, then fetch the resource normally and abort these steps.

6. Fail the resource load as if there had been a generic network error.

The above algorithm ensures that so long as the online whitelist wildcard flag is blocking, resources that are not present in the manifest will always fail to load (at least, after the application cache has been primed the first time), making the testing of offline applications simpler.

#### 7.7.7 Expiring application caches

As a general rule, user agents should not expire application caches, except on request from the user, or after having been left unused for an extended period of time.

Application caches and cookies have similar implications with respect to privacy (e.g. if the site can identify the user when providing the cache, it can store data in the cache that can be used for cookie resurrection). Implementors are therefore encouraged to expose application caches in a manner related to HTTP cookies, allowing caches to be expunged together with cookies and other origin-specific data.

For example, a user agent could have a "delete site-specific data" feature that clears all cookies, application caches, local storage, databases, etc, from an origin all at once.

#### 7.7.8 Disk space

User agents should consider applying constraints on disk usage of application caches, and care should be taken to ensure that the restrictions cannot be easily worked around using subdomains.

User agents should allow users to see how much space each domain is using, and may offer the user the ability to delete specific application caches.

For predictability, quotas should be based on the uncompressed size of data stored.

How quotas are presented to the user is not defined by this specification. User agents are encouraged to provide features such as allowing a user to indicate that certain sites are trusted to use more than the default quota, e.g. by presenting a non-modal user interface while a cache is being updated, or by having an explicit whitelist in the user agent's configuration interface.

#### 7.7.9 Security concerns with offline applications caches

This section is non-normative.

The main risk introduced by offline application caches is that an injection attack can be elevated into persistent site-wide page replacement. This attack involves using an injection vulnerability to upload two files to the victim site. The first file is an application cache manifest consisting of just a fallback entry pointing to the second file, which is an HTML page whose manifest is declared as that first file. Once the user has been directed to that second file, all subsequent accesses to any file covered by the given fallback namespace while either the user or the site is offline will instead show that second file. Targetted denial-of-service attacks or cookie bombing attacks (where the client is made to send so many cookies that the server refuses to process the request) can be used to ensure that the site appears offline.

To mitigate this, manifests can only specify fallbacks that are in the same path as the manifest itself. This means that a content injection upload vulnerability in a particular directory on a server can only be escalated to a take-over of that directory and its subdirectories. If there is no way to inject a file into the root directory, the entire site cannot be taken over.

If a site has been attacked in this way, simply removing the offending manifest might eventually clear the problem, since the next time the manifest is updated, a 404 error will be seen, and the user agent will clear the cache. "Eventually" is the key word here, however; while the attack on the user or server is ongoing, such that connections from an affected user to the affected site are blocked, the user agent will simply assume that the user is offline and will continue to use the hostile manifest. Unfortunately, if a cookie bombing attack has also been used, merely removing the manifest is insufficient; in addition, the server has to be configured to return a 404 or 410 response instead of the 413 "Request Entity Too Large" response.

TLS does not inherently protect a site from this attack, since the attack relies on content being served from the server itself. Not using application caches also does not prevent this attack, since the attack relies on an attacker-provided manifest.

#### 7.7.10 Application cache API

    [Exposed=(Window,SharedWorker)]
    interface ApplicationCache : EventTarget {

      // update status
      const unsigned short UNCACHED = 0;
      const unsigned short IDLE = 1;
      const unsigned short CHECKING = 2;
      const unsigned short DOWNLOADING = 3;
      const unsigned short UPDATEREADY = 4;
      const unsigned short OBSOLETE = 5;
      readonly attribute unsigned short status;

      // updates
      void update();
      void abort();
      void swapCache();

      // events
      attribute EventHandler onchecking;
      attribute EventHandler onerror;
      attribute EventHandler onnoupdate;
      attribute EventHandler ondownloading;
      attribute EventHandler onprogress;
      attribute EventHandler onupdateready;
      attribute EventHandler oncached;
      attribute EventHandler onobsolete;
    };

cache = window . `applicationCache`

  (In a window.) Returns the `ApplicationCache` object that applies to the active document of that `Window`.

cache = self . `applicationCache`

  (In a shared worker.) Returns the `ApplicationCache` object that applies to the current shared worker.

cache . `status`

  Returns the current status of the application cache, as given by the constants defined below.

cache . `update`()

  Invokes the application cache download process.

  Throws an `InvalidStateError` exception if there is no application cache to update.

  Calling this method is not usually necessary, as user agents will generally take care of updating application caches automatically.

  The method can be useful in situations such as long-lived applications. For example, a Web mail application might stay open in a browser tab for weeks at a time. Such an application could want to test for updates each day.

cache . `abort`()

  Cancels the application cache download process.

  This method is intended to be used by Web application showing their own caching progress UI, in case the user wants to stop the update (e.g. because bandwidth is limited).

cache . `swapCache`()

  Switches to the most recent application cache, if there is a newer one. If there isn't, throws an `InvalidStateError` exception.

  This does not cause previously-loaded resources to be reloaded; for example, images do not suddenly get reloaded and style sheets and scripts do not get reparsed or reevaluated. The only change is that subsequent requests for cached resources will obtain the newer copies.

  The `updateready` event will fire before this method can be called. Once it fires, the Web application can, at its leisure, call this method to switch the underlying cache to the one with the more recent updates. To make proper use of this, applications have to be able to bring the new features into play; for example, reloading scripts to enable new features.

  An easier alternative to `swapCache()` is just to reload the entire page at a time suitable for the user, using `location.reload()`.

There is a one-to-one mapping from cache hosts to `ApplicationCache` objects. The `applicationCache` attribute on `Window` objects must return the `ApplicationCache` object associated with the `Window` object's active document. The `applicationCache` attribute on `SharedWorkerGlobalScope` objects must return the `ApplicationCache` object associated with the worker.

A `Window` or `SharedWorkerGlobalScope` object has an associated `ApplicationCache` object even if that cache host has no actual application cache.

The `status` attribute, on getting, must return the current state of the application cache that the `ApplicationCache` object's cache host is associated with, if any. This must be the appropriate value from the following list:

`UNCACHED` (numeric value 0)

  The `ApplicationCache` object's cache host is not associated with an application cache at this time.

`IDLE` (numeric value 1)

  The `ApplicationCache` object's cache host is associated with an application cache whose application cache group's update status is idle, and that application cache is the newest cache in its application cache group, and the application cache group is not marked as obsolete.

`CHECKING` (numeric value 2)

  The `ApplicationCache` object's cache host is associated with an application cache whose application cache group's update status is checking.

`DOWNLOADING` (numeric value 3)

  The `ApplicationCache` object's cache host is associated with an application cache whose application cache group's update status is downloading.

`UPDATEREADY` (numeric value 4)

  The `ApplicationCache` object's cache host is associated with an application cache whose application cache group's update status is idle, and whose application cache group is not marked as obsolete, but that application cache is not the newest cache in its group.

`OBSOLETE` (numeric value 5)

  The `ApplicationCache` object's cache host is associated with an application cache whose application cache group is marked as obsolete.

If the `update()` method is invoked, the user agent must invoke the application cache download process, in the background, for the application cache group of the application cache with which the `ApplicationCache` object's cache host is associated, but without giving that cache host to the algorithm. If there is no such application cache, or if its application cache group is marked as obsolete, then the method must throw an `InvalidStateError` exception instead.

If the `abort()` method is invoked, the user agent must send a signal to the current application cache download process for the application cache group of the application cache with which the `ApplicationCache` object's cache host is associated, if any. If there is no such application cache, or it does not have a current application cache download process, then do nothing.

If the `swapCache()` method is invoked, the user agent must run the following steps:

1. Check that `ApplicationCache` object's cache host is associated with an application cache. If it is not, then throw an `InvalidStateError` exception and abort these steps.

2. Let cache be the application cache with which the `ApplicationCache` object's cache host is associated. (By definition, this is the same as the one that was found in the previous step.)

3. If cache's application cache group is marked as obsolete, then unassociate the `ApplicationCache` object's cache host from cache and abort these steps. (Resources will now load from the network instead of the cache.)

4. Check that there is an application cache in the same application cache group as cache whose completeness flag is complete and that is newer than cache. If there is not, then throw an `InvalidStateError` exception and abort these steps.

5. Let new cache be the newest application cache in the same application cache group as cache whose completeness flag is complete.

6. Unassociate the `ApplicationCache` object's cache host from cache and instead associate it with new cache.

The following are the event handlers (and their corresponding event handler event types) that must be supported, as event handler IDL attributes, by all objects implementing the `ApplicationCache` interface:

Event handler | Event handler event type
--- | ---
`onchecking` | `checking`
`onerror` | `error`
`onnoupdate` | `noupdate`
`ondownloading` | `downloading`
`onprogress` | `progress`
`onupdateready` | `updateready`
`oncached` | `cached`
`onobsolete` | `obsolete`

#### 7.7.11 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.

The `navigator.onLine` attribute must return false if the user agent will not contact the network when the user follows links or when a script requests a remote page (or knows that such an attempt would fail), and must return true otherwise.

When the value that would be returned by the `navigator.onLine` attribute of a `Window` or `WorkerGlobalScope` changes from true to false, the user agent must queue a task to fire a simple event named `offline` at the `Window` or `WorkerGlobalScope` object.

On the other hand, when the value that would be returned by the `navigator.onLine` attribute of a `Window` or `WorkerGlobalScope` changes from false to true, the user agent must queue a task to fire a simple event named `online` at the `Window` or `WorkerGlobalScope` object.

The task source for these tasks is the networking task source.

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

In this example, an indicator is updated as the browser goes online and offline.

    <!DOCTYPE HTML>
    <html>
     <head>
      <title>Online status</title>
      <script>
       function updateIndicator() {
         document.getElementById('indicator').textContent = navigator.onLine ? 'online' : 'offline';
       }
      </script>
     </head>
     <body onload="updateIndicator()" ononline="updateIndicator()" onoffline="updateIndicator()">
      <p>The network is: <span id="indicator">(state unknown)</span>
     </body>
    </html>