HTML 5

Draft Recommendation — 2 December 2008

5 Web browsers

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

5.1 Browsing contexts

A browsing context is a collection of one or more Document objects, and one or more views.

At any one time, one of the Documents in a browsing context is the active document. The collection of Documents is the browsing context's session history.

A view is a user agent interface tied to a particular media used for the presentation of Document objects in some media. A view may be interactive. Each view is represented by an AbstractView object. Each view belongs to a browsing context. [DOM2VIEWS]

The document attribute of an AbstractView object representing a view gives the Document object of the view's browsing context's active document. [DOM2VIEWS]

Events that use the UIEvent interface are related to a specific view (the view in which the event happened); the AbstractView of that view is given in the event object's view attribute. [DOM3EVENTS]

A typical Web browser has one obvious view per browsing context: the browser's window (screen media). If a page is printed, however, a second view becomes evident, that of the print media. The two views always share the same underlying Document, but they have a different presentation of that document. A speech browser also establishes a browsing context, one with a view in the speech media.

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

The main view through which a user primarily interacts with a user agent is the default view.

The default view of a Document is given by the defaultView attribute on the Document object's DocumentView interface. [DOM3VIEWS]

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, and whose character encoding is UTF-8. The Document must have a single child html node, which itself has a single child body node. If the browsing context is created specifically to be immediately navigated, then that initial navigation will have replacement enabled.

The origin of the about:blank Document is set when the Document is created, in a manner dependent on whether the browsing context created is a nested browsing context, as follows:

If the new browsing context is a nested browsing context: The origin of the about:blank Document is the origin of the active document of the new browsing context's parent browsing context at the time of its creation.
If the new browsing context is an auxiliary browsing context: The origin of the about:blank Document is the origin of the active document of the new browsing context's opener browsing context at the time of the new browsing context's creation.
Otherwise: The origin of the about:blank Document is a globally unique identifier assigned when the new browsing context is created.

5.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 an element E in one of its Documents D that nests another browsing context C inside it, then P is said to be the parent browsing context of C, C is said to be a child browsing context of P, C is said to be nested through D, and E is said to be the browsing context container of C.

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 there is a browsing context P that is a child browsing context of A and that is the parent browsing context of B.

The browsing context with no parent browsing context is the top-level browsing context of all the browsing contexts nested within it (either directly or indirectly through other nested browsing contexts).

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

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 the Document through which that browsing context 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 Documents 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.

5.1.1.1 Navigating nested browsing contexts in the DOM

The top DOM attribute on the Window object of a browsing context b must return the Window object of its top-level browsing context (which would be its own Window object if it was a top-level browsing context itself).

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

The frameElement DOM attribute on the Window object of a browsing context b, on getting, must run the following algorithm:

If b is not a child browsing context, return null and abort these steps.
If the parent browsing context's active document does not have the same effective script origin as the script that is accessing the frameElement attribute, then throw a SECURITY_ERR exception.
Otherwise, return the browsing context container for b.

5.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, and it has a furthest ancestor browsing context, which is the top-level browsing context of the opener browsing context when the auxiliary browsing context was created.

5.1.2.1 Navigating auxiliary browsing contexts in the DOM

The opener DOM attribute on the Window object must return the Window object of the browsing context from which the current browsing context was created (its opener browsing context), if there is one and it is still available.

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

5.1.4 Security

A browsing context A is allowed to navigate 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 and its top-level browsing context is B, or
The browsing context B is an auxiliary browsing context and A is allowed to navigate 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).

5.1.5 Groupings of browsing contexts

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

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

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

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.

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 _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.
If the given browsing context name is _top, then the chosen browsing context must be the most top-level browsing context of the current one.
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 allowed to navigate 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.
Otherwise, a new browsing context is being requested, and what happens depends on the user agent's configuration and/or abilities:

If the current browsing context has the sandboxed navigation browsing context flag set.

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). Otherwise (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) there must not be a chosen browsing context.

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

5.2 The default view

The AbstractView object of default views must also implement the Window and EventTarget interfaces.

[NoInterfaceObject] interface Window {
  // the current browsing context
  readonly attribute Window window;
  readonly attribute Window self;
           attribute DOMString name;
  [PutForwards=href] readonly attribute Location location;
  readonly attribute History history;
  readonly attribute UndoManager undoManager;
  Selection getSelection();

  // other browsing contexts
  readonly attribute Window frames;
  readonly attribute unsigned long length;
  [IndexGetter] Window XXX4(in unsigned long index); 
  readonly attribute Window top;
  readonly attribute Window opener;
  readonly attribute Window parent;
  readonly attribute Element frameElement;
  Window open();
  Window open(in DOMString url);
  Window open(in DOMString url, in DOMString target);
  Window open(in DOMString url, in DOMString target, in DOMString features);
  Window open(in DOMString url, in DOMString target, in DOMString features, in DOMString replace);

  // the user agent
  readonly attribute Navigator navigator; 
  readonly attribute Storage localStorage;
  readonly attribute Storage sessionStorage;
  Database openDatabase(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize);

  // user prompts
  void alert(in DOMString message);
  boolean confirm(in DOMString message);
  DOMString prompt(in DOMString message);
  DOMString prompt(in DOMString message, in DOMString default);
  void print();
  any showModalDialog(in DOMString url);
  any showModalDialog(in DOMString url, in any arguments);
  void showNotification(in DOMString title, in DOMString subtitle, in DOMString description);
  void showNotification(in DOMString title, in DOMString subtitle, in DOMString description, in VoidCallback onclick);

  // cross-document messaging
  void postMessage(in DOMString message, in DOMString targetOrigin);
  void postMessage(in DOMString message, in MessagePort messagePort, in DOMString targetOrigin);

  // event handler DOM attributes
           attribute EventListener onabort;
           attribute EventListener onbeforeunload;
           attribute EventListener onblur;
           attribute EventListener onchange;
           attribute EventListener onclick;
           attribute EventListener oncontextmenu;
           attribute EventListener ondblclick;
           attribute EventListener ondrag;
           attribute EventListener ondragend;
           attribute EventListener ondragenter;
           attribute EventListener ondragleave;
           attribute EventListener ondragover;
           attribute EventListener ondragstart;
           attribute EventListener ondrop;
           attribute EventListener onerror;
           attribute EventListener onfocus;
           attribute EventListener onhashchange;
           attribute EventListener onkeydown;
           attribute EventListener onkeypress;
           attribute EventListener onkeyup;
           attribute EventListener onload;
           attribute EventListener onmessage;
           attribute EventListener onmousedown;
           attribute EventListener onmousemove;
           attribute EventListener onmouseout;
           attribute EventListener onmouseover;
           attribute EventListener onmouseup;
           attribute EventListener onmousewheel;
           attribute EventListener onresize;
           attribute EventListener onscroll;
           attribute EventListener onselect;
           attribute EventListener onstorage;
           attribute EventListener onsubmit;
           attribute EventListener onunload;
};

// VoidCallback waiting on WebIDL

The window, frames, and self DOM attributes must all return the Window object itself.

The Window object also provides the scope for script execution. Each Document in a browsing context has an associated list of added properties that, when a document is active, are available on the Document's default view's Window object. A Document object's list of added properties must be empty when the Document object is created.

5.2.1 Security

User agents must raise a SECURITY_ERR exception whenever any of the members of a Window object are accessed by scripts whose effective script origin is not the same as the Window object's browsing context's active document's effective script origin, with the following exceptions:

The location object
The postMessage() method with two arguments
The postMessage() method with three arguments
The frames attribute
The XXX4 method

User agents must not allow scripts to override the location object's setter.

5.2.2 APIs for creating and navigating browsing contexts by name

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

The method has four arguments, though they are all optional.

The first argument, url, must be a valid URL for a page to load in the browsing context. If no arguments are provided, or if the first argument is the empty string, then the url argument defaults to "about:blank". The argument must be resolved to an absolute URL (or an error) when the method is invoked.

The second argument, target, specifies the name of the browsing context that is to be navigated. It must be a valid browsing context name or keyword. If fewer than two arguments are provided, then the name argument defaults to the value "_blank".

The third argument, features, has no effect and is supported for historical reasons only.

The fourth argument, replace, specifies whether or not the new page will replace the page currently loaded in the browsing context, when target identifies an existing browsing context (as opposed to leaving the current page in the browsing context's session history). When three or fewer arguments are provided, replace defaults to false.

When the method is invoked, the user agent must first select a browsing context to navigate by applying the rules for choosing a browsing context given a browsing context name using the target argument as the name and the browsing context of the script as the context in which the algorithm is executed, unless the user has indicated a preference, in which case the browsing context to navigate may instead be the one indicated by the user.

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.

Then, the user agent must navigate the selected browsing context to the absolute URL (or error) obtained from resolving url. If the replace is true, then replacement must be enabled; otherwise, it must not be enabled unless the browsing context was just created as part of the the rules for choosing a browsing context given a browsing context name. The navigation must be done with the script browsing context of the script that invoked the method as the source browsing context.

The method must return the Window object of the default view of the browsing context that was navigated, or null if no browsing context was navigated.

The name attribute of the Window object must, on getting, return the current name of the browsing context, 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.

5.2.3 Accessing other browsing contexts

The length DOM attribute on the Window interface must return the number of child browsing contexts of the active Document.

The XXX4(index) method must return the indexth child browsing context of the active Document, sorted in document order of the elements nesting those browsing contexts.

5.3 Origin

The origin of a resource and the effective script origin of a resource are both either opaque identifiers or 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.

These characteristics are defined as follows:

For URLs

The origin and effective script origin of the URL is whatever is returned by the following algorithm:

Let url be the URL for which the origin is being determined.
Parse url.
If url does not use a server-based naming authority, or if parsing url failed, or if url is not an absolute URL, then return a new globally unique identifier.
Let scheme be the <scheme> component of url, converted to lowercase.
If the UA doesn't support the protocol given by scheme, then return a new globally unique identifier.
If scheme is "file", then the user agent may return a UA-specific value.
Let host be the <host> component of url.
Apply the IDNA ToASCII algorithm to host, with both the AllowUnassigned and UseSTD3ASCIIRules flags set. Let host be the result of the ToASCII algorithm.

If ToASCII fails to convert one of the components of the string, e.g. because it is too long or because it contains invalid characters, then return a new globally unique identifier. [RFC3490]
Let host be the result of converting host to lowercase.
If there is no <port> component, then let port be the default port for the protocol given by scheme. Otherwise, let port be the <port> component of url.
Return the tuple (scheme, host, port).

In addition, if the URL is in fact associated with a Document object that was created by parsing the resource obtained from fetching URL, and this was done over a secure connection, then the server's secure certificate may be added to the origin as additional data.

For scripts

The origin and effective script origin of a script are determined from another resource, called the owner:

If a script is in a script element: The owner is the Document to which the script element belongs.
If a script is in an event handler content attribute: The owner is the Document to which the attribute node belongs.
If a script is a function or other code reference created by another script: The owner is the script that created it.
If a script is a javascript: URL that was returned as the location of an HTTP redirect (or equivalent in other protocols): The owner is the URL that redirected to the javascript: URL.
If a script is a javascript: URL in an attribute: The owner is the Document of the element on which the attribute is found.
If a script is a javascript: URL in a style sheet: The owner is the URL of the style sheet.
If a script is a javascript: URL to which a browsing context is being navigated, the URL having been provided by the user (e.g. by using a bookmarklet): The owner is the Document of the browsing context's active document.
If a script is a javascript: URL to which a browsing context is being navigated, the URL having been declared in markup: The owner is the Document of the element (e.g. an a or area element) that declared the URL.
If a script is a javascript: URL to which a browsing context is being navigated, the URL having been provided by script: The owner is the script that provided the URL.

The origin of the script is then equal to the origin of the owner, and the effective script origin of the script is equal to the effective script origin of the owner.

For Document objects and images

If a Document is in a browsing context whose sandboxed origin browsing context flag is set: The origin is a globally unique identifier assigned when the Document is created.
If a Document or image was returned by the XMLHttpRequest API: The origin and effective script origin are equal to the origin and effective script origin of the Document object that was the active document of the browsing context of the Window object from which the XMLHttpRequest constructor was invoked. (That is, they track the Document to which the XMLHttpRequest object's Document pointer pointed when it was created.) [XHR]
If a Document or image was generated from a javascript: URL: The origin is equal to the origin of the script of that javascript: URL.
If a Document or image was served over the network and has an address that uses a URL scheme with a server-based naming authority: The origin is the origin of the address of the Document or the URL of the image, as appropriate.
If a Document or image was generated from a data: URL that was returned as the location of an HTTP redirect (or equivalent in other protocols): The origin is the origin of the URL that redirected to the data: URL.
If a Document or image was generated from a data: URL found in another Document or in a script: The origin is the origin of the Document or script in which the data: URL was found.
If a Document has the address "about:blank": The origin of the Document is the origin it was assigned when its browsing context was created.
If a Document or image was obtained in some other manner (e.g. a data: URL typed in by the user, a Document created using the createDocument() API, a data: URL returned as the location of an HTTP redirect, etc): The origin is a globally unique identifier assigned when the Document or image is created.

When a Document is created, unless stated otherwise above, its effective script origin is initialized to the origin of the Document. However, the document.domain attribute can be used to change it.

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

If the origin in question is not a scheme/host/port tuple, then return the literal string "null" and abort these steps.
Otherwise, let result be the scheme part of the origin tuple.
Append the string "://" to result.
Apply the IDNA ToUnicode 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.
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.
Return result.

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

If the origin in question is not a scheme/host/port tuple, then return the literal string "null" and abort these steps.
Otherwise, let result be the scheme part of the origin tuple.
Append the string "://" to result.
Apply the IDNA ToASCII algorithm the host part of the origin tuple, with both the AllowUnassigned and UseSTD3ASCIIRules flags set, and append the results result.

If ToASCII fails to convert one of the components of the string, e.g. because it is too long or because it contains invalid characters, then return the empty string and abort these steps. [RFC3490]
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.
Return result.

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

Let A be the first origin being compared, and B be the second origin being compared.
If A and B are both opaque identifiers, and their value is equal, then return true.
Otherwise, if either A or B or both are opaque identifiers, return false.
If A and B have scheme components that are not identical, return false.
If A and B have host components that are not identical, return false.
If A and B have port components that are not identical, return false.
If either A or B have additional data, but that data is not identical for both, return false.
Return true.

5.3.1 Relaxing the same-origin restriction

The domain attribute on Document objects must be initialized to the document's domain, if it has one, and the empty string otherwise. On getting, the attribute must return its current value, unless the document was created by XMLHttpRequest, in which case it must throw an INVALID_ACCESS_ERR exception. On setting, the user agent must run the following algorithm:

If the document was created by XMLHttpRequest, throw an INVALID_ACCESS_ERR exception and abort these steps.
Apply the IDNA ToASCII algorithm to the new value, with both the AllowUnassigned and UseSTD3ASCIIRules flags set. Let new value be the result of the ToASCII algorithm.

If ToASCII fails to convert one of the components of the string, e.g. because it is too long or because it contains invalid characters, then throw a SECURITY_ERR exception and abort these steps. [RFC3490]
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 IP address, throw a SECURITY_ERR 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 SECURITY_ERR exception and abort these steps.
Set the attribute's value to new value.
Set the host part of the effective script origin tuple of the Document to new value.
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 that 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.

5.4 Scripting

Various mechanisms can cause author-provided executable code to run in the context of a document. These mechanisms include, but are probably not limited to:

Processing of script elements.
Processing of inline javascript: URLs (e.g. the src attribute of img elements, or an @import rule in a CSS style element block).
Event handlers, whether registered through the DOM using addEventListener(), by explicit event handler content attributes, by event handler DOM attributes, or otherwise.
Processing of technologies like XBL or SVG that have their own scripting features.

When a script is created, it is associated with a script execution context, a script browsing context, and a script document context.

5.4.1 Script execution contexts

The script execution context of a script is defined when that script is created. In this specification, it is either a Window object or an empty object; other specifications might make the script execution context be some other object.

When the script execution context of a script is an empty object, it can't do anything that interacts with the environment.

A script execution context always has an associated browsing context, known as the script browsing context. If the script execution context is a Window object, then that object's browsing context is it. Otherwise, the script execution context is associated explicitly with a browsing context when it is created.

Every script whose script execution context is a Window object is also associated with a Document object, known as its script document context. It is used to resolve URLs. The document is assigned when the script is created, as with the script browsing context.

It is said that scripting is disabled in a script execution context when any of the following conditions are true:

The user agent does not support scripting.
The user has disabled scripting for this script execution context. (User agents may provide users with the option to disable scripting globally, on a per-origin basis, or in other ways down to the granularity of individual script execution contexts.)
The script execution context's associated browsing context's active document has designMode enabled.
The script execution context's associated browsing context has the sandboxed scripts browsing context flag set.

A node is said to be without script if either the Document object of the node (the node itself, if it is itself a Document object) does not have an associated browsing context, or scripting is disabled in that browsing context.

A node is said to be with script if it is not without script.

If you can find a better pair of terms than "with script" and "without script" let me know. The only things I can find that are less confusing are also way, way longer.

When a script is to be executed in a script execution context in which scripting is disabled, the script must do nothing and return nothing (a void return value).

Thus, for instance, enabling designMode will disable any event handler attributes, event listeners, timeouts, etc, that were set by scripts in the document.

5.4.2 Event loops

To coordinate events, user interaction, scripts, rendering, networking, and so forth, user agents must use event loops as described in this section.

There must be at least one event loop per user agent, and at most one event loop per unit of related similar-origin browsing contexts.

An event loop always has at least one browsing context. If an event loop's browsing contexts all go away, then the event loop goes away as well. A browsing context always has an event loop coordinating its activities.

An event loop has one or more task queues. A task queue is an ordered list of tasks, which can be:

Events

Asynchronously dispatching an Event object at a particular EventTarget object is a task.

Not all events are dispatched using the task queue, many are dispatched synchronously during other tasks.

Parsing

The HTML parser tokenising a single byte, and then processing any resulting tokens, is a task.

Callbacks

Calling a callback asynchronously is a task.

Using a resource

When an algorithm fetches a resource, if the fetching occurs asynchronously then the processing of the resource once some or all of the resource is available is a task.

Reacting to DOM manipulation

Some elements have tasks that trigger in response to DOM manipulation, e.g. when that element is inserted into the document.

When a user agent is to queue a task, it must add the given task to one of the task queues of the relevant event loop. All the tasks from one particular task source (e.g. the callbacks generated by timers, the events dispatched for mouse movements, the tasks queued for the parser) must always be added to the same task queue, but tasks from different task sources may be placed in different task queues.

For example, a user agent could have one task queue for mouse and key events (the user interaction task source), and another for everything else. The user agent could then give keyboard and mouse events preference over other tasks three quarters of the time, keeping the interface responsive but not starving other task queues, and never processing events from any one task source out of order.

An event loop must continually run through the following steps for as long as it exists:

Run the oldest task on one of the event loop's task queues. The user agent may pick any task queue.
Remove that task from its task queue.
If necessary, update the rendering or user interface of any Document or browsing context to reflect the current state.
Return to the first step of the event loop.

5.4.2.1 Generic task sources

The following task sources are used by a number of mostly unrelated features in this and other specifications.

The DOM manipulation task source

This task source is used for features that react to DOM manipulations, such as things that happen asynchronously when an element is inserted into the document.

Asynchronous mutation events must be dispatched using tasks queued with the DOM manipulation task source. [DOMEVENTS]

The user interaction task source

This task source is used for features that react to user interaction, for example keyboard or mouse input.

Asynchronous events sent in response to user input (e.g. click events) must be dispatched using tasks queued with the user interaction task source. [DOMEVENTS]

The networking task source

This task source is used for features that trigger in response to network activity.

5.4.3 The `javascript:` protocol

A URL using the javascript: protocol must, if and when dereferenced, be evaluated by executing the script obtained using the content retrieval operation defined for javascript: URLs. [JSURL]

When a browsing context is navigated to a javascript: URL, and the active document of that browsing context has the same origin as the script given by that URL, the script execution context must be the Window object of the browsing context being navigated, and the script document context must be that active document.

When a browsing context is navigated to a javascript: URL, and the active document of that browsing context has an origin that is not the same as that of the script given by the URL, the script execution context must be an empty object, and the script browsing context must be the browsing context being navigated.

Otherwise, if the Document object of the element, attribute, or style sheet from which the javascript: URL was reached has an associated browsing context, the script execution context must be an empty object, and the script execution context's associated browsing context must be that browsing context.

Otherwise, the script is not executed and its return value is void.

If the result of executing the script is void (there is no return value), then the URL must be treated in a manner equivalent to an HTTP resource with an HTTP 204 No Content response.

Otherwise, the URL must be treated in a manner 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.

Certain contexts, in particular img elements, ignore the Content-Type metadata.

So for example a javascript: URL for a src attribute of an img element would be evaluated in the context of an empty object as soon as the attribute is set; it would then be sniffed to determine the image type and decoded as an image.

A javascript: URL in an href attribute of an a element would only be evaluated when the link was followed.

The src attribute of an iframe element would be evaluated in the context of the iframe's own browsing context; once evaluated, its return value (if it was not void) would replace that browsing context's document, thus changing the variables visible in that browsing context.

The rules for handling script execution in a script execution context include making the script not execute (and just return void) in certain cases, e.g. in a sandbox or when the user has disabled scripting altogether.

5.4.4 Events

We need to define how to handle events that are to be fired on a Document that is no longer the active document of its browsing context, and for Documents that have no browsing context. Do the events fire? Do the handlers in that document not fire? Do we just define scripting to be disabled when the document isn't active, with events still running as is? See also the script element section, which says scripts don't run when the document isn't active.

5.4.4.1 Event handler attributes

HTML elements can have event handler attributes specified. These act as bubbling event listeners for the element on which they are specified.

Each event handler attribute has two parts, an event handler content attribute and an event handler DOM attribute. Event handler attributes must initially be set to null. When their value changes (through the changing of their event handler content attribute or their event handler DOM attribute), they will either be null, or have an EventListener object assigned to them.

Objects other than Element objects, in particular Window, only have event handler DOM attribute (since they have no content attributes).

Event handler content attributes, when specified, must contain valid ECMAScript code matching the ECMAScript FunctionBody production. [ECMA262]

When an event handler content attribute is set, if the element is owned by a Document that is in a browsing context, its new value must be interpreted as the body of an anonymous function with a single argument called event, with the new function's scope chain being linked from the activation object of the handler, to the element, to the element's form element if it is a form control, to the Document object, to the Window object of the browsing context of that Document. The function's this parameter must be the Element object representing the element. The resulting function must then be set as the value of the corresponding event handler attribute, and the new value must be set as the value of the content attribute. If the given function body fails to compile, then the corresponding event handler attribute must be set to null instead (the content attribute must still be updated to the new value, though).

See ECMA262 Edition 3, sections 10.1.6 and 10.2.3, for more details on activation objects. [ECMA262]

The script execution context of the event handler must be the Window object at the end of the scope chain. The script document context of the event handler must be the Document object that owns the event handler content attribute that was set.

When an event handler content attribute is set on an element owned by a Document that is not in a browsing context, the corresponding event handler attribute is not changed.

Removing an event handler content attribute does not reset the corresponding event handler attribute either.

How do we allow non-JS event handlers?

Event handler DOM attributes, on setting, must set the corresponding event handler attribute to their new value, and on getting, must return whatever the current value of the corresponding event handler attribute is (possibly null).

The following are the event handler attributes that must be supported by all HTML elements, as both content attributes and DOM attributes, and on Window objects, as DOM attributes:

onabort

Must be invoked whenever an abort event is targeted at or bubbles through the element.

onbeforeunload

Must be invoked whenever a beforeunload event is targeted at or bubbles through the element.

onblur

Must be invoked whenever a blur event is targeted at or bubbles through the element.

onchange

Must be invoked whenever a change event is targeted at or bubbles through the element.

onclick

Must be invoked whenever a click event is targeted at or bubbles through the element.

oncontextmenu

Must be invoked whenever a contextmenu event is targeted at or bubbles through the element.

ondblclick

Must be invoked whenever a dblclick event is targeted at or bubbles through the element.

ondrag

Must be invoked whenever a drag event is targeted at or bubbles through the element.

ondragend

Must be invoked whenever a dragend event is targeted at or bubbles through the element.

ondragenter

Must be invoked whenever a dragenter event is targeted at or bubbles through the element.

ondragleave

Must be invoked whenever a dragleave event is targeted at or bubbles through the element.

ondragover

Must be invoked whenever a dragover event is targeted at or bubbles through the element.

ondragstart

Must be invoked whenever a dragstart event is targeted at or bubbles through the element.

ondrop

Must be invoked whenever a drop event is targeted at or bubbles through the element.

onerror

Must be invoked whenever an error event is targeted at or bubbles through the element.

The onerror handler is also used for reporting script errors.

onfocus

Must be invoked whenever a focus event is targeted at or bubbles through the element.

onhashchange

Must be invoked whenever a hashchange event is targeted at or bubbles through the element.

onkeydown

Must be invoked whenever a keydown event is targeted at or bubbles through the element.

onkeypress

Must be invoked whenever a keypress event is targeted at or bubbles through the element.

onkeyup

Must be invoked whenever a keyup event is targeted at or bubbles through the element.

onload

Must be invoked whenever a load event is targeted at or bubbles through the element.

onmessage

Must be invoked whenever a message event is targeted at or bubbles through the element.

onmousedown

Must be invoked whenever a mousedown event is targeted at or bubbles through the element.

onmousemove

Must be invoked whenever a mousemove event is targeted at or bubbles through the element.

onmouseout

Must be invoked whenever a mouseout event is targeted at or bubbles through the element.

onmouseover

Must be invoked whenever a mouseover event is targeted at or bubbles through the element.

onmouseup

Must be invoked whenever a mouseup event is targeted at or bubbles through the element.

onmousewheel

Must be invoked whenever a mousewheel event is targeted at or bubbles through the element.

onresize

Must be invoked whenever a resize event is targeted at or bubbles through the element.

onscroll

Must be invoked whenever a scroll event is targeted at or bubbles through the element.

onselect

Must be invoked whenever a select event is targeted at or bubbles through the element.

onstorage

Must be invoked whenever a storage event is targeted at or bubbles through the element.

onsubmit

Must be invoked whenever a submit event is targeted at or bubbles through the element.

onunload

Must be invoked whenever an unload event is targeted at or bubbles through the element.

When an event handler attribute is invoked, its argument must be set to the Event object of the event in question. If the function returns the exact boolean value false, the event's preventDefault() method must then invoked. Exception: for historical reasons, for the HTML mouseover event, the preventDefault() method must be called when the function returns true instead.

All event handler attributes on an element, whether set to null or to a function, must be registered as event listeners on the element, as if the addEventListenerNS() method on the Element object's EventTarget interface had been invoked when the element was created, with the event type (type argument) equal to the type described for the event handler attribute in the list above, the namespace (namespaceURI argument) set to null, the listener set to be a target and bubbling phase listener (useCapture argument set to false), the event group set to the default group (evtGroup argument set to null), and the event listener itself (listener argument) set to do nothing while the event handler attribute is null, and set to invoke the function associated with the event handler attribute otherwise. (The listener argument is emphatically not the event handler attribute itself.)

5.4.4.2 Event firing

maybe this should be moved higher up (terminology? conformance? DOM?) Also, the whole terminology thing should be changed so that we don't define any specific events here, we only define 'simple event', 'progress event', 'mouse event', 'key event', and the like, and have the actual dispatch use those generic terms when firing events.

Certain operations and methods are defined as firing events on elements. For example, the click() method on the HTMLElement interface is defined as firing a click event on the element. [DOM3EVENTS]

Firing a click event means that a click event with no namespace, which bubbles and is cancelable, and which uses the MouseEvent interface, must be dispatched at the given element. The event object must have its screenX, screenY, clientX, clientY, and button attributes set to 0, its ctrlKey, shiftKey, altKey, and metaKey attributes set according to the current state of the key input device, if any (false for any keys that are not available), its detail attribute set to 1, and its relatedTarget attribute set to null. The getModifierState() method on the object must return values appropriately describing the state of the key input device at the time the event is created.

Firing a contextmenu event means that a contextmenu event with no namespace, which bubbles and is cancelable, and which uses the Event interface, must be dispatched at the given element.

Firing a simple event called e means that an event with the name e, with no namespace, which does not bubble but is cancelable (unless otherwise stated), and which uses the Event interface, must be dispatched at the given element.

Firing a show event means firing a simple event called show. Actually this should fire an event that has modifier information (shift/ctrl etc), as well as having a pointer to the node on which the menu was fired, and with which the menu was associated (which could be an ancestor of the former).

Firing a load event means firing a simple event called load. Firing an error event means firing a simple event called error.

Firing a progress event called e means something that hasn't yet been defined, in the [PROGRESS] spec.

The default action of these event is to do nothing unless otherwise stated.

If you dispatch a custom "click" event at an element that would normally have default actions, should they get triggered? If so, we need to go through the entire spec and make sure that any default actions are defined in terms of any event of the right type on that element, not those that are dispatched in expected ways.

5.4.4.3 Events and the `Window` object

When an event is dispatched at a DOM node in a Document in a browsing context, if the event is not a load event, the user agent must also dispatch the event to the Window, as follows:

In the capture phase, the event must be dispatched to the Window object before being dispatched to any of the nodes.
In the bubble phase, the event must be dispatched to the Window object at the end of the phase, unless bubbling has been prevented.

5.4.4.4 Runtime script errors

This section only applies to user agents that support scripting in general and ECMAScript in particular.

Whenever a runtime script error occurs in one of the scripts associated with the document, the value of the onerror event handler DOM attribute of the Window object must be processed, as follows:

If the value is a function

The function referenced by the onerror attribute must be invoked with three arguments, before notifying the user of the error.

The three arguments passed to the function are all DOMStrings; the first must give the message that the UA is considering reporting, the second must give the absolute URL of the resource in which the error occurred, and the third must give the line number in that resource on which the error occurred.

If the function returns false, then the error should not be reported to the user. Otherwise, if the function returns another value (or does not return at all), the error should be reported to the user.

Any exceptions thrown or errors caused by this function must be reported to the user immediately after the error that the function was called for, without calling the function again.

If the value is null

The error should not reported to the user.

If the value is anything else

The error should be reported to the user.

The initial value of onerror must be undefined.

5.5 User prompts

5.5.1 Simple dialogs

The alert(message) method, when invoked, must show the given message to the user. The user agent may make the method wait for the user to acknowledge the message before returning; if so, the user agent must pause while the method is waiting.

The confirm(message) method, when invoked, must show the given message to the user, and ask the user to respond with a positive or negative response. The user agent must then pause as the method waits for the user's response. If the user responds positively, the method must return true, and if the user responds negatively, the method must return false.

The prompt(message, default) method, when invoked, must show the given message to the user, and ask the user to either respond with a string value or abort. The user agent must then pause as the method waits for the user's response. The second argument is optional. If the second argument (default) is present, then the response must be defaulted to the value given by default. If the user aborts, then the method must return null; otherwise, the method must return the string that the user responded with.

5.5.2 Printing

The print() method, when invoked, must run the printing steps.

User agents should also run the printing steps whenever the user attempts to obtain a physical form (e.g. printed copy), or the representation of a physical form (e.g. PDF copy), of a document.

The printing steps are as follows:

The user agent may display a message to the user and/or may abort these steps.

For instance, a kiosk browser could silently ignore any invocations of the print() method.

For instance, a browser on a mobile device could detect that there are no printers in the vicinity and display a message saying so before continuing to offer a "save to PDF" option.
The user agent must fire a simple event called beforeprint at the Window object of the browsing context of the Document that is being printed, as well as any nested browsing contexts in it.

The beforeprint event can be used to annotate the printed copy, for instance adding the time at which the document was printed.
The user agent should offer the user the opportunity to obtain a physical form (or the representation of a physical form) of the document. The user agent may wait for the user to either accept or decline before returning; if so, the user agent must pause while the method is waiting. Even if the user agent doesn't wait at this point, the user agent must use the state of the relevant documents as they are at this point in the algorithm if and when it eventually creates the alternate form.
The user agent must fire a simple event called afterprint at the Window object of the browsing context of the Document that is being printed, as well as any nested browsing contexts in it.

The afterprint event can be used to revert annotations added in the earlier event, as well as showing post-printing UI. For instance, if a page is walking the user through the steps of applying for a home loan, the script could automatically advance to the next step after having printed a form or other.

5.5.3 Dialogs implemented using separate documents

The showModalDialog(url, arguments) method, when invoked, must cause the user agent to run the following steps:

If the user agent is configured such that this invocation of showModalDialog() is somehow disabled, then the method returns the empty string; abort these steps.

User agents are expected to disable this method in certain cases to avoid user annoyance. For instance, a user agent could require that a site be white-listed before enabling this method, or the user agent could be configured to only allow one modal dialog at a time.
Let the list of background browsing contexts be a list of all the browsing contexts that:
- are part of the same unit of related browsing contexts as the browsing context of the Window object on which the showModalDialog() method was called, and that
- have an active document whose origin is the same as the origin of the script that called the showModalDialog() method at the time the method was called,
...as well as any browsing contexts that are nested inside any of the browsing contexts matching those conditions.
Disable the user interface for all the browsing contexts in the list of background browsing contexts. This should prevent the user from navigating those browsing contexts, causing events to to be sent to those browsing context, or editing any content in those browsing contexts. However, it does not prevent those browsing contexts from receiving events from sources other than the user, from running scripts, from running animations, and so forth.
Create a new auxiliary browsing context, with the opener browsing context being the browsing context of the Window object on which the showModalDialog() method was called. The new auxiliary browsing context has no name.

This browsing context implements the ModalWindow interface.
Let the dialog arguments of the new browsing context be set to the value of arguments.
Let the dialog arguments' origin be the origin of the script that called the showModalDialog() method.
Navigate the new browsing context to url, with replacement enabled, and with the script browsing context of the script that invoked the method as the source browsing context.
Wait for the browsing context to be closed. (The user agent must allow the user to indicate that the browsing context is to be closed.)
Reenable the user interface for all the browsing contexts in the list of background browsing contexts.
Return the auxiliary browsing context's return value.

Browsing contexts created by the above algorithm must implement the ModalWindow interface:

[XXX] interface ModalWindow {
  readonly attribute any dialogArguments;
           attribute DOMString returnValue;
};

Such browsing contexts have associated dialog arguments, which are stored along with the dialog arguments' origin. These values are set by the showModalDialog() method in the algorithm above, when the browsing context is created, based on the arguments provided to the method.

The dialogArguments DOM attribute, on getting, must check whether its browsing context's active document's origin is the same as the dialog arguments' origin. If it is, then the browsing context's dialog arguments must be returned unchanged. Otherwise, if the dialog arguments are an object, then the empty string must be returned, and if the dialog arguments are not an object, then the stringification of the dialog arguments must be returned.

These browsing contexts also have an associated return value. The return value of a browsing context must be initialized to the empty string when the browsing context is created.

The returnValue DOM attribute, on getting, must return the return value of its browsing context, and on setting, must set the return value to the given new value.

5.5.4 Notifications

Notifications are short, transient messages that bring the user's attention to new information, or remind the user of scheduled events.

Since notifications can be annoying if abused, this specification defines a mechanism that scopes notifications to a site's existing rendering area unless the user explicitly indicates that the site can be trusted.

To this end, each origin can be flagged as being a trusted notification source. By default origins should not be flagged as such, but user agents may allow users to whitelist origins or groups of origins as being trusted notification sources. Only origins flagged as trusted in this way are allowed to show notification UI outside of their tab.

For example, a user agent could allow a user to mark all subdomains and ports of example.org as trusted notification sources. Then, mail.example.org and calendar.example.org would both be able to show notifications, without the user having to flag them individually.

The showNotification(title, subtitle, description, onclick) method, when invoked, must cause the user agent to show a notification.

If the method was invoked from a script whose script browsing context has the sandboxed annoyances browsing context flag set, then the notification must be shown within that browsing context. The notification is said to be a sandboxed notification.

Otherwise, if the origin of the script browsing context of the script that invoked the method is not flagged as being a trusted notification source, then the notification should be rendered within the top-level browsing context of the script browsing context of the script that invoked the method. The notification is said to be a normal notification. User agents should provide a way to set the origin's trusted notification source flag from the notification, so that the user can benefit from notifications even when the user agent is not the active application.

Otherwise, the origin is flagged as a trusted notification source, and the notification should be shown using the platform conventions for system-wide notifications. The notification is said to be a trusted notification. User agents may provide a way to unset the origin's trusted notification source flag from within the notification, so as to allow users to easily disable notifications from sites that abuse the privilege.

For example, if a site contains a gadget of a mail application in a sandboxed iframe and that frame triggers a notification upon the receipt of a new e-mail message, that notification would be displayed on top of the gadget only.

However, if the user then goes to the main site of that mail application, the notification would be displayed over the entire rendering area of the tab for the site.

The notification, in this case, would have a button on it to let the user indicate that he trusts the site. If the user clicked this button, the next notification would use the system-wide notification system, appearing even if the tab for the mail application was buried deep inside a minimised window.

The style of notifications varies from platform to platform. On some, it is typically displayed as a "toast" window that slides in from the bottom right corner. In others, notifications are shown as semi-transparent white-on-grey overlays centered over the screen. Other schemes could include simulated ticker tapes, and speech-synthesis playback.

When a normal notification (but not a sandboxed notification) is shown, the user agent may bring the user's attention to the top-level browsing context of the script browsing context of the script that invoked the method, if that would be useful; but user agents should not use system-wide notification mechanisms to do so.

When a trusted notification is shown, the user agent should bring the user's attention to the notification and the script browsing context of the script that invoked the method, as per the platform conventions for attracting the user's attention to applications.

In the case of normal notifications, typically the only attention-grabbing device that would be employed would be something like flashing the tab's caption, or making it bold, or some such.

In addition, in the case of a trusted notification, the entire window could flash, or the browser's application icon could bounce or flash briefly, or a short sound effect could be played.

Notifications should include the following content:

The title, subtitle, and description strings passed to the method. They may be truncated or abbreviated if necessary.
The application name, if available, or else the document title, of the active document of the script browsing context of the script that invoked the method.
An icon chosen from the external resource links of type icon, if any are available.

If a new notification from one browsing context has title, subtitle, and description strings that are identical to the title, subtitle, and description strings of an already-active notification from the same browsing context or another browsing context with the same origin, the user agent should not display the new notification, but should instead add an indicator to the already-active notification that another identical notification would otherwise have been shown.

For instance, if a user has his mail application open in three windows, and thus the same "New Mail" notification is fired three times each time a mail is received, instead of displaying three identical notifications each time, the user agent could just show one, with the title "New Mail x3".

Notifications should have a lifetime based on the platform conventions for notifications. However, the lifetime of a notification should not begin until the user has had the opportunity to see it, so if a notification is spawned for a browsing context that is hidden, it should be shown for its complete lifetime once the user brings that browsing context into view.

User agents should support multiple notifications at once.

User agents should support user interaction with notifications, if and as appropriate given the platform conventions. If a user activates a notification, and the onclick callback argument was present and is not null, then the script browsing context of the function given by onclick should be brought to the user's attention, and the onclick callback should then be invoked.

5.6 System state and capabilities

The navigator attribute of the Window interface must return an instance of the Navigator interface, which represents the identity and state of the user agent (the client), and allows Web pages to register themselves as potential protocol and content handlers:

interface Navigator {
  // objects implementing this interface also implement the interfaces given below
};

[NoInterfaceObject] interface NavigatorID {
  readonly attribute DOMString appName;
  readonly attribute DOMString appVersion;
  readonly attribute DOMString platform;
  readonly attribute DOMString