dom.bs

<pre class='metadata'>
Title: DOM Standard
H1: DOM
Shortname: dom
Status: LS
Group: WHATWG
No Editor: true
!Participate: <a href=https://github.com/whatwg/dom>GitHub whatwg/dom</a> (<a href=https://github.com/whatwg/dom/issues/new>new issue</a>, <a href=https://github.com/whatwg/dom/issues>open issues</a>, <a href=https://www.w3.org/Bugs/Public/buglist.cgi?component=DOM&amp;product=WebAppsWG&amp;resolution=--->legacy open bugs</a>)
!Participate: <a href=https://wiki.whatwg.org/wiki/IRC>IRC: #whatwg on Freenode</a>
!Commits: <a href=https://github.com/whatwg/dom/commits>GitHub whatwg/dom/commits</a>
!Commits: <a href=https://twitter.com/thedomstandard>@thedomstandard</a>
!Translation (non-normative): <span title=Japanese><a href=https://triple-underscore.github.io/DOM4-ja.html lang=ja hreflang=ja rel=alternate>日本語</a></span>
Logo: https://resources.whatwg.org/logo-dom.svg
Abstract: DOM defines a platform-neutral model for events and node trees.
Ignored Terms: EmptyString, Array, Document
Ignored Vars: p, documentFragment, ev, oldParent, em, processingInstruction, obj, tree, insertedNode, removedNode, C, *, intersects, collapsed
Boilerplate: omit conformance, omit feedback-header
</pre>

<!--
Bikeshed problems:

"Document" isn't properly defining itself, and the force switch isn't working.
-->

<script src=https://resources.whatwg.org/file-issue.js async></script>
<script id=head src=https://resources.whatwg.org/dfn.js defer></script>

<pre class='anchors'>
urlPrefix: https://encoding.spec.whatwg.org/
    type: dfn;
        text: ascii whitespace
        text: utf-8
        text: encoding
        text: name
urlPrefix: https://www.w3.org/TR/xml/#NT-
    type: type
        text: Name; url: Name
        text: Char; url: Char
        text: PubidChar; url: PubidChar
urlPrefix: https://www.w3.org/TR/xml-names/#NT-
    type: type
        text: QName; url: QName
urlPrefix: https://heycam.github.io/webidl/
    type: dfn; urlPrefix: #dfn-
        text: throw
        text: dictionary member
        text: identifier
        text: callback this value
        text: supported property indices
        text: supported property names
        text: code unit
    type: interface;
        text: DOMTimeStamp; urlPrefix: #common-
urlPrefix: https://html.spec.whatwg.org/multipage/
    type: dfn
        urlPrefix: webappapis.html
            text: report the exception
            text: queue a microtask
            text: compound microtask
            text: execute a compound microtask subtask
        urlPrefix: syntax.html
            text: html parser
            text: html parsing; url: #html-parser
        urlPrefix: browsers.html
            text: concept-document-bc
            text: concept-document-window
            text: unit of related similar-origin browsing contexts
            text: origin; url: concept-origin
        urlPrefix: infrastructure.html
            text: in parallel
            text: document base URL
url: https://w3c.github.io/DOM-Parsing/#widl-Range-createContextualFragment-DocumentFragment-DOMString-fragment
    type: method; text: createContextualFragment(); for: Range;
type: interface
    urlPrefix: https://w3c.github.io/uievents/#interface-
        text: KeyboardEvent
        text: MouseEvent
        text: UIEvent
    url: https://www.w3.org/TR/touch-events/#touchevent-interface
        text: TouchEvent
urlPrefix: https://slightlyoff.github.io/ServiceWorker/spec/service_worker/#
    type: interface; text: ServiceWorkerGlobalScope; url: service-worker-global-scope-interface
    type: dfn; urlPrefix: dfn-
        text: service worker
        text: script resource
        text: has ever been evaluated flag
urlPrefix: https://tc39.github.io/ecma262/#; spec: ECMASCRIPT
    text: Construct; url: sec-construct; type: abstract-op
</pre>

<pre class='link-defaults'>
spec:html; type:element
    text: title
    text: script
</pre>

<h2 id=goals class=no-num>Goals</h2>

This specification standardizes the DOM. It does so as follows:

<ol>
 <li>
  <p>By consolidating <cite>DOM Level 3 Core</cite> [[DOM-Level-3-Core]],
  <cite>Element Traversal</cite> [[ELEMENTTRAVERSAL]],
  <cite>Selectors API Level 2</cite> [[SELECTORS-API2]], the
  "DOM Event Architecture" and "Basic Event Interfaces" chapters of
  <cite>DOM Level 3 Events</cite> [[uievents-20031107]] (specific types of events do not
  belong in the DOM Standard), and <cite>DOM Level 2 Traversal and Range</cite>
  [[DOM-Level-2-Traversal-Range]], and:

  <ul class=brief>
   <li>Aligning them with the JavaScript ecosystem where possible.
   <li>Aligning them with existing implementations.
   <li>Simplifying them as much as possible.
  </ul>

 <li><p>By moving features from the HTML Standard [[!HTML]] that make more sense to be
 specified as part of the DOM Standard.

 <li>
  <p>By defining a replacement for the "Mutation Events" and
  "Mutation Name Event Types" chapters of <cite>DOM Level 3 Events</cite>
  [[uievents-20031107]] as the old model
  was problematic.

  <p class="note no-backref">The old model is expected to be removed from implementations
  in due course.

 <li><p>By defining new features that simplify common DOM operations.
</ol>


<h2 id=conformance>Conformance</h2>

All diagrams, examples, and notes in this specification are
non-normative, as are all sections explicitly marked non-normative.
Everything else in this specification is normative.

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in RFC 2119.
For readability, these words do not appear in all uppercase letters in this
specification. [[!RFC2119]]

Requirements phrased in the imperative as part of algorithms
(such as "strip any leading space characters" or "return false and
terminate these steps") are to be interpreted with the meaning of the
keyword ("must", "should", "may", etc.) used in introducing the
algorithm.

Conformance requirements phrased as algorithms or specific steps
may be implemented in any manner, so long as the end result is
equivalent. (In particular, the algorithms defined in this
specification are intended to be easy to follow, and not intended to
be performant.)

<p id="hardwareLimitations">User agents may impose
implementation-specific limits on otherwise unconstrained inputs,
e.g. to prevent denial of service attacks, to guard against running
out of memory, or to work around platform-specific limitations.

When a method or an attribute is said to call another method or attribute, the user agent must invoke its internal API for that attribute or method so that e.g. the author can't change the behavior by overriding attributes or methods with custom properties or functions in JavaScript.

Unless otherwise stated, string comparisons are done in a <a>case-sensitive</a> manner.

<h3 id=dependencies>Dependencies</h3>

The IDL fragments in this specification must be interpreted as
required for conforming IDL fragments, as described in the Web IDL
specification. [[!WEBIDL]]

Some of the terms used in this specification are defined in
<cite>Encoding</cite>, <cite>Selectors</cite>, <cite>Web IDL</cite>, <cite>XML</cite>, and
<cite>Namespaces in XML</cite>.
[[!ENCODING]]
[[!SELECTORS4]]
[[!WEBIDL]]
[[!XML]]
[[!XML-NAMES]]

<h3 id=extensibility>Extensibility</h3>

Vendor-specific proprietary extensions to this specification are
strongly discouraged. Authors must not use such extensions, as
doing so reduces interoperability and fragments the user base,
allowing only users of specific user agents to access the content in
question.

When extensions are needed, the DOM Standard can be updated accordingly, or a new standard
can be written that hooks into the provided extensibility hooks for
<dfn export lt="other applicable specifications">applicable specifications</dfn>.
<!-- https://www.w3.org/mid/17E341CD-E790-422C-9F9A-69347EE01CEB@iki.fi -->


<h2 id=terminology>Terminology</h2>

The term <dfn export>context object</dfn> means the object on which the algorithm,
attribute getter, attribute setter, or method being discussed was called. When the
<a>context object</a> is unambiguous, the term can be omitted.

<!-- XXX we should prolly explain that "set attribute X to Y" works even for
readonly attributes when it is language for implementors -->

<h3 id=trees>Trees</h3> <!-- Sorry reddit, this is not /r/trees -->

A <dfn export id=concept-tree>tree</dfn> is a finite hierarchical tree structure. In
<dfn export id=concept-tree-order>tree order</dfn> is preorder, depth-first
traversal of a <a>tree</a>.
<!-- https://en.wikipedia.org/wiki/Depth-first_search -->

An object that <dfn export for=tree id=concept-tree-participate lt="participate|participate in a tree|participates in a tree">participates</dfn> in
a <a>tree</a> has a
<dfn export for=tree id=concept-tree-parent>parent</dfn>, which is either another object
or null, and an ordered list of zero or more
<dfn export for=tree id=concept-tree-child lt="child|children">child</dfn> objects. An object <var>A</var> whose
<a>parent</a> is object <var>B</var> is a
<a>child</a> of <var>B</var>.

<p>The <dfn export for=tree id=concept-tree-root>root</dfn> of an object is itself, if its
<a>parent</a> is null, or else it is the <a for=tree>root</a> of its <a>parent</a>. The
<a for=tree>root</a> of a <a>tree</a> is any object <a for=tree>participating</a> in that
<a>tree</a> whose <a for=tree>parent</a> is null.

An object <var>A</var> is called a
<dfn export for=tree id=concept-tree-descendant>descendant</dfn> of an object
<var>B</var>, if either <var>A</var> is a
<a>child</a> of <var>B</var> or
<var>A</var> is a <a>child</a> of an
object <var>C</var> that is a
<a>descendant</a> of <var>B</var>.

An
<dfn export for=tree id=concept-tree-inclusive-descendant>inclusive descendant</dfn> is
an object or one of its
<a>descendants</a>.

An object <var>A</var> is called an
<dfn export for=tree id=concept-tree-ancestor>ancestor</dfn> of an object
<var>B</var> if and only if <var>B</var> is a
<a>descendant</a> of
<var>A</var>.

An <dfn export for=tree id=concept-tree-inclusive-ancestor>inclusive ancestor</dfn> is
an object or one of its <a>ancestors</a>.

An object <var>A</var> is called a
<dfn export for=tree id=concept-tree-sibling>sibling</dfn> of an object
<var>B</var>, if and only if <var>B</var> and <var>A</var>
share the same non-null <a>parent</a>.

An <dfn export for=tree id=concept-tree-inclusive-sibling>inclusive sibling</dfn> is an
object or one of its <a>siblings</a>.

An object <var>A</var> is
<dfn export for=tree id=concept-tree-preceding>preceding</dfn> an object
<var>B</var> if <var>A</var> and <var>B</var> are in the
same <a>tree</a> and <var>A</var> comes
before <var>B</var> in
<a>tree order</a>.

An object <var>A</var> is
<dfn export for=tree id=concept-tree-following>following</dfn> an object
<var>B</var> if <var>A</var> and <var>B</var> are in the
same <a>tree</a> and <var>A</var> comes
after <var>B</var> in
<a>tree order</a>.

The <dfn export for=tree id=concept-tree-first-child>first child</dfn> of an object is its
first <a>child</a> or null if it has no <a>children</a>.

The <dfn export for=tree id=concept-tree-last-child>last child</dfn> of an object is its
last <a>child</a> or null if it has no <a>children</a>.

The <dfn export for=tree id=concept-tree-previous-sibling>previous sibling</dfn> of an
object is its first <a>preceding</a>
<a>sibling</a> or null if it has no
<a>preceding</a>
<a>sibling</a>.

The <dfn export for=tree id=concept-tree-next-sibling>next sibling</dfn> of an
object is its first <a>following</a>
<a>sibling</a> or null if it has no
<a>following</a>
<a>sibling</a>.

The <dfn export for=tree id=concept-tree-index>index</dfn> of an object is its number
of <a>preceding</a>
<a>siblings</a>.


<h3 id=strings>Strings</h3>

Comparing two strings in a
<dfn export lt="case-sensitive|case-sensitively">case-sensitive</dfn> manner means
comparing them exactly, code point for code point.

Comparing two strings in a
<dfn export lt="ASCII case-insensitive|ASCII case-insensitively">ASCII case-insensitive</dfn>
manner means comparing them exactly, code point for code point, except that the characters
in the range U+0041 to U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z),
inclusive, and the corresponding characters in the range U+0061 to U+007A (i.e.
LATIN SMALL LETTER A to LATIN SMALL LETTER Z), inclusive, are considered to also match.

<dfn export lt="converted to ASCII uppercase">Converting a string to ASCII uppercase</dfn>
means replacing all characters in the range U+0061 to U+007A, inclusive, with the
corresponding characters in the range U+0041 to U+005A, inclusive.

<dfn export lt="converted to ASCII lowercase">Converting a string to ASCII lowercase</dfn>
means replacing all characters in the range U+0041 to U+005A, inclusive, with the
corresponding characters in the range U+0061 to U+007A, inclusive.

A string <var>pattern</var> is a <dfn export>prefix match</dfn> for a string <var>s</var>
when <var>pattern</var> is not longer than <var>s</var> and truncating <var>s</var> to
<var>pattern</var>'s length leaves the two strings as matches of each other.


<h3 id="ordered sets">Ordered sets</h3>

The <dfn export id=concept-ordered-set-parser>ordered set parser</dfn> takes a string
<var>input</var> and then runs these steps:

<ol>
 <li>Let <var>position</var> be a pointer into <var>input</var>,
 initially pointing at the start of the string.

 <li>Let <var>tokens</var> be an ordered set of tokens, initially empty.

 <li><a>Skip ASCII whitespace</a>.

 <li>While <var>position</var> is not past the end of
 <var>input</var>:

  <ol>
   <li><a>Collect a code point sequence</a> of code points that are
   not <a>ASCII whitespace</a>.

   <li>If the collected string is not in <var>tokens</var>, append the
   collected string to <var>tokens</var>.

   <li><a>Skip ASCII whitespace</a>.
  </ol>

 <li>Return <var>tokens</var>.
</ol>

To <dfn export>collect a code point sequence</dfn> of
<var>code points</var>, run these steps:

<ol>
 <li>Let <var>input</var> and <var>position</var> be the same
 variables as those of the same name in the algorithm that invoked these
 steps.

 <li>Let <var>result</var> be the empty string.

 <li>While <var>position</var> does not point past the end of
 <var>input</var> and the code point at <var>position</var> is
 one of <var>code points</var>, append that code point to the end
 of <var>result</var> and advance <var>position</var> to the
 next code point in <var>input</var>.

 <li>Return <var>result</var>.
</ol>

To <dfn export>skip ASCII whitespace</dfn> means to
<a>collect a code point sequence</a> of
<a>ASCII whitespace</a> and discard the
return value.

The <dfn export id=concept-ordered-set-serializer>ordered set serializer</dfn> takes a
<var>set</var> and returns the concatenation of the strings in <var>set</var>, separated from each other by U+0020, if <var>set</var> is non-empty, and the empty string otherwise.


<h3 id=selectors>Selectors</h3>

To <dfn export>match a relative selectors string</dfn> <var>relativeSelectors</var>
against a <var>set</var>, run these steps:

<ol>
 <li>Let <var>s</var> be the result of
 <a>parse a relative selector</a> from
 <var>relativeSelectors</var> against <var>set</var>.
 [[!SELECTORS4]]

 <li>If <var>s</var> is failure, <a>throw</a> a {{SyntaxError}}.

 <li>Return the result of <a>evaluate a selector</a> <var>s</var>
  using <a>:scope elements</a> <var>set</var>. [[!SELECTORS4]]
</ol>

To <dfn export>scope-match a selectors string</dfn> <var>selectors</var> against a
<var>node</var>, run these steps:

<ol>
 <li>Let <var>s</var> be the result of
 <a>parse a selector</a> <var>selectors</var>.
 [[!SELECTORS4]]

 <li>If <var>s</var> is failure, <a>throw</a> a
 {{SyntaxError}}.

 <li>Return the result of <a>evaluate a selector</a>
 <var>s</var> against
 <var>node</var>'s <a for=tree>root</a> using
 <a>scoping root</a> <var>node</var> and
 scoping method
 <a>scope-filtered</a>.
 [[!SELECTORS4]].
</ol>

<p class=note>Support for namespaces within selectors is not planned and will not be
added.


<h3 id=namespaces>Namespaces</h3>

The <dfn export>HTML namespace</dfn> is
<code>http://www.w3.org/1999/xhtml</code>.

The <dfn export>SVG namespace</dfn> is
<code>http://www.w3.org/2000/svg</code>.

The <dfn export>XML namespace</dfn> is
<code>http://www.w3.org/XML/1998/namespace</code>.

The <dfn export>XMLNS namespace</dfn> is
<code>http://www.w3.org/2000/xmlns/</code>.

To <dfn export>validate</dfn> a <var>qualifiedName</var>, run these steps:

<ol>
 <li><p>If <var>qualifiedName</var> does not match the <code><a type>Name</a></code> production,
 then <a>throw</a> an {{InvalidCharacterError}}.

 <li><p>If <var>qualifiedName</var> does not match the <code><a type>QName</a></code> production,
 then <a>throw</a> a {{NamespaceError}}.
</ol>

To <dfn export>validate and extract</dfn> a <var>namespace</var> and <var>qualifiedName</var>,
run these steps:

<ol>
 <li>If <var>namespace</var> is the empty string, set it to null.

 <li><a>Validate</a> <var>qualifiedName</var>. Rethrow any exceptions.

 <li>Let <var>prefix</var> be null.

 <li>Let <var>localName</var> be <var>qualifiedName</var>.

 <li>If <var>qualifiedName</var> contains a "<code>:</code>" (U+003E), then split the
 string on it and set <var>prefix</var> to the part before and <var>localName</var> to
 the part after.

 <li>If <var>prefix</var> is non-null and <var>namespace</var> is null, then <a>throw</a> a
 {{NamespaceError}}.

 <li>If <var>prefix</var> is "<code>xml</code>" and <var>namespace</var> is not the
 <a>XML namespace</a>, then <a>throw</a> a {{NamespaceError}}.

 <li>If either <var>qualifiedName</var> or <var>prefix</var> is
 "<code>xmlns</code>" and <var>namespace</var> is not the
 <a>XMLNS namespace</a>, then <a>throw</a> a
 {{NamespaceError}}.

 <li>If <var>namespace</var> is the <a>XMLNS namespace</a> and neither <var>qualifiedName</var>
 nor <var>prefix</var> is "<code>xmlns</code>", then <a>throw</a> a {{NamespaceError}}.

 <li>Return <var>namespace</var>, <var>prefix</var>, and <var>localName</var>.
</ol>



<h2 id=events>Events</h2>

<h3 id=introduction-to-dom-events>Introduction to "DOM Events"</h3>

Throughout the web platform <a>events</a> are <a>dispatched</a> to objects to signal an
occurrence, such as network activity or user interaction. These objects implement the
{{EventTarget}} interface and can therefore add <a>event listeners</a> to observe
<a>events</a> by calling {{EventTarget/addEventListener()}}:

<pre class=lang-javascript>
obj.addEventListener("load", imgFetched)

function imgFetched(ev) {
  // great success
  &hellip;
}
</pre>

<a>Event listeners</a> can be removed
by utilizing the
{{EventTarget/removeEventListener()}}
method, passing the same arguments.

<a>Events</a> are objects too and implement the
{{Event}} interface (or a derived interface). In the example above
<var>ev</var> is the <a>event</a>. It is
passed as argument to
<a>event listener</a>'s <b>callback</b>
(typically a JavaScript Function as shown above).
<a>Event listeners</a> key off the
<a>event</a>'s
{{Event/type}} attribute value
("<code>load</code>" in the above example). The
<a>event</a>'s
{{Event/target}} attribute value returns the
object to which the <a>event</a> was
<a>dispatched</a>
(<var>obj</var> above).

Now while typically <a>events</a> are
<a>dispatched</a> by the user agent as
the result of user interaction or the completion of some task, applications
can <a>dispatch</a>
<a>events</a> themselves, commonly known as
synthetic events:

<pre class='lang-javascript'>
// add an appropriate event listener
obj.addEventListener("cat", function(e) { process(e.detail) })

// create and dispatch the event
var event = new CustomEvent("cat", {"detail":{"hazcheeseburger":true}})
obj.dispatchEvent(event)
</pre>

Apart from signaling, <a>events</a> are
sometimes also used to let an application control what happens next in an
operation. For instance as part of form submission an
<a>event</a> whose
{{Event/type}} attribute value is
"<code>submit</code>" is
<a>dispatched</a>. If this
<a>event</a>'s
{{Event/preventDefault()}} method is
invoked, form submission will be terminated. Applications who wish to make
use of this functionality through <a>events</a>
<a>dispatched</a> by the application
(synthetic events) can make use of the return value of the
{{EventTarget/dispatchEvent()}} method:

<pre class='lang-javascript'>
if(obj.dispatchEvent(event)) {
  // event was not canceled, time for some magic
  &hellip;
}
</pre>

When an <a>event</a> is
<a>dispatched</a> to an object that
<a>participates</a> in a
<a>tree</a> (e.g. an
<a for="/">element</a>), it can reach
<a>event listeners</a> on that object's
<a>ancestors</a> too. First all object's
<a>ancestor</a>
<a>event listeners</a> whose
<b>capture</b> variable is set to true are invoked, in
<a>tree order</a>. Second, object's own
<a>event listeners</a> are invoked. And
finally, and only if <a>event</a>'s
{{Event/bubbles}} attribute value is true,
object's  <a>ancestor</a>
<a>event listeners</a> are invoked again,
but now in reverse <a>tree order</a>.

Lets look at an example of how <a>events</a> work in a <a>tree</a>:

<pre class='lang-markup'>
&lt;!doctype html>
&lt;html>
 &lt;head>
  &lt;title>Boring example&lt;/title>
 &lt;/head>
 &lt;body>
  &lt;p>Hello &lt;span id=x>world&lt;/span>!&lt;/p>
  &lt;script>
   function test(e) {
     debug(e.target, e.currentTarget, e.eventPhase)
   }
   document.addEventListener("hey", test, {capture: true})
   document.body.addEventListener("hey", test)
   var ev = new Event("hey", {bubbles:true})
   document.getElementById("x").dispatchEvent(ev)
  &lt;/script>
 &lt;/body>
&lt;/html>
</pre>

The <code>debug</code> function will be invoked twice. Each time the <a>event</a>'s
{{Event/target}} attribute value will be the
<code>span</code> <a for="/">element</a>. The
first time {{Event/currentTarget}} attribute's
value will be the <a>document</a>, the second
time the <code>body</code> <a for="/">element</a>.
{{Event/eventPhase}} attribute's value
switches from {{Event/CAPTURING_PHASE}}
to {{Event/BUBBLING_PHASE}}. If an
<a>event listener</a> was registered for
the <code>span</code> <a for="/">element</a>,
{{Event/eventPhase}} attribute's value
would have been {{Event/AT_TARGET}}.


<h3 id=interface-event>Interface {{Event}}</h3>

<pre class="idl">
[Constructor(DOMString type, optional EventInit eventInitDict),
 Exposed=(Window,Worker)]
interface Event {
  readonly attribute DOMString type;
  readonly attribute EventTarget? target;
  readonly attribute EventTarget? currentTarget;
  sequence&lt;EventTarget> composedPath();

  const unsigned short NONE = 0;
  const unsigned short CAPTURING_PHASE = 1;
  const unsigned short AT_TARGET = 2;
  const unsigned short BUBBLING_PHASE = 3;
  readonly attribute unsigned short eventPhase;

  void stopPropagation();
  void stopImmediatePropagation();

  readonly attribute boolean bubbles;
  readonly attribute boolean cancelable;
  void preventDefault();
  readonly attribute boolean defaultPrevented;
  readonly attribute boolean composed;

  [Unforgeable] readonly attribute boolean isTrusted;
  readonly attribute DOMTimeStamp timeStamp;

  void initEvent(DOMString type, boolean bubbles, boolean cancelable); // historical
};

dictionary EventInit {
  boolean bubbles = false;
  boolean cancelable = false;
  boolean composed = false;
};
</pre>

<p>An {{Event}} object is simply named an <dfn export id=concept-event>event</dfn>. It allows for
signaling that something has occurred, e.g., that an image has completed downloading.</p>

<p>An <a>event</a> has an associated <dfn export for=Event>path</dfn>. A <a for=Event>path</a> is a
list of tuples, each of which consists of an <b>item</b> (an {{EventTarget}} object) and a
<b>target</b> (null or an {{EventTarget}} object). A tuple is formatted as (<b>item</b>,
<b>target</b>). A <a for=Event>path</a> is initially the empty list.</p>

<dl class=domintro>
 <dt><code><var>event</var> = new <a constructor lt="Event()">Event</a>(<var>type</var> [, <var>eventInitDict</var>])</code>
 <dd>Returns a new <var>event</var> whose
 {{Event/type}} attribute value is set to
 <var>type</var>. The optional <var>eventInitDict</var> argument
 allows for setting the {{Event/bubbles}} and
 {{Event/cancelable}} attributes via object
 members of the same name.

 <dt><code><var>event</var> . {{Event/type}}</code>
 <dd>Returns the type of <var>event</var>, e.g.
 "<code>click</code>", "<code>hashchange</code>", or
 "<code>submit</code>".

 <dt><code><var>event</var> . {{Event/target}}</code>
 <dd>Returns the object to which <var>event</var> is <a>dispatched</a>.

 <dt><code><var>event</var> . {{Event/currentTarget}}</code>
 <dd>Returns the object whose <a>event listener</a>'s <b>callback</b> is currently being
 invoked.

 <dt><code><var>event</var> . {{Event/composedPath()}}</code>
 <dd>Returns the <b>item</b> objects of <var>event</var>'s <a for=Event>path</a> (objects on which
 listeners will be invoked), except for any <a>nodes</a> in <a>shadow trees</a> of which the
 <a for=/>shadow root</a>'s <a for=ShadowRoot>mode</a> is "<code>closed</code>" that are not
 reachable from <var>event</var>'s {{Event/currentTarget}}.

 <dt><code><var>event</var> . {{Event/eventPhase}}</code>
 <dd>Returns the <a>event</a>'s phase, which is one of {{Event/NONE}},
 {{Event/CAPTURING_PHASE}},
 {{Event/AT_TARGET}}, and
 {{Event/BUBBLING_PHASE}}.

 <dt><code><var>event</var> . <a method for=Event lt="stopPropagation()">stopPropagation</a>()</code>
 <dd>When <a>dispatched</a> in a <a>tree</a>, invoking this method prevents
 <var>event</var> from reaching any objects other than the current object.

 <dt><code><var>event</var> . <a method for=Event lt="stopImmediatePropagation()">stopImmediatePropagation</a>()</code>
 <dd>Invoking this method prevents <var>event</var> from reaching
 any registered <a>event listeners</a> after the current one finishes running and, when
 <a>dispatched</a> in a <a>tree</a>, also prevents <var>event</var> from reaching any
 other objects.

 <dt><code><var>event</var> . {{Event/bubbles}}</code>
 <dd>Returns true or false depending on how <var>event</var> was initialized. True if
 <var>event</var> goes through its {{Event/target}} attribute value's <a>ancestors</a>
 in reverse <a>tree order</a>, and false otherwise.

 <dt><code><var>event</var> . {{Event/cancelable}}</code>
 <dd>Returns true or false depending on how <var>event</var> was initialized. Its return
 value does not always carry meaning, but true can indicate that part of the operation
 during which <var>event</var> was <a>dispatched</a>, can be canceled by invoking the
 {{Event/preventDefault()}} method.

 <dt><code><var>event</var> . <a method for=Event lt="preventDefault()">preventDefault</a>()</code>
 <dd>If invoked when the {{Event/cancelable}} attribute value is true, and while executing a
 listener for the <var>event</var> with {{AddEventListenerOptions/passive}} set to false, signals to
 the operation that caused <var>event</var> to be <a>dispatched</a> that it needs to be canceled.

 <dt><code><var>event</var> . {{Event/defaultPrevented}}</code>
 <dd>Returns true if {{Event/preventDefault()}} was invoked successfully to indicate cancellation,
 and false otherwise.

 <dt><code><var>event</var> . {{Event/composed}}</code>
 <dd>Returns true or false depending on how <var>event</var> was initialized. True if
 <var>event</var> invokes listeners past a {{ShadowRoot}} <a>node</a> that is the
 <a for=tree>root</a> of its {{Event/target}} attribute value, and false otherwise.

 <dt><code><var>event</var> . {{Event/isTrusted}}</code>
 <dd>Returns true if <var>event</var> was
 <a>dispatched</a> by the user agent, and
 false otherwise.

 <dt><code><var>event</var> . {{Event/timeStamp}}</code>
 <dd>Returns the creation time of <var>event</var> as the number of milliseconds that
 passed since 00:00:00 UTC on 1 January 1970.
</dl>

The <dfn attribute for=Event><code>type</code></dfn> attribute must
return the value it was initialized to. When an
<a>event</a> is created the attribute must be
initialized to the empty string.

The <dfn attribute for=Event><code>target</code></dfn> and
<dfn attribute for=Event><code>currentTarget</code></dfn>
attributes must return the values they were initialized to. When an
<a>event</a> is created the attributes must be
initialized to null.

<p>The <dfn method for=Event><code>composedPath()</code></dfn> method, when invoked, must run these
steps:

<ol>
 <li><p>Let <var>composedPath</var> be a new empty list.

 <li><p>Let <var>currentTarget</var> be <a>context object</a>'s <code for=Event>currentTarget</code>
 attribute value.

 <li>
  <p>For each <var>tuple</var> in <a>context object</a>'s <a for=Event>path</a>:

  <ol><li><p>If <var>currentTarget</var> is a <a>node</a> and <var>tuple</var>'s <b>item</b> is an
  <a>unclosed node</a> of <var>currentTarget</var>, or <var>currentTarget</var> is <em>not</em> a
  <a>node</a>, then append <var>tuple</var>'s <b>item</b> to <var>composedPath</var>.</p></li></ol>

 <li><p>Return <var>composedPath</var>.
</ol>

<p class="note no-backref">This algorithm assumes that when the <var>target</var> argument to the
<a>dispatch</a> algorithm is not a <a>node</a>, none of the tuples in <var>event</var> argument's
eventual <a for=Event>path</a> will contain a <a>node</a> either.

The <dfn attribute for=Event><code>eventPhase</code></dfn>
attribute must return the value it was initialized to, which must be one of
the following:
<dl>
 <dt><dfn const for=Event>NONE</dfn> (numeric value 0)
 <dd><a>Events</a> not currently
 <a>dispatched</a> are in this phase.
 <dt><dfn const for=Event>CAPTURING_PHASE</dfn> (numeric value 1)
 <dd>When an <a>event</a> is
 <a>dispatched</a> to an object that
 <a>participates</a> in a
 <a>tree</a> it will be in this phase before it
 reaches its {{Event/target}} attribute value.
 <dt><dfn const for=Event>AT_TARGET</dfn> (numeric value 2)
 <dd>When an <a>event</a> is
 <a>dispatched</a> it will be in this
 phase on its {{Event/target}} attribute value.
 <dt><dfn const for=Event>BUBBLING_PHASE</dfn> (numeric value 3)
 <dd>When an <a>event</a> is
 <a>dispatched</a> to an object that
 <a>participates</a> in a
 <a>tree</a> it will be in this phase after it
 reaches its {{Event/target}} attribute value.
</dl>
Initially the attribute must be initialized to
{{Event/NONE}}.

<hr>

Each <a>event</a> has the following associated
flags that are all initially unset:
<ul>
 <li><dfn export for=Event id=stop-propagation-flag>stop propagation flag</dfn>
 <li><dfn export for=Event id=stop-immediate-propagation-flag>stop immediate propagation flag</dfn>
 <li><dfn export for=Event id=canceled-flag>canceled flag</dfn>
 <li><dfn export for=Event id=in-passive-listener-flag>in passive listener flag</dfn>
 <li><dfn export for=Event id=composed-flag>composed flag</dfn>
 <li><dfn export for=Event id=initialized-flag>initialized flag</dfn>
 <li><dfn export for=Event id=dispatch-flag>dispatch flag</dfn>
</ul>

<p>The <dfn method for=Event><code>stopPropagation()</code></dfn> method, when invoked, must set the
<a>context object</a>'s <a>stop propagation flag</a>.</p>

<p>The <dfn method for=Event><code>stopImmediatePropagation()</code></dfn> method, when invoked,
must set <a>context object</a>'s <a>stop propagation flag</a> and <a>context object</a>'s
<a>stop immediate propagation flag</a>.</p>

The <dfn attribute for=Event><code>bubbles</code></dfn> and
<dfn attribute for=Event><code>cancelable</code></dfn> attributes
must return the values they were initialized to.

The <dfn method for=Event><code>preventDefault()</code></dfn> method, when invoked, must set the
<a>canceled flag</a> if the {{Event/cancelable}} attribute value is true and the
<a>in passive listener flag</a> is unset.

<p class="note no-backref">This means there are scenarios where invoking {{preventDefault()}} has no
effect. User agents are encouraged to log the precise cause in a developer console, to aid
debugging.

<p>The <dfn attribute for=Event><code>defaultPrevented</code></dfn> attribute's getter must return
true if <a>context object</a>'s <a>canceled flag</a> is set, and false otherwise.</p>

<p>The <dfn attribute for=Event><code>composed</code></dfn> attribute's getter must return true if
<a>context object</a>'s <a>composed flag</a> is set, and false otherwise.</p>

<hr>

The <dfn attribute for=Event><code>isTrusted</code></dfn> attribute
must return the value it was initialized to. When an
<a>event</a> is created the attribute must be
initialized to false.

The <dfn attribute for=Event><code>timeStamp</code></dfn> attribute
must return the value it was initialized to. When an
<a>event</a> is created the attribute must be
initialized to the number of milliseconds that have passed since
00:00:00 UTC on 1 January 1970, ignoring leap seconds.
<!-- leap seconds are ignored by JavaScript too -->

<p class=XXX>This is highly likely to change and already does not reflect implementations well.
Please see <a href=https://github.com/whatwg/dom/issues/23>dom #23</a> for more details.

<hr>

To <dfn export for=Event id=concept-event-initialize>initialize</dfn> an
<var>event</var>, with <var>type</var>,
<var>bubbles</var>, and <var>cancelable</var>, run these steps:

<ol>
 <li>Set the <a>initialized flag</a>.
 <li>Unset the <a>stop propagation flag</a>,
 <a>stop immediate propagation flag</a>, and
 <a>canceled flag</a>.
 <li>Set the {{Event/isTrusted}} attribute
 to false.
 <li>Set the {{Event/target}} attribute to
 null.
 <li>Set the {{Event/type}} attribute to
 <var>type</var>.
 <li>Set the {{Event/bubbles}} attribute to
 <var>bubbles</var>.
 <li>Set the {{Event/cancelable}} attribute
 to <var>cancelable</var>.
</ol>

<p>The
<dfn method for=Event><code>initEvent(<var>type</var>, <var>bubbles</var>, <var>cancelable</var>)</code></dfn>
method, when invoked, must run these steps:</p>

<ol>
 <li><p>If <a>context object</a>'s <a>dispatch flag</a> is set, then return.

 <li><p><a>Initialize</a> <a>context object</a> with <var>type</var>, <var>bubbles</var>, and
 <var>cancelable</var>.
</ol>

<p class="note no-backref">As <a>events</a> have constructors {{Event/initEvent()}} is redundant and
incapable of setting {{Event/composed}}. It has to be supported for legacy content.


<h3 id=interface-customevent>Interface {{CustomEvent}}</h3>

<pre class=idl>
[Constructor(DOMString type, optional CustomEventInit eventInitDict),
 Exposed=(Window,Worker)]
interface CustomEvent : Event {
  readonly attribute any detail;

  void initCustomEvent(DOMString type, boolean bubbles, boolean cancelable, any detail);
};

dictionary CustomEventInit : EventInit {
  any detail = null;
};
</pre>

<a>Events</a> using the
{{CustomEvent}} interface can be used to carry custom data.

<dl class=domintro>
 <dt><code><var>event</var> = new <a constructor lt="CustomEvent()">CustomEvent</a>(<var>type</var> [, <var>eventInitDict</var>])</code>
 <dd>Works analogously to the constructor for {{Event}} except
 that the optional <var>eventInitDict</var> argument now
 allows for setting the {{CustomEvent/detail}} attribute
 too.

 <dt><code><var>event</var> . {{CustomEvent/detail}}</code>
 <dd>Returns any custom data <var>event</var> was created with.
 Typically used for synthetic events.

 <!-- initCustomEvent is dead -->
</dl>

The <dfn attribute for=CustomEvent><code>detail</code></dfn> attribute
must return the value it was initialized to.

The
<dfn method for=CustomEvent><code>initCustomEvent(<var>type</var>, <var>bubbles</var>, <var>cancelable</var>, <var>detail</var>)</code></dfn>
method must, when invoked, run these steps:

<ol>
 <li>If <a>context object</a>'s <a>dispatch flag</a> is set, terminate
 these steps.

 <li><a>Initialize</a> the
 <a>context object</a> with <var>type</var>, <var>bubbles</var>, and
 <var>cancelable</var>.

 <li>Set <a>context object</a>'s {{CustomEvent/detail}}
 attribute to <var>detail</var>.
</ol>


<h3 id=constructing-events>Constructing events</h3>

When a <dfn export for=Event id=concept-event-constructor>constructor</dfn> of the
{{Event}} interface, or of an interface that inherits from the {{Event}} interface, is
invoked, these steps must be run:

<ol>
 <li><p>Create an <a>event</a> that uses the interface the constructor was invoked upon.

 <li><p>Set its <a>initialized flag</a>.

 <li><p>Initialize the {{Event/type}} attribute to the <var>type</var> argument.

 <li><p>If there is an <var>eventInitDict</var> argument, then for each
 <a>dictionary member</a> present, find the attribute on <a>event</a> whose
 <a>identifier</a> matches the key of the <a>dictionary member</a> and then set the
 attribute to the value of that <a>dictionary member</a>.

 <li><p>Return the <a>event</a>.
</ol>


<h3 id=defining-event-interfaces>Defining event interfaces</h3>

In general, when defining a new interface that inherits from {{Event}} please always ask
feedback from the <a href=https://whatwg.org/>WHATWG</a> or the
<a href=https://www.w3.org/2008/webapps/>W3C WebApps WG</a> community.

The {{CustomEvent}} interface can be used as starting point.
However, do not introduce any <code>init<var>*</var>Event()</code>
methods as they are redundant with constructors. Interfaces that inherit
from the {{Event}} interface that have such a method only have it
for historical reasons.


<h3 id=interface-eventtarget>Interface {{EventTarget}}</h3>

<pre class=idl>
[Exposed=(Window,Worker)]
interface EventTarget {
  void addEventListener(DOMString type, EventListener? callback, optional (AddEventListenerOptions or boolean) options);
  void removeEventListener(DOMString type, EventListener? callback, optional (EventListenerOptions or boolean) options);
  boolean dispatchEvent(Event event);
};

callback interface EventListener {
  void handleEvent(Event event);
};

dictionary EventListenerOptions {
  boolean capture = false;
};

dictionary AddEventListenerOptions : EventListenerOptions {
  boolean passive = false;
  boolean once = false;
};
</pre>

<p>The {{EventTarget}} object represents the target to which an <a>event</a> is <a>dispatched</a>
when something has occurred.

<p>Each {{EventTarget}} object has an associated list of <a>event listeners</a>.

<p>An <dfn export id=concept-event-listener>event listener</dfn> can be used to observe a specific
<a>event</a>.

<p>An <a>event listener</a> consists of these fields:</p>

<ul class="brief">
 <li><b>type</b> (a string)
 <li><b>callback</b> (an {{EventListener}})
 <li><b>capture</b> (a boolean, initially false)
 <li><b>passive</b> (a boolean, initially false)
 <li><b>once</b> (a boolean, initially false)
 <li><b>removed</b> (a boolean for bookkeeping purposes, initially false)
</ul>

<p class="note no-backref">Although <b>callback</b> is an {{EventListener}}, as can be seen from the
fields above, an <a>event listener</a> is a broader concept.

<p>Each {{EventTarget}} object also has an associated <dfn export>get the parent</dfn> algorithm,
which takes an <a>event</a> <var>event</var>, and returns an {{EventTarget}} object. Unless
specified otherwise it returns null.

<p class="note no-backref"><a>Nodes</a>, <a for=/>shadow roots</a>, and <a>documents</a> override
the <a>get the parent</a> algorithm.

<dl class=domintro>
 <dt><code><var>target</var> . <a method lt="addEventListener()">addEventListener</a>(<var>type</var>, <var>callback</var> [, <var>options</var>])</code>
 <dd>
  Appends an <a>event listener</a> for <a>events</a> whose {{Event/type}} attribute value
  is <var>type</var>. The <var>callback</var> argument sets the <b>callback</b> that will
  be invoked when the <a>event</a> is <a>dispatched</a>.

  The <var>options</var> argument sets listener-specific options. For compatibility this can be just
  a boolean, in which case the method behaves exactly as if the value was specified as
  <var>options</var>' <code>capture</code> member.

  When set to true, <var>options</var>' <code>capture</code> member prevents <b>callback</b> from
  being invoked when the <a>event</a>'s {{Event/eventPhase}} attribute value is
  {{Event/BUBBLING_PHASE}}. When false (or not present), <b>callback</b> will not be invoked when
  <a>event</a>'s {{Event/eventPhase}} attribute value is {{Event/CAPTURING_PHASE}}. Either way,
  <b>callback</b> will be invoked if <a>event</a>'s {{Event/eventPhase}} attribute value is
  {{Event/AT_TARGET}}.

  When set to true, <var>options</var>' <code>passive</code> member indicates that the
  <b>callback</b> will not cancel the event by invoking {{preventDefault()}}. This is used to enable
  performance optimizations described in [[#observing-event-listeners]].

  When set to true, <var>options</var>'s <code>once</code> member indicates that the <b>callback</b>
  will only be invoked once after which the event listener will be removed.

  The <a>event listener</a> is appended to <var>target</var>'s list of <a>event listeners</a> and is
  not appended if it is a duplicate, i.e., having the same <b>type</b>, <b>callback</b>, and
  <b>capture</b> values.

 <dt><code><var>target</var> . <a method lt="removeEventListener()">removeEventListener</a>(<var>type</var>, <var>callback</var> [, <var>options</var>])</code>
 <dd>Remove the <a>event listener</a>
 in <var>target</var>'s list of
 <a>event listeners</a> with the same
 <var>type</var>, <var>callback</var>, and
 <var>options</var>.

 <dt><code><var>target</var> . <a method lt="dispatchEvent()">dispatchEvent</a>(<var>event</var>)</code>
 <dd><a>Dispatches</a> a synthetic event <var>event</var> to <var>target</var> and returns
 true if either <var>event</var>'s {{Event/cancelable}} attribute value is false or its
 {{Event/preventDefault()}} method was not invoked, and false otherwise.
</dl>

<p>To <dfn export for=Event id=concept-flatten-options>flatten</dfn> <var>options</var>, run these
steps:

<ol>
 <li><p>Let <var>capture</var> be false.

 <li><p>If <var>options</var> is a boolean, set <var>capture</var> to <var>options</var>.

 <li><p>If <var>options</var> is a dictionary, then set <var>capture</var> to <var>options</var>'s
 <code>{{EventListenerOptions/capture}}</code>.

 <li><p>Return <var>capture</var>.
</ol>

<p>To <dfn export for=Event>flatten more</dfn><!-- sorry --> <var>options</var>, run these
steps:

<ol>
 <li><p>Let <var>capture</var> be the result of <a>flattening</a> <var>options</var>.

 <li><p>Let <var>once</var> and <var>passive</var> be false.

 <li><p>If <var>options</var> is a dictionary, then set <var>passive</var> to <var>options</var>'s
 <code>{{AddEventListenerOptions/passive}}</code> and <var>once</var> to <var>options</var>'s
 <code>{{AddEventListenerOptions/once}}</code>.

 <li><p>Return <var>capture</var>, <var>passive</var>, and <var>once</var>.
</ol>

<p>The
<dfn method for=EventTarget><code>addEventListener(<var>type</var>, <var>callback</var>, <var>options</var>)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li>
  <p>If the <a>context object</a>'s global object is a {{ServiceWorkerGlobalScope}} object and its
  associated <a>service worker</a>'s <a>script resource</a>'s <a>has ever been evaluated flag</a> is
  set, <a>throw</a> a <code>TypeError</code>. [[!SERVICE-WORKERS]]

  <p class="note no-backref">To optimize storing the event types allowed for the service worker and
  to avoid non-deterministic changes to the event listeners, invocation of the method is allowed
  only during the very first evaluation of the service worker script.

 <li><p>If <var>callback</var> is null, terminate these steps.

 <li><p>Let <var>capture</var>, <var>passive</var>, and <var>once</var> be the result of
 <a lt="flatten more">flattening more</a> <var>options</var>.

 <li><p>If <a>context object</a>'s associated list of <a>event listener</a> does not contain an
 <a>event listener</a> whose <b>type</b> is <var>type</var>, <b>callback</b> is <var>callback</var>,
 and <b>capture</b> is <var>capture</var>, then append a new <a>event listener</a> to it, whose
 <b>type</b> is <var>type</var>, <b>callback</b> is <var>callback</var>, <b>capture</b> is
 <var>capture</var>, <b>passive</b> is <var>passive</var>, and <b>once</b> is <var>once</var>.
</ol>

<p>The
<dfn method for=EventTarget><code>removeEventListener(<var>type</var>, <var>callback</var>, <var>options</var>)</code></dfn>
method, when invoked, must, run these steps

<ol>
 <li><p>If the <a>context object</a>'s global object is a {{ServiceWorkerGlobalScope}} object and
 its associated <a>service worker</a>'s <a>script resource</a>'s <a>has ever been evaluated flag</a>
 is set, <a>throw</a> a <code>TypeError</code>. [[!SERVICE-WORKERS]]

 <li><p>Let <var>capture</var> be the result of <a>flattening</a> <var>options</var>.

 <li><p>If there is an <a>event listener</a> in the associated list of <a>event listeners</a> whose
 <b>type</b> is <var>type</var>, <b>callback</b> is <var>callback</var>, and <b>capture</b> is
 <var>capture</var>, then set that <a>event listener</a>'s <b>removed</b> to true and remove it from
 the associated list of <a>event listeners</a>.
</ol>

<p>The <dfn method for=EventTarget><code>dispatchEvent(<var>event</var>)</code></dfn> method, when
invoked, must run these steps:

<ol>
 <li><p>If <var>event</var>'s <a>dispatch flag</a> is set, or if its <a>initialized flag</a> is not
 set, then <a>throw</a> an {{InvalidStateError}}.

 <li><p>Initialize <var>event</var>'s {{Event/isTrusted}} attribute to false.

 <li><p>Return the result of <a>dispatching</a> <var>event</var> to <a>context object</a>.
</ol>


<h3 id=observing-event-listeners>Observing event listeners</h3>

<p>In general, developers do not expect the presence of an <a>event listener</a> to be observable.
The impact of an <a>event listener</a> is determined by its <b>callback</b>. That is, a developer
adding a no-op <a>event listener</a> would not expect it to have any side effects.

<p>Unfortunately, some event APIs have been designed such that implementing them efficiently
requires observing <a>event listeners</a>. This can make the presence of listeners observable in
that even empty listeners can have a dramatic performance impact on the behavior of the application.
For example, touch and wheel events which can be used to block asynchronous scrolling. In some cases
this problem can be mitigated by specifying the event to be {{Event/cancelable}} only when there is
at least one non-{{AddEventListenerOptions/passive}} listener. For example,
non-{{AddEventListenerOptions/passive}} {{TouchEvent}} listeners must block scrolling, but if all
listeners are {{AddEventListenerOptions/passive}} then scrolling can be allowed to start
<a>in parallel</a> by making the {{TouchEvent}} uncancelable (so that calls to
{{Event/preventDefault()}} are ignored). So code dispatching an event is able to observe the absence
of non-{{AddEventListenerOptions/passive}} listeners, and use that to clear the {{Event/cancelable}}
property of the event being dispatched.

<p>Ideally, any new event APIs are defined such that they do not need this property (use
<a href="https://lists.w3.org/Archives/Public/public-script-coord/">public-scrip-coord@w3.org</a>
for discussion).


<h3 id=dispatching-events>Dispatching events</h3>

<p>To <dfn export for=Event id=concept-event-dispatch>dispatch</dfn> an <var>event</var> to a
<var>target</var>, with an optional <var>targetOverride</var>, run these steps:

<ol>
 <li><p>Set <var>event</var>'s <a>dispatch flag</a>.

 <li>
  <p>If <var>targetOverride</var> is not given, let <var>targetOverride</var> be <var>target</var>.

  <p class="note">The <var>targetOverride</var> argument is only used by HTML and only under very
  specific circumstances.
  <!-- We should consider refactoring it to make it have less of a scope, since we don't really want
       folks to start using it for non-legacy scenarios. -->

 <li><p>Append (<var>target</var>, <var>targetOverride</var>) to <var>event</var>'s
 <a for=Event>path</a>.

 <li><p>Let <var>parent</var> be the result of invoking <var>target</var>'s <a>get the parent</a>
 with <var>event</var>.

 <li>
  <p>While <var>parent</var> is non-null:</p>

  <ol>
   <li><p>If <var>target</var>'s <a for=tree>root</a> is a
   <a>shadow-including inclusive ancestor</a> of <var>parent</var>, then append
   (<var>parent</var>, null) to <var>event</var>'s <a for=Event>path</a>.

   <li><p>Otherwise, set <var>target</var> to <var>parent</var> and append
   (<var>parent</var>, <var>target</var>) to <var>event</var>'s <a for=Event>path</a>.

   <li><p>Set <var>parent</var> to the result of invoking <var>parent</var>'s <a>get the parent</a>
   with <var>event</var>.
  </ol>

 <li><p>Set <var>event</var>'s {{Event/eventPhase}} attribute to {{Event/CAPTURING_PHASE}}.

 <li>
  <p>For each <var>tuple</var> in <var>event</var>'s <a for=Event>path</a>, in reverse order:

  <ol>
   <li><p>Set <var>event</var>'s {{Event/target}} attribute to the <b>target</b> of the last tuple
   in <var>event</var>'s <a for=Event>path</a>, that is either <var>tuple</var> or preceding
   <var>tuple</var>, whose <b>target</b> is non-null.

   <li><p>If <var>tuple</var>'s <b>target</b> is null, then <a>invoke</a> <var>tuple</var>'s
   <b>item</b> with <var>event</var>.
  </ol>

 <li>
  <p>For each <var>tuple</var> in <var>event</var>'s <a for=Event>path</a>, in order:

  <ol>
   <li><p>Set <var>event</var>'s {{Event/target}} attribute to the <b>target</b> of the last tuple
   in <var>event</var>'s <a for=Event>path</a>, that is either <var>tuple</var> or preceding
   <var>tuple</var>, whose <b>target</b> is non-null.

   <li><p>If <var>tuple</var>'s <b>target</b> is non-null, then set <var>event</var>'s
   {{Event/eventPhase}} attribute to {{Event/AT_TARGET}}.

   <li><p>Otherwise, set <var>event</var>'s {{Event/eventPhase}} attribute to
   {{Event/BUBBLING_PHASE}}.

   <li><p>If either <var>event</var>'s {{Event/eventPhase}} attribute is {{Event/BUBBLING_PHASE}}
   and <var>event</var>'s {{Event/bubbles}} attribute is true or <var>event</var>'s
   {{Event/eventPhase}} attribute is {{Event/AT_TARGET}}, then <a>invoke</a> <var>tuple</var>'s
   <b>item</b> with <var>event</var>.
  </ol>

 <li><p>Unset <var>event</var>'s <a>dispatch flag</a>.

 <li><p>Set <var>event</var>'s {{Event/eventPhase}} attribute to {{Event/NONE}}.

 <li><p>Set <var>event</var>'s {{Event/currentTarget}} attribute to null.

 <li><p>Set <var>event</var>'s <a for=Event>path</a> to the empty list.

 <li><p>Return false if <var>event</var>'s <a>canceled flag</a> is set, and true otherwise.
</ol>

<p>To <dfn noexport for="event listener" id=concept-event-listener-invoke>invoke</dfn> an
<var>object</var> with <var>event</var>, run these steps:

<ol>
 <li><p>If <var>event</var>'s <a>stop propagation flag</a> is set, then terminate these steps.

 <li><p>Let <var>listeners</var> be the empty list.

 <li>
  <p>For each <a>event listener</a> associated with <var>object</var>, append a pointer to the
  <a>event listener</a> to <var>listeners</var>.

  <p class="note no-backref">This avoids <a>event listeners</a> added after this point from being
  run. Note that removal still has an effect due to the <b>removed</b> field.

 <li><p>Initialize <var>event</var>'s {{Event/currentTarget}} attribute to <var>object</var>.

 <li><p>Let <var>found</var> be the result of running <a>inner invoke</a> <var>object</var> with
 <var>event</var>.

 <li>
  <p>If <var>found</var> is false, run these substeps:

  <ol>
   <li><p>Let <var>originalEventType</var> be <var>event</var>'s {{Event/type}} attribute value.

   <li>
    <p>If <var>event</var>'s {{Event/type}} attribute value is a match for any of the strings in the
    first column in the following table, set <var>event</var>'s {{Event/type}} attribute value to
    the string in the second column on the same row as the matching string, and terminate these
    substeps otherwise.

    <table>
     <thead>
      <tr><th>Event type<th>Legacy event type
     <tbody>
      <tr><td>"<code>animationend</code>"<td>"<code>webkitAnimationEnd</code>"
      <tr><td>"<code>animationiteration</code>"<td>"<code>webkitAnimationIteration</code>"
      <tr><td>"<code>animationstart</code>"<td>"<code>webkitAnimationStart</code>"
      <tr><td>"<code>transitionend</code>"<td>"<code>webkitTransitionEnd</code>"
    </table>

   <li><p><a>Inner invoke</a> <var>object</var> with <var>event</var>.

   <li><p>Set <var>event</var>'s {{Event/type}} attribute value to <var>originalEventType</var>.
  </ol>
</ol>

<p>To <dfn noexport for="event listener" id=concept-event-listener-inner-invoke>inner invoke</dfn>
an <var>object</var> with <var>event</var>, run these steps:

<ol>
 <li><p>Let <var>found</var> be false.

 <li>
  <p>For each <var>listener</var> in <var>listeners</var>, whose <b>removed</b> is false, run
  these substeps:

  <ol>
   <li><p>If <var>event</var>'s {{Event/type}} attribute value is not <var>listener</var>'s
   <b>type</b>, terminate these substeps (and run them for the next <a>event listener</a>).

   <li><p>Set <var>found</var> to true.

   <li><p>If <var>event</var>'s {{Event/eventPhase}} attribute value is {{Event/CAPTURING_PHASE}}
   and <var>listener</var>'s <b>capture</b> is false, terminate these substeps (and run them for the
   next <a>event listener</a>).

   <li><p>If <var>event</var>'s {{Event/eventPhase}} attribute value is {{Event/BUBBLING_PHASE}} and
   <var>listener</var>'s <b>capture</b> is true, terminate these substeps (and run them for the next
   <a>event listener</a>).

   <li><p>If <var>listener</var>'s <b>once</b> is true, then remove <var>listener</var> from
   <var>object</var>'s associated list of <a>event listeners</a>.
   <!-- Do this before invocation to avoid reentrancy issues. No need to set removed to true since
        each listener in listeners is run once anyway. -->

   <li><p>If <var>listener</var>'s <b>passive</b> is true, set <var>event</var>'s
   <a>in passive listener flag</a>.

   <li><p>Call <var>listener</var>'s <b>callback</b>'s {{EventListener/handleEvent()}}, with
   <var>event</var> as argument and <var>event</var>'s {{Event/currentTarget}} attribute value as
   <a>callback this value</a>. If this throws an exception, <a>report the exception</a>.

   <li><p>Unset <var>event</var>'s <a>in passive listener flag</a>.

   <li><p>If <var>event</var>'s <a>stop immediate propagation flag</a> is set,
   return <var>found</var>.
  </ol>

 <li><p>Return <var>found</var>.
</ol>

<h3 id=firing-events>Firing events</h3>

To
<dfn export id=concept-event-fire lt="fire an event">fire an event named <var>e</var></dfn>
means that a new <a>event</a> using the
{{Event}} interface, with its
{{Event/type}} attribute initialized to
<var>e</var>, and its {{Event/isTrusted}}
attribute initialized to <code>true</code>, is to be
<a>dispatched</a> to the given object.

<p class="note no-backref">Fire in the context of DOM is short for creating, initializing,
and <a>dispatching</a> an <a>event</a>.
<a>Fire an event</a> makes that process easier to write
down. If the <a>event</a> needs its {{Event/bubbles}} or
{{Event/cancelable}} attribute initialized, one could write
"<a>fire an event</a> named
<code>submit</code> with its {{Event/cancelable}} attribute
initialized to true".


<h3 id=action-versus-occurance>Action versus occurrence</h3>

<p>An <a>event</a> signifies an occurrence, not an action. Phrased differently, it
represents a notification from an algorithm and can be used to influence the future course
of that algorithm (e.g., through invoking {{preventDefault()}}). <a>Events</a> must not be
used as actions or initiators that cause some algorithm to start running. That is not what
they are for.

<p class="note no-backref">This is called out here specifically because previous
iterations of the DOM had a concept of "default actions" associated with <a>events</a>
that gave folks all the wrong ideas. <a>Events</a> do not represent or cause actions, they
can only be used to influence an ongoing one.



<h2 id=nodes>Nodes</h2>

<h3 id=introduction-to-the-dom>Introduction to "The DOM"</h3>

In its original sense, "The DOM" is an API for
accessing and manipulating documents (in particular, HTML and XML
documents). In this specification, the term "document" is used for any
markup-based resource, ranging from short static documents to long essays or
reports with rich multimedia, as well as to fully-fledged interactive
applications.

Each such document is represented as a <a>node tree</a>. Some of the <a>nodes</a> in a <a>tree</a>
can have <a>children</a>, while others are always leaves.

To illustrate, consider this HTML document:

<pre class='lang-markup'>
&lt;!DOCTYPE html>
&lt;html class=e>
 &lt;head>&lt;title>Aliens?&lt;/title>&lt;/head>
 &lt;body>Why yes.&lt;/body>
&lt;/html>
</pre>

It is represented as follows:

<ul class="domTree">
 <li>
  <a>Document</a>
  <ul>
   <li class="t10"><a>Doctype</a>: <code>html</code>
   <li class="t1">{{Element}}: <code>html</code> <span class="t2"><code class="attribute name">class</code>="<code class="attribute value">e</code>"</span>
    <ul>
     <li class="t1">
      {{Element}}: <code>head</code>
      <ul>
       <li class="t1">
        {{Element}}: <code>title</code>
        <ul>
         <li class="t3">{{Text}}: <span>Aliens?</span>
        </ul>

      </ul>

     <li class="t3">{{Text}}: <span>⏎␣</span>
     <li class="t1">
      {{Element}}: <code>body</code>
      <ul>
       <li class="t3">{{Text}}: <span>Why yes.⏎</span>
      </ul>

    </ul>

  </ul>

</ul>

<!--
http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C!DOCTYPE%20html%3E%0D%0A%3Chtml%20class%3De%3E%0D%0A%20%3Chead%3E%3Ctitle%3EAliens%3F%3C%2Ftitle%3E%3C%2Fhead%3E%0D%0A%20%3Cbody%3EWhy%20yes.%3C%2Fbody%3E%0D%0A%3C%2Fhtml%3E
-->

Note that, due to the magic that is
<a>HTML parsing</a>, not all
<a>ASCII whitespace</a> were turned into
{{Text}} <a>nodes</a>, but the general
concept is clear. Markup goes in, a <a>tree</a> of
<a>nodes</a> comes out.
<!-- You /can/ explain that! harharhar -->

<p class="note no-backref">The most excellent
<a href="http://software.hixie.ch/utilities/js/live-dom-viewer/">Live DOM Viewer</a>
can be used to explore this matter in more detail.


<h3 id=node-trees>Node tree</h3>

<p>{{Document}}, {{DocumentType}}, {{DocumentFragment}}, {{ShadowRoot}}, {{Element}}, {{Text}},
{{ProcessingInstruction}}, and {{Comment}} objects (simply called
<dfn export id=concept-node>nodes</dfn>) <a>participate</a> in a <a>tree</a>, simply named the
<dfn export id=concept-node-tree>node tree</dfn>.

<p>A <a>node tree</a> is constrained as follows, expressed as a relationship between the type of
<a>node</a> and its allowed <a>children</a>:

<dl>
 <dt>{{Document}}
 <dd>
  <p>In <a>tree order</a>:
  <ol>
   <li><p>Zero or more nodes each of which is {{ProcessingInstruction}} or {{Comment}}.
   <li><p>Optionally one {{DocumentType}} node.
   <li><p>Zero or more nodes each of which is {{ProcessingInstruction}} or {{Comment}}.
   <li><p>Optionally one {{Element}} node.
   <li><p>Zero or more nodes each of which is {{ProcessingInstruction}} or {{Comment}}.
  </ol>
 <dt>{{DocumentFragment}}
 <dt>{{ShadowRoot}}
 <dt>{{Element}}
 <dd><p>Zero or more nodes each of which is {{Element}}, {{Text}}, {{ProcessingInstruction}}, or
 {{Comment}}.
 <dt>{{DocumentType}}
 <dt>{{Text}}
 <dt>{{ProcessingInstruction}}
 <dt>{{Comment}}
 <dd><p>None.
</dl>
<!--AttrExodus -->

The <dfn export id=concept-node-length for=Node>length</dfn> of a
<a>node</a> <var>node</var> depends on
<var>node</var>:
<dl class=switch>
 <dt>{{DocumentType}}
 <dd>Zero.

 <dt>{{Text}}
 <dt>{{ProcessingInstruction}}
 <dt>{{Comment}}
 <dd>Its {{CharacterData/length}} attribute
 value.

 <dt>Any other node
 <dd>Its number of <a>children</a>.
</dl>

A <a>node</a> is considered
<dfn export id=concept-node-empty for=Node>empty</dfn> if its
<a>length</a> is zero.


<h4 id=document-trees>Document tree</h4>

<p>A <dfn export id=concept-document-tree>document tree</dfn> is a <a>node tree</a> whose
<a for=tree>root</a> is a <a>document</a>.

<p>The <dfn export>document element</dfn> of a <a>document</a> is the <a for="/">element</a> whose
<a>parent</a> is that <a>document</a>, if it exists, and null otherwise.

<p class="note no-backref">Per the <a>node tree</a> constraints, there can be only one such
<a for="/">element</a>.

<p>An <a for=/>element</a> is <dfn export>in a document</dfn> if its <a for=tree>root</a> is a
<a>document</a>.


<h4 id=shadow-trees>Shadow tree</h4>

<p>A <dfn export id=concept-shadow-tree>shadow tree</dfn> is a <a>node tree</a> whose
<a for=tree>root</a> is a <a for=/>shadow root</a>.

<p>A <a for=/>shadow root</a> is always connected to another <a>node tree</a> through its
<a for=DocumentFragment>host</a>. A <a>shadow tree</a> is therefore never alone. The
<a>node tree</a> of a <a for=/>shadow root</a>'s <a for=DocumentFragment>host</a> is sometimes
referred to as the <dfn export id=concept-light-tree>light tree</dfn>.</p>

<p class="note">A <a>shadow tree</a>'s corresponding <a>light tree</a> can be a <a>shadow tree</a>
itself.</p>

<p>An <a for=/>element</a> is <dfn export>in a shadow-including document</dfn> if its
<a>shadow-including root</a> is a <a>document</a>.

<h5 id=shadow-tree-slots>Slots</h5>

<p>A <a>shadow tree</a> contains zero or more <a for=/>elements</a> that are
<dfn export id=concept-slot lt=slot>slots</dfn>.</p>

<p class="note">A <a>slot</a> can only be created through HTML's <{slot}> element.</p>

<p>A <a>slot</a> has an associated <dfn export for=slot>name</dfn> (a string). Unless stated
otherwise it is the empty string.</p>

<p>Use these <a>attribute change steps</a> to update a <a>slot</a>'s <a for=slot>name</a>:

<ol>
 <li>
  <p>If <var>element</var> is a <a>slot</a>, <var>localName</var> is <code>name</code>, and
  <var>namespace</var> is null, then:

  <ol>
   <li><p>If <var>value</var> is <var>oldValue</var>, then return.

   <li><p>If <var>value</var> is null and <var>oldValue</var> is the empty string, then return.

   <li><p>If <var>value</var> is the empty string and <var>oldValue</var> is null, then return.

   <li><p>If <var>value</var> is null or the empty string, then set <var>element</var>'s
   <a for=slot>name</a> to the empty string.

   <li><p>Otherwise, set <var>element</var>'s <a for=slot>name</a> to <var>value</var>.

   <li><p>Run <a>assign slotables for a tree</a> with <var>element</var>'s <a>tree</a>.
  </ol>
</ol>

<p class="note">The first <a>slot</a> in a <a>shadow tree</a>, in <a>tree order</a>, whose
<a for=slot>name</a> is the empty string, is sometimes known as the "default slot".</p>

<p>A <a>slot</a> has an associated <dfn export for=slot>assigned nodes</dfn> (a list of
<a>slotables</a>). Unless stated otherwise it is empty.</p>

<h5 id=light-tree-slotables>Slotables</h5>

<p>{{Element}} and {{Text}} <a>nodes</a> are
<dfn export id=concept-slotable lt=slotable>slotables</dfn>.</p>

<p class="note">A <a>slot</a> can be a <a>slotable</a>.

<p>A <a>slotable</a> has an associated <dfn export for=slotable>name</dfn> (a string). Unless stated
otherwise it is the empty string.</p>

<p>Use these <a>attribute change steps</a> to update a <a>slotable</a>'s <a for=slotable>name</a>:

<ol>
 <li>
  <p>If <var>localName</var> is <code>slot</code> and <var>namespace</var> is null, then:

  <ol>
   <li><p>If <var>value</var> is <var>oldValue</var>, then return.

   <li><p>If <var>value</var> is null and <var>oldValue</var> is the empty string, then return.

   <li><p>If <var>value</var> is the empty string and <var>oldValue</var> is null, then return.

   <li><p>If <var>value</var> is null or the empty string, then set <var>element</var>'s
   <a for=slotable>name</a> to the empty string.

   <li><p>Otherwise, set <var>element</var>'s <a for=slotable>name</a> to <var>value</var>.

   <li><p>If <var>element</var> is <a for=slotable>assigned</a>, then run <a>assign slotables</a>
   for <var>element</var>'s <a for=slotable>assigned slot</a>.

   <li><p>Run <a>assign a slot</a> for <var>element</var>.
  </ol>
</ol>

<p>A <a>slotable</a> has an associated <dfn export for=slotable>assigned slot</dfn> (null or a
<a>slot</a>). Unless stated otherwise it is null. A <a>slotable</a> is
<dfn export for=slotable>assigned</dfn> if its <a>assigned slot</a> is non-null.</p>

<h5 id=finding-slots-and-slotables>Finding slots and slotables</h5>

<p>To <dfn export lt="find a slot|finding a slot">find a slot</dfn> for a given <a>slotable</a>
<var>slotable</var> and an optional <i>open flag</i> (unset unless stated otherwise), run these
steps:</p>

<ol>
 <li><p>If <var>slotable</var>'s <a>parent</a> is null, then return null.</p></li>

 <li><p>Let <var>shadow</var> be <var>slotable</var>'s <a>parent</a>'s
 <a for=Element>shadow root</a>.</p></li>

 <li><p>If <var>shadow</var> is null, then return null.</p></li>

 <li><p>If the <i>open flag</i> is set and <var>shadow</var>'s <a for=ShadowRoot>mode</a> is
 <em>not</em> "<code>open</code>", then return null.</p></li>

 <li><p>Return the first <a>slot</a> in <var>shadow</var>'s <a>tree</a> whose <a for=slot>name</a>
 is <var>slotable</var>'s <a for=slotable>name</a>, if any, and null otherwise.</p></li>
</ol>

<p>To <dfn export lt="find slotables|finding slotables">find slotables</dfn> for a given <a>slot</a>
<var>slot</var>, run these steps:</p>

<ol>
 <li><p>Let <var>result</var> be an empty list.</p></li>

 <li><p>If <var>slot</var>'s <a for=tree>root</a> is not a <a for=/>shadow root</a>, then return
 <var>result</var>.</p></li>

 <li><p>Let <var>host</var> be <var>slot</var>'s <a for=tree>root</a>'s
 <a for=DocumentFragment>host</a>.</p></li>

 <li>
  <p>For each <a>slotable</a> <a>child</a> of <var>host</var>, <var>slotable</var>, in
  <a>tree order</a>, run these substeps:</p>

  <ol>
   <li><p>Let <var>foundSlot</var> be the result of <a>finding a slot</a> given
   <var>slotable</var>.</p></li>

   <li><p>If <var>foundSlot</var> is <var>slot</var>, then append <var>slotable</var> to
   <var>result</var>.</p></li>
  </ol>
 </li>

 <li><p>Return <var>result</var>.</p></li>
</ol>

<p>To
<dfn export lt="find flattened slotables|finding flattened slotables">find flattened slotables</dfn>
for a given <a>slot</a> <var>slot</var>, run these steps:</p>

<ol>
 <li><p>Let <var>result</var> be an empty list.</p></li>

 <li><p>Let <var>slotables</var> be the result of <a>finding slotables</a> given
 <var>slot</var>.</p></li>

 <li><p>If <var>slotables</var> is the empty list, then append each <a>slotable</a>
 <a for=tree>child</a> of <var>slot</var>, in <a>tree order</a>, to <var>slotables</var>.</p></li>

 <li>
  <p>For each <var>node</var> in <var>slotables</var>, run these substeps:</p>

  <ol>
   <li>
    <p>If <var>node</var> is a <a>slot</a>, run these subsubsteps:</p>

    <ol>
     <li><p>Let <var>temporaryResult</var> be the result of <a>finding flattened slotables</a> given
     <var>node</var>.</p></li>

     <li><p>Append each <a>slotable</a> in <var>temporaryResult</var>, in order, to
     <var>result</var>.</p></li>
    </ol>

   <li><p>Otherwise, append <var>node</var> to <var>result</var>.</p></li>
  </ol>
 </li>

 <li><p>Return <var>result</var>.</p></li>
</ol>

<h5 id=assigning-slotables-and-slots>Assigning slotables and slots</h5>

<p>To <dfn noexport>assign slotables</dfn>, for a <a>slot</a> <var>slot</var> with an optional
<var>suppress signaling flag</var> (unset unless stated otherwise), run these steps:

<ol>
 <li><p>Let <var>slotables</var> be the result of <a>finding slotables</a> for <var>slot</var>.

 <li><p>If <var>suppress signaling flag</var> is unset, and <var>slotables</var> and
 <var>slot</var>'s <a>assigned nodes</a> are not identical, then run <a>signal a slot change</a> for
 <var>slot</var>.

 <li><p>Set <var>slot</var>'s <a>assigned nodes</a> to <var>slotables</var>.

 <li><p>For each <var>slotable</var> in <var>slotables</var>, set <var>slotable</var>'s
 <a>assigned slot</a> to <var>slot</var>.
</ol>

<p>To <dfn noexport>assign slotables for a tree</dfn>, given a <a>tree</a> <var>tree</var> and an
optional set of <a>slots</a> <var>noSignalSlots</var> (empty unless stated otherwise), run these
steps for each <a>slot</a> <var>slot</var> in <var>tree</var>, in <a>tree order</a>:

<ol>
 <li><p>Let <var>suppress signaling flag</var> be set, if <var>slot</var> is in
 <var>noSignalSlots</var>, and unset otherwise.</p></li>

 <li><p>Run <a>assign slotables</a> for <var>slot</var> with <var>suppress signaling flag</var>.
</ol>

<p>To <dfn noexport>assign a slot</dfn>, given a <a>slotable</a> <var>slotable</var>, run these
steps:

<ol>
 <li><p>Let <var>slot</var> be the result of <a>finding a slot</a> with <var>slotable</var>.

 <li><p>If <var>slot</var> is non-null, then run <a>assign slotables</a> for <var>slot</var>.
</ol>

<h5 id=signaling-slot-change>Signaling slot change</h5>

<p>Each <a>unit of related similar-origin browsing contexts</a> has a
<dfn export>signal slot list</dfn> (a list of <a>slots</a>). Unless stated otherwise it is empty.
[[!HTML]]

<p>To <dfn noexport>signal a slot change</dfn>, for a <a>slot</a> <var>slot</var>, run these steps:

<ol>
 <li><p>If <var>slot</var> is not in <a>unit of related similar-origin browsing contexts</a>'
 <a>signal slot list</a>, append <var>slot</var> to
 <a>unit of related similar-origin browsing contexts</a>' <a>signal slot list</a>.

 <li><p>If <var>slot</var> is <a for=slotable>assigned</a>, then run <a>signal a slot change</a> for
 <var>slot</var>'s <a>assigned slot</a>.

 <li><p>Otherwise, if <var>slot</var>'s <a>parent</a> is a <a>slot</a> and <var>slot</var>'s
 <a>parent</a>'s <a>assigned nodes</a> is the empty list, then run <a>signal a slot change</a> for
 <var>slot</var>'s <a>parent</a>.

 <li><p><a>Queue a mutation observer compound microtask</a>.
</ol>


<h4 id=mutation-algorithms>Mutation algorithms</h4>

To <dfn export for=Node id=concept-node-ensure-pre-insertion-validity>ensure pre-insertion validity</dfn>
of a <var>node</var> into a <var>parent</var> before a
<var>child</var>, run these steps:

<ol>
 <li>If <var>parent</var> is not a {{Document}},
 {{DocumentFragment}}, or {{Element}}
 <a>node</a>,
 <a>throw</a> a
 {{HierarchyRequestError}}.

 <li>If <var>node</var> is a
 <a>host-including inclusive ancestor</a>
 of <var>parent</var>, <a>throw</a> a
 {{HierarchyRequestError}}.

 <li>If <var>child</var> is not null and its <a>parent</a> is not <var>parent</var>, then
 <a>throw</a> a {{NotFoundError}}.

 <li>If <var>node</var> is not a
 {{DocumentFragment}}, {{DocumentType}},
 {{Element}}, {{Text}},
 {{ProcessingInstruction}}, or {{Comment}}
 <a>node</a>,
 <a>throw</a> a
 {{HierarchyRequestError}}.

 <li>If either <var>node</var> is a {{Text}}
 <a>node</a> and <var>parent</var> is a
 <a>document</a>, or <var>node</var> is a
 <a>doctype</a> and <var>parent</var> is
 not a <a>document</a>,
 <a>throw</a> a
 {{HierarchyRequestError}}.

 <li>
  If <var>parent</var> is a
  <a>document</a>, and any of the statements below, switched
  on <var>node</var>, are true, <a>throw</a> a
  {{HierarchyRequestError}}.

  <dl class=switch>
   <dt>{{DocumentFragment}} <a>node</a>
   <dd>
    If <var>node</var> has more than one
    <a for="/">element</a> <a>child</a>
    or has a {{Text}} <a>node</a>
    <a>child</a>.

    Otherwise, if <var>node</var> has one
    <a for="/">element</a>
    <a>child</a> and either <var>parent</var> has an
    <a for="/">element</a>
    <a>child</a>, <var>child</var> is a
    <a>doctype</a>, or <var>child</var> is not null and
    a <a>doctype</a> is
    <a>following</a> <var>child</var>.
    <!--"inclusively following"-->

   <dt><a for="/">element</a>
   <dd><var>parent</var> has an <a for="/">element</a>
   <a>child</a>, <var>child</var> is a
   <a>doctype</a>, or <var>child</var> is not null and a
   <a>doctype</a> is
   <a>following</a> <var>child</var>.
   <!--"inclusively following"-->

   <dt><a>doctype</a> <dd><var>parent</var> has a <a>doctype</a> <a>child</a>, <var>child</var> is
   non-null and an <a for="/">element</a> is <a>preceding</a> <var>child</var>, or <var>child</var>
   is null and <var>parent</var> has an <a for="/">element</a> <a>child</a>.
  </dl>
</ol>

To <dfn export for=Node id=concept-node-pre-insert>pre-insert</dfn> a
<var>node</var> into a <var>parent</var> before a
<var>child</var>, run these steps:

<ol>
 <li><a>Ensure pre-insertion validity</a>
 of <var>node</var> into <var>parent</var> before
 <var>child</var>.

 <li>Let <var>reference child</var> be <var>child</var>.

 <li>If <var>reference child</var> is <var>node</var>, set it
 to <var>node</var>'s
 <a>next sibling</a>.

 <li><a>Adopt</a>
 <var>node</var> into <var>parent</var>'s
 <a>node document</a>.

 <li><a for=Node>Insert</a> <var>node</var>
 into <var>parent</var> before <var>reference child</var>.

 <li>Return <var>node</var>.
 <!-- technically this is post-insert -->
</ol>

<p><a lt="Other applicable specifications">Specifications</a> may define
<dfn export for=Node id=concept-node-insert-ext>insertion steps</dfn> for all or some <a>nodes</a>.
The algorithm is passed <var>insertedNode</var>, as indicated in the <a for=Node>insert</a>
algorithm below.
<!-- See https://github.com/whatwg/dom/issues/34#issuecomment-125571750 for why we might need to
     adjust this further based on the requirements of the script element. There might be other ways
     to define that though as Olli suggests, so leaving that out for now. -->

To <dfn export id=concept-node-insert for=Node>insert</dfn> a <var>node</var>
into a <var>parent</var> before a <var>child</var>, with an optional
<i>suppress observers flag</i>, run these steps:

<ol>
 <li>Let <var>count</var> be the number of
 <a>children</a> of <var>node</var> if
 it is a {{DocumentFragment}} <a>node</a>,
 and one otherwise.

 <li>
  If <var>child</var> is non-null, run these substeps:

  <ol>
   <li>For each <a>range</a> whose
   <a>start node</a> is
   <var>parent</var> and
   <a>start offset</a> is greater than
   <var>child</var>'s <a>index</a>,
   increase its <a>start offset</a> by
   <var>count</var>.

   <li>For each <a>range</a> whose
   <a>end node</a> is
   <var>parent</var> and
   <a>end offset</a> is greater than
   <var>child</var>'s <a>index</a>,
   increase its <a>end offset</a> by
   <var>count</var>.
  </ol>

 <li>Let <var>nodes</var> be <var>node</var>'s
 <a>children</a> if <var>node</var> is
 a {{DocumentFragment}} <a>node</a>, and a
 list containing solely <var>node</var> otherwise.

 <li>If <var>node</var> is a {{DocumentFragment}}
 <a>node</a>,
 <a>remove</a> its
 <a>children</a> with the
 <i>suppress observers flag</i> set.

 <li>
  If <var>node</var> is a {{DocumentFragment}} <a>node</a>,
  <a>queue a mutation record</a> of "<code>childList</code>" for
  <var>node</var> with removedNodes <var>nodes</var>.

  <p class="note no-backref">This step intentionally does not pay attention to the
  <i>suppress observers flag</i>.

 <li>
  <p>For each <var>node</var> in <var>nodes</var>, in <a>tree order</a>, run these substeps:

  <ol>
   <li><p>Insert <var>node</var> into <var>parent</var> before <var>child</var> or at the end of
   <var>parent</var> if <var>child</var> is null.

   <li><p>If <var>parent</var> is a <a for=Element>shadow host</a> and <var>node</var> is a
   <a>slotable</a>, then <a>assign a slot</a> for <var>node</var>.

   <li><p>If <var>parent</var> is a <a>slot</a> whose <a>assigned nodes</a> is the empty list, then
   run <a>signal a slot change</a> for <var>parent</var>.

   <li><p>Run <a>assign slotables for a tree</a> with <var>node</var>'s <a>tree</a> and a set
   containing each <a>inclusive descendant</a> of <var>node</var> that is a <a>slot</a>.

   <li>
    <p>For each <a>shadow-including inclusive descendant</a> <var>inclusiveDescendant</var> of
    <var>node</var>, in <a>shadow-including tree order</a>, run these subsubsteps:

    <ol>
     <li><p>Run the <a>insertion steps</a> with <var>inclusiveDescendant</var>.

     <li>
      <p>If <var>inclusiveDescendant</var> is <a>in a shadow-including document</a>, then:

      <ol>
       <li><p>If <var>inclusiveDescendant</var> is <a>custom</a>, then
       <a>enqueue a custom element callback reaction</a> with <var>inclusiveDescendant</var>,
       callback name "<code>connectedCallback</code>", and an empty argument list.

       <li>
        <p>Otherwise, <a lt="try to upgrade an element">try to upgrade</a>
        <var>inclusiveDescendant</var>.

        <p class=note>If this successfully upgrades <var>inclusiveDescendant</var>, its
        <code>connectedCallback</code> will be enqueued automatically during the
        <a>upgrade an element</a> algorithm.
      </ol>
     </li>
    </ol>
   </li>
  </ol>

 <li>If <i>suppress observers flag</i> is unset,
 <a>queue a mutation record</a> of "<code>childList</code>" for
 <var>parent</var> with addedNodes <var>nodes</var>, nextSibling
 <var>child</var>, and previousSibling <var>child</var>'s
 <a>previous sibling</a> or <var>parent</var>'s <a>last child</a> if
 <var>child</var> is null.
</ol>


To <dfn export for=Node id=concept-node-append>append</dfn> a <var>node</var>
to a <var>parent</var>,
<a>pre-insert</a> <var>node</var>
into <var>parent</var> before null.


To <dfn export for=Node id=concept-node-replace>replace</dfn> a <var>child</var>
with <var>node</var> within a <var>parent</var>, run these
steps:

<!-- Step 1-5 could be shared with concept-node-pre-insert, although step 3
     in pre-insert is a superset (which is fine). Step 6.1.1 could also be
     shared. -->

<ol>
 <li>If <var>parent</var> is not a {{Document}},
 {{DocumentFragment}}, or {{Element}}
 <a>node</a>,
 <a>throw</a> a
 {{HierarchyRequestError}}.

 <li>If <var>node</var> is a
 <a>host-including inclusive ancestor</a>
 of <var>parent</var>, <a>throw</a> a
 {{HierarchyRequestError}}.

 <li>If <var>child</var>'s <a>parent</a> is not <var>parent</var>, then <a>throw</a> a
 {{NotFoundError}}.

 <li>If <var>node</var> is not a
 {{DocumentFragment}}, {{DocumentType}},
 {{Element}}, {{Text}},
 {{ProcessingInstruction}}, or {{Comment}}
 <a>node</a>,
 <a>throw</a> a
 {{HierarchyRequestError}}.

 <li>If either <var>node</var> is a {{Text}}
 <a>node</a> and <var>parent</var> is a
 <a>document</a>, or <var>node</var> is a
 <a>doctype</a> and <var>parent</var> is
 not a <a>document</a>,
 <a>throw</a> a
 {{HierarchyRequestError}}.

 <li>
  If <var>parent</var> is a
  <a>document</a>, and any of the statements below, switched
  on <var>node</var>, are true, <a>throw</a> a
  {{HierarchyRequestError}}.

  <dl class=switch>
   <dt>{{DocumentFragment}} <a>node</a>
   <dd>
    If <var>node</var> has more than one
    <a for="/">element</a> <a>child</a>
    or has a {{Text}} <a>node</a>
    <a>child</a>.

    Otherwise, if <var>node</var> has one
    <a for="/">element</a> <a>child</a>
    and either <var>parent</var> has an <a for="/">element</a>
    <a>child</a> that is not <var>child</var> or a
    <a>doctype</a> is
    <a>following</a> <var>child</var>.

   <dt><a for="/">element</a>
   <dd><var>parent</var> has an <a for="/">element</a>
   <a>child</a> that is not <var>child</var> or a
   <a>doctype</a> is
   <a>following</a> <var>child</var>.

   <dt><a>doctype</a>
   <dd><var>parent</var> has a <a>doctype</a>
   <a>child</a> that is not <var>child</var>, or an
   <a for="/">element</a> is
   <a>preceding</a> <var>child</var>.
  </dl>

  <p class="note no-backref">The above statements differ from the
  <a>pre-insert</a> algorithm.

 <li>Let <var>reference child</var> be <var>child</var>'s
 <a>next sibling</a>.

 <li>If <var>reference child</var> is <var>node</var>, set it
 to <var>node</var>'s
 <a>next sibling</a>.

 <li><p>Let <var>previousSibling</var> be <var>child</var>'s <a>previous sibling</a>.

 <li><a>Adopt</a>
 <var>node</var> into <var>parent</var>'s
 <a>node document</a>.

 <li>Let <var>removedNodes</var> be the empty list.

 <li>
  <p>If <var>child</var>'s <a>parent</a> is not null, run these substeps:

  <ol>
   <li><p>Set <var>removedNodes</var> to a list solely containing <var>child</var>.

   <li><p><a>Remove</a> <var>child</var> from its <var>parent</var> with the
   <i>suppress observers flag</i> set.
  </ol>

  <p class="note no-backref">The above can only be false if <var>child</var> is <var>node</var>.

 <li>Let <var>nodes</var> be <var>node</var>'s <a>children</a> if <var>node</var> is a
 {{DocumentFragment}} <a>node</a>, and a list containing solely <var>node</var> otherwise.
 <!-- This needs to come before insert as that removes the children of a
      DocumentFragment node. -->

 <li><a for=Node>Insert</a> <var>node</var>
 into <var>parent</var> before <var>reference child</var> with
 the <i>suppress observers flag</i> set.

 <li><a>Queue a mutation record</a> of "<code>childList</code>" for target
 <var>parent</var> with addedNodes <var>nodes</var>, removedNodes <var>removedNodes</var>,
 nextSibling <var>reference child</var>, and previousSibling
 <var>previousSibling</var>.

 <li>Return <var>child</var>.
</ol>


To <dfn export for=Node id=concept-node-replace-all>replace all</dfn> with a
<var>node</var> within a <var>parent</var>, run these steps:

<ol>
 <li>If <var>node</var> is not null,
 <a>adopt</a> <var>node</var> into
 <var>parent</var>'s
 <a>node document</a>.

 <li>Let <var>removedNodes</var> be <var>parent</var>'s
 <a>children</a>.

 <li>Let <var>addedNodes</var> be the empty list if <var>node</var> is
 null, <var>node</var>'s <a>children</a> if
 <var>node</var> is a {{DocumentFragment}}
 <a>node</a>, and a list containing <var>node</var>
 otherwise.

 <li><a>Remove</a> all
 <var>parent</var>'s <a>children</a>, in
 <a>tree order</a>, with the
 <i>suppress observers flag</i> set.

 <li>If <var>node</var> is not null,
 <a for=Node>insert</a> <var>node</var> into
 <var>parent</var> before null with the <i>suppress observers flag</i> set.

 <li><a>Queue a mutation record</a> of "<code>childList</code>" for
 <var>parent</var> with addedNodes <var>addedNodes</var> and
 removedNodes <var>removedNodes</var>.
</ol>

<p class="note no-backref">This algorithm does not make any checks with regards to the
<a>node tree</a> constraints. Specification authors need to use it wisely.


To <dfn export for=Node id=concept-node-pre-remove>pre-remove</dfn> a
<var>child</var> from a <var>parent</var>, run these steps:

<ol>
 <li>If <var>child</var>'s <a>parent</a> is not <var>parent</var>, then <a>throw</a> a
 {{NotFoundError}}.

 <li><a>Remove</a> <var>child</var>
 from <var>parent</var>.

 <li>Return <var>child</var>.
 <!-- technically this is post-remove -->
</ol>


<p><a lt="Other applicable specifications">Specifications</a> may define
<dfn export for=Node id=concept-node-remove-ext>removing steps</dfn> for all or some <a>nodes</a>.
The algorithm is passed <var>removedNode</var>, and optionally <var>oldParent</var>, as indicated in
the <a>remove</a> algorithm below.

To <dfn export for=Node id=concept-node-remove>remove</dfn> a <var>node</var>
from a <var>parent</var>, with an optional <i>suppress observers flag</i>, run these
steps:

<ol>
 <li>Let <var>index</var> be <var>node</var>'s
 <a>index</a>.

 <li>For each <a>range</a> whose
 <a>start node</a> is an
 <a>inclusive descendant</a> of
 <var>node</var>, set its
 <a>start</a> to
 (<var>parent</var>, <var>index</var>).

 <li>For each <a>range</a> whose
 <a>end node</a> is an
 <a>inclusive descendant</a> of
 <var>node</var>, set its
 <a>end</a> to
 (<var>parent</var>, <var>index</var>).

 <li>For each <a>range</a> whose
 <a>start node</a> is
 <var>parent</var> and
 <a>start offset</a> is greater than
 <var>index</var>, decrease its
 <a>start offset</a> by one.

 <li>For each <a>range</a> whose
 <a>end node</a> is
 <var>parent</var> and
 <a>end offset</a> is greater than
 <var>index</var>, decrease its
 <a>end offset</a> by one.

 <li><p>For each {{NodeIterator}} object <var>iterator</var> whose
 <a for=traversal>root</a>'s <a>node document</a> is <var>node</var>'s
 <a>node document</a>, run the <a><code>NodeIterator</code> pre-removing steps</a> given
 <var>node</var> and <var>iterator</var>.

 <li>Let <var>oldPreviousSibling</var> be <var>node</var>'s <a>previous sibling</a>.

 <li>Let <var>oldNextSibling</var> be <var>node</var>'s <a>next sibling</a>.

 <li>Remove <var>node</var> from its <var>parent</var>.

 <li><p>If <var>node</var> is <a for=slotable>assigned</a>, then run <a>assign slotables</a> for
 <var>node</var>'s <a>assigned slot</a>.

 <li><p>If <var>parent</var> is a <a>slot</a> whose <a>assigned nodes</a> is the empty list, then
 run <a>signal a slot change</a> for <var>parent</var>.

 <li><p>If <var>node</var> has an <a>inclusive descendant</a> that is a <a>slot</a>, then:

  <ol>
   <li><p>Run <a>assign slotables for a tree</a> with <var>parent</var>'s <a>tree</a>.

   <li><p>Run <a>assign slotables for a tree</a> with <var>node</var>'s <a>tree</a> and a set
   containing each <a>inclusive descendant</a> of <var>node</var> that is a <a>slot</a>.
  </ol>

 <li><p>Run the <a>removing steps</a> with <var>node</var> and <var>parent</var>.

 <li>
  <p>If <var>node</var> is <a>custom</a>, then <a>enqueue a custom element callback reaction</a>
  with <var>node</var>, callback name "<code>disconnectedCallback</code>", and an empty argument
  list.

  <p class=note>It is intentional for now that <a>custom</a> <a for=/>elements</a> do not get
  <var>parent</var> passed. This might change in the future if there is a need.

 <li>
  <p>For each <a>shadow-including descendant</a> <var>descendant</var> of <var>node</var>, in
  <a>shadow-including tree order</a>, run these substeps:

  <ol>
   <li><p>Run the <a>removing steps</a> with <var>descendant</var>.

   <li><p>If <var>descendant</var> is <a>custom</a>, then
   <a>enqueue a custom element callback reaction</a> with <var>descendant</var>, callback name
   "<code>disconnectedCallback</code>", and an empty argument list.
  </ol>
 </li>

 <li>For each <a>inclusive ancestor</a> <var>inclusiveAncestor</var> of
 <var>parent</var>, if <var>inclusiveAncestor</var> has any <a>registered observers</a>
 whose <b>options</b>' {{MutationObserverInit/subtree}} is true, then for each
 such <a>registered observer</a> <var>registered</var>, append a
 <a>transient registered observer</a> whose <b>observer</b> and <b>options</b>
 are identical to those of <var>registered</var> and <b>source</b>  which is
 <var>registered</var> to <var>node</var>'s list of
 <a>registered observers</a>.

 <li>If <i>suppress observers flag</i> is unset,
 <a>queue a mutation record</a> of "<code>childList</code>" for
 <var>parent</var> with removedNodes a list solely containing <var>node</var>,
 nextSibling <var>oldNextSibling</var>, and previousSibling
 <var>oldPreviousSibling</var>.
</ol>


<h4 id=interface-nonelementparentnode>Mixin {{NonElementParentNode}}</h4>

<p class="note no-backref">Web compatibility prevents the {{NonElementParentNode/getElementById()}}
method from being exposed on <a for="/">elements</a> (and therefore on {{ParentNode}}).

<pre class=idl>
[NoInterfaceObject,
 Exposed=Window]
interface NonElementParentNode {
  Element? getElementById(DOMString elementId);
};
Document implements NonElementParentNode;
DocumentFragment implements NonElementParentNode;
</pre>

<dl class=domintro>
 <dt><code><var>node</var> . <a method for=NonElementParentNode lt="getElementById()">getElementById</a>(<var>elementId</var>)</code>
 <dd><p>Returns the first <a for="/">element</a> within <var>node</var>'s <a>descendants</a> whose
 <a>ID</a> is <var>elementId</var>.
</dl>

<p>The <dfn method for=NonElementParentNode><code>getElementById(<var>elementId</var>)</code></dfn>
method, when invoked, must return the first <a for="/">element</a>, in <a>tree order</a>, within
<a>context object</a>'s <a>descendants</a>, whose <a>ID</a> is <var>elementId</var>, and null if
there is no such <a for="/">element</a> otherwise.


<h4 id=mixin-documentorshadowroot>Mixin {{DocumentOrShadowRoot}}</h4>

<pre class=idl>
[NoInterfaceObject,
 Exposed=Window]
interface DocumentOrShadowRoot {
};
Document implements DocumentOrShadowRoot;
ShadowRoot implements DocumentOrShadowRoot;
</pre>

<p class="note no-backref">The {{DocumentOrShadowRoot}} mixin is expected to be used by other
standards that want to define APIs shared between <a for=/>documents</a> and
<a for=/>shadow roots</a>.


<h4 id=interface-parentnode>Mixin {{ParentNode}}</h4>

To <dfn export lt="converting nodes into a node">convert nodes into a node</dfn>, given
<var>nodes</var> and <var>document</var>, run these steps:

<ol>
 <li><p>Let <var>node</var> be null.

 <li><p>Replace each string in <var>nodes</var> with a new {{Text}} <a>node</a> whose <a>data</a> is
 the string and <a>node document</a> is <var>document</var>.

 <li><p>If <var>nodes</var> contains one <a>node</a>, set <var>node</var> to that
 <a>node</a>.

 <li><p>Otherwise, set <var>node</var> to a new {{DocumentFragment}} whose <a>node document</a> is
 <var>document</var>, and then <a>append</a> each <a>node</a> in <var>nodes</var>, if any, to it.
 Rethrow any exceptions.

 <li><p>Return <var>node</var>.
</ol>

<pre class=idl>
[NoInterfaceObject,
 Exposed=Window]
interface ParentNode {
  [SameObject] readonly attribute HTMLCollection children;
  readonly attribute Element? firstElementChild;
  readonly attribute Element? lastElementChild;
  readonly attribute unsigned long childElementCount;

  [CEReactions, Unscopable] void prepend((Node or DOMString)... nodes);
  [CEReactions, Unscopable] void append((Node or DOMString)... nodes);

  Element? querySelector(DOMString selectors);
  [NewObject] NodeList querySelectorAll(DOMString selectors);
};
Document implements ParentNode;
DocumentFragment implements ParentNode;
Element implements ParentNode;
</pre>
<!--
  [Unscopable] Element? query(DOMString relativeSelectors);
  [NewObject, Unscopable] Elements queryAll(DOMString relativeSelectors);
-->

<dl class=domintro>
 <dt><code><var>collection</var> = <var>node</var> . {{ParentNode/children}}</code>
 <dd>Returns the <a>child</a> <a for="/">elements</a>.

 <dt><code><var>element</var> = <var>node</var> . {{ParentNode/firstElementChild}}</code>
 <dd>Returns the first <a>child</a> that is an <a for="/">element</a>, and null otherwise.

 <dt><code><var>element</var> = <var>node</var> . {{ParentNode/lastElementChild}}</code>
 <dd>Returns the last <a>child</a> that is an <a for="/">element</a>, and null otherwise.

 <!-- childElementCount is redundant -->

 <dt><code><var>node</var> . <a method for=ParentNode lt="prepend()">prepend</a>(<var>nodes</var>)</code>
 <dd>
  Inserts <var>nodes</var> before the
  <a>first child</a> of
  <var>node</var>, while replacing strings in <var>nodes</var>
  with equivalent {{Text}} <a>nodes</a>.

  <a>Throws</a> a
  {{HierarchyRequestError}} if the constraints of the
  <a>node tree</a> are violated.
  <!-- "NotFoundError" is impossible -->

 <dt><code><var>node</var> . <a method for=ParentNode lt="append()">append</a>(<var>nodes</var>)</code>
 <dd>
  Inserts <var>nodes</var> after the
  <a>last child</a> of
  <var>node</var>, while replacing strings in <var>nodes</var>
  with equivalent {{Text}} <a>nodes</a>.

  <a>Throws</a> a
  {{HierarchyRequestError}} if the constraints of the
  <a>node tree</a> are violated.
  <!-- "NotFoundError" is impossible -->

 <!--<dt><code><var>node</var> . <a method for=ParentNode lt="query()">query</a>(<var>relativeSelectors</var>)</code>
 <dd>
  Returns the first <a for="/">element</a> that is a
  <a>descendant</a> of <var>node</var> that
  matches <var>relativeSelectors</var>.

 <dt><code><var>node</var> . <a method for=ParentNode lt="queryAll()">queryAll</a>(<var>relativeSelectors</var>)</code>
 <dd>
  Returns all <a for="/">element</a>
  <a>descendants</a> of <var>node</var> that
  match <var>relativeSelectors</var>.-->

 <dt><code><var>node</var> . <a method for=ParentNode lt="querySelector()">querySelector</a>(<var>selectors</var>)</code>
 <dd>
  Returns the first <a for="/">element</a> that is a
  <a>descendant</a> of <var>node</var> that
  matches <var>selectors</var>.

 <dt><code><var>node</var> . <a method for=ParentNode lt="querySelectorAll()">querySelectorAll</a>(<var>selectors</var>)</code>
 <dd>
  Returns all <a for="/">element</a>
  <a>descendants</a> of <var>node</var> that
  match <var>selectors</var>.
</dl>

The <dfn attribute for=ParentNode>children</dfn>
attribute must return an {{HTMLCollection}}
<a>collection</a> rooted at the
<a>context object</a> matching only
<a for="/">element</a>
<a>children</a>.

The
<dfn attribute for=ParentNode>firstElementChild</dfn>
attribute must return the first <a>child</a>
that is an <a for="/">element</a>, and null otherwise.

The
<dfn attribute for=ParentNode>lastElementChild</dfn>
attribute must return the last <a>child</a>
that is an <a for="/">element</a>, and null otherwise.

The
<dfn attribute for=ParentNode>childElementCount</dfn>
attribute must return the number of <a>children</a> of the <a>context object</a> that are <a for="/">elements</a>.

The
<dfn method for=ParentNode>prepend(<var>nodes</var>)</dfn>
method must run these steps:

<ol>
 <li><p>Let <var>node</var> be the result of <a>converting nodes into a node</a> given
 <var>nodes</var> and <a>context object</a>'s <a>node document</a>. Rethrow any exceptions.

 <li><p><a>Pre-insert</a> <var>node</var> into <a>context object</a> before the
 <a>context object</a>'s <a>first child</a>. Rethrow any exceptions.
</ol>

The
<dfn method for=ParentNode>append(<var>nodes</var>)</dfn>
method must run these steps:

<ol>
 <li><p>Let <var>node</var> be the result of <a>converting nodes into a node</a> given
 <var>nodes</var> and <a>context object</a>'s <a>node document</a>. Rethrow any exceptions.

 <li><p><a>Append</a> <var>node</var> to <a>context object</a>. Rethrow any exceptions.
</ol>

<!--The <dfn method for=ParentNode><code>query(<var>relativeSelectors</var>)</code></dfn>
method, when invoked, must return the first result of running
<a>match a relative selectors string</a> <var>relativeSelectors</var> against
a set consisting of <a>context object</a>, and null if the result is an empty list.

The <dfn method for=ParentNode><code>queryAll(<var>relativeSelectors</var>)</code></dfn>
method, when invoked, must return an {{Elements}} array initialized with the result of
running <a>match a relative selectors string</a> <var>relativeSelectors</var> against
a set consisting of <a>context object</a>.-->

The <dfn method for=ParentNode><code>querySelector(<var>selectors</var>)</code></dfn>
method, when invoked, must return the first result of running
<a>scope-match a selectors string</a> <var>selectors</var> against the
<a>context object</a>, and null if the result is an empty list otherwise.

The <dfn method for="ParentNode"><code>querySelectorAll(<var>selectors</var>)</code></dfn>
method, when invoked, must return the <a lt="static collection">static</a> result of
running <a>scope-match a selectors string</a> <var>selectors</var> against the
<a>context object</a>.


<h4 id=interface-nondocumenttypechildnode>Mixin {{NonDocumentTypeChildNode}}</h4>

<p class="note no-backref">Web compatibility prevents the {{previousElementSibling}} and
{{nextElementSibling}} attributes from being exposed on <a for=/>doctypes</a> (and therefore on
{{ChildNode}}).

<pre class=idl>
[NoInterfaceObject,
 Exposed=Window]
interface NonDocumentTypeChildNode {
  readonly attribute Element? previousElementSibling;
  readonly attribute Element? nextElementSibling;
};
Element implements NonDocumentTypeChildNode;
CharacterData implements NonDocumentTypeChildNode;
</pre>

<dl class=domintro>
 <dt><code><var>element</var> = <var>node</var> . {{previousElementSibling}}</code>
 <dd>Returns the first
 <a>preceding</a>
 <a>sibling</a> that
 is an <a for="/">element</a>, and null otherwise.

 <dt><code><var>element</var> = <var>node</var> . {{nextElementSibling}}</code>
 <dd>Returns the first
 <a>following</a>
 <a>sibling</a> that
 is an <a for="/">element</a>, and null otherwise.
</dl>

The <dfn attribute for="NonDocumentTypeChildNode">previousElementSibling</dfn>
attribute must return the first <a>preceding</a> <a>sibling</a> that is an <a for="/">element</a>,
and null otherwise.

The <dfn attribute for=NonDocumentTypeChildNode>nextElementSibling</dfn>
attribute must return the first <a>following</a> <a>sibling</a> that is an <a for="/">element</a>,
and null otherwise.


<h4 id=interface-childnode>Mixin {{ChildNode}}</h4>

<pre class=idl>
[NoInterfaceObject,
 Exposed=Window]
interface ChildNode {
  [CEReactions, Unscopable] void before((Node or DOMString)... nodes);
  [CEReactions, Unscopable] void after((Node or DOMString)... nodes);
  [CEReactions, Unscopable] void replaceWith((Node or DOMString)... nodes);
  [CEReactions, Unscopable] void remove();
};
DocumentType implements ChildNode;
Element implements ChildNode;
CharacterData implements ChildNode;
</pre>

<dl class=domintro>
 <dt><code><var>node</var> . {{before(nodes)}}</code>
 <dd>
  Inserts <var>nodes</var> just before <var>node</var>,
  while replacing strings in <var>nodes</var> with equivalent
  {{Text}} <a>nodes</a>.

  <a>Throws</a> a
  {{HierarchyRequestError}} if the constraints of the
  <a>node tree</a> are violated.

 <dt><code><var>node</var> . {{after(nodes)}}</code>
 <dd>
  Inserts <var>nodes</var> just after <var>node</var>,
  while replacing strings in <var>nodes</var> with equivalent
  {{Text}} <a>nodes</a>.

  <a>Throws</a> a
  {{HierarchyRequestError}} if the constraints of the
  <a>node tree</a> are violated.

 <dt><code><var>node</var> . {{replaceWith(nodes)}}</code>
 <dd>
  Replaces <var>node</var> with <var>nodes</var>, while
  replacing strings in <var>nodes</var> with equivalent
  {{Text}} <a>nodes</a>.

  <a>Throws</a> a
  {{HierarchyRequestError}} if the constraints of the
  <a>node tree</a> are violated.

 <dt><code><var>node</var> . {{ChildNode/remove()}}</code>
 <dd>Removes <var>node</var>.
</dl>

The <dfn method for=ChildNode><code>before(<var>nodes</var>)</code></dfn> method, when
invoked, must run these steps:

<ol>
 <li><p>Let <var>parent</var> be <a>context object</a>'s <a>parent</a>.

 <li><p>If <var>parent</var> is null, terminate these steps.

 <li><p>Let <var>viablePreviousSibling</var> be <a>context object</a>'s first
 <a>preceding</a> <a>sibling</a> not in <var>nodes</var>, and null otherwise.

 <li><p>Let <var>node</var> be the result of <a>converting nodes into a node</a>, given
 <var>nodes</var> and <a>context object</a>'s <a>node document</a>. Rethrow any exceptions.

 <li><p>If <var>viablePreviousSibling</var> is null, set it to <var>parent</var>'s
 <a>first child</a>, and to <var>viablePreviousSibling</var>'s <a>next sibling</a> otherwise.

 <li><p><a>Pre-insert</a> <var>node</var> into <var>parent</var> before
 <var>viablePreviousSibling</var>. Rethrow any exceptions.
</ol>

The <dfn method for=ChildNode><code>after(<var>nodes</var>)</code></dfn> method, when
invoked, must run these steps:

<ol>
 <li><p>Let <var>parent</var> be <a>context object</a>'s <a>parent</a>.

 <li><p>If <var>parent</var> is null, terminate these steps.

 <li><p>Let <var>viableNextSibling</var> be <a>context object</a>'s first <a>following</a>
 <a>sibling</a> not in <var>nodes</var>, and null otherwise.

 <li><p>Let <var>node</var> be the result of <a>converting nodes into a node</a>, given
 <var>nodes</var> and <a>context object</a>'s <a>node document</a>. Rethrow any exceptions.

 <li><p><a>Pre-insert</a> <var>node</var> into <var>parent</var> before
 <var>viableNextSibling</var>. Rethrow any exceptions.
</ol>

The <dfn method for=ChildNode><code>replaceWith(<var>nodes</var>)</code></dfn> method,
when invoked, must run these steps:

<ol>
 <li><p>Let <var>parent</var> be <a>context object</a>'s <a>parent</a>.

 <li><p>If <var>parent</var> is null, terminate these steps.

 <li><p>Let <var>viableNextSibling</var> be <a>context object</a>'s first <a>following</a>
 <a>sibling</a> not in <var>nodes</var>, and null otherwise.

 <li><p>Let <var>node</var> be the result of <a>converting nodes into a node</a>, given
 <var>nodes</var> and <a>context object</a>'s <a>node document</a>. Rethrow any exceptions.

 <li>
  <p>If <a>context object</a>'s <a>parent</a> is <var>parent</var>, <a>replace</a> the
  <a>context object</a> with <var>node</var> within <var>parent</var>. Rethrow any exceptions.

  <p class=note><a>Context object</a> could have been inserted into <var>node</var>.

 <li><p>Otherwise, <a>pre-insert</a> <var>node</var> into <var>parent</var> before
 <var>viableNextSibling</var>. Rethrow any exceptions.
</ol>

The <dfn method for=ChildNode><code>remove()</code></dfn> method, when invoked, must run
these steps:

<ol>
 <li><p>If <a>context object</a>'s <a>parent</a> is null, terminate these steps.

 <li><p><a>Remove</a> the <a>context object</a> from <a>context object</a>'s
 <a>parent</a>.
</ol>


<h4 id=mixin-slotable>Mixin: {{Slotable}}</h4>

<pre class=idl>
[NoInterfaceObject,
 Exposed=Window]
interface Slotable {
  readonly attribute HTMLSlotElement? assignedSlot;
};
Element implements Slotable;
Text implements Slotable;
</pre>

<p>The <dfn attribute for=Slotable><code>assignedSlot</code></dfn> attribute's getter must return
the result of <a>find a slot</a> given <a>context object</a> and with the <i>open flag</i> set.</p>


<!--<h4 id=element-collections>Collections: {{Elements}}</h4>

<pre class='idl' data-no-idl>
class <dfn interface>Elements</dfn> extends Array {
  Element? <dfn method for=Elements lt="query(DOMString relativeSelectors)">query</dfn>(DOMString relativeSelectors);
  Elements <dfn method for=Elements lt="queryAll(DOMString relativeSelectors)">queryAll</dfn>(DOMString relativeSelectors);
};
</pre>

<div class=XXX>
IDL bugs: <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=20020">
Array subclassing</a> and <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=23225">class, not interface</a>.

{{Elements}} is a subclass of {{Array}} with two additional methods. It replaces the need
for {{HTMLCollection}} and {{NodeList}}. (If <a>nodes</a> need to be represented rather
than <a for="/">elements</a> a simple {{Array}} can be used.)
</div>

<dl class=domintro>
 <dt><code><var>elements</var> . {{Elements/query(relativeSelectors)}}</code>
 <dd>
  Returns the first <a for="/">element</a> that is a
  <a>descendant</a> of <var>elements</var> that
  matches <var>relativeSelectors</var>.

 <dt><code><var>elements</var> . {{Elements/queryAll(relativeSelectors)}}</code>
 <dd>
  Returns all <a for="/">element</a>
  <a>descendants</a> of <var>elements</var> that
  match <var>relativeSelectors</var>.
</dl>

The <dfn method for=Elements><code>query(<var>relativeSelectors</var>)</code></dfn>
method, when invoked, must return the first result of running
<a>match a relative selectors string</a> <var>relativeSelectors</var>
against the <a>context object</a>, and null if the result is an empty list.

The <dfn method for=Elements><code>queryAll(<var>relativeSelectors</var>)</code></dfn>
method, when invoked, must return the result of running
<code class='lang-javascript'>this.constructor</code> with the result of running
<a>match a relative selectors string</a> <var>relativeSelectors</var> against the
<a>context object</a>.-->


<h4 id=old-style-collections>Old-style collections: {{NodeList}} and {{HTMLCollection}}</h4>

A <dfn export for=Node id=concept-collection>collection</dfn> is an object that
represents a lists of DOM nodes. A
<a>collection</a> can be either
<dfn export for=Node id=concept-collection-live lt="live collection" local-lt="live">live</dfn> or
<dfn export for=Node id=concept-collection-static lt="static collection">static</dfn>. Unless otherwise stated,
a <a>collection</a> must be <a>live</a>.

If a <a>collection</a> is <a>live</a>, then the attributes and methods
on that object must operate on the actual underlying data, not a snapshot of
the data.

When a <a>collection</a> is created, a
filter and a root are associated with it.

The <a>collection</a> then
<dfn export for=Node lt="represented by the collection" id=represented-by-the-collection>represents</dfn>
a view of the subtree rooted at the <a>collection's</a> root, containing only nodes that match the
given filter. The view is linear. In the absence of specific requirements to the contrary, the nodes
within the <a>collection</a> must be sorted in <a>tree order</a>.


<h5 id=interface-nodelist>Interface {{NodeList}}</h5>

A {{NodeList}} object is a
<a>collection</a> of
<a>nodes</a>.

<pre class=idl>
[Exposed=Window]
interface NodeList {
  getter Node? item(unsigned long index);
  readonly attribute unsigned long length;
  iterable&lt;Node>;
};
</pre>

<dl class=domintro>
 <dt><var>collection</var> . {{NodeList/length}}</code>
 <dd>
  Returns the number of <a>nodes</a> in the
  <a>collection</a>.

 <dt><var>element</var> = <var>collection</var> . {{NodeList/item(index)}}
 <dt><var>element</var> = <var>collection</var>[<var>index</var>]
 <dd>
  Returns the <a>node</a> with index
  <var>index</var> from the
  <a>collection</a>. The
  <a>nodes</a> are sorted in
  <a>tree order</a>.
</dl>

<div class=impl>

The object's <a>supported property indices</a>
are the numbers in the range zero to one less than the number of nodes
<a>represented by the collection</a>. If there are no such elements, then
there are no <a>supported property indices</a>.

The <dfn attribute for=NodeList>length</dfn> attribute must
return the number of nodes <a>represented by the collection</a>.

The <dfn method for=NodeList><code>item(<var>index</var>)</code></dfn> method must return
the <var>index</var><sup>th</sup> <a>node</a> in the <a>collection</a>. If there is no
<var>index</var><sup>th</sup> <a>node</a> in the <a>collection</a>, then the method must
return null.

</div>


<h5 id=interface-htmlcollection>Interface {{HTMLCollection}}</h5>

<pre class=idl>
[Exposed=Window, LegacyUnenumerableNamedProperties]
interface HTMLCollection {
  readonly attribute unsigned long length;
  getter Element? item(unsigned long index);
  getter Element? namedItem(DOMString name);
};
</pre>

<p>An {{HTMLCollection}} object is a <a>collection</a> of <a for="/">elements</a>.

<p class="note no-backref">{{HTMLCollection}} is an historical artifact we cannot rid the web of.
While developers are of course welcome to keep using it, new API standard designers ought not to use
it (use <code>sequence&lt;T></code> in IDL instead).

<dl class=domintro>
 <dt><var>collection</var> . {{HTMLCollection/length}}
 <dd>
  Returns the number of <a for="/">elements</a> in
  the <a>collection</a>.

 <dt><var>element</var> = <var>collection</var> . {{HTMLCollection/item(index)}}
 <dt><var>element</var> = <var>collection</var>[<var>index</var>]
 <dd>
  Returns the <a for="/">element</a> with index
  <var>index</var> from the <a>collection</a>.
  The <a for="/">elements</a> are sorted in <a>tree order</a>.

 <dt><var>element</var> = <var>collection</var> . {{namedItem(name)}}
 <dt><var>element</var> = <var>collection</var>[<var>name</var>]
 <dd>
  Returns the first <a for="/">element</a> with <a>ID</a> or name <var>name</var>
  from the collection.
</dl>

<p>The object's <a>supported property indices</a> are the numbers in the range zero to one less than
the number of elements <a>represented by the collection</a>. If there are no such elements, then
there are no <a>supported property indices</a>.

<p>The <dfn attribute for=HTMLCollection><code>length</code></dfn> attribute's getter must return
the number of nodes <a>represented by the collection</a>.

<p>The <dfn method for=HTMLCollection><code>item(<var>index</var>)</code></dfn> method, when
invoked, must return the <var>index</var><sup>th</sup> <a for="/">element</a> in the
<a>collection</a>. If there is no <var>index</var><sup>th</sup> <a for="/">element</a> in the
<a>collection</a>, then the method must return null.

<p>The <a>supported property names</a> are the values from the list returned by these steps:

<ol>
 <li><p>Let <var>result</var> be an empty list.

 <li>
  <p>For each <var>element</var> <a>represented by the collection</a>, in <a>tree order</a>, run
  these substeps:

  <ol>
   <li><p>If <var>element</var> has an <a>ID</a> which is not in <var>result</var>, append
   <var>element</var>'s <a>ID</a> to <var>result</var>.

   <li><p>If <var>element</var> is in the <a>HTML namespace</a> and <a lt="has an attribute">has</a>
   a <a lt="named attribute"><code>name</code> attribute</a> whose <a for=Attr>value</a> is neither
   the empty string nor is in <var>result</var>, append <var>element</var>'s
   <a lt="named attribute"><code>name</code> attribute</a> <a for=Attr>value</a> to
   <var>result</var>.
  </ol>

 <li><p>Return <var>result</var>.
</ol>

<p>The <dfn method for=HTMLCollection><code>namedItem(<var>key</var>)</code></dfn> method, when
invoked, must run these steps:

<ol>
 <li><p>If <var>key</var> is the empty string, return null.

 <li>
  <p>Return the first <a for="/">element</a> in the <a>collection</a> for which at least one of
  the following is true:

  <ul>
   <li>it has an <a>ID</a> which is <var>key</var>;

   <li>it is in the <a>HTML namespace</a> and <a lt="has an attribute">has</a> a
   <a lt="named attribute"><code>name</code> attribute</a> whose <a for=Attr>value</a> is
   <var>key</var>;
  </ul>

  <p>or null if there is no such <a for="/">element</a>.
</ol>



<h3 id=mutation-observers>Mutation observers</h3>

Each
<a>unit of related similar-origin browsing contexts</a> has a
<dfn export>mutation observer compound microtask queued flag</dfn>, which is initially unset, and an
associated list of {{MutationObserver}} objects, which is initially empty.
[[!HTML]]

To <dfn export>queue a mutation observer compound microtask</dfn>, run these steps:

<ol>
 <li>If <a>mutation observer compound microtask queued flag</a> is set, terminate
 these steps.

 <li>Set <a>mutation observer compound microtask queued flag</a>.

 <li><a lt="queue a microtask">Queue</a> a
 <a>compound microtask</a> to
 <a>notify mutation observers</a>.
</ol>

To <dfn export>notify mutation observers</dfn>, run these steps:

<ol>
 <li>Unset <a>mutation observer compound microtask queued flag</a>.

 <li>Let <var>notify list</var> be a copy of
 <a>unit of related similar-origin browsing contexts</a>'
 list of {{MutationObserver}} objects.

 <li>
  For each {{MutationObserver}} object <var>mo</var> in <var>notify list</var>,
  <a>execute a compound microtask subtask</a> to run these steps: [[!HTML]]

  <ol>
   <li>Let <var>queue</var> be a copy of <var>mo</var>'s <a>record queue</a>.

   <li>Empty <var>mo</var>'s <a>record queue</a>.

   <li>Remove all <a>transient registered observers</a>
   whose <b>observer</b> is <var>mo</var>.

   <li>If <var>queue</var> is non-empty, call
   <var>mo</var>'s <a>callback</a>
   with <var>queue</var> as first argument, and
   <var>mo</var> (itself) as second argument and
   <a>callback this value</a>. If this throws an exception,
   <a>report the exception</a>.
  </ol>

 <li><p>Let <var>signalList</var> be a copy of
 <a>unit of related similar-origin browsing contexts</a>' <a>signal slot list</a>.

 <li><p>Empty <a>unit of related similar-origin browsing contexts</a>' <a>signal slot list</a>.

 <li><p>For each <a>slot</a> <var>slot</var> in <var>signalList</var>, in order,
 <a>fire an event</a> named <code>slotchange</code>, with its {{Event/bubbles}} attribute set to
 true, at <var>slot</var>.
</ol>

<hr>

Each <a>node</a> has an associated list of
<a>registered observers</a>.
<!-- XXX also mention this in the {{Node}} section non-normatively? -->

A <dfn export for=MutationObserver id=registered-observer>registered observer</dfn> consists of an
<b>observer</b> (a {{MutationObserver}} object) and <b>options</b> (a
{{MutationObserverInit}} dictionary). A
<dfn export for=MutationObserver id=transient-registered-observer>transient registered observer</dfn>
is a specific type of <a>registered observer</a> that has a <b>source</b> which is a
<a>registered observer</a>.

<p class="note no-backref"><a>Transient registered observers</a> are used to track
mutations within a given <a>node</a>'s <a>descendants</a> after <a>node</a> has been
removed so they do not get lost when <code>subtree</code> is set to true on <a>node</a>'s
<a>parent</a>.


<h4 id=interface-mutationobserver>Interface {{MutationObserver}}</h4>

<pre class="idl">
[Constructor(MutationCallback callback)]
interface MutationObserver {
  void observe(Node target, MutationObserverInit options);
  void disconnect();
  sequence&lt;MutationRecord> takeRecords();
};

callback MutationCallback = void (sequence&lt;MutationRecord> mutations, MutationObserver observer);

dictionary MutationObserverInit {
  boolean childList = false;
  boolean attributes;
  boolean characterData;
  boolean subtree = false;
  boolean attributeOldValue;
  boolean characterDataOldValue;
  sequence&lt;DOMString> attributeFilter;
};
</pre>

A {{MutationObserver}} object can be used to observe mutations
to the <a>tree</a> of
<a>nodes</a>.

Each {{MutationObserver}} object has these associated concepts:
<ul>
 <li>A <dfn export for=MutationObserver id=concept-mo-callback>callback</dfn> set on creation.
 <li>A list of <a>nodes</a> on which it is a <a>registered observer</a>'s <b>observer</b> that is initially empty.
 <li>A list of {{MutationRecord}} objects called the
 <dfn export for=MutationObserver id=concept-mo-queue>record queue</dfn> that is initially empty.
</ul>

<dl class=domintro>
 <dt><code><var>observer</var> = new {{MutationObserver(callback)}}</code>
 <dd>Constructs a {{MutationObserver}} object and sets its
 <a>callback</a> to
 <var>callback</var>. The <var>callback</var> is invoked with a
 list of {{MutationRecord}} objects as first argument and the
 constructed {{MutationObserver}} object as second argument. It is
 invoked after <a>nodes</a> registered with the
 {{MutationObserver/observe()}} method, are
 mutated.

 <dt><code><var>observer</var> . {{observe(target, options)}}</code>
 <dd>
  Instructs the user agent to observe a given <var>target</var>
  (a <a>node</a>) and report any mutations based on
  the criteria given by <var>options</var> (an object).

  The <var>options</var> argument allows for setting mutation
  observation options via object members. These are the object members that
  can be used:

  <dl>
   <dt>{{MutationObserverInit/childList}}
   <dd>Set to true if mutations to <var>target</var>'s <a>children</a> are to be observed.

   <dt>{{MutationObserverInit/attributes}}
   <dd>Set to true if mutations to <var>target</var>'s
   <a>attributes</a> are to be observed. Can be omitted if
   {{MutationObserverInit/attributeOldValue}} and/or
   {{MutationObserverInit/attributeFilter}} is
   specified.

   <dt>{{MutationObserverInit/characterData}}
   <dd>Set to true if mutations to <var>target</var>'s
   <a>data</a> are to be observed. Can be omitted if
   {{MutationObserverInit/characterDataOldValue}}
   is specified.

   <dt>{{MutationObserverInit/subtree}}
   <dd>Set to true if mutations to not just <var>target</var>, but
   also <var>target</var>'s
   <a>descendants</a> are to be
   observed.

   <dt>{{MutationObserverInit/attributeOldValue}}
   <dd>Set to true if
   {{MutationObserverInit/attributes}} is true or omitted
   and <var>target</var>'s
   <a>attribute</a>
   <a for=Attr>value</a> before the mutation
   needs to be recorded.

   <dt>{{MutationObserverInit/characterDataOldValue}}
   <dd>Set to true if
   {{MutationObserverInit/characterData}}
   is set to true or omitted and <var>target</var>'s
   <a>data</a> before the mutation
   needs to be recorded.

   <dt>{{MutationObserverInit/attributeFilter}}
   <dd>Set to a list of <a>attribute</a>
   <a for=Attr>local names</a> (without <a for=Attr>namespace</a>) if not all
   <a>attribute</a> mutations need to be
   observed and {{MutationObserverInit/attributes}} is true
   or omitted.
  </dl>

 <dt><code><var>observer</var> . {{disconnect()}}</code>
 <dd>Stops <var>observer</var> from observing any mutations.
 Until the {{observe()}} method
 is used again, <var>observer</var>'s
 <a>callback</a> will not be invoked.

 <dt><code><var>observer</var> . {{takeRecords()}}</code>
 <dd>Empties the <a>record queue</a> and
 returns what was in there.
</dl>

The
<dfn constructor for=MutationObserver>MutationObserver(<var>callback</var>)</dfn>
constructor must create a new {{MutationObserver}} object with
<a>callback</a> set to <var>callback</var>,
append it to the
<a>unit of related similar-origin browsing contexts</a>' list
of {{MutationObserver}} objects, and then return it.

The
<dfn method for=MutationObserver>observe(<var>target</var>, <var>options</var>)</dfn>
method, when invoked, must run these steps:

<ol>
 <li>If either <var>options</var>'
 {{MutationObserverInit/attributeOldValue}} or
 {{MutationObserverInit/attributeFilter}} is present
 and <var>options</var>'
 {{MutationObserverInit/attributes}} is omitted, set
 <var>options</var>'
 {{MutationObserverInit/attributes}} to true.

 <li>If <var>options</var>'
 {{MutationObserverInit/characterDataOldValue}}
 is present and <var>options</var>'
 {{MutationObserverInit/characterData}} is omitted, set
 <var>options</var>'
 {{MutationObserverInit/characterData}} to true.

 <li>If none of <var>options</var>'
 {{MutationObserverInit/childList}}
 {{MutationObserverInit/attributes}}, and
 {{MutationObserverInit/characterData}} is true,
 <a>throw</a> a <code>TypeError</code>.

 <li>If <var>options</var>'
 {{MutationObserverInit/attributeOldValue}} is true
 and <var>options</var>'
 {{MutationObserverInit/attributes}} is false,
 <a>throw</a> a <code>TypeError</code>.

 <li>If <var>options</var>'
 {{MutationObserverInit/attributeFilter}} is present
 and <var>options</var>'
 {{MutationObserverInit/attributes}} is false,
 <a>throw</a> a <code>TypeError</code>.

 <li>If <var>options</var>'
 {{MutationObserverInit/characterDataOldValue}}
 is true and <var>options</var>'
 {{MutationObserverInit/characterData}} is false,
 <a>throw</a> a <code>TypeError</code>.

 <li>
  For each <a>registered observer</a> <var>registered</var> in
  <var>target</var>'s list of
  <a>registered observers</a> whose <b>observer</b> is
  the <a>context object</a>:

  <ol>
   <li>Remove all
   <a>transient registered observers</a> whose
   <b>source</b> is <var>registered</var>.

   <li>Replace <var>registered</var>'s <b>options</b> with
   <var>options</var>.
  </ol>

 <li>Otherwise, add a new <a>registered observer</a> to
 <var>target</var>'s list of
 <a>registered observers</a> with the
 <a>context object</a> as the <b>observer</b> and <var>options</var> as the <b>options</b>,
 and add <var>target</var> to <a>context object</a>'s list of <a>nodes</a> on which it is registered.
</ol>

The
<dfn method for=MutationObserver>disconnect()</dfn>
method must, for each <a>node</a>
<var>node</var> in the <a>context object</a>'s list of
<a>nodes</a>, remove any
<a>registered observer</a> on <var>node</var>
for which the <a>context object</a> is the <b>observer</b>, and also
empty <a>context object</a>'s
<a>record queue</a>.

The
<dfn method for=MutationObserver>takeRecords()</dfn>
method must return a copy of the
<a>record queue</a> and then empty the
<a>record queue</a>.


<h4 id=queueing-a-mutation-record>Queuing a mutation record</h4>

To <dfn export>queue a mutation record</dfn> of <var>type</var> for
<var>target</var> with one or more of (depends on
<var>type</var>) name <var>name</var>, namespace
<var>namespace</var>, oldValue <var>oldValue</var>, addedNodes
<var>addedNodes</var>, removedNodes <var>removedNodes</var>,
previousSibling <var>previousSibling</var>, and nextSibling
<var>nextSibling</var>, run these steps:

<ol>
 <li>Let <var>interested observers</var> be an initially empty set
 of {{MutationObserver}} objects optionally paired with a string.

 <li>Let <var>nodes</var> be the <a>inclusive ancestors</a> of <var>target</var>.

 <li>
  <p>Then, for each <var>node</var> in <var>nodes</var>, and then for each
  <var>registered observer</var> (with <var>registered observer</var>'s <b>options</b> as
  <var>options</var>) in <var>node</var>'s list of <a>registered observers</a>, run these substeps:

  <ol>
   <li>
    <p>If none of the following are true

    <ul class=brief>
     <li><var>node</var> is not <var>target</var> and <var>options</var>' <code>subtree</code> is
     false

     <li><var>type</var> is "<code>attributes</code>" and <var>options</var>'
     <code>attributes</code> is not true
     <!--not true==false||omitted-->

     <li><var>type</var> is "<code>attributes</code>", <var>options</var>'
     <code>attributeFilter</code> is present, and <var>options</var>' <code>attributeFilter</code>
     does not contain <var>name</var> or <var>namespace</var> is non-null

     <li><var>type</var> is "<code>characterData</code>" and <var>options</var>'
     <code>characterData</code> is not true
     <!--not true==false||omitted-->

     <li><var>type</var> is "<code>childList</code>" and <var>options</var>' <code>childList</code>
     is false
    </ul>

    <p>then run these subsubsteps:

    <ol>
     <li><p>If <var>registered observer</var>'s <b>observer</b> is not in
     <var>interested observers</var>, append <var>registered observer</var>'s <b>observer</b> to
     <var>interested observers</var>.

     <li><p>If either <var>type</var> is "<code>attributes</code>" and <var>options</var>'
     <code>attributeOldValue</code> is true, or <var>type</var> is "<code>characterData</code>" and
     <var>options</var>' <code>characterDataOldValue</code> is true, set the paired string of
     <var>registered observer</var>'s <b>observer</b> in <var>interested observers</var> to
     <var>oldValue</var>.
    </ol>
  </ol>

 <li>
  <p>Then, for each <var>observer</var> in <var>interested observers</var>, run these substeps:

  <ol>
   <li>Let <var>record</var> be a new {{MutationRecord}}
   object with its {{MutationRecord/type}} set to
   <var>type</var> and
   {{MutationRecord/target}} set to
   <var>target</var>.

   <li>If <var>name</var> and <var>namespace</var> are given,
   set <var>record</var>'s
   {{MutationRecord/attributeName}} to
   <var>name</var>, and <var>record</var>'s
   {{MutationRecord/attributeNamespace}}
   to <var>namespace</var>.

   <li>If <var>addedNodes</var> is given, set <var>record</var>'s
   {{MutationRecord/addedNodes}} to
   <var>addedNodes</var>.

   <li>If <var>removedNodes</var> is given, set <var>record</var>'s
   {{MutationRecord/removedNodes}} to
   <var>removedNodes</var>,

   <li>If <var>previousSibling</var> is given, set <var>record</var>'s
   {{MutationRecord/previousSibling}} to
   <var>previousSibling</var>.

   <li>If <var>nextSibling</var> is given, set <var>record</var>'s
   {{MutationRecord/nextSibling}} to
   <var>nextSibling</var>.

   <li>If <var>observer</var> has a paired string,
   set <var>record</var>'s {{MutationRecord/oldValue}}
   to <var>observer</var>'s paired string.

   <li>Append <var>record</var> to <var>observer</var>'s
   <a>record queue</a>.
  </ol>

 <li><a>Queue a mutation observer compound microtask</a>.
</ol>


<h4 id=interface-mutationrecord>Interface {{MutationRecord}}</h4>

<pre class=idl>
[Exposed=Window]
interface MutationRecord {
  readonly attribute DOMString type;
  [SameObject] readonly attribute Node target;
  [SameObject] readonly attribute NodeList addedNodes;
  [SameObject] readonly attribute NodeList removedNodes;
  readonly attribute Node? previousSibling;
  readonly attribute Node? nextSibling;
  readonly attribute DOMString? attributeName;
  readonly attribute DOMString? attributeNamespace;
  readonly attribute DOMString? oldValue;
};
</pre>

<dl class=domintro>
 <dt><code><var>record</var> . {{MutationRecord/type}}</code>
 <dd>Returns "<code>attributes</code>" if it was an
 <a>attribute</a> mutation.
 "<code>characterData</code>" if it was a mutation to a
 {{CharacterData}} <a>node</a>. And
 "<code>childList</code>" if it was a mutation to the
 <a>tree</a> of
 <a>nodes</a>.

 <dt><code><var>record</var> . {{MutationRecord/target}}</code>
 <dd>Returns the <a>node</a> the mutation
 affected, depending on the {{MutationRecord/type}}.
 For "<code>attributes</code>", it is the
 <a for="/">element</a> whose
 <a>attribute</a> changed. For
 "<code>characterData</code>", it is the {{CharacterData}}
 <a>node</a>. For "<code>childList</code>",
 it is the  <a>node</a> whose
 <a>children</a> changed.

 <dt><code><var>record</var> . {{MutationRecord/addedNodes}}</code>
 <dt><code><var>record</var> . {{MutationRecord/removedNodes}}</code>
 <dd>Return the <a>nodes</a> added and removed
 respectively.

 <dt><code><var>record</var> . {{MutationRecord/previousSibling}}</code>
 <dt><code><var>record</var> . {{MutationRecord/nextSibling}}</code>
 <dd>Return the <a lt="previous sibling">previous</a> and <a>next sibling</a> respectively
 of the added or removed <a>nodes</a>, and null otherwise.

 <dt><code><var>record</var> . {{MutationRecord/attributeName}}</code>
 <dd>Returns the
 <a for=Attr>local name</a> of the
 changed <a>attribute</a>, and null otherwise.

 <dt><code><var>record</var> . {{MutationRecord/attributeNamespace}}</code>
 <dd>Returns the <a for=Attr>namespace</a> of the
 changed <a>attribute</a>, and null otherwise.

 <dt><code><var>record</var> . {{MutationRecord/oldValue}}</code>
 <dd>The return value depends on
 {{MutationRecord/type}}. For
 "<code>attributes</code>", it is the
 <a for=Attr>value</a> of the
 changed <a>attribute</a> before the change.
 For "<code>characterData</code>", it is the
 <a>data</a> of the changed
 <a>node</a> before the change. For
 "<code>childList</code>", it is null.
</dl>

The <dfn attribute for=MutationRecord>type</dfn> and
<dfn attribute for=MutationRecord>target</dfn>
attributes must return the values they were initialized to.

The <dfn attribute for="MutationRecord">addedNodes</dfn> and
<dfn attribute for="MutationRecord">removedNodes</dfn>
attributes must return the values they were initialized to. Unless stated
otherwise, when a {{MutationRecord}} object is created, they must
both be initialized to an empty {{NodeList}}.

The
<dfn attribute for="MutationRecord">previousSibling</dfn>,
<dfn attribute for="MutationRecord">nextSibling</dfn>,
<dfn attribute for="MutationRecord">attributeName</dfn>,
<dfn attribute for="MutationRecord">attributeNamespace</dfn>, and
<dfn attribute for="MutationRecord">oldValue</dfn>
attributes must return the values they were initialized to. Unless stated
otherwise, when a {{MutationRecord}} object is created, they must
be initialized to null.

<h4 id=garbage-collection>Garbage collection</h4>

<a>Nodes</a> have a strong reference to
<a>registered observers</a> in their
list of <a>registered observers</a>.

<a>Registered observers</a> in a
<a>node</a>'s list of
<a>registered observers</a> have a weak
reference to the <a>node</a>.


<h3 id=interface-node>Interface {{Node}}</h3>

<pre class=idl>
[Exposed=Window]
interface Node : EventTarget {
  const unsigned short ELEMENT_NODE = 1;
  const unsigned short ATTRIBUTE_NODE = 2; // historical
  const unsigned short TEXT_NODE = 3;
  const unsigned short CDATA_SECTION_NODE = 4; // historical
  const unsigned short ENTITY_REFERENCE_NODE = 5; // historical
  const unsigned short ENTITY_NODE = 6; // historical
  const unsigned short PROCESSING_INSTRUCTION_NODE = 7;
  const unsigned short COMMENT_NODE = 8;
  const unsigned short DOCUMENT_NODE = 9;
  const unsigned short DOCUMENT_TYPE_NODE = 10;
  const unsigned short DOCUMENT_FRAGMENT_NODE = 11;
  const unsigned short NOTATION_NODE = 12; // historical
  readonly attribute unsigned short nodeType;
  readonly attribute DOMString nodeName;

  readonly attribute USVString baseURI;

  readonly attribute boolean isConnected;
  readonly attribute Document? ownerDocument;
  readonly attribute Node? parentNode;
  readonly attribute Element? parentElement;
  boolean hasChildNodes();
  [SameObject] readonly attribute NodeList childNodes;
  readonly attribute Node? firstChild;
  readonly attribute Node? lastChild;
  readonly attribute Node? previousSibling;
  readonly attribute Node? nextSibling;

  [CEReactions] attribute DOMString? nodeValue;
  [CEReactions] attribute DOMString? textContent;
  [CEReactions] void normalize();

  [CEReactions, NewObject] Node cloneNode(optional boolean deep = false);
  boolean isEqualNode(Node? otherNode);
  boolean isSameNode(Node? otherNode); // historical alias of ===

  const unsigned short DOCUMENT_POSITION_DISCONNECTED = 0x01;
  const unsigned short DOCUMENT_POSITION_PRECEDING = 0x02;
  const unsigned short DOCUMENT_POSITION_FOLLOWING = 0x04;
  const unsigned short DOCUMENT_POSITION_CONTAINS = 0x08;
  const unsigned short DOCUMENT_POSITION_CONTAINED_BY = 0x10;
  const unsigned short DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x20;
  unsigned short compareDocumentPosition(Node other);
  boolean contains(Node? other);

  DOMString? lookupPrefix(DOMString? namespace);
  DOMString? lookupNamespaceURI(DOMString? prefix);
  boolean isDefaultNamespace(DOMString? namespace);

  [CEReactions] Node insertBefore(Node node, Node? child);
  [CEReactions] Node appendChild(Node node);
  [CEReactions] Node replaceChild(Node node, Node child);
  [CEReactions] Node removeChild(Node child);
};
</pre>

<p class="note no-backref">{{Node}} is an abstract interface and does not exist as <a>node</a>. It
is used by all <a>nodes</a> ({{Document}}, {{DocumentType}}, {{DocumentFragment}}, {{ShadowRoot}},
{{Element}}, {{Text}}, {{ProcessingInstruction}}, and {{Comment}}).

Each <a>node</a> has an associated
<dfn export for=Node id=concept-node-document>node document</dfn>, set upon creation,
that is a <a>document</a>.

<p class="note no-backref">A <a>node</a>'s <a>node document</a> can be changed by the
<a>adopt</a> algorithm.

<p>A <a>node</a>'s <a>get the parent</a> algorithm, given an <var>event</var>, returns the
<a>node</a>'s <a>assigned slot</a>, if <a>node</a> is <a>assigned</a>, and <a>node</a>'s
<a>parent</a> otherwise.

<hr>

<dl class=domintro>
 <dt><code><var>node</var> . {{Node/nodeType}}</code>
 <dd>
  Returns the type of <var>node</var>, represented by a number from the following list:

  <dl>
   <dt><code>{{Node}} . {{Node/ELEMENT_NODE}}</code> (1)
   <dd><var>node</var> is an
   <a for="/">element</a>.

   <dt><code>{{Node}} . {{Node/TEXT_NODE}}</code> (3)
   <dd><var>node</var> is a {{Text}}
   <a>node</a>.

   <dt><code>{{Node}} . {{Node/PROCESSING_INSTRUCTION_NODE}}</code> (7)
   <dd><var>node</var> is a {{ProcessingInstruction}}
   <a>node</a>.

   <dt><code>{{Node}} . {{Node/COMMENT_NODE}}</code> (8)
   <dd><var>node</var> is a {{Comment}}
   <a>node</a>.

   <dt><code>{{Node}} . {{Node/DOCUMENT_NODE}}</code> (9)
   <dd><var>node</var> is a
   <a>document</a>.

   <dt><code>{{Node}} . {{Node/DOCUMENT_TYPE_NODE}}</code> (10)
   <dd><var>node</var> is a
   <a>doctype</a>.

   <dt><code>{{Node}} . {{Node/DOCUMENT_FRAGMENT_NODE}}</code> (11)
   <dd><var>node</var> is a {{DocumentFragment}} or {{ShadowRoot}} <a>node</a>.
  </dl>

 <dt><code><var>node</var> . {{Node/nodeName}}</code>
 <dd>
  Returns a string appropriate for the type of <var>node</var>, as
  follows:

  <dl>
   <dt>{{Element}}
   <dd>Its {{Element/tagName}} attribute value.

   <dt>{{Text}}
   <dd>"<code>#text</code>".

   <dt>{{ProcessingInstruction}}
   <dd>Its <a for=ProcessingInstruction>target</a>.

   <dt>{{Comment}}
   <dd>"<code>#comment</code>".

   <dt>{{Document}}
   <dd>"<code>#document</code>".

   <dt>{{DocumentType}}
   <dd>Its <a for=DocumentType>name</a>.

   <dt>{{DocumentFragment}}
   <dt>{{ShadowRoot}}
   <dd>"<code>#document-fragment</code>".
  </dl>
</dl>

The <dfn attribute for=Node>nodeType</dfn> attribute's getter, when invoked, must return
the first matching statement, switching on the <a>context object</a>:

<dl class=switch>
 <dt>{{Element}}
 <dd><dfn const for=Node>ELEMENT_NODE</dfn> (1)

 <!--AttrExodus
 <dt>{{Attr}}
 <dd><dfn const for=Node>ATTRIBUTE_NODE</dfn> (2, historical);
 -->

 <dt>{{Text}}
 <dd><dfn const for=Node>TEXT_NODE</dfn> (3);

 <!-- XXX CDATA
 <dfn const for=Node>CDATA_SECTION_NODE</dfn> (4, historical);
 -->

 <dt>{{ProcessingInstruction}}
 <dd><dfn const for=Node>PROCESSING_INSTRUCTION_NODE</dfn> (7);

 <dt>{{Comment}}
 <dd><dfn const for=Node>COMMENT_NODE</dfn> (8);

 <dt>{{Document}}
 <dd><dfn const for=Node>DOCUMENT_NODE</dfn> (9);

 <dt>{{DocumentType}}
 <dd><dfn const for=Node>DOCUMENT_TYPE_NODE</dfn> (10);

 <dt>{{DocumentFragment}}
 <dt>{{ShadowRoot}}
 <dd><dfn const for=Node>DOCUMENT_FRAGMENT_NODE</dfn> (11).
</dl>

<!-- NodeExodus
<hr>

The <dfn attribute for=Node>namespaceURI</dfn> attribute must return the namespace that is associated with the node, if there is one and it's not the empty string, and null otherwise.

The <dfn attribute for=Node>prefix</dfn> attribute must return the prefix that is associated with the node, if there is one and it's not the empty string, and null otherwise.
<!- - support setting? - - On setting, it must run these steps:

<ol>
 <li>Let <var>prefix</var> be the value being assigned.
 <li>
  If <var>prefix</var> is not null, run these substeps:
  <ol>
   <li>If <var>prefix</var> does not match the
   <code><a type>Name</a></code> production in XML,
   <a>throw</a> an
   {{InvalidCharacterError}} exception.
   <li>If <var>prefix</var> does not match the <a type>NCName</a> production in Namespaces in XML, <a>throw</a> a
   {{NamespaceError}} exception.
  </ol>
 <li>Actually this does not match any browser. Let's try to drop it instead.
</ol>- ->

The <dfn attribute for=Node>localName</dfn> attribute
must return the local name that is associated with the node, if it has one,
and null otherwise.-->

The <dfn attribute for=Node>nodeName</dfn> attribute's getter, when invoked, must return
the first matching statement, switching on the <a>context object</a>:

<dl class=switch>
 <dt>{{Element}}
 <dd>Its {{Element/tagName}} attribute value.
 <!-- XXX internal concept -->

 <!--AttrExodus
 <dt>{{Attr}}
 <dd>The <a>context object</a>'s
 {{Attr/name}} attribute.
 -->

 <dt>{{Text}}
 <dd>"<code>#text</code>".

 <dt>{{ProcessingInstruction}}
 <dd>Its <a for=ProcessingInstruction>target</a>.

 <dt>{{Comment}}
 <dd>"<code>#comment</code>".

 <dt>{{Document}}
 <dd>"<code>#document</code>".

 <dt>{{DocumentType}}
 <dd>Its <a for=DocumentType>name</a>.

 <dt>{{DocumentFragment}}
 <dt>{{ShadowRoot}}
 <dd>"<code>#document-fragment</code>".
</dl>

<hr>

<dl class=domintro>
 <dt><code><var>node</var> . {{Node/baseURI}}</code>
 <dd>Returns <var>node</var>'s <a>node document</a>'s <a>document base URL</a>.
</dl>

The <dfn attribute for=Node><code>baseURI</code></dfn> attribute's getter must return
<a>node document</a>'s <a>document base URL</a>, <a lt="URL serializer" spec=url>serialized</a>.

<hr>

<dl class=domintro>
 <dt><code><var>node</var> . {{Node/isConnected}}</code>
 <dd><p>Returns true if <var>node</var> is <a>in a shadow-including document</a> and false
 otherwise.

 <dt><code><var>node</var> . {{Node/ownerDocument}}</code>
 <dd>
  Returns the <a>node document</a>.
  Returns null for <a>documents</a>.

 <dt><code><var>node</var> . {{Node/parentNode}}</code>
 <dd>Returns the <a>parent</a>.

 <dt><code><var>node</var> . {{Node/parentElement}}</code>
 <dd>Returns the <a>parent element</a>.

 <dt><code><var>node</var> . {{Node/hasChildNodes()}}</code>
 <dd>Returns whether <var>node</var> has
 <a>children</a>.

 <dt><code><var>node</var> . {{Node/childNodes}}</code>
 <dd>Returns the <a>children</a>.

 <dt><code><var>node</var> . {{Node/firstChild}}</code>
 <dd>Returns the <a>first child</a>.

 <dt><code><var>node</var> . {{Node/lastChild}}</code>
 <dd>Returns the <a>last child</a>.

 <dt><code><var>node</var> . {{Node/previousSibling}}</code>
 <dd>Returns the
 <a>previous sibling</a>.

 <dt><code><var>node</var> . {{Node/nextSibling}}</code>
 <dd>Returns the
 <a>next sibling</a>.
</dl>

<p>The <dfn attribute for=Node><code>isConnected</code></dfn> attribute's getter must return true,
if <a>context object</a> is <a>in a shadow-including document</a>, and false otherwise.</p>

<p>The <dfn attribute for=Node><code>ownerDocument</code></dfn> attribute's getter must return null,
if the <a>context object</a> is a <a>document</a>, and the <a>context object</a>'s
<a>node document</a> otherwise.

<p class="note">The <a>node document</a> of a <a>document</a> is that <a>document</a> itself. All
<a>nodes</a> have a <a>node document</a> at all times.

<p>The <dfn attribute for=Node><code>parentNode</code></dfn> attribute's getter must return the
<a>context object</a>'s <a>parent</a>.
<!-- AttrExodus
<li>If the <a>context object</a> is an {{Attr}} node,
return null.
-->

<p>The <dfn attribute for=Node><code>parentElement</code></dfn> attribute's getter must return the
<a>context object</a>'s <a>parent element</a>.

<p>The <dfn method for=Node><code>hasChildNodes()</code></dfn> method, when invoked, must return
true if the <a>context object</a> has <a>children</a>, and false otherwise.

<p>The <dfn attribute for=Node><code>childNodes</code></dfn> attribute's getter must return a
{{NodeList}} rooted at the <a>context object</a> matching only <a>children</a>.

<p>The <dfn attribute for=Node><code>firstChild</code> </dfn> attribute's getter must return the
<a>context object</a>'s <a>first child</a>.

<p>The <dfn attribute for=Node><code>lastChild</code></dfn> attribute's getter must return the
<a>context object</a>'s <a>last child</a>.

<p>The <dfn attribute for=Node><code>previousSibling</code></dfn> attribute's getter must return the
<a>context object</a>'s <a>previous sibling</a>.
<!-- AttrExodus
 <li>If the <a>context object</a> is an {{Attr}} node,
 return null.
-->

<p>The <dfn attribute for=Node><code>nextSibling</code></dfn> attribute's getter must return the
<a>context object</a>'s <a>next sibling</a>.
<!-- AttrExodus
 <li>If the <a>context object</a> is an {{Attr}} node,
 return null.
-->

<hr>

<!-- TODO: domintro -->

The <dfn attribute for=Node>nodeValue</dfn> attribute
must return the following, depending on the <a>context object</a>:

<dl class=switch>
 <!--AttrExodus <dt>{{Attr}} -->
 <dt>{{Text}}
 <dt>{{ProcessingInstruction}}
 <dt>{{Comment}}
 <dd>The <a>context object</a>'s
 <a>data</a>.

 <dt>Any other node
 <dd>Null.
</dl>

The {{Node/nodeValue}} attribute must,
on setting, if the new value is null, act as if it was the empty string
instead, and then do as described below, depending on the <a>context object</a>:

<dl class=switch>
 <!--AttrExodus <dt>{{Attr}} -->
 <dt>{{Text}}
 <dt>{{ProcessingInstruction}}
 <dt>{{Comment}}
 <dd><a>Replace data</a> with node
 <a>context object</a>, offset 0, count
 {{CharacterData/length}} attribute value, and
 data new value.

 <dt>Any other node
 <dd>Do nothing.
</dl>

<p>The <dfn attribute for=Node><code>textContent</code></dfn> attribute's getter must return the
following, switching on <a>context object</a>:

<dl class=switch>
 <dt>{{DocumentFragment}}
 <dt>{{ShadowRoot}}
 <dt>{{Element}}
 <!--AttrExodus <dt>{{Attr}} -->
 <dd>The concatenation of <a>data</a> of all
 the {{Text}} <a>node</a>
 <a>descendants</a> of the
 <a>context object</a>, in
 <a>tree order</a>.

 <dt>{{Text}}
 <dt>{{ProcessingInstruction}}
 <dt>{{Comment}}
 <dd>The <a>context object</a>'s
 <a>data</a>.

 <dt>Any other node
 <dd>Null.
</dl>

<p>The {{Node/textContent}} attribute's setter must, if the given value is null, act as if it was
the empty string instead, and then do as described below, switching on <a>context object</a>:

<dl class=switch>
 <dt>{{DocumentFragment}}
 <dt>{{ShadowRoot}}
 <dt>{{Element}}
 <!--AttrExodus <dt>{{Attr}} -->
 <dd>
  <ol>
   <li><p>Let <var>node</var> be null.

   <li><p>If the given value is not the empty string, set <var>node</var> to a new {{Text}}
   <a>node</a> whose <a>data</a> is the given value and <a>node document</a> is
   <a>context object</a>'s <a>node document</a>.

   <li><p><a>Replace all</a> with <var>node</var> within the <a>context object</a>.
  </ol>

 <dt>{{Text}}
 <dt>{{ProcessingInstruction}}
 <dt>{{Comment}}
 <dd><p><a>Replace data</a> with node <a>context object</a>, offset 0, count
 {{CharacterData/length}} attribute value, and data the given value.

 <dt>Any other node
 <dd><p>Do nothing.
</dl>

<hr>

<dl class=domintro>
 <dt><code><var>node</var> . {{Node/normalize()}}</code>
 <dd>Removes <a>empty</a>
 {{Text}} <a>nodes</a> and concatenates
 the <a>data</a> of remaining
 <a>contiguous <code>Text</code> nodes</a> into the first of their
 <a>nodes</a>.
</dl>

The <dfn method for=Node>normalize()</dfn> method
must run these steps:

For each {{Text}} <a>node</a>
<a>descendant</a> of the
<a>context object</a>:

<ol>
 <li>Let <var>node</var> be the {{Text}}
 <a>node</a>
 <a>descendant</a>.

 <li>Let <var>length</var> be <var>node</var>'s
 {{CharacterData/length}} attribute value.

 <li>If <var>length</var> is zero,
 <a>remove</a> <var>node</var> and
 continue with the next {{Text}}
 <a>node</a>, if any.

 <li>Let <var>data</var> be the concatenation of the
 <a>data</a> of <var>node</var>'s
 <a>contiguous <code>Text</code> nodes</a> (excluding itself), in
 <a>tree order</a>.

 <li><a>Replace data</a> with node
 <var>node</var>, offset <var>length</var>,
 count 0, and data <var>data</var>.

 <li>Let <var>current node</var> be <var>node</var>'s
 <a>next sibling</a>.

 <li>While <var>current node</var> is a {{Text}} node:

 <ol>
  <li>For each <a>range</a> whose
  <a>start node</a> is
  <var>current node</var>, add <var>length</var> to its
  <a>start offset</a> and set its
  <a>start node</a> to
  <var>node</var>.

  <li>For each <a>range</a> whose
  <a>end node</a> is
  <var>current node</var>, add <var>length</var> to its
  <a>end offset</a> and set its
  <a>end node</a> to
  <var>node</var>.

  <li>For each <a>range</a> whose
  <a>start node</a> is
  <var>current node</var>'s
  <a>parent</a> and
  <a>start offset</a> is
  <var>current node</var>'s
  <a>index</a>, set its
  <a>start node</a> to
  <var>node</var> and its
  <a>start offset</a> to
  <var>length</var>.

  <li>For each <a>range</a> whose
  <a>end node</a> is
  <var>current node</var>'s
  <a>parent</a> and
  <a>end offset</a> is
  <var>current node</var>'s
  <a>index</a>, set its
  <a>end node</a> to
  <var>node</var> and its
  <a>end offset</a> to
  <var>length</var>.

  <li>Add <var>current node</var>'s
  {{CharacterData/length}} attribute value to
  <var>length</var>.

  <li>Set <var>current node</var> to its
  <a>next sibling</a>.
 </ol>

 <li><a>Remove</a>
 <var>node</var>'s
 <a>contiguous <code>Text</code> nodes</a> (excluding itself), in
 <a>tree order</a>.
</ol>

<hr>

<dl class=domintro>
 <dt><code><var>node</var> . <a method lt="cloneNode()">cloneNode([<var>deep</var> = false])</a></code>
 <dd>Returns a copy of <var>node</var>. If
 <var>deep</var> is true, the copy also includes the
 <var>node</var>'s <a>descendants</a>.

 <dt><code><var>node</var> . {{Node/isEqualNode(otherNode)}}</code>
 <dd>Returns whether <var>node</var> and <var>otherNode</var>
 have the same properties.
</dl>

<div class=impl>

<a lt="Other applicable specifications">Specifications</a> may define
<dfn export for=Node id=concept-node-clone-ext>cloning steps</dfn> for all or some
<a>nodes</a>. The algorithm is passed <var>copy</var>,
<var>node</var>, <var>document</var>, and an optional <i>clone children flag</i>, as
indicated in the <a lt="clone a node">clone</a> algorithm.

<p class="note no-backref">HTML defines <a>cloning steps</a> for <{script}> and <{input}>
elements. SVG ought to do the same for its <{script}> elements, but does not call this out
at the moment.

To
<dfn export for=Node id=concept-node-clone lt="clone a node" local-lt="clone">clone</dfn>
a <var>node</var>, with an optional <var>document</var> and <i>clone children flag</i>,
run these steps:
<!-- This algorithm is used by dom-Node-cloneNode, dom-Document-importNode,
dom-Range-extractContents, dom-Range-cloneContents -->

<ol>
 <li><p>If <var>document</var> is not given, let <var>document</var> be <var>node</var>'s
 <a>node document</a>.

 <li>
  <p>If <var>node</var> is an <a for=/>element</a>, then:

  <ol>
   <li><p>Let <var>copy</var> be the result of <a>creating an element</a>, given
   <var>document</var>, <var>node</var>'s <a for=Element>local name</a>, <var>node</var>'s
   <a for=Element>namespace</a>, <var>node</var>'s <a for=Element>namespace prefix</a>, and the
   value of <var>node</var>'s <code>is</code> attribute if present (or null if not). The
   <var>synchronous custom elements flag</var> should be unset.

   <li>
    <p>For each <var>attribute</var> in <var>node</var>'s
    <a for=Element>attribute list</a>, in order, run these substeps:

    <ol>
     <li><p>Let <var>copyAttribute</var> be a new <a>attribute</a>.

     <li><p>Set <var>copyAttribute</var>'s <a for=Attr>namespace</a>,
     <a for=Attr>namespace prefix</a>, <a for=Attr>local name</a>,
     and <a for=Attr>value</a>, to those of <var>attribute</var>.

     <li><p><a lt="append an attribute">Append</a> <var>copyAttribute</var> to
     <var>copy</var>.
    </ol>
   </li>
  </ol>
 </li>

 <li>
  <p>Otherwise, let <var>copy</var> be a <a>node</a> that implements the same interfaces as
  <var>node</var>, and fulfills these additional requirements, switching on
  <var>node</var>:

  <dl class=switch>
   <dt>{{Document}}
   <dd>
    <p>Set <var>copy</var>'s <a for=Document>encoding</a>,
    <a for=Document>content type</a>, <a for=Document>URL</a>, <a for=Document>type</a>,
    and <a for=Document>mode</a>, to those of <var>node</var>.

   <dt>{{DocumentType}}
   <dd><p>Set <var>copy</var>'s <a for=DocumentType>name</a>, <a>public ID</a>, and
   <a>system ID</a>, to those of <var>node</var>.

   <!--AttrExodus
   <dt>{{Attr}}
   <dd>{{Attr/value}}
   -->

   <dt>{{Text}}
   <dt>{{Comment}}
   <dd>Set <var>copy</var>'s <a>data</a>, to that of <var>node</var>.

   <dt>{{ProcessingInstruction}}
   <dd>Set <var>copy</var>'s <a for=ProcessingInstruction>target</a> and <a>data</a> to
   those of <var>node</var>.

   <dt>Any other node
   <dd>&mdash;
  </dl>

 <li><p>Set <var>copy</var>'s <a>node document</a> and <var>document</var> to
 <var>copy</var>, if <var>copy</var> is a <a>document</a>, and set <var>copy</var>'s
 <a>node document</a> to <var>document</var> otherwise.

 <li>Run any <a>cloning steps</a> defined for <var>node</var> in
 <a>other applicable specifications</a> and pass <var>copy</var>, <var>node</var>,
 <var>document</var> and the <i>clone children flag</i> if set, as parameters.

 <li>If the <i>clone children flag</i> is set, <a lt="clone a node">clone</a> all the
 <a>children</a> of <var>node</var> and append them to <var>copy</var>, with
 <var>document</var> as specified and the <i>clone children flag</i> being set.

 <li>Return <var>copy</var>.
</ol>

<p>The <dfn method for=Node><code>cloneNode(<var>deep</var>)</code></dfn> method, when
invoked, must run these steps:

<ol>
 <li><p>If <a>context object</a> is a <a for=/>shadow root</a>, then <a>throw</a> a
 {{NotSupportedError}}.

 <li><p>Return a <a lt="clone a node">clone</a> of the <a>context object</a>, with the
 <i>clone children flag</i> set if <var>deep</var> is true.
</ol>

A <a>node</a> <var>A</var>
<dfn export for=Node id=concept-node-equals>equals</dfn> a <a>node</a>
<var>B</var> if all of the following conditions are true:

<ul>
 <li><var>A</var> and <var>B</var>'s
 {{Node/nodeType}} attribute value is identical.
 <li>
  The following are also equal, depending on <var>A</var>:
  <dl class=switch>
   <dt>{{DocumentType}}
   <dd>Its <a for=DocumentType>name</a>,
   <a>public ID</a>, and
   <a>system ID</a>.

   <dt>{{Element}}
   <dd>
    Its <a for=Element>namespace</a>,
    <a for=Element>namespace prefix</a>,
    <a for=Element>local name</a>, and its
    number of <a>attributes</a> in its
    <a for=Element>attribute list</a>.

   <!--AttrExodus
   <dt>{{Attr}}
   <dd>{{Attr/value}}
   -->

   <dt>{{ProcessingInstruction}}
   <dd>Its <a for=ProcessingInstruction>target</a> and
   <a>data</a>.

   <dt>{{Text}}
   <dt>{{Comment}}
   <dd>Its <a>data</a>.

   <dt>Any other node
   <dd>&mdash;
  </dl>
 <li>If <var>A</var> is an <a for="/">element</a>, each
 <a>attribute</a> in its
 <a for=Element>attribute list</a> has an
 <a>attribute</a> with the same
 <a for=Attr>namespace</a>,
 <a for=Attr>local name</a>, and
 <a for=Attr>value</a> in <var>B</var>'s
 <a for=Element>attribute list</a>.
 <li><var>A</var> and <var>B</var> have the same number of
 <a>children</a>.
 <li>Each <a>child</a> of <var>A</var>
 <a for=Node>equals</a> the
 <a>child</a> of <var>B</var> at the identical
 <a>index</a>.
</ul>

<p>The <dfn method for=Node><code>isEqualNode(<var>otherNode</var>)</code></dfn> method, when
invoked, must return true if <var>otherNode</var> is non-null and <a>context object</a>
<a for=Node>equals</a> <var>otherNode</var>, and false otherwise.

<p>The <dfn method for=Node><code>isSameNode(<var>otherNode</var>)</code></dfn> method, when
invoked, must return true if <var>otherNode</var> is <a>context object</a>, and false otherwise.

</div>

<hr>

<dl class=domintro>
 <dt><code><var>node</var> . {{compareDocumentPosition(other)}}</code>
 <dd>
  Returns a bitmask indicating the position of <var>other</var>
  relative to <var>node</var>. These are the bits that can be set:

  <dl>
   <dt><code>{{Node}} . {{Node/DOCUMENT_POSITION_DISCONNECTED}}</code> (1)
   <dd>Set when <var>node</var> and <var>other</var> are not in the
   same <a>tree</a>.

   <dt><code>{{Node}} . {{Node/DOCUMENT_POSITION_PRECEDING}}</code> (2)
   <dd>Set when <var>other</var> is
   <a>preceding</a>
   <var>node</var>.

   <dt><code>{{Node}} . {{Node/DOCUMENT_POSITION_FOLLOWING}}</code> (4)
   <dd>Set when <var>other</var> is
   <a>following</a>
   <var>node</var>.

   <dt><code>{{Node}} . {{Node/DOCUMENT_POSITION_CONTAINS}}</code> (8)
   <dd>Set when <var>other</var> is an
   <a>ancestor</a> of
   <var>node</var>.

   <dt><code>{{Node}} . {{Node/DOCUMENT_POSITION_CONTAINED_BY}}</code> (16, 10 in hexadecimal)
   <dd>Set when <var>other</var> is a
   <a>descendant</a> of
   <var>node</var>.
  </dl>

 <dt><code><var>node</var> . {{Node/contains(other)}}</code>
 <dd>Returns true if <var>other</var> is an
 <a>inclusive descendant</a>
 of <var>node</var>, and false otherwise.
</dl>

These are the constants
{{compareDocumentPosition()}}
returns as mask:

<ul class="brief">
 <li><dfn const for=Node>DOCUMENT_POSITION_DISCONNECTED</dfn> (1);
 <li><dfn const for=Node>DOCUMENT_POSITION_PRECEDING</dfn> (2);
 <li><dfn const for=Node>DOCUMENT_POSITION_FOLLOWING</dfn> (4);
 <li><dfn const for=Node>DOCUMENT_POSITION_CONTAINS</dfn> (8);
 <li><dfn const for=Node>DOCUMENT_POSITION_CONTAINED_BY</dfn> (16, 10 in hexadecimal);
 <li><dfn const for=Node>DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC</dfn> (32, 20 in hexadecimal).
</ul>

The <dfn method for=Node>compareDocumentPosition(<var>other</var>)</dfn>
method must run these steps:

<ol>
 <li>Let <var>reference</var> be the <a>context object</a>.
 <li>If <var>other</var> and <var>reference</var> are the
 same object, return zero.

 <li>
  If <var>other</var> and <var>reference</var> are not
  in the same <a>tree</a>, return the result of
  adding
  {{Node/DOCUMENT_POSITION_DISCONNECTED}},
  {{Node/DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC}},
  and either
  {{Node/DOCUMENT_POSITION_PRECEDING}} or
  {{Node/DOCUMENT_POSITION_FOLLOWING}},
  with the constraint that this is to be consistent, together.

  <p class="note no-backref">Whether to return
  {{Node/DOCUMENT_POSITION_PRECEDING}} or
  {{Node/DOCUMENT_POSITION_FOLLOWING}}
  is typically implemented via pointer comparison. In JavaScript
  implementations <code class='lang-javascript'>Math.random()</code> can be used.

 <li>If <var>other</var> is an
 <a>ancestor</a> of
 <var>reference</var>, return the result of adding
 {{Node/DOCUMENT_POSITION_CONTAINS}}
 to
 {{Node/DOCUMENT_POSITION_PRECEDING}}.

 <li>If <var>other</var> is a
 <a>descendant</a> of
 <var>reference</var>, return the result of adding
 {{Node/DOCUMENT_POSITION_CONTAINED_BY}}
 to
 {{Node/DOCUMENT_POSITION_FOLLOWING}}.

 <li>If <var>other</var> is
 <a>preceding</a>
 <var>reference</var> return
 {{Node/DOCUMENT_POSITION_PRECEDING}}.

 <li>Return
 {{Node/DOCUMENT_POSITION_FOLLOWING}}.
</ol>

<!-- AttrExodus compareDocumentPosition() works differently if Attr inherits
     from Node -->

The
<dfn method for=Node>contains(<var>other</var>)</dfn>
method must return true if <var>other</var> is an
<a>inclusive descendant</a> of
the <a>context object</a>, and false otherwise (including when
<var>other</var> is null).

<hr>

<!-- TODO: domintro -->

<!--
 XXX apparently these algorithms might not be quite correct
 https://bugzilla.mozilla.org/show_bug.cgi?id=312019
 https://bugzilla.mozilla.org/show_bug.cgi?id=505178
-->

To <dfn export lt="locate a namespace prefix|locating a namespace prefix">locate a namespace prefix</dfn> for an <var>element</var> using
<var>namespace</var> run these steps:

<ol>
 <li>If <var>element</var>'s
 <a for=Element>namespace</a> is
 <var>namespace</var> and its
 <a for=Element>namespace prefix</a> is not
 null, return its
 <a for=Element>namespace prefix</a>.

 <li>If <var>element</var> <a lt="has an attribute">has</a> an <a>attribute</a> whose
 <a for=Attr>namespace prefix</a> is
 "<code>xmlns</code>" and
 <a for=Attr>value</a> is
 <var>namespace</var>, then return <var>element</var>'s first
 such <a>attribute</a>'s
 <a for=Attr>local name</a>.

 <li>If <var>element</var>'s <a>parent element</a> is not null,
 return the result of running <a>locate a namespace prefix</a> on that
 <a for="/">element</a> using <var>namespace</var>.
 Otherwise, return null.
</ol>

To <dfn export>locate a namespace</dfn> for a <var>node</var> using
<var>prefix</var> depends on <var>node</var>:

<dl class=switch>
 <dt>{{Element}}
 <dd>
  <ol>
   <li>If its <a for=Element>namespace</a> is
   not null and its
   <a for=Element>namespace prefix</a> is
   <var>prefix</var>, return
   <a for=Element>namespace</a>.

   <li>
    If it <a lt="has an attribute">has</a> an
    <a>attribute</a> whose
    <a for=Attr>namespace</a> is the
    <a>XMLNS namespace</a>,
    <a for=Attr>namespace prefix</a>
    is "<code>xmlns</code>" and
    <a for=Attr>local name</a> is
    <var>prefix</var>, or if <var>prefix</var> is null and it
    <a lt="has an attribute">has</a> an
    <a>attribute</a> whose
    <a for=Attr>namespace</a> is the
    <a>XMLNS namespace</a>,
    <a for=Attr>namespace prefix</a>
    is null and <a for=Attr>local name</a>
    is "<code>xmlns</code>":

    <ol>
     <li>Let <var>value</var> be its
     <a for=Attr>value</a> if it is not the empty
     string, and null otherwise.

     <li>Return <var>value</var>.
    </ol>

   <li>If its <a>parent element</a> is null, return null.

   <li>Return the result of running <a>locate a namespace</a> on
   its <a>parent element</a> using <var>prefix</var>.
  </ol>

 <!--AttrExodus {{Attr}} -->
 <dt>{{Document}}
 <dd>
  <ol>
   <li>If its <a>document element</a> is null, return null.

   <li>Return the result of running <a>locate a namespace</a> on
   its <a>document element</a> using <var>prefix</var>.
  </ol>

 <dt>{{DocumentType}}
 <dt>{{DocumentFragment}}
 <dt>{{ShadowRoot}}
 <dd>Return null.

 <dt>Any other node
 <dd>
  <ol>
   <li>If its <a>parent element</a> is null, return null.

   <li>Return the result of running <a>locate a namespace</a> on
   its <a>parent element</a> using <var>prefix</var>.
  </ol>
</dl>

The
<dfn method for=Node>lookupPrefix(<var>namespace</var>)</dfn>
method must run these steps:

<ol>
 <li>If <var>namespace</var> is null or the empty string, return null.

 <li>
  Otherwise it depends on the <a>context object</a>:

  <dl class=switch>
   <dt>{{Element}}
   <dd>Return the result of
   <a>locating a namespace prefix</a>
   for the node using <var>namespace</var>.

   <!--AttrExodus {{Attr}} -->
   <dt>{{Document}}
   <dd>Return the result of
   <a>locating a namespace prefix</a>
   for its <a>document element</a>, if that is not null, and null
   otherwise.

   <dt>{{DocumentType}}
   <dt>{{DocumentFragment}}
   <dt>{{ShadowRoot}}
   <dd>Return null.

   <dt>Any other node
   <dd>Return the result of
   <a>locating a namespace prefix</a>
   for its <a>parent element</a>, or if that is null, null.
  </dl>
</ol>

The
<dfn method for=Node>lookupNamespaceURI(<var>prefix</var>)</dfn>
method must run these steps:

<ol>
 <li>If <var>prefix</var> is the empty string, set it to null.

 <li>Return the result of running <a>locate a namespace</a> for the
 <a>context object</a> using <var>prefix</var>.
</ol>

The
<dfn method for=Node>isDefaultNamespace(<var>namespace</var>)</dfn>
method must run these steps:

<ol>
 <li>If <var>namespace</var> is the empty string, set it to null.

 <li>Let <var>defaultNamespace</var> be the result of running
 <a>locate a namespace</a> for the <a>context object</a> using
 null.

 <li>Return true if <var>defaultNamespace</var> is the same as
 <var>namespace</var>, and false otherwise.
</ol>

<hr>

The
<dfn method for=Node>insertBefore(<var>node</var>, <var>child</var>)</dfn>
method must return the result of
<a>pre-inserting</a>
<var>node</var> into the <a>context object</a> before
<var>child</var>.

The
<dfn method for=Node>appendChild(<var>node</var>)</dfn>
method must return the result of
<a>appending</a> <var>node</var> to
the <a>context object</a>.

The
<dfn method for=Node>replaceChild(<var>node</var>, <var>child</var>)</dfn>
method must return the result of
<a>replacing</a> <var>child</var>
with <var>node</var> within the <a>context object</a>.

The
<dfn method for=Node>removeChild(<var>child</var>)</dfn>
method must return the result of
<a>pre-removing</a>
<var>child</var> from the <a>context object</a>.

<hr><!-- Collections -->

<p>The
<dfn export id=concept-getelementsbytagname>list of elements with qualified name <var>qualifiedName</var></dfn>
for a <a>node</a> <var>root</var> is the {{HTMLCollection}} returned by the following algorithm:

<ol>
 <li><p>If <var>qualifiedName</var> is "<code>*</code>" (U+002A), return a {{HTMLCollection}} rooted
 at <var>root</var>, whose filter matches only <a>descendant</a> <a for="/">elements</a>.

 <li>
  <p>Otherwise, if <var>root</var>'s <a>node document</a> is an <a>HTML document</a>, return a
  {{HTMLCollection}} rooted at <var>root</var>, whose filter matches the following <a>descendant</a>
  <a for="/">elements</a>:

  <ul>
   <li><p>Whose <a for=Element>namespace</a> is the <a>HTML namespace</a> and whose
   <a for=Element>qualified name</a> is <var>qualifiedName</var>,
   <a>converted to ASCII lowercase</a>.

   <li><p>Whose <a for=Element>namespace</a> is <em>not</em> the <a>HTML namespace</a> and whose
   <a for=Element>qualified name</a> is <var>qualifiedName</var>.
  </ul>

 <li><p>Otherwise, return a {{HTMLCollection}} rooted at <var>root</var>, whose filter matches
 <a>descendant</a> <a for="/">elements</a> whose <a for=Element>qualified name</a> is
 <var>qualifiedName</var>.
</ol>

<p>When invoked with the same argument, and as long as <var>root</var>'s <a>node document</a>'s
<a for=Document>type</a> has not changed, the same {{HTMLCollection}} object may be returned as
returned by an earlier call.

The
<dfn export id=concept-getelementsbytagnamens>list of elements with namespace
<var>namespace</var> and local name <var>localName</var></dfn>
for a <a>node</a> <var>root</var> is the
{{HTMLCollection}} returned by the following algorithm:

<ol>
 <li>If <var>namespace</var> is the empty string, set it to null.

 <li>If both <var>namespace</var> and <var>localName</var>
 are "<code>*</code>" (U+002A), return a {{HTMLCollection}} rooted at
 <var>root</var>, whose filter matches
 <a>descendant</a>
 <a for="/">elements</a>.

 <li>Otherwise, if <var>namespace</var> is "<code>*</code>"
 (U+002A), return a {{HTMLCollection}} rooted at
 <var>root</var>, whose filter matches
 <a>descendant</a>
 <a for="/">elements</a> whose
 <a for=Element>local name</a> is
 <var>localName</var>.

 <li>Otherwise, if <var>localName</var> is "<code>*</code>"
 (U+002A), return a {{HTMLCollection}} rooted at
 <var>root</var>, whose filter matches
 <a>descendant</a>
 <a for="/">elements</a> whose
 <a for=Element>namespace</a> is
 <var>namespace</var>.

 <li>Otherwise, return a {{HTMLCollection}} rooted at
 <var>root</var>, whose filter matches
 <a>descendant</a>
 <a for="/">elements</a> whose
 <a for=Element>namespace</a> is
 <var>namespace</var> and
 <a for=Element>local name</a> is
 <var>localName</var>.
</ol>

When invoked with the same arguments, the same {{HTMLCollection}}
object may be returned as returned by an earlier call.


The
<dfn export id=concept-getelementsbyclassname>list of elements with class names <var>classNames</var></dfn>
for a <a>node</a> <var>root</var> is the
{{HTMLCollection}} returned by the following algorithm:
<ol>
 <li>
  Let <var>classes</var> be the result of running the
  <a>ordered set parser</a> on
  <var>classNames</var>.

 <li>
  If <var>classes</var> is the empty set, return an empty
  {{HTMLCollection}}.

 <li>
  Return a {{HTMLCollection}} rooted at <var>root</var>,
  whose filter matches <a>descendant</a>
  <a for="/">elements</a> that have all their
  <a>classes</a> in <var>classes</var>.

  The comparisons for the <a>classes</a> must be done in an <a>ASCII case-insensitive</a>
  manner if <var>root</var>'s <a>node document</a>'s <a for=Document>mode</a> is
  "<code>quirks</code>", and in a <a>case-sensitive</a> manner otherwise.
</ol>

When invoked with the same argument, the same {{HTMLCollection}}
object may be returned as returned by an earlier call.


<h3 id=interface-document>Interface {{Document}}</h3>

<pre class=idl force="Document">
[Constructor,
 Exposed=Window]
interface Document : Node {
  [SameObject] readonly attribute DOMImplementation implementation;
  readonly attribute USVString URL;
  readonly attribute USVString documentURI;
  readonly attribute USVString origin;
  readonly attribute DOMString compatMode;
  readonly attribute DOMString characterSet;
  readonly attribute DOMString charset; // historical alias of .characterSet
  readonly attribute DOMString inputEncoding; // historical alias of .characterSet
  readonly attribute DOMString contentType;

  readonly attribute DocumentType? doctype;
  readonly attribute Element? documentElement;
  HTMLCollection getElementsByTagName(DOMString qualifiedName);
  HTMLCollection getElementsByTagNameNS(DOMString? namespace, DOMString localName);
  HTMLCollection getElementsByClassName(DOMString classNames);

  [NewObject] Element createElement(DOMString localName, optional ElementCreationOptions options);
  [NewObject] Element createElementNS(DOMString? namespace, DOMString qualifiedName, optional ElementCreationOptions options);
  [NewObject] DocumentFragment createDocumentFragment();
  [NewObject] Text createTextNode(DOMString data);
  [NewObject] Comment createComment(DOMString data);
  [NewObject] ProcessingInstruction createProcessingInstruction(DOMString target, DOMString data);

  [CEReactions, NewObject] Node importNode(Node node, optional boolean deep = false);
  [CEReactions] Node adoptNode(Node node);

  [NewObject] Attr createAttribute(DOMString localName);
  [NewObject] Attr createAttributeNS(DOMString? namespace, DOMString qualifiedName);

  [NewObject] Event createEvent(DOMString interface);

  [NewObject] Range createRange();

  // NodeFilter.SHOW_ALL = 0xFFFFFFFF
  [NewObject] NodeIterator createNodeIterator(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null);
  [NewObject] TreeWalker createTreeWalker(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null);
};

[Exposed=Window]
interface XMLDocument : Document {};

dictionary ElementCreationOptions {
  DOMString is;
};
</pre>

{{Document}} <a>nodes</a> are simply
known as <dfn export id=concept-document lt="document">documents</dfn>.

Each <a>document</a> has an associated
<dfn export for=Document id=concept-document-encoding>encoding</dfn> (an <a for="/">encoding</a>),
<dfn export for=Document id=concept-document-content-type>content type</dfn> (a string),
<dfn export for=Document id=concept-document-url>URL</dfn> (a <a for=url>URL</a>),
<dfn export for=Document id=concept-document-type>type</dfn> ("<code>xml</code>" or "<code>html</code>"), and
<dfn export for=Document id=concept-document-mode>mode</dfn> ("<code>no-quirks</code>", "<code>quirks</code>", or "<code>limited-quirks</code>").
[[!ENCODING]]
[[!URL]]

Unless stated otherwise, a <a>document</a>'s <a for=Document>encoding</a> is the <a>utf-8</a>
<a for="/">encoding</a>, <a for=Document>content type</a> is
"<code>application/xml</code>", <a for=Document>URL</a> is "<code>about:blank</code>",
<a for=Document>type</a> is "<code>xml</code>", and its
<a for=Document>mode</a> is "<code>no-quirks</code>".

Unless stated otherwise, a <a>document</a>'s <a>origin</a> is a new <a>opaque origin</a>. [[!HTML]]

A <a>document</a> is said to be an <dfn export>XML document</dfn> if its
<a for=Document>type</a> is "<code>xml</code>", and an <dfn export>HTML document</dfn>
otherwise. Whether a <a>document</a> is an <a>HTML document</a> or an <a>XML document</a>
affects the behavior of certain APIs.

A <a>document</a> is said to be in
<dfn export id=concept-document-no-quirks>no-quirks mode</dfn> if its
<a for=Document>mode</a> is "<code>no-quirks</code>",
<dfn export id=concept-document-quirks>quirks mode</dfn> if its <a for=Document>mode</a>
is "<code>quirks</code>", and
<dfn export id=concept-document-limited-quirks>limited-quirks mode</dfn> if its
<a for=Document>mode</a> is "<code>limited-quirks</code>".

<div class="note no-backref">
 <p>The mode is only ever changed from the default if the <a>document</a> is created by
 the <a>HTML parser</a>, based on the presence, absence, or value of the DOCTYPE string.
 [[!HTML]]

 <p><a>No-quirks mode</a> was originally known as "standards mode"
 and <a>limited-quirks mode</a> was once known as "almost standards mode". They have been
 renamed because their details are now defined by standards. (And because Ian Hickson
 vetoed their original names on the basis that they are nonsensical.)
</div>

<p>A <a>document</a>'s <a>get the parent</a> algorithm, given an <var>event</var>, returns
null if <var>event</var>'s <code for=Event>type</code> attribute value is "<code>load</code>" or
<a>document</a> does not have a <a lt=concept-document-bc>browsing context</a>, and the
<a>document</a>'s <a lt=concept-document-window>associated</a> {{Window}} object otherwise.

<hr>

<dl class=domintro>
 <dt><code><var>document</var> = new {{Document()}}</code>
 <dd>Returns a new <a>document</a>.

 <dt><code><var>document</var> . {{Document/implementation}}</code>
 <dd>Returns <var>document</var>'s {{DOMImplementation}} object.

 <dt><code><var>document</var> . {{Document/URL}}</code>
 <dt><code><var>document</var> . {{Document/documentURI}}</code>
 <dd>Returns <var>document</var>'s <a for=Document>URL</a>.

 <dt><code><var>document</var> . {{Document/origin}}</code>
 <dd>Returns <var>document</var>'s <a>origin</a>.

 <dt><code><var>document</var> . {{Document/compatMode}}</code>
 <dd>
  Returns the string "<code>BackCompat</code>" if <var>document</var>'s
  <a for=Document>mode</a> is "<code>quirks</code>", and "<code>CSS1Compat</code>"
  otherwise.

 <dt><code><var>document</var> . {{Document/characterSet}}</code>
 <dd>Returns <var>document</var>'s
 <a for=Document>encoding</a>.

 <dt><code><var>document</var> . {{Document/contentType}}</code>
 <dd>Returns <var>document</var>'s
 <a for=Document>content type</a>.
</dl>

<p>The <dfn constructor for=Document><code>Document()</code></dfn> constructor, when invoked, must
return a new <a>document</a> whose <a>origin</a> is the <a>origin</a> of the global object's
associated <a>document</a>. [[!HTML]]

<p class="note no-backref">Unlike
{{createDocument()}}
this constructor does not return an {{XMLDocument}} object, but a
<a>document</a> ({{Document}} object).

The
<dfn attribute for=Document><code>implementation</code></dfn> attribute's getter must return the
{{DOMImplementation}} object that is associated with the <a>document</a>.

The <dfn attribute for=Document><code>URL</code></dfn> attribute's getter and
<dfn attribute for=Document><code>documentURI</code></dfn> attribute's getter must return the
<a for=Document>URL</a>, <a lt="URL serializer" spec=url>serialized</a>.

The <dfn attribute for=Document><code>origin</code></dfn> attribute's getter must return the
<a lt="Unicode serialisation of an origin">Unicode serialization</a> of <a>context object</a>'s
<a>origin</a>.

The <dfn attribute for=Document><code>compatMode</code></dfn> attribute's getter must
return "<code>BackCompat</code>" if <a>context object</a>'s <a for=Document>mode</a> is
"<code>quirks</code>", and "<code>CSS1Compat</code>" otherwise.

The <dfn attribute for=Document><code>characterSet</code></dfn> attribute's getter,
<dfn attribute for=Document><code>charset</code></dfn> attribute's getter, and
<dfn attribute for=Document><code>inputEncoding</code></dfn> attribute's getter, must return
<a>context object</a>'s <a for=Document>encoding</a>'s <a for=/>name</a>.

The <dfn attribute for=Document><code>contentType</code></dfn> attribute's getter must return the
<a for=Document>content type</a>.

<hr>

<dl class=domintro>
 <dt><var>document</var> . {{Document/doctype}}
 <dd>Returns the <a>doctype</a> or null if
 there is none.

 <dt><var>document</var> . {{Document/documentElement}}
 <dd>Returns the <a>document element</a>.

 <dt><var>collection</var> = <var>document</var> . {{Document/getElementsByTagName(qualifiedName)}}</code>

 <dd>
  <p>If <var>qualifiedName</var> is "<code>*</code>" returns a {{HTMLCollection}} of all
  <a>descendant</a> <a for="/">elements</a>.

  <p>Otherwise, returns a {{HTMLCollection}} of all <a>descendant</a> <a for="/">elements</a> whose
  <a for=Element>qualified name</a> is <var>qualifiedName</var>. (Matches case-insensitively against
  <a for="/">elements</a> in the <a>HTML namespace</a> within an <a>HTML document</a>.)

 <dt><var>collection</var> = <var>document</var> . {{Document/getElementsByTagNameNS(namespace, localName)}}</code>

 <dd>
  If <var>namespace</var> and <var>localName</var> are
  "<code>*</code>" returns a {{HTMLCollection}} of all
  <a>descendant</a>
  <a for="/">elements</a>.

  If only <var>namespace</var> is "<code>*</code>" returns a
  {{HTMLCollection}} of all
  <a>descendant</a>
  <a for="/">elements</a> whose
  <a for=Element>local name</a> is
  <var>localName</var>.

  If only <var>localName</var> is "<code>*</code>" returns a
  {{HTMLCollection}} of all
  <a>descendant</a>
  <a for="/">elements</a> whose
  <a for=Element>namespace</a> is
  <var>namespace</var>.

  Otherwise, returns a {{HTMLCollection}} of all
  <a>descendant</a>
  <a for="/">elements</a> whose
  <a for=Element>namespace</a> is
  <var>namespace</var> and
  <a for=Element>local name</a> is
  <var>localName</var>.

 <dt><var>collection</var> = <var>document</var> . {{Document/getElementsByClassName(classNames)}}</code>
 <dt><var>collection</var> = <var>element</var> . {{Element/getElementsByClassName(classNames)}}</code>
 <dd>
  Returns a {{HTMLCollection}} of the
  <a for="/">elements</a> in the object on which
  the method was invoked (a <a>document</a> or
  an <a for="/">element</a>) that have all the classes
  given by <var>classNames</var>.
  The <var>classNames</var> argument is interpreted as a
  space-separated list of classes.
</dl>

The <dfn attribute for=Document><code>doctype</code></dfn> attribute's getter must return the
<a>child</a> of the <a>document</a> that is a <a>doctype</a>, and null otherwise.

The <dfn attribute for=Document><code>documentElement</code></dfn> attribute's getter must return
the <a>document element</a>.

The <dfn method for=Document><code>getElementsByTagName(<var>qualifiedName</var>)</code></dfn>
method, when invoked, must return the
<a>list of elements with qualified name <var>qualifiedName</var></a> for the <a>context object</a>.

<p class="note no-backref">Thus, in an <a>HTML document</a>,
<code class='lang-javascript'>document.getElementsByTagName("FOO")</code> will match
<code>&lt;FOO></code> elements that are not in the
<a>HTML namespace</a>, and <code>&lt;foo></code> elements that are in
the <a>HTML namespace</a>, but not <code>&lt;FOO></code> elements
that are in the <a>HTML namespace</a>.

The
<dfn method for=Document><code>getElementsByTagNameNS(<var>namespace</var>, <var>localName</var>)</code></dfn>
method, when invoked, must return the
<a>list of elements with namespace <var>namespace</var> and local name <var>localName</var></a> for
the <a>context object</a>.

The <dfn method for=Document><code>getElementsByClassName(<var>classNames</var>)</code></dfn>
method, when invoked, must return the <a>list of elements with class names <var>classNames</var></a>
for the <a>context object</a>.

<div class="example">
 Given the following XHTML fragment:

 <pre><code class="lang-html">
  &lt;div id="example"&gt;
    &lt;p id="p1" class="aaa bbb"/&gt;
    &lt;p id="p2" class="aaa ccc"/&gt;
    &lt;p id="p3" class="bbb ccc"/&gt;
  &lt;/div&gt;
 </code></pre>

 A call to
 <code class="lang-javascript">document.getElementById("example").getElementsByClassName("aaa")</code>
 would return a {{HTMLCollection}} with the two paragraphs
 <code>p1</code> and <code>p2</code> in it.

 A call to
 <code class="lang-javascript">getElementsByClassName("ccc&nbsp;bbb")</code>
 would only return one node, however, namely <code>p3</code>. A call to
 <code class="lang-javascript">document.getElementById("example").getElementsByClassName("bbb&nbsp;&nbsp;ccc&nbsp;")</code>
 would return the same thing.

 A call to
 <code class="lang-javascript">getElementsByClassName("aaa,bbb")</code>
 would return no nodes; none of the elements above are in the
 <code>aaa,bbb</code> class.
</div>

<hr>

<dl class=domintro>
 <dt><code><var>element</var> = <var>document</var> . <a method lt=createElement()>createElement(localName [, options])</a></code>
 <dd>
  Returns an <a for="/">element</a> in the
  <a>HTML namespace</a> with <var>localName</var> as
  <a for=Element>local name</a>. (In an
  <a>HTML document</a> <var>localName</var> is lowercased.)

  If <var>localName</var> does not match the
  <code><a type>Name</a></code> production an
  {{InvalidCharacterError}} will be thrown.

  When supplied, <var>options</var>' <code>is</code> member can be used to create a
  <a>customized built-in element</a>.


 <dt><code><var>element</var> = <var>document</var> . <a method lt=createElementNS()>createElementNS(namespace, qualifiedName [, options])</a></code>

 <dd>
  Returns an <a for="/">element</a> with
  <a for=Element>namespace</a>
  <var>namespace</var>. Its
  <a for=Element>namespace prefix</a> will
  be everything before "<code>:</code>" (U+003E) in
  <var>qualifiedName</var> or null. Its
  <a for=Element>local name</a> will be
  everything after "<code>:</code>" (U+003E) in
  <var>qualifiedName</var> or <var>qualifiedName</var>.

  If <var>localName</var> does not match the
  <code><a type>Name</a></code> production an
  {{InvalidCharacterError}} will be thrown.

  If one of the following conditions is true a
  {{NamespaceError}} will be thrown:

  <ul>
   <li><var>localName</var> does not match the
   <code><a type>QName</a></code> production.
   <li><a for=Element>Namespace prefix</a>
   is not null and <var>namespace</var> is the empty string.
   <li><a for=Element>Namespace prefix</a>
   is "<code>xml</code>" and <var>namespace</var> is not the
   <a>XML namespace</a>.
   <li><var>qualifiedName</var> or
   <a for=Element>namespace prefix</a>
   is "<code>xmlns</code>" and <var>namespace</var> is not the
   <a>XMLNS namespace</a>.
   <li><var>namespace</var> is the <a>XMLNS namespace</a> and
   neither <var>qualifiedName</var> nor
   <a for=Element>namespace prefix</a>
   is "<code>xmlns</code>".
  </ul>

  When supplied, <var>options</var>' <code>is</code> member can be used to create a
  <a>customized built-in element</a>.

 <dt><code><var>documentFragment</var> = <var>document</var> . {{createDocumentFragment()}}</code>
 <dd>Returns a {{DocumentFragment}}
 <a>node</a>.

 <dt><code><var>text</var> = <var>document</var> . {{createTextNode(data)}}</code>
 <dd>Returns a {{Text}} <a>node</a>
 whose <a>data</a> is <var>data</var>.

 <dt><code><var>comment</var> = <var>document</var> . {{createComment(data)}}</code>
 <dd>Returns a {{Comment}} <a>node</a>
 whose <a>data</a> is <var>data</var>.

 <dt><code><var>processingInstruction</var> = <var>document</var> . {{createProcessingInstruction(target, data)}}</code>
 <dd>
  Returns a {{ProcessingInstruction}}
  <a>node</a> whose
  <a for=ProcessingInstruction>target</a> is <var>target</var> and
  <a>data</a> is <var>data</var>.
  If <var>target</var> does not match the
  <code><a type>Name</a></code> production an
  {{InvalidCharacterError}} will be thrown.
  If <var>data</var> contains "<code>?></code>" an
  {{InvalidCharacterError}} will be thrown.
</dl>

The <dfn export id=concept-element-interface>element interface</dfn> for any
<var>name</var> and <var>namespace</var> is {{Element}}, unless
stated otherwise.

<p class="note no-backref">The HTML Standard will e.g. define that for <code>html</code>
and the <a>HTML namespace</a>, the {{HTMLHtmlElement}} interface is used.
[[!HTML]]

The <dfn method for=Document><code>createElement(<var>localName</var>, <var>options</var>)</code></dfn> method, when
invoked, must run these steps:

<ol>
 <li><p>If <var>localName</var> does not match the <code><a type>Name</a></code> production, then
 <a>throw</a> an {{InvalidCharacterError}}.

 <li>If the <a>context object</a> is an <a>HTML document</a>,
 let <var>localName</var> be
 <a>converted to ASCII lowercase</a>.
 <!-- XXX why restrict this to HTML documents? -->

 <li>Let <var>is</var> be the value of <code>is</code> member of <var>options</var>, or null if no
 such member exists.

 <li>Let <var>definition</var> be the result of
 <a lt="look up a custom element definition">looking up a custom element definition</a>, given the
 <a>context object</a>, the <a>HTML namespace</a>, <var>localName</var>, and <var>is</var>.

 <li>If <var>is</var> is non-null and <var>definition</var> is null, then <a>throw</a> a
 {{NotFoundError}}.

 <li>Let <var>namespace</var> be the <a>HTML namespace</a>, if the <a>context object</a>'s
 <a for=Document>content type</a> is "<code>text/html</code>" or
 "<code>application/xhtml+xml</code>" or if the <a>context object<a> is an <a>HTML document</a>, and null otherwise.

 <li>Let <var>element</var> be the result of <a>creating an element</a> given the
 <a>context object</a>, <var>localName</var>, <var>namespace</var>, null, <var>is</var>, and with
 the <var>synchronous custom elements</var> flag set. Rethrow any exceptions.

 <li>If <var>is</var> is non-null, then <a>set an attribute value</a> for <var>element</var> using
 "<code>is</code>" and <var>is</var>.

 <li>Return <var>element</var>.
</ol>

<p>The <dfn noexport>internal <code>createElementNS</code> steps</dfn>, given <var>document</var>,
<var>namespace</var>, <var>qualifiedName</var>, and <var>options</var>, are as follows:

<ol>
 <li>Let <var>namespace</var>, <var>prefix</var>, and <var>localName</var> be the result of passing
 <var>namespace</var> and <var>qualifiedName</var> to <a>validate and extract</a>. Rethrow any
 exceptions.

 <li>Let <var>is</var> be the value of <code>is</code> member of <var>options</var>, or null if no
 such member exists.

 <li>Let <var>definition</var> be the result of
 <a lt="look up a custom element definition">looking up a custom element definition</a>, given the
 <a>context object</a>, <var>namespace</var>, <var>localName</var>, and <var>is</var>.

 <li>If <var>is</var> is non-null and <var>definition</var> is null, then <a>throw</a> a
 {{NotFoundError}}.

 <li><p>Let <var>element</var> be the result of <a>creating an element</a> given
 <var>document</var>, <var>localName</var>, <var>namespace</var>, <var>prefix</var>, <var>is</var>,
 and with the <var>synchronous custom elements</var> flag set. Rethrow any exceptions.

 <li>If <var>is</var> is non-null, then <a>set an attribute value</a> for <var>element</var> using
 "<code>is</code>" and <var>is</var>.

 <li>Return <var>element</var>.
</ol>

<p>The
<dfn method for=Document><code>createElementNS(<var>namespace</var>, <var>qualifiedName</var>, <var>options</var>)</code></dfn>
method, when invoked, must return the result of running the
<a>internal <code>createElementNS</code> steps</a>, given <a>context object</a>,
<var>namespace</var>, <var>qualifiedName</var>, and <var>options</var>.

The <dfn method for=Document><code>createDocumentFragment()</code></dfn> method, when invoked,
must return a new {{DocumentFragment}} <a>node</a> with its <a>node document</a> set to the
<a>context object</a>.

The <dfn method for=Document><code>createTextNode(<var>data</var>)</code></dfn> method, when
invoked, must return a new {{Text}} <a>node</a> with its <a>data</a> set to <var>data</var> and
<a>node document</a> set to the <a>context object</a>.

<p class="note no-backref">No check is performed that <var>data</var> consists of
characters that match the <code><a type>Char</a></code> production.

The <dfn method for=Document><code>createComment(<var>data</var>)</code></dfn> method, when invoked,
must return a new {{Comment}} <a>node</a> with its <a>data</a> set to <var>data</var> and
<a>node document</a> set to the <a>context object</a>.

<p class="note no-backref">No check is performed that <var>data</var> consists of
characters that match the <code><a type>Char</a></code> production
or that it contains two adjacent hyphens or ends with a hyphen.

The
<dfn method for=Document><code>createProcessingInstruction(<var>target</var>, <var>data</var>)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li>If <var>target</var> does not match the
 <!--<code data-anolis-type>PITarget</code>-->
 <code><a type>Name</a></code> production,
 then <a>throw</a> an {{InvalidCharacterError}}. <!-- DOM3 does not check for "xml" -->

 <li>If <var>data</var> contains the string
 "<code>?></code>", then <a>throw</a> an
 {{InvalidCharacterError}}. <!-- Gecko does this. -->

 <li>Return a new {{ProcessingInstruction}}
 <a>node</a>, with
 <a for=ProcessingInstruction>target</a> set to <var>target</var>,
 <a>data</a> set to <var>data</var>, and
 <a>node document</a> set to the
 <a>context object</a>.
</ol>

<p class="note no-backref">No check is performed that <var>target</var> contains
"<code>xml</code>" or "<code>:</code>", or that
<var>data</var> contains characters that match the
<code><a type>Char</a></code> production.

<hr>

<dl class=domintro>
 <dt><var>clone</var> = <var>document</var> . <a method lt=importNode()>importNode(<var>node</var> [, <var>deep</var> = false])</a>
 <dd>
 <dd>
  Returns a copy of <var>node</var>. If
  <var>deep</var> is true, the copy also includes the
  <var>node</var>'s <a>descendants</a>.

  If <var>node</var> is a <a>document</a> or a <a for=/>shadow root</a>, throws a
  {{NotSupportedError}}.

 <dt><var>node</var> = <var>document</var> . {{adoptNode(node)}}

 <dd>
  Moves <var>node</var> from another
  <a>document</a> and returns it.

  If <var>node</var> is a <a>document</a>, throws a {{NotSupportedError}} or, if
  <var>node</var> is a <a for=/>shadow root</a>, throws a {{HierarchyRequestError}}.
</dl>

The <dfn method for=Document><code>importNode(<var>node</var>, <var>deep</var>)</code></dfn> method,
when invoked, must run these steps:

<ol>
 <li><p>If <var>node</var> is a <a>document</a> or <a for=/>shadow root</a>, then <a>throw</a> a
 {{NotSupportedError}}.

 <li><p>Return a <a lt="clone a node">clone</a> of <var>node</var>, with <a>context object</a> and
 the <i>clone children flag</i> set if <var>deep</var> is true.
</ol>

<a lt="Other applicable specifications">Specifications</a> may define
<dfn export for=Node id=concept-node-adopt-ext>adopting steps</dfn> for all or some
<a>nodes</a>. The algorithm is passed <var>node</var> and
<var>oldDocument</var>, as indicated in the
<a>adopt</a> algorithm.

To <dfn export for=Node id=concept-node-adopt>adopt</dfn> a <var>node</var> into
a <var>document</var>, run these steps:

<ol>
 <li><p>Let <var>oldDocument</var> be <var>node</var>'s <a>node document</a>.

 <li><p>If <var>node</var>'s <a>parent</a> is not null, <a>remove</a> <var>node</var> from its
 <a>parent</a>.

 <li>
  <p>If <var>document</var> is not the same as <var>oldDocument</var>, run these substeps:

  <ol>
   <li><p>For each <var>inclusiveDescendant</var> in <var>node</var>'s
   <a>shadow-including inclusive descendants</a>, set <var>inclusiveDescendant</var>'s
   <a>node document</a> to <var>document</var>.
   <!--AttrExodus as well as any associated {{Attr}} nodes-->

   <li>
    <p>For each <var>inclusiveDescendant</var> in <var>node</var>'s
    <a>shadow-including inclusive descendants</a> that is an <a for=/>element</a> with
    <a>custom element state</a> of "<code>custom</code>", set <var>inclusiveDescendant</var>'s
    <a>custom element state</a> to "<code>undefined</code>".</p>

    <p class="note">
     If this adoption is followed by an <a lt="insert" for="Node">insertion</a>, as most are, then
     the insertion will <a lt="try to upgrade an element">try to upgrade</a>
     <var>inclusiveDescendant</var>, potentially causing it to become <a>custom</a> again.
    </p>
   </li>

   <li><p>For each <var>inclusiveDescendant</var> in <var>node</var>'s
   <a>shadow-including inclusive descendants</a>, in <a>shadow-including tree order</a>, run the
   <a>adopting steps</a> with <var>inclusiveDescendant</var> and <var>oldDocument</var>.
  </ol>
</ol>

The <dfn method for=Document><code>adoptNode(<var>node</var>)</code></dfn> method, when invoked,
must run these steps:

<ol>
 <li>If <var>node</var> is a <a>document</a>, then <a>throw</a> a {{NotSupportedError}}.

 <li>If <var>node</var> is a <a for=/>shadow root</a>, then <a>throw</a> a
 {{HierarchyRequestError}}.

 <li><a>Adopt</a> <var>node</var>
 into the <a>context object</a>.

 <li>Return <var>node</var>.
</ol>

<hr>

The <dfn method for=Document><code>createAttribute(<var>localName</var>)</code></dfn> method, when
invoked, must run these steps:

<ol>
 <li><p>If <var>localName</var> does not match the <code><a type>Name</a></code> production in XML,
 then <a>throw</a> an {{InvalidCharacterError}}.

 <li>If the <a>context object</a> is an <a>HTML document</a>, let
 <var>localName</var> be <a>converted to ASCII lowercase</a>.

 <li>Return a new <a>attribute</a> whose
 <a for=Attr>local name</a> is <var>localName</var>.
</ol>

The
<dfn method for=Document><code>createAttributeNS(<var>namespace</var>, <var>qualifiedName</var>)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li><p>Let <var>namespace</var>, <var>prefix</var>, and <var>localName</var> be the result of
 passing <var>namespace</var> and <var>qualifiedName</var> to <a>validate and extract</a>. Rethrow
 any exceptions.

 <li><p>Return a new <a>attribute</a> whose <a for=Attr>namespace</a> is <var>namespace</var>,
 <a for=Attr>namespace prefix</a> is <var>prefix</var>, and <a for=Attr>local name</a> is
 <var>localName</var>.
</ol>

<hr>

<p>The <dfn method for=Document><code>createEvent(<var>interface</var>)</code></dfn> method, when
invoked, must run these steps:

<ol>
 <li><p>Let <var>constructor</var> be null.

 <li>
  <p>If <var>interface</var> is an <a>ASCII case-insensitive</a> match for any of the strings in the
  first column in the following table, then set <var>constructor</var> to the interface in the
  second column on the same row as the matching string:

  <table>
   <thead>
    <tr><th>String<th>Interface<td>Notes
   <tbody>
    <tr><td>"<code>animationevent</code>"<td>{{AnimationEvent}}<td>[[!CSS3-ANIMATIONS]]
    <tr><td>"<code>beforeunloadevent</code>"<td>{{BeforeUnloadEvent}}<td rowspan=2>[[!HTML]]
    <tr><td>"<code>closeevent</code>"<td>{{CloseEvent}}
    <tr><td>"<code>compositionevent</code>"<td>{{CompositionEvent}}<td>[[!UIEVENTS]]
    <!-- textevent also maps to CompositionEvent -->
    <tr><td>"<code>customevent</code>"<td>{{CustomEvent}}<td>
    <tr><td>"<code>devicemotionevent</code>"<td>{{DeviceMotionEvent}}<td rowspan=2>[[!DEVICE-ORIENTATION]]
    <tr><td>"<code>deviceorientationevent</code>"<td>{{DeviceOrientationEvent}}
    <tr><td>"<code>dragevent</code>"<td>{{DragEvent}}<td rowspan=2>[[!HTML]]
    <tr><td>"<code>errorevent</code>"<td>{{ErrorEvent}}
    <tr><td>"<code>event</code>"<td rowspan=2>{{Event}}<td rowspan=2>
    <tr><td>"<code>events</code>"
    <!-- htmlevents and svgevents also map to Event -->
    <tr><td>"<code>focusevent</code>"<td>{{FocusEvent}}<td>[[!UIEVENTS]]
    <tr><td>"<code>hashchangeevent</code>"<td>{{HashChangeEvent}}<td>[[!HTML]]
    <tr><td>"<code>htmlevents</code>"<td>{{Event}}<td>
    <tr><td>"<code>idbversionchangeevent</code>"<td>{{IDBVersionChangeEvent}}<td>[[INDEXEDDB]]
    <tr><td>"<code>keyboardevent</code>"<td>{{KeyboardEvent}}<td>[[!UIEVENTS]]
    <tr><td>"<code>messageevent</code>"<td>{{MessageEvent}}<td>[[!HTML]]
    <tr><td>"<code>mouseevent</code>"<td rowspan=2>{{MouseEvent}}<td rowspan=2>[[!UIEVENTS]]
    <tr><td>"<code>mouseevents</code>"
    <tr><td>"<code>pagetransitionevent</code>"<td>{{PageTransitionEvent}}<td rowspan=2>[[!HTML]]
    <tr><td>"<code>popstateevent</code>"<td>{{PopStateEvent}}
    <tr><td>"<code>progressevent</code>"<td>{{ProgressEvent}}<td>[[!XHR]]
    <tr><td>"<code>storageevent</code>"<td>{{StorageEvent}}<td>[[!HTML]]
    <tr><td>"<code>svgevents</code>"<td>{{Event}}<td>
    <tr><td>"<code>svgzoomevent</code>"<td rowspan=2>{{SVGZoomEvent}}<td rowspan=2>[[!SVG]]
    <tr><td>"<code>svgzoomevents</code>"
    <tr><td>"<code>textevent</code>"<td>{{CompositionEvent}}<td>[[!UIEVENTS]]
    <tr><td>"<code>touchevent</code>"<td>{{TouchEvent}}<td>[[!TOUCH-EVENTS]]
    <tr><td>"<code>trackevent</code>"<td>{{TrackEvent}}<td>[[!HTML]]
    <tr><td>"<code>transitionevent</code>"<td>{{TransitionEvent}}<td>[[!CSS3-TRANSITIONS]]
    <tr><td>"<code>uievent</code>"<td rowspan=2>{{UIEvent}}<td rowspan=2>[[!UIEVENTS]]
    <tr><td>"<code>uievents</code>"
    <tr><td>"<code>webglcontextevent</code>"<td>{{WebGLContextEvent}}<td>[[!WEBGL]]
    <tr><td>"<code>wheelevent</code>"<td>{{WheelEvent}}<td>[[!UIEVENTS]]
  </table>

 <li><p>If <var>constructor</var> is null, then <a>throw</a> a {{NotSupportedError}}.

 <li>
  <p>If the initial value of <var>constructor</var> is undefined, then <a>throw</a> a
  {{NotSupportedError}}.

  <p class=note>Typically user agents disable support for touch events in some configurations, in
  which case the initial value of {{TouchEvent}} is undefined.

 <li><p>Let <var>event</var> be the result of <a for=Event lt=constructor>invoking</a> the initial
 value of <var>constructor</var> with the empty string as argument.
 <!-- "initial value" as in before script could get to it -->

 <li><p>Unset <var>event</var>'s <a>initialized flag</a>.

 <li><p>Return <var>event</var>.
</ol>

<p class=note><a>Event</a> constructors ought to be used instead.

<hr>

The <dfn method for=Document><code>createRange()</code></dfn> method, when invoked, must return a
new <a>range</a> with (<a>context object</a>, 0) as its <a>start</a> and <a>end</a>.

<p class=note>The {{Range/Range()}} constructor ought to be used instead.

<hr>

The
<dfn method for=Document><code>createNodeIterator(<var>root</var>, <var>whatToShow</var>, <var>filter</var>)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li>Create a {{NodeIterator}} object.
 <li>Set <a for="traversal">root</a> to <var>root</var> and initialize the
 {{NodeIterator/referenceNode}} attribute to <var>root</var>.
 <li>Initialize the {{NodeIterator/pointerBeforeReferenceNode}} attribute to true.
 <li>Set <a for="traversal">whatToShow</a> to <var>whatToShow</var>.
 <li>Set <a for="traversal">filter</a> to <var>filter</var>.
 <li>Return the newly created {{NodeIterator}} object.
</ol>

The
<dfn method for=Document><code>createTreeWalker(<var>root</var>, <var>whatToShow</var>, <var>filter</var>)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li>Create a {{TreeWalker}} object.
 <li>Set <a for="traversal">root</a> to <var>root</var> and initialize the
 {{TreeWalker/currentNode}} attribute to <var>root</var>.
 <li>Set <a for="traversal">whatToShow</a> to <var>whatToShow</var>.
 <li>Set <a for="traversal">filter</a> to <var>filter</var>.
 <li>Return the newly created {{TreeWalker}} object.
</ol>



<h4 id='interface-domimplementation'>
Interface {{DOMImplementation}}</h4>

User agents must create a {{DOMImplementation}} object whenever
a <a>document</a> is created and associate it
with that <a>document</a>.

<pre class=idl>
[Exposed=Window]
interface DOMImplementation {
  [NewObject] DocumentType createDocumentType(DOMString qualifiedName, DOMString publicId, DOMString systemId);
  [NewObject] XMLDocument createDocument(DOMString? namespace, [TreatNullAs=EmptyString] DOMString qualifiedName, optional DocumentType? doctype = null);
  [NewObject] Document createHTMLDocument(optional DOMString title);

  boolean hasFeature(); // useless; always returns true
};
</pre>

<dl class=domintro>
 <dt><code><var>doctype</var> = <var>document</var> . {{Document/implementation}} . {{createDocumentType(qualifiedName, publicId, systemId)}}</code>

 <dd>
  Returns a <a>doctype</a>, with the given
  <var>qualifiedName</var>, <var>publicId</var>, and
  <var>systemId</var>. If <var>qualifiedName</var> does not
  match the <code><a type>Name</a></code> production, an
  {{InvalidCharacterError}} is thrown, and if it does not match the
  <code><a type>QName</a></code> production, a
  {{NamespaceError}} is thrown.

 <dt><code><var>doc</var> = <var>document</var> . {{Document/implementation}} . <a method lt="createDocument()">createDocument(<var>namespace</var>, <var>qualifiedName</var> [, <var>doctype</var> = null])</a></code>

 <dd>
  Returns an {{XMLDocument}}, with a
  <a>document element</a> whose
  <a for=Element>local name</a> is
  <var>qualifiedName</var> and whose
  <a for=Element>namespace</a> is
  <var>namespace</var> (unless <var>qualifiedName</var> is the
  empty string), and with <var>doctype</var>, if it is given, as its
  <a>doctype</a>.

  This method throws the same exceptions as the {{createElementNS()}} method, when
  invoked with <var>namespace</var> and <var>qualifiedName</var>.

 <dt><code><var>doc</var> = <var>document</var> . {{Document/implementation}} . <a lt="createHTMLDocument()">createHTMLDocument([<var>title</var>])</a></code>

 <dd>
  Returns a <a>document</a>, with a basic
  <a>tree</a> already constructed including a
  <{title}> element, unless the <var>title</var>
  argument is omitted.
</dl>

<div class=impl>

The
<dfn method for="DOMImplementation"><code>createDocumentType(<var>qualifiedName</var>, <var>publicId</var>, <var>systemId</var>)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li><p><a>Validate</a> <var>qualifiedName</var>. Rethrow any exceptions.

 <li><p>Return a new <a>doctype</a>, with <var>qualifiedName</var> as its
 <a for=DocumentType>name</a>, <var>publicId</var> as its <a>public ID</a>, and <var>systemId</var>
 as its <a>system ID</a>, and with its <a>node document</a> set to the associated <a>document</a> of
 the <a>context object</a>.
</ol>

<p class=note>No check is performed that <var>publicId</var> code points match the
<code><a type>PubidChar</a></code> production or that <var>systemId</var> does not contain both a
'<code>"</code>' and a "<code>'</code>".

<p>The
<dfn method for=DOMImplementation><code>createDocument(<var>namespace</var>, <var>qualifiedName</var>, <var>doctype</var>)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li>
  <p>Let <var>document</var> be a new {{XMLDocument}}.

  <p class="note no-backref">This method creates an {{XMLDocument}} rather than a normal
  <a>document</a>. They are identical except for the addition of the
  {{XMLDocument/load()}} method deployed content relies upon.
  [[!HTML]]

 <li><p>Let <var>element</var> be null.

 <li><p>If <var>qualifiedName</var> is not the empty string, then set <var>element</var> to the
 result of running the <a>internal <code>createElementNS</code> steps</a>, given
 <var>document</var>, <var>namespace</var>, <var>qualifiedName</var>, and an empty dictionary.
 Rethrow any exceptions.

 <li><p>If <var>doctype</var> is non-null, <a>append</a> <var>doctype</var> to <var>document</var>.

 <li><p>If <var>element</var> is non-null, <a>append</a> <var>element</var> to <var>document</var>.

 <li><p><var>document</var>'s <a>origin</a> is the <a>origin</a> of the <a>context object</a>'s
 associated <a>document</a>. [[!HTML]]

 <li>
  <p><var>document</var>'s <a for=Document>content type</a> is determined by <var>namespace</var>:

  <dl class=switch>
   <dt><a>HTML namespace</a>
   <dd><code>application/xhtml+xml</code>

   <dt><a>SVG namespace</a>
   <dd><code>image/svg+xml</code>

   <dt>Any other namespace
   <dd><code>application/xml</code>
  </dl>

 <li><p>Return <var>document</var>.
</ol>

The
<dfn method for=DOMImplementation><code>createHTMLDocument(<var>title</var>)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li><p>Let <var>doc</var> be a new <a>document</a> that is an <a>HTML document</a>.

 <li><p>Set <var>doc</var>'s <a for=Document>content type</a> to "<code>text/html</code>".

 <li><p><a>Append</a> a new <a>doctype</a>, with "<code>html</code>" as its
 <a for=DocumentType>name</a> and with its <a>node document</a> set to <var>doc</var>, to
 <var>doc</var>.

 <li><p><a>Append</a> the result of <a>creating an element</a> given <var>doc</var>, <{html}>, and
 the <a>HTML namespace</a>, to <var>doc</var>.

 <li><p><a>Append</a> the result of <a>creating an element</a> given <var>doc</var>, <{head}>, and
 the <a>HTML namespace</a>, to the <{html}> element created earlier.

 <li>
  <p>If <var>title</var> is given:

  <ol>
   <li><p><a>Append</a> the result of <a>creating an element</a> given <var>doc</var>, <{title}>,
   and the <a>HTML namespace</a>, to the <{head}> element created earlier.

   <li><p><a>Append</a> a new {{Text}} <a>node</a>, with its <a>data</a> set to
   <var>title</var> (which could be the empty string) and its <a>node document</a> set to
   <var>doc</var>, to the <{title}> element created earlier.
  </ol>

 <li><p><a>Append</a> the result of <a>creating an element</a> given <var>doc</var>, <{body}>, and
 the <a>HTML namespace</a>, to the <{html}> element created earlier.</li>

 <li><p><var>doc</var>'s <a>origin</a> is the <a>origin</a> of the <a>context object</a>'s
 associated <a>document</a>. [[!HTML]]

 <li><p>Return <var>doc</var>.
</ol>

The <dfn method for="DOMImplementation"><code>hasFeature()</code></dfn> method, when
invoked, must return true.

<p class="note no-backref">{{hasFeature()}} originally would report whether the user agent
claimed to support a given DOM feature, but experience proved it was not nearly as
reliable or granular as simply checking whether the desired objects, attributes, or
methods existed. As such, it is no longer to be used, but continues to exist (and simply
returns true) so that old pages don't stop working.

</div>


<h3 id='interface-documenttype'>Interface {{DocumentType}}</h3>

<pre class=idl>
[Exposed=Window]
interface DocumentType : Node {
  readonly attribute DOMString name;
  readonly attribute DOMString publicId;
  readonly attribute DOMString systemId;
};
</pre>

<p>{{DocumentType}} <a>nodes</a> are simply known as
<dfn export id=concept-doctype lt="doctype">doctypes</dfn>.

<p><a>Doctypes</a> have an associated
<dfn export id=concept-doctype-name for=DocumentType>name</dfn>,
<dfn export id=concept-doctype-publicid for=DocumentType>public ID</dfn>, and
<dfn export id=concept-doctype-systemid for=DocumentType>system ID</dfn>.

<p>When a <a>doctype</a> is created, its <a for=DocumentType>name</a> is always given. Unless
explicitly given when a <a>doctype</a> is created, its <a>public ID</a> and <a>system ID</a> are the
empty string.

<p>The <dfn attribute for=DocumentType><code>name</code></dfn> attribute's getter must return the
<a>context object</a>'s <a for=DocumentType>name</a>.

<p>The <dfn attribute for=DocumentType><code>publicId</code></dfn> attribute's getter must return
the <a>context object</a>'s <a>public ID</a>.

<p>The <dfn attribute for=DocumentType><code>systemId</code></dfn> attribute's getter must return
the <a>context object</a>'s <a>system ID</a>.


<h3 id='interface-documentfragment'>Interface {{DocumentFragment}}</h3>

<pre class=idl>
[Constructor,
 Exposed=Window]
interface DocumentFragment : Node {
};
</pre>

<p>A {{DocumentFragment}} <a>node</a> has an associated
<dfn export id=concept-documentfragment-host for=DocumentFragment>host</dfn> (null or an
<a for="/">element</a> in a different <a>node tree</a>). It is null unless otherwise stated.

<p>An object <var>A</var> is a
<dfn export id=concept-tree-host-including-inclusive-ancestor>host-including inclusive ancestor</dfn>
of an object <var>B</var>, if either <var>A</var> is an <a>inclusive ancestor</a> of <var>B</var>,
or if <var>B</var>'s <a for=tree>root</a> has a non-null <a for=DocumentFragment>host</a> and
<var>A</var> is a <a>host-including inclusive ancestor</a> of <var>B</var>'s <a for=tree>root</a>'s
<a for=DocumentFragment>host</a>.

<p class="note no-backref">The {{DocumentFragment}} <a>node</a>'s <a for=DocumentFragment>host</a>
concept is useful for HTML's <{template}> element and for <a for=/>shadow roots</a>, and impacts the
<a>pre-insert</a> and <a>replace</a> algorithms.

<dl class=domintro>
 <dt><code><var>tree</var> = new {{DocumentFragment()}}</code>
 <dd>Returns a new {{DocumentFragment}} <a>node</a>.
</dl>

<p>The <dfn constructor for=DocumentFragment><code>DocumentFragment()</code></dfn> constructor, when
invoked, must return a new {{DocumentFragment}} <a>node</a> whose <a>node document</a> is the
global object's associated <a>document</a>.


<h3 id=interface-shadowroot>Interface {{ShadowRoot}}</h3>

<pre class=idl>
[Exposed=Window]
interface ShadowRoot : DocumentFragment {
  readonly attribute ShadowRootMode mode;
  readonly attribute Element host;
};

enum ShadowRootMode { "open", "closed" };
</pre>

<p>{{ShadowRoot}} <a>nodes</a> are simply known as
<dfn export id=concept-shadow-root lt="shadow root">shadow roots</dfn>.

<p><a for=/>Shadow roots</a> have an associated <dfn for=ShadowRoot>mode</dfn> ("<code>open</code>"
or "<code>closed</code>").</p>

<p><a for=/>Shadow roots</a>'s associated <a for=DocumentFragment>host</a> is never null.</p>
<!-- If we ever change this, e.g., add a ShadowRoot object constructor, that would have serious
     consequences for innerHTML. -->

<p>A <a for=/>shadow root</a>'s <a>get the parent</a> algorithm, given an <var>event</var>, returns
null if <var>event</var>'s <a>composed flag</a> is unset and <a for=/>shadow root</a> is the
<a for=tree>root</a> of <var>event</var>'s <a for=Event>path</a>'s first tuple's <b>item</b>, and
<a for=/>shadow root</a>'s <a for=DocumentFragment>host</a> otherwise.

<p>The <dfn attribute for=ShadowRoot><code>mode</code></dfn> attribute's getter must return the
<a>context object</a>'s <a for=ShadowRoot>mode</a>.</p>

<p>The <dfn attribute for=ShadowRoot><code>host</code></dfn> attribute's getter must return the
<a>context object</a>'s <a for=DocumentFragment>host</a>.

<hr>

<p>In <dfn export id=concept-shadow-including-tree-order>shadow-including tree order</dfn>, is
<a>shadow-including preorder, depth-first traversal</a> of a <a>node tree</a>.
<dfn noexport>shadow-including preorder, depth-first traversal</dfn> of a <a>node tree</a>
<var>tree</var> is preorder, depth-first traversal of <var>tree</var>, with for each
<a for=Element>shadow host</a> encountered in <var>tree</var>,
<a>shadow-including preorder, depth-first traversal</a> of that <a for=/>element</a>'s
<a for=Element>shadow root</a>'s <a>node tree</a> just after it is encountered.

<p>The <dfn export id=concept-shadow-including-root>shadow-including root</dfn> of an object is its
<a for=tree>root</a>'s <a for=DocumentFragment>host</a>'s <a>shadow-including root</a>, if the
object's <a for=tree>root</a> is a <a for=/>shadow root</a>, and its <a for=tree>root</a>
otherwise.</p>

<p>An object <var>A</var> is a
<dfn export id=concept-shadow-including-descendant>shadow-including descendant</dfn> of an object
<var>B</var>, if <var>A</var> is a <a>descendant</a> of <var>B</var>, or <var>A</var>'s
<a for=tree>root</a> is a <a for=/>shadow root</a> and <var>A</var>'s <a for=tree>root</a>'s
<a for=DocumentFragment>host</a> is a <a>shadow-including inclusive descendant</a> of <var>B</var>.

<p>A
<dfn export id=concept-shadow-including-inclusive-descendant>shadow-including inclusive descendant</dfn>
is an object or one of its <a>shadow-including descendants</a>.

<p>An object <var>A</var> is a
<dfn export id=concept-shadow-including-ancestor>shadow-including ancestor</dfn> of an object
<var>B</var>, if and only if <var>B</var> is a <a>shadow-including descendant</a> of <var>A</var>.

<p>A
<dfn export id=concept-shadow-including-inclusive-ancestor>shadow-including inclusive ancestor</dfn>
is an object or one of its <a>shadow-including ancestors</a>.

<p>A <a>node</a> <var>A</var> is an <dfn export id=concept-unclosed-node>unclosed node</dfn> of a
<a>node</a> <var>B</var>, if <var>A</var>'s <a for=tree>root</a> is not a <a for=/>shadow root</a>,
<var>A</var>'s <a for=tree>root</a> is a <a>shadow-including inclusive ancestor</a> of <var>B</var>,
or <var>A</var>'s <a for=tree>root</a> is a <a for=/>shadow root</a> whose
<a for=ShadowRoot>mode</a> is "<code>open</code>" and <a for=DocumentFragment>host</a> is an
<a>unclosed node</a> of <var>B</var>.

<hr>

<p class="XXX">For now you can find more information about this object in
<a href="https://w3c.github.io/webcomponents/spec/shadow/">Shadow DOM</a>. The DOM Standard will be
updated over time to cover more details.


<h3 id='interface-element'>Interface {{Element}}</h3>

<pre class=idl>
[Exposed=Window]
interface Element : Node {
  readonly attribute DOMString? namespaceURI;
  readonly attribute DOMString? prefix;
  readonly attribute DOMString localName;
  readonly attribute DOMString tagName;

  [CEReactions] attribute DOMString id;
  [CEReactions] attribute DOMString className;
  [CEReactions, SameObject, PutForwards=value] readonly attribute DOMTokenList classList;
  [CEReactions] attribute DOMString slot;

  boolean hasAttributes();
  [SameObject] readonly attribute NamedNodeMap attributes;
  sequence&lt;DOMString> getAttributeNames();
  DOMString? getAttribute(DOMString qualifiedName);
  DOMString? getAttributeNS(DOMString? namespace, DOMString localName);
  [CEReactions] void setAttribute(DOMString qualifiedName, DOMString value);
  [CEReactions] void setAttributeNS(DOMString? namespace, DOMString qualifiedName, DOMString value);
  [CEReactions] void removeAttribute(DOMString qualifiedName);
  [CEReactions] void removeAttributeNS(DOMString? namespace, DOMString localName);
  boolean hasAttribute(DOMString qualifiedName);
  boolean hasAttributeNS(DOMString? namespace, DOMString localName);

  Attr? getAttributeNode(DOMString qualifiedName);
  Attr? getAttributeNodeNS(DOMString? namespace, DOMString localName);
  [CEReactions] Attr? setAttributeNode(Attr attr);
  [CEReactions] Attr? setAttributeNodeNS(Attr attr);
  [CEReactions] Attr removeAttributeNode(Attr attr);

  ShadowRoot attachShadow(ShadowRootInit init);
  readonly attribute ShadowRoot? shadowRoot;

  Element? closest(DOMString selectors);
  boolean matches(DOMString selectors);
  boolean webkitMatchesSelector(DOMString selectors); // historical alias of .matches

  HTMLCollection getElementsByTagName(DOMString qualifiedName);
  HTMLCollection getElementsByTagNameNS(DOMString? namespace, DOMString localName);
  HTMLCollection getElementsByClassName(DOMString classNames);

  [CEReactions] Element? insertAdjacentElement(DOMString where, Element element); // historical
  void insertAdjacentText(DOMString where, DOMString data); // historical
};

dictionary ShadowRootInit {
  required ShadowRootMode mode;
};
</pre>

<p>{{Element}} <a>nodes</a> are simply known as
<dfn export id=concept-element lt=element>elements</dfn>.

<p><a for=/>Elements</a> have an associated
<dfn export id=concept-element-namespace for=Element>namespace</dfn>,
<dfn export id=concept-element-namespace-prefix for=Element>namespace prefix</dfn>,
<dfn export id=concept-element-local-name for=Element>local name</dfn>,
<dfn export id=concept-element-custom-element-state for=Element>custom element state</dfn>, and
<dfn export id=concept-element-is-value for=Element><code>is</code> value</dfn>. When an
<a for="/">element</a> is <a lt="create an element">created</a>, all of these values are
initialized.

<p>An <a for=/>element</a>'s <a>custom element state</a> is one of "<code>undefined</code>",
"<code>uncustomized</code>", or "<code>custom</code>". An <a for=/>element</a> whose
<a>custom element state</a> is "<code>uncustomized</code>" or "<code>custom</code>" is said to be
<dfn export id=concept-element-defined for=Element>defined</dfn>. An <a for=/>element</a> whose
<a>custom element state</a> is "<code>custom</code>", is said to be
<dfn export id=concept-element-custom for=Element>custom</dfn>.

<p class=note>Whether or not an element is <a>defined</a> is used to determine the behavior of the
'':defined'' pseudo-class. Whether or not an element is <a>custom</a> is used to determine the
behavior of the <a href=#mutation-algorithms>mutation algorithms</a>.</p>

<div class=example>
 <p>The following code illustrates elements in each of these three states:</p>

 <pre><code class="lang-html">
  &lt;!DOCTYPE html>
  &lt;script>
    window.customElements.define("sw-rey", class extends HTMLElement {})
    window.customElements.define("sw-finn", class extends HTMLElement {}, { extends: "p" })
    window.customElements.define("sw-kylo", class extends HTMLElement {
      constructor() {
        // super() intentionally omitted for this example
      }
    })
  &lt;/script>

  &lt;!-- "undefined" (not defined, not custom) -->
  &lt;sw-han>&lt;/sw-han>
  &lt;sw-kylo>&lt;/sw-kylo>
  &lt;p is="sw-luke">&lt;/p>
  &lt;p is="asdf">&lt;/p>

  &lt;!-- "uncustomized" (defined, not custom) -->
  &lt;p>&lt;/p>
  &lt;asdf>&lt;/asdf>

  &lt;!-- "custom" (defined, custom) -->
  &lt;sw-rey>&lt;/sw-rey>
  &lt;p is="sw-finn">&lt;/p>
 </code></pre>
</div>

<p><a for=/>Elements</a> also have an associated
<dfn export id=concept-element-shadow-root for=Element>shadow root</dfn> (null or a
<a for=/>shadow root</a>). It is null unless otherwise stated. An <a for=/>element</a> is a
<dfn export for=Element>shadow host</dfn> if its <a for=Element>shadow root</a> is non-null.

<p>An <a for=/>element</a>'s
<dfn export id=concept-element-qualified-name for=Element>qualified name</dfn> is its
<a for=Element>local name</a> if its <a for=Element>namespace prefix</a> is null, and its
<a for=Element>namespace prefix</a>, followed by "<code>:</code>", followed by its
<a for=Element>local name</a>, otherwise.

<p class=note>User agents could have this as an internal slot as an optimization, but are not
required to do so. The standard has this concept for readability.

<p>To
<dfn export id=concept-create-element lt="create an element|creating an element">create an element</dfn>,
given a <var>document</var>, <var>localName</var>, <var>namespace</var>, and optional
<var>prefix</var>, <var>is</var>, and <var>synchronous custom elements flag</var>, run these steps:

<ol>
 <li><p>If <var>prefix</var> was not given, let <var>prefix</var> be null.

 <li><p>If <var>is</var> was not given, let <var>is</var> be null.

 <li><p>Let <var>result</var> be null.

 <li><p>Let <var>definition</var> be the result of
 <a lt="look up a custom element definition">looking up a custom element definition</a> given
 <var>document</var>, <var>namespace</var>, <var>localName</var>, and <var>is</var>.

 <li>
  <p>If <var>definition</var> is non-null, and <var>definition</var>'s
  <a for="custom element definition">name</a> is not equal to its
  <a for="custom element definition">local name</a> (i.e., <var>definition</var> represents a
  <a>customized built-in element</a>), then:

  <ol>
   <li><p>Let <var>interface</var> be the <a>element interface</a> for <var>localName</var> and the
   <a>HTML namespace</a>.

   <li><p>Set <var>result</var> to a new <a for=/>element</a> that implements <var>interface</var>,
   with no attributes, <a for=Element>namespace</a> set to the <a>HTML namespace</a>,
   <a for=Element>namespace prefix</a> set to <var>prefix</var>, <a for=Element>local name</a> set
   to <var>localName</var>, <a>custom element state</a> set to "<code>undefined</code>",
   <a><code>is</code> value</a> set to <var>is</var>, and <a>node document</a> set to
   <var>document</var>.

   <li><p>If the <var>synchronous custom elements flag</var> is set,
   <a lt="upgrade an element">upgrade</a> <var>element</var> using <var>definition</var>.

   <li><p>Otherwise, <a>enqueue a custom element upgrade reaction</a> given <var>result</var> and
   <var>definition</var>.
  </ol>
 </li>

 <li>
  <p>Otherwise, if <var>definition</var> is non-null, then:

  <ol>
   <li>
    <p>If the <var>synchronous custom elements flag</var> is set:

    <ol>
     <li><p>Let <var>C</var> be <var>definition</var>'s
     <a for="custom element definition">constructor</a>.

     <li><p>Set <var>result</var> to <a abstract-op>Construct</a>(<var>C</var>). Rethrow any
     exceptions.

     <li>
      <p>If <var>result</var> does not implement the {{HTMLElement}} interface, <a>throw</a> a
      <code>TypeError</code>.

      <p class=note>This is meant to be a brand check to ensure that the object was allocated by the
      {{HTMLElement}} constructor. See
      <a href="https://github.com/heycam/webidl/issues/97">webidl #97</a> about making this more
      precise.
     </li>

     <li><p>If <var>result</var>'s <a for=Element>attribute list</a> is not empty, then <a>throw</a>
     a {{NotSupportedError}}.

     <li><p>If <var>result</var> has <a>children</a>, then <a>throw</a> a {{NotSupportedError}}.

     <li><p>If <var>result</var>'s <a>parent</a> is not null, then <a>throw</a> a
     {{NotSupportedError}}.

     <li><p>If <var>result</var>'s <a>node document</a> is not <var>document</var>, then
     <a>throw</a> a {{NotSupportedError}}.

     <li><p>If <var>result</var>'s <a for=Element>namespace</a> is not the <a>HTML namespace</a>,
     then <a>throw</a> a {{NotSupportedError}}.

     <li><p>If <var>result</var>'s <a for=Element>local name</a> is not equal to
     <var>localName</var>, then <a>throw</a> a {{NotSupportedError}}.

     <li><p>Set <var>result</var>'s <a for=Element>namespace prefix</a> to <var>prefix</var>.

     <li><p>Set <var>result</var>'s <a><code>is</code> value</a> to null.
    </ol>
   </li>

   <li>
    <p>Otherwise:

    <ol>
     <li><p>Set <var>result</var> to a new <a for=/>element</a> that implements the {{HTMLElement}}
     interface, with no attributes, <a for=Element>namespace</a> set to the <a>HTML namespace</a>,
     <a for=Element>namespace prefix</a> set to <var>prefix</var>, <a for=Element>local name</a> set
     to <var>localName</var>, <a>custom element state</a> set to "<code>undefined</code>",
     <a><code>is</code> value</a> set to null, and <a>node document</a> set to <var>document</var>.

     <li><p><a>Enqueue a custom element upgrade reaction</a> given <var>result</var> and
     <var>definition</var>.
    </ol>
   </li>
  </ol>
 </li>

 <li>
  <p>Otherwise:

  <ol>
   <li><p>Let <var>interface</var> be the <a>element interface</a> for <var>localName</var> and
   <var>namespace</var>.

   <li><p>Set <var>result</var> to a new <a for=/>element</a> that implements <var>interface</var>,
   with no attributes, <a for=Element>namespace</a> set to <var>namespace</var>,
   <a for=Element>namespace prefix</a> set to <var>prefix</var>, <a for=Element>local name</a> set
   to <var>localName</var>, <a>custom element state</a> set to "<code>uncustomized</code>",
   <a><code>is</code> value</a> set to <var>is</var>, and <a>node document</a> set to
   <var>document</var>.

   <li><p>If <var>document</var> has a <a lt=concept-document-bc>browsing context</a>, and
   <var>namespace</var> is the <a>HTML namespace</a>, and either <var>localName</var> is a
   <a>valid custom element name</a> or <var>is</var> is is non-null, set <var>result</var>'s
   <a>custom element state</a> to "<code>undefined</code>".
  </ol>
 </li>

 <li><p>Return <var>result</var>.
</ol>

<a for="/">Elements</a> also have an ordered
<dfn export id=concept-element-attribute for=Element>attribute list</dfn> exposed through a
{{NamedNodeMap}}. Unless explicitly given when an
<a for="/">element</a> is created, its
<a for=Element>attribute list</a> is empty. An
<a for="/">element</a>
<dfn export id=concept-element-attribute-has lt="has an attribute">has</dfn> an
<a>attribute</a> <var>A</var> if
<var>A</var> is in its
<a for=Element>attribute list</a>.

This and <a lt="other applicable specifications">other specifications</a> may define
<dfn id=concept-element-attributes-change-ext>attribute change steps</dfn> for
<a for=/>elements</a>. The algorithm is passed <var>element</var>, <var>localName</var>,
<var>oldValue</var>, <var>value</var>, and <var>namespace</var>.

To <dfn export id=concept-element-attributes-change lt="change an attribute">change</dfn> an
<a>attribute</a> <var>attribute</var>
from an <a for="/">element</a> <var>element</var>
to <var>value</var>, run these steps:

<ol>
 <li><a>Queue a mutation record</a> of "<code>attributes</code>"
 for <var>element</var> with name <var>attribute</var>'s
 <a for=Attr>local name</a>, namespace
 <var>attribute</var>'s
 <a for=Attr>namespace</a>, and oldValue
 <var>attribute</var>'s
 <a for=Attr>value</a>.

 <li>If <var>element</var> is <a>custom</a>, then <a>enqueue a custom element callback reaction</a>
 with <var>element</var>, callback name "<code>attributeChangedCallback</code>", and an argument
 list containing <var>attribute</var>'s <a for=Attr>local name</a>, <var>attribute</var>'s
 <a for=Attr>value</a>, <var>value</var>, and <var>attribute</var>'s <a for=Attr>namespace</a>.

 <li><p>Run the <a>attribute change steps</a> with <var>element</var>, <var>attribute</var>'s
 <a for=Attr>local name</a>, <var>attribute</var>'s <a for=Attr>value</a>, <var>value</var>, and
 <var>attribute</var>'s <a for=Attr>namespace</a>.

 <li>Set <var>attribute</var>'s
 <a for=Attr>value</a> to <var>value</var>.
</ol>

To <dfn export id=concept-element-attributes-append lt="append an attribute">append</dfn> an
<a>attribute</a> <var>attribute</var> to
an <a for="/">element</a> <var>element</var>,
run these steps:

<ol>
 <li><a>Queue a mutation record</a> of "<code>attributes</code>"
 for <var>element</var> with name <var>attribute</var>'s
 <a for=Attr>local name</a>, namespace
 <var>attribute</var>'s
 <a for=Attr>namespace</a>, and oldValue
 null.

 <li>If <var>element</var> is <a>custom</a>, then <a>enqueue a custom element callback reaction</a>
 with <var>element</var>, callback name "<code>attributeChangedCallback</code>", and an argument
 list containing <var>attribute</var>'s <a for=Attr>local name</a>, null, <var>attribute</var>'s
 <a for=Attr>value</a>, and <var>attribute</var>'s <a for=Attr>namespace</a>.

 <li><p>Run the <a>attribute change steps</a> with <var>element</var>, <var>attribute</var>'s
 <a for=Attr>local name</a>, null, <var>attribute</var>'s <a for=Attr>value</a>, and
 <var>attribute</var>'s <a for=Attr>namespace</a>.

 <li>Append the <var>attribute</var> to the <var>element</var>'s
 <a for=Element>attribute list</a>.

 <li>Set <var>attribute</var>'s
 <a for=Attr>element</a> to <var>element</var>.
</ol>

To <dfn export id=concept-element-attributes-remove lt="remove an attribute">remove</dfn> an
<a>attribute</a> <var>attribute</var>
from an <a for="/">element</a> <var>element</var>,
run these steps:

<ol>
 <li><a>Queue a mutation record</a> of "<code>attributes</code>"
 for <var>element</var> with name <var>attribute</var>'s
 <a for=Attr>local name</a>, namespace
 <var>attribute</var>'s
 <a for=Attr>namespace</a>, and oldValue
 <var>attribute</var>'s
 <a for=Attr>value</a>.

 <li>If <var>element</var> is <a>custom</a>, then <a>enqueue a custom element callback reaction</a>
 with <var>element</var>, callback name "<code>attributeChangedCallback</code>", and an argument
 list containing <var>attribute</var>'s <a for=Attr>local name</a>, <var>attribute</var>'s
 <a for=Attr>value</a>, null, and <var>attribute</var>'s <a for=Attr>namespace</a>.

 <li><p>Run the <a>attribute change steps</a> with <var>element</var>, <var>attribute</var>'s
 <a for=Attr>local name</a>, <var>attribute</var>'s <a for=Attr>value</a>, null, and
 <var>attribute</var>'s <a for=Attr>namespace</a>.

 <li>Remove <var>attribute</var> from the
 <var>element</var>'s
 <a for=Element>attribute list</a>.

 <li>Set <var>attribute</var>'s
 <a for=Attr>element</a> to null.
</ol>

To <dfn export id=concept-element-attributes-replace lt="replace an attribute">replace</dfn> an
<a>attribute</a> <var>oldAttr</var> by an <a>attribute</a> <var>newAttr</var>
in an <a for="/">element</a> <var>element</var>, run these steps:

<ol>
 <li><p><a>Queue a mutation record</a> of "<code>attributes</code>" for <var>element</var>
 with name <var>oldAttr</var>'s <a for=Attr>local name</a>,
 namespace <var>oldAttr</var>'s <a for=Attr>namespace</a>,
 and oldValue <var>oldAttr</var>'s <a for=Attr>value</a>.

 <li>If <var>element</var> is <a>custom</a>, then <a>enqueue a custom element callback reaction</a>
 with <var>element</var>, callback name "<code>attributeChangedCallback</code>", and an argument
 list containing <var>oldAttr</var>'s <a for=Attr>local name</a>, <var>oldAttr</var>'s
 <a for=Attr>value</a>, <var>newAttr</var>'s <a for=Attr>value</a>, and <var>oldAttr</var>'s
 <a for=Attr>namespace</a>.

 <li><p>Run the <a>attribute change steps</a> with <var>element</var>, <var>oldAttr</var>'s
 <a for=Attr>local name</a>, <var>oldAttr</var>'s <a for=Attr>value</a>, <var>newAttr</var>'s
 <a for=Attr>value</a>, and <var>oldAttr</var>'s <a for=Attr>namespace</a>.

 <li><p>Replace <var>oldAttr</var> by <var>newAttr</var> in the <var>element</var>'s
 <a for=Element>attribute list</a>.

 <li><p>Set <var>oldAttr</var>'s <a for=Attr>element</a> to null.

 <li><p>Set <var>newAttr</var>'s <a for=Attr>element</a> to <var>element</var>.
</ol>

<hr>

To <dfn export id=concept-element-attributes-get-by-name>get an attribute by name</dfn> given a
<var>qualifiedName</var> and <a for="/">element</a> <var>element</var>, run these steps:

<ol>
 <li><p>If <var>element</var> is in the <a>HTML namespace</a> and its <a>node document</a> is an
 <a>HTML document</a>, let <var>qualifiedName</var> be <a>converted to ASCII lowercase</a>.

 <li><p>Return the first <a>attribute</a> in <var>element</var>'s <a for=Element>attribute list</a>
 whose <a for=Attr>qualified name</a> is <var>qualifiedName</var>, and null otherwise.
</ol>

To
<dfn export id=concept-element-attributes-get-by-namespace>get an attribute by namespace and local name</dfn>
given a <var>namespace</var>, <var>localName</var>, and <a for="/">element</a> <var>element</var>,
run these steps:

<ol>
 <li>If <var>namespace</var> is the empty string, set it to null.

 <li>Return the <a>attribute</a> in
 <var>element</var>'s <a for=Element>attribute list</a>
 whose <a for="Attr">namespace</a> is
 <var>namespace</var> and
 <a for="Attr">local name</a> is
 <var>localName</var>, if any, and null otherwise.
</ol>

<p>To <dfn export id=concept-element-attributes-get-value>get an attribute value</dfn> given an
<a for=/>element</a> <var>element</var>, <var>localName</var>, and optionally a <var>namespace</var>
(null unless stated otherwise), run these steps:</p>

<ol>
 <li><p>Let <var>attr</var> be the result of
 <a lt="get an attribute by namespace and local name">getting an attribute</a> given
 <var>namespace</var>, <var>localName</var>, and <var>element</var>.</p></li>

 <li><p>If <var>attr</var> is null, then return the empty string.</p></li>

 <li><p>Return <var>attr</var>'s <a for=Attr>value</a>.</p></li>
</ol>

To <dfn export id=concept-element-attributes-set>set an attribute</dfn> given an
<var>attr</var> and <var>element</var>, run these steps:

<ol>
 <li><p>If <var>attr</var>'s <a for=Attr>element</a> is neither null nor <var>element</var>,
 <a>throw</a> an {{InUseAttributeError}}.

 <li><p>Let <var>oldAttr</var> be the result of
 <a lt="get an attribute by namespace and local name">getting an attribute</a> given
 <var>attr</var>'s <a for="Attr">namespace</a>, <var>attr</var>'s <a for="Attr">local name</a>, and
 <var>element</var>.

 <li><p>If <var>oldAttr</var> is <var>attr</var>, return <var>attr</var>.

 <li><p>If <var>oldAttr</var> is non-null, <a lt="replace an attribute">replace</a> it
  by <var>attr</var> in <var>element</var>.

 <li><p>Otherwise, <a lt="append an attribute">append</a> <var>attr</var> to <var>element</var>.

 <li><p>Return <var>oldAttr</var>.
</ol>

To <dfn export id=concept-element-attributes-set-value>set an attribute value</dfn> for
an <a for="/">element</a> <var>element</var>
using a <var>localName</var> and <var>value</var>, and an optional <var>prefix</var>, and
<var>namespace</var>, run these steps:

<ol>
 <li>If <var>prefix</var> is not given, set it to null.

 <li>If <var>namespace</var> is not given, set it to null.

 <li>Let <var>attribute</var> be the result of
 <a lt="get an attribute by namespace and local name">getting an attribute</a> given
 <var>namespace</var>, <var>localName</var>, and <var>element</var>.

 <li>If <var>attribute</var> is null, create an
 <a>attribute</a> whose
 <a for=Attr>namespace</a> is <var>namespace</var>,
 <a for=Attr>namespace prefix</a> is
 <var>prefix</var>, <a for=Attr>local name</a> is
 <var>localName</var>,
 and <a for=Attr>value</a> is <var>value</var>, and then
 <a lt="append an attribute">append</a> this
 <a>attribute</a> to <var>element</var>
 and terminate these steps.

 <li><a lt="change an attribute">Change</a>
 <var>attribute</var> from <var>element</var> to
 <var>value</var>.
</ol>

To
<dfn export id=concept-element-attributes-remove-by-name>remove an attribute by name</dfn>
given a <var>qualifiedName</var> and <a for="/">element</a> <var>element</var>, run these steps:

<ol>
 <li><p>Let <var>attr</var> be the result of
 <a lt="get an attribute by name">getting an attribute</a> given
 <var>qualifiedName</var> and <var>element</var>.

 <li><p>If <var>attr</var> is non-null, <a lt="remove an attribute">remove</a> it from
 <var>element</var>.

 <li><p>Return <var>attr</var>.
</ol>

To
<dfn export id=concept-element-attributes-remove-by-namespace>remove an attribute by namespace and local name</dfn>
given a <var>namespace</var>, <var>localName</var>, and
<a for="/">element</a> <var>element</var>, run these steps:

<ol>
 <li>Let <var>attr</var> be the result of
 <a lt="get an attribute by namespace and local name">getting an attribute</a> given
 <var>namespace</var>, <var>localName</var>, and <var>element</var>.

 <li>If <var>attr</var> is non-null,
 <a lt="remove an attribute">remove</a> it from
 <var>element</var>.

 <li>Return <var>attr</var>.
</ol>

<hr>

An <a for=/>element</a> can have an associated
<dfn export for=Element id=concept-id lt="ID">unique identifier (ID)</dfn>

<p class=note>Historically <a for="/">elements</a> could have multiple identifiers e.g., by using
the HTML <code>id</code> <a>attribute</a> and a DTD. This specification makes <a>ID</a> a
concept of the DOM and allows for only one per <a for="/">element</a>, given by an
<a lt="named attribute"><code>id</code> attribute</a>.

<p>Use these <a>attribute change steps</a> to update an <a for=/>element</a>'s <a>ID</a>:

<ol>
 <li><p>If <var>localName</var> is <code>id</code>, <var>namespace</var> is null, and
 <var>value</var> is null or the empty string, then unset <var>element</var>'s <a>ID</a>.

 <li><p>Otherwise, if <var>localName</var> is <code>id</code>, <var>namespace</var> is null, then
 set <var>element</var>'s <a>ID</a> to <var>value</var>.
</ol>

<p class="note no-backref">While this specification defines requirements for <code>class</code>,
<code>id</code>, and <code>slot</code> <a>attributes</a> on any <a for="/">element</a>, it makes no
claims as to whether using them is conforming or not.

<hr>

A <a>node</a>'s
<a>parent</a> of type
{{Element}} is known as a <dfn export>parent element</dfn>. If the
<a>node</a> has a
<a>parent</a> of a different type, its
<a>parent element</a> is null.

<hr>

<dl class=domintro>
 <dt><var>namespace</var> = <var>element</var> . {{Element/namespaceURI}}
 <dd>Returns the <a for=Element>namespace</a>.

 <dt><var>prefix</var> = <var>element</var> . {{Element/prefix}}
 <dd>Returns the
 <a for=Element>namespace prefix</a>.

 <dt><var>localName</var> = <var>element</var> . {{Element/localName}}
 <dd>Returns the
 <a for=Element>local name</a>.

 <dt><var>qualifiedName</var> = <var>element</var> . {{Element/tagName}}
 <dd>Returns the <a for=Element>qualified name</a>. (The return value is uppercased in an
 <a>HTML document</a>.)
</dl>

<p>The <dfn attribute for="Element"><code>namespaceURI</code></dfn> attribute's getter must return
the <a>context object</a>'s <a for=Element>namespace</a>.

<p>The <dfn attribute for="Element"><code>prefix</code></dfn> attribute's getter must return the
<a>context object</a>'s <a for=Element>namespace prefix</a>.

<p>The <dfn attribute for="Element"><code>localName</code></dfn> attribute's getter must return the
<a>context object</a>'s <a for=Element>local name</a>.

<p>The <dfn attribute for="Element"><code>tagName</code></dfn> attribute's getter must run these
steps:

<ol>
 <li><p>Let <var>qualifiedName</var> be <a>context object</a>'s <a for=Element>qualified name</a>.

 <li><p>If the <a>context object</a> is in the <a>HTML namespace</a> and its <a>node document</a> is
 an <a>HTML document</a>, let <var>qualifiedName</var> be <a>converted to ASCII uppercase</a>.

 <li>Return <var>qualifiedName</var>.
</ol>

<hr>

<p>IDL attributes that are defined to <dfn export for=Attr id=concept-reflect>reflect</dfn> a
content <a>attribute</a> of a given <var>name</var>, must have a getter and setter that follow these
steps:</p>

<dl>
 <dt>getter
 <dd><p>Return the result of running <a>get an attribute value</a> given <a>context object</a> and
 <var>name</var>.</p></dd>

 <dt>setter
 <dd><p><a>Set an attribute value</a> for the <a>context object</a> using <var>name</var> and the
 given value.</p></dd>
</dl>

<p>The <dfn attribute for="Element"><code>id</code></dfn> attribute must <a>reflect</a> the
"<code>id</code>" content attribute.

<p>The <dfn attribute for="Element"><code>className</code></dfn> attribute must <a>reflect</a> the
"<code>class</code>" content attribute.

<p>The <dfn attribute for="Element"><code>classList</code></dfn> attribute's getter must return a
{{DOMTokenList}} object whose associated <a for=/>element</a> is the <a>context object</a> and whose
associated <a>attribute</a>'s <a for=Attr>local name</a> is <code>class</code>. The <a>tokens</a> of
this particular {{DOMTokenList}} object are also known as the <a for="/">element</a>'s
<dfn export for=Element id=concept-class lt="class">classes</dfn>.

<p>The <dfn attribute for=Element><code>slot</code></dfn> attribute must <a>reflect</a> the
"<code>slot</code>" content attribute.

<p class="note"><code>id</code>, <code>class</code>, and <code>slot</code> are effectively
superglobal attributes as they can appear on any element, regardless of that element's
namespace.</p>

<hr>

<!-- all members in this subsection are affected by AttrExodus -->

The <dfn method for="Element">hasAttributes()</dfn> method,
when invoked, must return false if <a>context object</a>'s
<a for=Element>attribute list</a> is empty, and true
otherwise.

The <dfn attribute for="Element">attributes</dfn>
attribute must return the associated {{NamedNodeMap}}.

The <dfn method for=Element><code>getAttributeNames()</code></dfn> method, when invoked, must return
the <a for=Attr>qualified names</a> of the <a>attributes</a> in the <a>context object</a>'s
<a for=Element>attribute list</a>, in order, and the empty sequence otherwise.

<p class=note>These are not guaranteed to be unique.<!-- A theoretical getAttributeNamesNS() could
return an array of unique two-value-arrays. -->

The <dfn method for="Element"><code>getAttribute(<var>qualifiedName</var>)</code></dfn> method, when
invoked, must run these steps:

<ol>
 <li><p>Let <var>attr</var> be the result of
 <a lt="get an attribute by name">getting an attribute</a> given <var>qualifiedName</var> and the
 <a>context object</a>.

 <li><p>If <var>attr</var> is null, return null.

 <li><p>Return <var>attr</var>'s <a for=Attr>value</a>.
</ol>

<p>The
<dfn method for="Element"><code>getAttributeNS(<var>namespace</var>, <var>localName</var>)</code></dfn>
method, when invoked, must these steps:

<ol>
 <li><p>Let <var>attr</var> be the result of
 <a lt="get an attribute by namespace and local name">getting an attribute</a> given
 <var>namespace</var>, <var>localName</var>, and the <a>context object</a>.

 <li><p>If <var>attr</var> is null, return null.

 <li><p>Return <var>attr</var>'s <a for=Attr>value</a>.
</ol>

The
<dfn method for="Element"><code>setAttribute(<var>qualifiedName</var>, <var>value</var>)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li><p>If <var>qualifiedName</var> does not match the <code><a type>Name</a></code> production in
 XML, then <a>throw</a> an {{InvalidCharacterError}}.

 <li><p>If the <a>context object</a> is in the <a>HTML namespace</a> and its <a>node document</a> is
 an <a>HTML document</a>, let <var>qualifiedName</var> be <a>converted to ASCII lowercase</a>.

 <li><p>Let <var>attribute</var> be the first <a>attribute</a> in <a>context object</a>'s
 <a for=Element>attribute list</a> whose <a for=Attr>qualified name</a> is <var>qualifiedName</var>,
 and null otherwise.
 <!-- This is step 2 of "get an attribute by name", modified as appropriate -->

 <li><p>If <var>attribute</var> is null, create an <a>attribute</a> whose
 <a for="Attr">local name</a> is <var>qualifiedName</var> and <a for=Attr>value</a> is
 <var>value</var>, <a lt="append an attribute">append</a> this <a>attribute</a> to the
 <a>context object</a>'s <a for=Element>attribute list</a>, and then terminate these steps.

 <li><p><a lt="change an attribute">Change</a> <var>attribute</var> from <a>context object</a> to
 <var>value</var>.
</ol>

The
<dfn method for="Element"><code>setAttributeNS(<var>namespace</var>, <var>qualifiedName</var>, <var>value</var>)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li><p>Let <var>namespace</var>, <var>prefix</var>, and <var>localName</var> be the result of
 passing <var>namespace</var> and <var>qualifiedName</var> to <a>validate and extract</a>. Rethrow
 any exceptions.

 <li><p><a>Set an attribute value</a> for the <a>context object</a> using <var>localName</var>,
 <var>value</var>, and also <var>prefix</var> and <var>namespace</var>.
</ol>

The
<dfn method for="Element"><code>removeAttribute(<var>qualifiedName</var>)</code></dfn>
method, when invoked, must <a lt="remove an attribute by name">remove an attribute</a> given
<var>qualifiedName</var> and the <a>context object</a>, and then return undefined.

The
<dfn method for="Element">removeAttributeNS(<var>namespace</var>, <var>localName</var>)</dfn>
method must
<a lt="remove an attribute by namespace and local name">remove an attribute</a>
given <var>namespace</var>, <var>localName</var>, and the
<a>context object</a>, and then return undefined.

<p>The <dfn method for="Element"><code>hasAttribute(<var>qualifiedName</var>)</code></dfn> method,
when invoked, must run these steps:

<ol>
 <li><p>If the <a>context object</a> is in the <a>HTML namespace</a> and its <a>node document</a> is
 an <a>HTML document</a>, let <var>qualifiedName</var> be <a>converted to ASCII lowercase</a>.

 <li><p>Return true if the <a>context object</a> <a lt="has an attribute">has</a> an
 <a>attribute</a> whose <a for=Attr>qualified name</a> is <var>qualifiedName</var>, and false
 otherwise.
</ol>

The
<dfn method for="Element"><code>hasAttributeNS(<var>namespace</var>, <var>localName</var>)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li>If <var>namespace</var> is the empty string, set it to null.

 <li>Return true if the <a>context object</a>
 <a lt="has an attribute">has</a> an
 <a>attribute</a> whose
 <a for="Attr">namespace</a> is <var>namespace</var>
 and <a for="Attr">local name</a> is
 <var>localName</var>, and false otherwise.
</ol>

<hr>

The
<dfn method for="Element"><code>getAttributeNode(<var>qualifiedName</var>)</code></dfn>
method, when invoked, must return the result of
<a lt="get an attribute by name">getting an attribute</a> given
<var>qualifiedName</var> and the <a>context object</a>.

The
<dfn method for="Element"><code>getAttributeNodeNS(<var>namespace</var>, <var>localName</var>)</code></dfn>
method, when invoked, must return the result of
<a lt="get an attribute by namespace and local name">getting an attribute</a> given
<var>namespace</var>, <var>localName</var>, and the <a>context object</a>.

The <dfn method for="Element"><code>setAttributeNode(<var>attr</var>)</code></dfn> and
<dfn method for="Element"><code>setAttributeNodeNS(<var>attr</var>)</code></dfn> methods, when
invoked, must return the result of <a lt="set an attribute">setting an attribute</a> given
<var>attr</var> and the <a>context object</a>. Rethrow any exceptions.

The
<dfn method for="Element"><code>removeAttributeNode(<var>attr</var>)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li><p>If <var>attr</var> is not in <a>context object</a>'s <a for=Element>attribute list</a>, then
 <a>throw</a> a {{NotFoundError}}.

 <li><p><a lt="remove an attribute">Remove</a> <var>attr</var> from <a>context object</a>.

 <li><p>Return <var>attr</var>.
</ol>

<hr>

<dl class=domintro>
 <dt><code>var shadow = <var>element</var> . {{attachShadow(init)}}</code>
 <dd><p>Creates a <a for=/>shadow root</a> for <var>element</var> and returns it.

 <dt><code>var shadow = <var>element</var> . {{shadowRoot}}</code>
 <dd><p>Returns <var>element</var>'s <a for=Element>shadow root</a>, if any, and if
 <a for=/>shadow root</a>'s <a for=ShadowRoot>mode</a> is "<code>open</code>", and null otherwise.
</dl>

<p>The <dfn method for=Element><code>attachShadow(<var>init</var>)</code></dfn> method, when
invoked, must run these steps:

<ol>
 <li><p>If <a>context object</a>'s <a for=Element>namespace</a> is <em>not</em> the
 <a>HTML namespace</a>, then <a>throw</a> a {{NotSupportedError}}.

 <li><p>If <a>context object</a>'s <a for=Element>local name</a> is <em>not</em> a
 <a>valid custom element name</a>,
 "<code>article</code>",
 "<code>aside</code>",
 "<code>blockquote</code>",
 "<code>body</code>",
 "<code>div</code>",
 "<code>footer</code>",
 "<code>h1</code>",
 "<code>h2</code>",
 "<code>h3</code>",
 "<code>h4</code>",
 "<code>h5</code>",
 "<code>h6</code>",
 "<code>header</code>",
 "<code>nav</code>",
 "<code>p</code>",
 "<code>section</code>", or
 "<code>span</code>", then <a>throw</a> a {{NotSupportedError}}.

 <li><p>If <a>context object</a> is a <a for=Element>shadow host</a>, then <a>throw</a> an
 {{InvalidStateError}}.

 <li><p>Let <var>shadow</var> be a new <a for=/>shadow root</a> whose <a>node document</a> is
 <a>context object</a>'s <a>node document</a>, <a for=DocumentFragment>host</a> is
 <a>context object</a>, and <a for=ShadowRoot>mode</a> is <var>init</var>'s {{ShadowRootInit/mode}}.

 <li><p>Set <a>context object</a>'s <a for=Element>shadow root</a> to <var>shadow</var>.

 <li><p>Return <var>shadow</var>.
</ol>

<p>The <dfn attribute for=Element><code>shadowRoot</code></dfn> attribute's getter must run these
steps:

<ol>
 <li><p>Let <var>shadow</var> be <a>context object</a>'s <a for=Element>shadow root</a>.

 <li><p>If <var>shadow</var> is null or its <a for=ShadowRoot>mode</a> is "<code>closed</code>",
 then return null.</p></li>

 <li><p>Return <var>shadow</var>.
</ol>

<hr>

<dl class=domintro>
 <dt><code><var>element</var> . {{closest(selectors)}}</code>
 <dd>Returns the first (starting at <var>element</var>)
 <a>inclusive ancestor</a> that matches
 <var>selectors</var>, and null otherwise.

 <dt><code><var>element</var> . {{matches(selectors)}}</code>
 <dd>Returns true if matching <var>selectors</var> against
 <var>element</var>'s <a for=tree>root</a> yields
 <var>element</var>, and false otherwise.
</dl>

The <dfn method for=Element><code>closest(<var>selectors</var>)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li>Let <var>s</var> be the result of
 <a>parse a selector</a> from <var>selectors</var>.
 [[!SELECTORS4]]

 <li>If <var>s</var> is failure, <a>throw</a> a
 {{SyntaxError}}.

 <li>Let <var>elements</var> be <a>context object</a>'s
 <a>inclusive ancestors</a> that are
 <a for="/">elements</a>, in reverse
 <a>tree order</a>.

 <li>For each <var>element</var> in <var>elements</var>, if
 <a>match a selector against an element</a>, using
 <var>s</var>, <var>element</var>, and
 <a>:scope element</a> <a>context object</a>,
 returns success, return <var>element</var>. [[!SELECTORS4]]

 <li>Return null.
</ol>

The <dfn method for=Element><code>matches(<var>selectors</var>)</code></dfn> and
<dfn method for=Element><code>webkitMatchesSelector(<var>selectors</var>)</code></dfn> methods, when
invoked, must run these steps:

<ol>
 <li>Let <var>s</var> be the result of
 <a>parse a selector</a> from <var>selectors</var>.
 [[!SELECTORS4]]

 <li>If <var>s</var> is failure, <a>throw</a> a
 {{SyntaxError}}.

 <li>Return true if the result of
 <a>match a selector against an element</a>, using
 <var>s</var>, <var>element</var>, and
 <a>:scope element</a> <a>context object</a>,
 returns success, and false otherwise. [[!SELECTORS4]]
</ol>

<hr>

<p>The <dfn method for="Element"><code>getElementsByTagName(<var>qualifiedName</var>)</code></dfn>
method, when invoked, must return the
<a>list of elements with qualified name <var>qualifiedName</var></a> for the <a>context object</a>.

The
<dfn method for="Element">getElementsByTagNameNS(<var>namespace</var>, <var>localName</var>)</dfn>
method must return the
<a>list of elements with namespace <var>namespace</var> and local name <var>localName</var></a>
for the <a>context object</a>.

The
<dfn method for="Element">getElementsByClassName(<var title>classNames</var>)</dfn>
method must return the
<a>list of elements with class names <var>classNames</var></a>
for the <a>context object</a>.

<hr>

<p>To <dfn>insert adjacent</dfn>, given an <a for=/>element</a> <var>element</var>, string
<var>where</var>, and a <a>node</a> <var>node</var>, run the steps associated with the first
<a>ASCII case-insensitive</a> match for <var>where</var>:

<dl class=switch>
 <dt>"<code>beforebegin</code>"
 <dd>
  <p>If <var>element</var>'s <a>parent</a> is null, return null.

  <p>Return the result of <a for=Node>pre-inserting</a> <var>node</var> into <var>element</var>'s
  <a>parent</a> before <var>element</var>. Rethrow any exceptions.

 <dt>"<code>afterbegin</code>"
 <dd><p>Return the result of <a for=Node>pre-inserting</a> <var>node</var> into <var>element</var>
 before <var>element</var>'s <a for=tree>first child</a>. Rethrow any exceptions.

 <dt>"<code>beforeend</code>"
 <dd><p>Return the result of <a for=Node>pre-inserting</a> <var>node</var> into <var>element</var>
 before null. Rethrow any exceptions.

 <dt>"<code>afterend</code>"
 <dd>
  <p>If <var>element</var>'s <a>parent</a> is null, return null.

  <p>Return the result of <a for=Node>pre-inserting</a> <var>node</var> into <var>element</var>'s
  <a>parent</a> before <var>element</var>'s <a for=tree>next sibling</a>. Rethrow any exceptions.

 <dt>Otherwise</dt>
 <dd><p><a>Throw</a> a {{SyntaxError}}.
</dl>

<p>The
<dfn method for=Element><code>insertAdjacentElement(<var>where</var>, <var>element</var>)</code></dfn>
method, when invoked, must return the result of running <a>insert adjacent</a>, given
<a>context object</a>, <var>where</var>, and <var>element</var>. Rethrow any exceptions.

<p>The
<dfn method for=Element><code>insertAdjacentText(<var>where</var>, <var>data</var>)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li><p>Let <var>text</var> be a new {{Text}} <a>node</a>  whose <a>data</a> is <var>data</var> and
 <a>node document</a> is <a>context object</a>'s <a>node document</a>.

 <li><p>Run <a>insert adjacent</a>, given <a>context object</a>, <var>where</var>, and
 <var>text</var>. Rethrow any exceptions.
</ol>

<p class="note">This method returns nothing because it existed before we had a chance to design it.


<h4 id='interface-namednodemap'>Interface {{NamedNodeMap}}</h4>

<pre class=idl>
[Exposed=Window, LegacyUnenumerableNamedProperties]
interface NamedNodeMap {
  readonly attribute unsigned long length;
  getter Attr? item(unsigned long index);
  getter Attr? getNamedItem(DOMString qualifiedName);
  Attr? getNamedItemNS(DOMString? namespace, DOMString localName);
  [CEReactions] Attr? setNamedItem(Attr attr);
  [CEReactions] Attr? setNamedItemNS(Attr attr);
  [CEReactions] Attr removeNamedItem(DOMString qualifiedName);
  [CEReactions] Attr removeNamedItemNS(DOMString? namespace, DOMString localName);
};
</pre>

A {{NamedNodeMap}} has an associated
<dfn export id=concept-namednodemap-element for=NamedNodeMap>element</dfn> (an
<a for="/">element</a>).

A {{NamedNodeMap}} object's
<dfn export id=concept-namednodemap-attribute for=NamedNodeMap>attribute list</dfn> is its
<a for=NamedNodeMap>element</a>'s
<a for=Element>attribute list</a>.

<hr>

A {{NamedNodeMap}} object's
<a>supported property indices</a> are the numbers in the
range zero to the number of <a>attributes</a> in its
<a for=NamedNodeMap>attribute list</a> map minus one, unless the
<a for=NamedNodeMap>attribute list</a> is empty, in which case
there are no <a>supported property indices</a>.

<p>The <dfn attribute for="NamedNodeMap"><code>length</code></dfn> attribute's getter must return
the number of <a>attributes</a> in the <a for=NamedNodeMap>attribute list</a>.

<p>The <dfn method for="NamedNodeMap"><code>item(<var>index</var>)</code></dfn> method, when
invoked, must run these steps:

<ol>
 <li><p>If <var>index</var> is equal to or greater than the number of <a>attributes</a> in the
 <a for=NamedNodeMap>attribute list</a>, return null.

 <li><p>Otherwise, return the <var>index</var>th <a>attribute</a> in the
 <a for=NamedNodeMap>attribute list</a>.
</ol>

<p>A {{NamedNodeMap}} object's <a>supported property names</a> are the return value of running these
steps:

<ol>
 <li><p>Let <var>names</var> be the <a for=Attr>qualified names</a> of the <a>attributes</a> in this
 {{NamedNodeMap}} object's <a for=NamedNodeMap>attribute list</a>, with duplicates omitted, in
 order.
 <!-- Even though not all names that map to an attribute are listed, due to lowercasing, ECMAScript
      invariants are not violated. https://github.com/whatwg/dom/issues/141#issuecomment-168753410
      has details. -->

 <li>
  <p>If this {{NamedNodeMap}} object's <a for=NamedNodeMap>element</a> is in the
  <a>HTML namespace</a> and its <a>node document</a> is an <a>HTML document</a>, then for each
  <var>name</var> in <var>names</var>, run these substeps:

  <ol>
   <li><p>Let <var>lowercaseName</var> be <var>name</var>, <a>converted to ASCII lowercase</a>.

   <li><p>If <var>lowercaseName</var> is not equal to <var>name</var>, remove <var>name</var> from
   <var>names</var>.
  </ol>

 <li><p>Return <var>names</var>.
</ol>

<p>The <dfn method for="NamedNodeMap"><code>getNamedItem(<var>qualifiedName</var>)</code></dfn>
method, when invoked, must return the result of
<a lt="get an attribute by name">getting an attribute</a> given <var>qualifiedName</var> and
<a for=NamedNodeMap>element</a>.

<p>The
<dfn method for="NamedNodeMap"><code>getNamedItemNS(<var>namespace</var>, <var>localName</var>)</code></dfn>
method, when invoked, must return the result of
<a lt="get an attribute by namespace and local name">getting an attribute</a> given
<var>namespace</var>, <var>localName</var>, and
<a for=NamedNodeMap>element</a>.

<p>The <dfn method for="NamedNodeMap"><code>setNamedItem(<var>attr</var>)</code></dfn> and
<dfn method for="NamedNodeMap"><code>setNamedItemNS(<var>attr</var>)</code></dfn>
methods, when invoked, must return the result of <a lt="set an attribute">setting an attribute</a> given <var>attr</var> and <a for=NamedNodeMap>element</a>. Rethrow any exceptions.

<p>The <dfn method for="NamedNodeMap"><code>removeNamedItem(<var>qualifiedName</var>)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li><p>Let <var>attr</var> be the result of
 <a lt="remove an attribute by name">removing an attribute</a> given
 <var>qualifiedName</var> and <a for=NamedNodeMap>element</a>.

 <li><p>If <var>attr</var> is null, then <a>throw</a> a {{NotFoundError}}.

 <li><p>Return <var>attr</var>.
</ol>

<p>The
<dfn method for="NamedNodeMap"><code>removeNamedItemNS(<var>namespace</var>, <var>localName</var>)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li><p>Let <var>attr</var> be the result of
 <a lt="remove an attribute by namespace and local name">removing an attribute</a> given
 <var>namespace</var>, <var>localName</var>, and <a for=NamedNodeMap>element</a>.

 <li><p>If <var>attr</var> is null, then <a>throw</a> a {{NotFoundError}}.

 <li><p>Return <var>attr</var>.
</ol>


<h4 id='interface-attr'>Interface {{Attr}}</h4>

<pre class=idl>
[Exposed=Window]
interface Attr {
  readonly attribute DOMString? namespaceURI;
  readonly attribute DOMString? prefix;
  readonly attribute DOMString localName;
  readonly attribute DOMString name;
  readonly attribute DOMString nodeName; // historical alias of .name
  [CEReactions] attribute DOMString value;
  [CEReactions, TreatNullAs=EmptyString] attribute DOMString nodeValue; // historical alias of .value
  [CEReactions, TreatNullAs=EmptyString] attribute DOMString textContent; // historical alias of .value

  readonly attribute Element? ownerElement;

  readonly attribute boolean specified; // useless; always returns true
};</pre>


{{Attr}} objects are simply known as
<dfn export id=concept-attribute lt="attribute">attributes</dfn>. They are sometimes referred
to as <em>content attributes</em> to avoid confusion with IDL attributes.

<a>Attributes</a> have a
<dfn export id=concept-attribute-namespace for=Attr>namespace</dfn> (null or a non-empty string),
<dfn export id=concept-attribute-namespace-prefix for=Attr>namespace prefix</dfn> (null or a non-empty string),
<dfn export id=concept-attribute-local-name for=Attr>local name</dfn> (a non-empty string),
<dfn export id=concept-attribute-value for=Attr>value</dfn> (a string), and
<dfn export id=concept-attribute-element for=Attr>element</dfn> (null or an
<a for="/">element</a>).

<p class="note no-backref">If designed today they would just have a name and value. ☹

<p>An <a>attribute</a>'s
<dfn export id=concept-attribute-qualified-name for=Attr>qualified name</dfn> is its
<a for=Attr>local name</a> if its <a for=Attr>namespace prefix</a> is null, and its
<a for=Attr>namespace prefix</a>, followed by "<code>:</code>", followed by its
<a for=Attr>local name</a>, otherwise.

<p class=note>User agents could have this as an internal slot as an optimization, but are not
required to do so. The standard has this concept for readability.

When an <a>attribute</a> is created, its
<a for=Attr>local name</a> is given. Unless explicitly
given when an <a>attribute</a> is created, its
<a for=Attr>namespace</a>,
<a for=Attr>namespace prefix</a>, and
<a for=Attr>element</a> are set to null, and its
<a for=Attr>value</a> is set to the empty string.

An
<dfn export id=concept-named-attribute lt="named attribute"><code><var>A</var></code> attribute</dfn>
is an <a>attribute</a> whose
<a for=Attr>local name</a> is
<code><var>A</var></code> and whose
<a for=Attr>namespace</a> and
<a for=Attr>namespace prefix</a> are
null.

<hr>

<p>The <dfn attribute for="Attr"><code>namespaceURI</code></dfn> attribute's getter must return the
<a for=Attr>namespace</a>.

<p>The <dfn attribute for="Attr"><code>prefix</code></dfn> attribute's getter must return the
<a for=Attr>namespace prefix</a>.

<p>The <dfn attribute for="Attr"><code>localName</code></dfn> attribute's getter must return the
<a for=Attr>local name</a>.

<p>The <dfn attribute for="Attr"><code>name</code></dfn> attribute's getter, and
<dfn attribute for="Attr"><code>nodeName</code></dfn> attribute's getter, must return the
<a for=Attr>qualified name</a>.

<p>The <dfn attribute for="Attr"><code>value</code></dfn> attribute's getter,
<dfn attribute for="Attr"><code>nodeValue</code></dfn> attribute's getter, and
<dfn attribute for="Attr"><code>textContent</code></dfn> attribute's getter, must return the
<a for=Attr>value</a>.

<p>The {{Attr/value}} attribute's setter, {{Attr/nodeValue}} attribute's setter, and
{{Attr/textContent}} attribute's setter, must run these steps:

<ol>
 <li>If <a>context object</a>'s
 <a for=Attr>element</a> is null, set
 <a>context object</a>'s <a for=Attr>value</a> to the
 given value.

 <li>Otherwise, <a lt="change an attribute">change</a> the
 <a>context object</a> from <a>context object</a>'s
 <a for=Attr>element</a> to the given value.
</ol>

<p class="note no-backref">Unlike <a>node</a>'s {{Node/textContent}}, no special null
handling is required.

<hr>

<p>The <dfn attribute for="Attr"><code>ownerElement</code></dfn> attribute's getter must return
<a>context object</a>'s <a for=Attr>element</a>.

<hr>

<p>The <dfn attribute for="Attr"><code>specified</code></dfn> attribute's getter must return true.


<h3 id='interface-characterdata'>Interface {{CharacterData}}</h3>

<pre class=idl>
[Exposed=Window]
interface CharacterData : Node {
  [TreatNullAs=EmptyString] attribute DOMString data;
  readonly attribute unsigned long length;
  DOMString substringData(unsigned long offset, unsigned long count);
  void appendData(DOMString data);
  void insertData(unsigned long offset, DOMString data);
  void deleteData(unsigned long offset, unsigned long count);
  void replaceData(unsigned long offset, unsigned long count, DOMString data);
};
</pre>

<p class="note no-backref">{{CharacterData}} is an abstract interface and does not exist as
<a>node</a>. It is used by {{Text}}, {{ProcessingInstruction}}, and {{Comment}} <a>nodes</a>.

Each <a>node</a> inheriting from the
{{CharacterData}} interface has an associated mutable string
called <dfn export id=concept-cd-data for="CharacterData, Text, Comment, ProcessingInstruction">data</dfn>.

To <dfn export for="CharacterData, Text, Comment, ProcessingInstruction" id=concept-cd-replace>replace data</dfn> of node
<var>node</var> with offset <var>offset</var>, count
<var>count</var>, and data <var>data</var>, run these steps:

<ol>
 <li>Let <var>length</var> be <var>node</var>'s
 {{CharacterData/length}} attribute value.

 <li>If <var>offset</var> is greater than <var>length</var>, then <a>throw</a> an
 {{IndexSizeError}}.

 <li>If <var>offset</var> plus <var>count</var> is greater
 than <var>length</var> let <var>count</var> be
 <var>length</var> minus <var>offset</var>.

 <li><a>Queue a mutation record</a> of "<code>characterData</code>"
 for <var>node</var> with oldValue <var>node</var>'s
 <a>data</a>.

 <li>Insert <var>data</var> into <var>node</var>'s
 <a>data</a> after <var>offset</var>
 <a>code units</a>.

 <li>Let <var>delete offset</var> be <var>offset</var> plus
 the number of
 <a>code units</a> in
 <var>data</var>.

 <li>Starting from <var>delete offset</var>
 <a>code units</a>, remove
 <var>count</var>
 <a>code units</a> from
 <var>node</var>'s <a>data</a>.

 <!-- ranges -->
 <li>For each <a>range</a> whose
 <a>start node</a> is
 <var>node</var> and
 <a>start offset</a> is greater than
 <var>offset</var> but less than or equal to <var>offset</var>
 plus <var>count</var>, set its
 <a>start offset</a> to
 <var>offset</var>.

 <li>For each <a>range</a> whose
 <a>end node</a> is
 <var>node</var> and
 <a>end offset</a> is greater than
 <var>offset</var> but less than or equal to <var>offset</var>
 plus <var>count</var>, set its
 <a>end offset</a> to
 <var>offset</var>.

 <li>For each <a>range</a> whose
 <a>start node</a> is
 <var>node</var> and
 <a>start offset</a> is greater than
 <var>offset</var> plus <var>count</var>, increase its
 <a>start offset</a> by the number of
 <a>code units</a> in
 <var>data</var>, then decrease it by <var>count</var>.

 <li>For each <a>range</a> whose
 <a>end node</a> is
 <var>node</var> and
 <a>end offset</a> is greater than
 <var>offset</var> plus <var>count</var>, increase its
 <a>end offset</a> by the number of
 <a>code units</a> in
 <var>data</var>, then decrease it by <var>count</var>.
</ol>
<!-- delete happens after insert for better cursor positioning with editing
https://www.w3.org/Bugs/Public/show_bug.cgi?id=13153 -->

<!-- If you set a node's data to a new value (e.g., using the data
attribute):

IE 9: Acts like the node was deleted and recreated, moves the boundary
points up to the parent
Firefox 4: Resets the offset to 0, always
Chrome 11 dev: Resets the offset to 0, except it does nothing if the new
data is the same as the old data
Opera 11: Sets a start offset to 0 and an end offset to the end of the
data, always

The spec originally followed WebKit, since it seemed to make the most sense.
Opera's approach of setting end offsets to the length of the new data
arguably makes more sense, but that's debatable, and it's greatly
outnumbered. However, after some feedback by bzbarsky that checking for
equality is expensive, I removed the special case and matched Firefox:

https://www.w3.org/Bugs/Public/show_bug.cgi?id=13250

Authors who want WebKit-like behavior can always use replaceData() instead.

XXX replaceData is the same as setting data these days -->


To <dfn export for="CharacterData, Text, Comment, ProcessingInstruction" id=concept-cd-substring>substring data</dfn> with node
<var>node</var>, offset <var>offset</var>, and count
<var>count</var>, run these steps:

<ol>
 <li>Let <var>length</var> be <var>node</var>'s
 {{CharacterData/length}} attribute value.

 <li>If <var>offset</var> is greater than <var>length</var>, then <a>throw</a> an
 {{IndexSizeError}}.

 <li>If <var>offset</var> plus <var>count</var> is
 greater than <var>length</var>, return a string whose value is the
 <a>code units</a> from the
 <var>offset</var><sup>th</sup>
 <a>code unit</a> to the end of
 <var>node</var>'s <a>data</a>, and then
 terminate these steps.

 <li>Return a string whose value is the
 <a>code units</a> from the
 <var>offset</var><sup>th</sup>
 <a>code unit</a> to the
 <var>offset</var>+<var>count</var><sup>th</sup>
 <a>code unit</a> in <var>node</var>'s
 <a>data</a>.
</ol>

<p>The <dfn attribute for="CharacterData"><code>data</code></dfn> attribute's getter must return
<a>context object</a>'s <a>data</a>. Its setter must <a>replace data</a> with node
<a>context object</a> offset 0, count {{CharacterData/length}} attribute value, and data new value.

<p>The <dfn attribute for="CharacterData"><code>length</code></dfn> attribute's getter must return
the number of <a>code units</a> in <a>context object</a>'s <a>data</a>.

<p>The
<dfn method for="CharacterData"><code>substringData(<var>offset</var>, <var>count</var>)</code></dfn>
method, when invoked, must return the result of running <a>substring data</a> with node
<a>context object</a>, offset <var>offset</var>, and count <var>count</var>.

<p>The <dfn method for="CharacterData"><code>appendData(<var>data</var>)</code></dfn> method, when
invoked, must <a>replace data</a> with node <a>context object</a>, offset {{CharacterData/length}}
attribute value, count 0, and data <var>data</var>.

<p>The
<dfn method for="CharacterData"><code>insertData(<var>offset</var>, <var>data</var>)</code></dfn>
method, when invoked, must <a>replace data</a> with node <a>context object</a>, offset
<var>offset</var>, count 0, and data <var>data</var>.

<p>The
<dfn method for="CharacterData"><code>deleteData(<var>offset</var>, <var>count</var>)</code></dfn>
method, when invoked, must <a>replace data</a> with node <a>context object</a>, offset
<var>offset</var>, count <var>count</var>, and data the empty string.

<p>The
<dfn method for="CharacterData"><code>replaceData(<var>offset</var>, <var>count</var>, <var>data</var>)</code></dfn>
method, when invoked, must <a>replace data</a> with node <a>context object</a>, offset
<var>offset</var>, count <var>count</var>, and data <var>data</var>.


<h3 id='interface-text'>Interface {{Text}}</h3>

<pre class=idl>
[Constructor(optional DOMString data = ""),
 Exposed=Window]
interface Text : CharacterData {
  [NewObject] Text splitText(unsigned long offset);
  readonly attribute DOMString wholeText;
};</pre>


<dl class=domintro>
 <dt><code><var>text</var> = new <a constructor lt=Text()>Text([<var>data</var> = ""])</a></code>
 <dd>Returns a new {{Text}} <a>node</a> whose
 <a>data</a> is <var>data</var>.

 <dt><code><var>text</var> . {{Text/splitText(offset)}}</code>
 <dd>Splits <a>data</a> at the given
 <var>offset</var> and returns the remainder as {{Text}}
 <a>node</a>.

 <dt><code><var>text</var> . {{Text/wholeText}}</code>
 <dd>Returns the combined <a>data</a> of all direct
 {{Text}} <a>node</a>
 <a>siblings</a>.
</dl>

The <dfn constructor for=Text>Text(<var>data</var>)</dfn> constructor
must return a new {{Text}} <a>node</a> whose
<a>data</a> is <var>data</var> and
<a>node document</a> is the global object's associated
<a>document</a>.

To <dfn export id=concept-text-split lt="split a Text node">split</dfn> a {{Text}}
<a>node</a> <var>node</var> with offset
<var>offset</var>, run these steps:

<ol>
 <li>Let <var>length</var> be <var>node</var>'s
 {{CharacterData/length}} attribute value.

 <li>If <var>offset</var> is greater than <var>length</var>, then <a>throw</a> an
 {{IndexSizeError}}.

 <li>Let <var>count</var> be <var>length</var> minus
 <var>offset</var>.

 <li>Let <var>new data</var> be the result of
 <a lt="substring data">substringing data</a> with node
 <var>node</var>, offset <var>offset</var>, and count
 <var>count</var>.

 <li>Let <var>new node</var> be a new {{Text}}
 <a>node</a>, with the same
 <a>node document</a> as
 <var>node</var>. Set <var>new node</var>'s
 <a>data</a> to <var>new data</var>.

 <li>Let <var>parent</var> be <var>node</var>'s
 <a>parent</a>.

 <li>
  If <var>parent</var> is not null, run these substeps:

  <ol>
   <li><a for=Node>Insert</a>
   <var>new node</var> into <var>parent</var> before
   <var>node</var>'s
   <a>next sibling</a>.
   <!-- Do this before we replace data, so that the data replacement won't
   mutate ranges prematurely:
   https://www.w3.org/Bugs/Public/show_bug.cgi?id=15325 -->

   <li>For each <a>range</a> whose
   <a>start node</a> is
   <var>node</var> and
   <a>start offset</a> is greater than
   <var>offset</var>, set its
   <a>start node</a> to
   <var>new node</var> and decrease its
   <a>start offset</a> by
   <var>offset</var>.

   <li>For each <a>range</a> whose
   <a>end node</a> is
   <var>node</var> and
   <a>end offset</a> is greater than
   <var>offset</var>, set its
   <a>end node</a> to
   <var>new node</var> and decrease its
   <a>end offset</a> by
   <var>offset</var>.

   <!-- This shit is complicated:
        https://www.w3.org/Bugs/Public/show_bug.cgi?id=19968 -->
   <li>For each <a>range</a> whose
   <a>start node</a> is
   <var>parent</var> and
   <a>start offset</a> is equal to
   the <a>index</a> of
   <var>node</var> + 1, increase its
   <a>start offset</a> by one.

   <li>For each <a>range</a> whose
   <a>end node</a> is
   <var>parent</var> and
   <a>end offset</a> is equal to
   the <a>index</a> of
   <var>node</var> + 1, increase its
   <a>end offset</a> by one.
  </ol>

 <li><a>Replace data</a> with node
 <var>node</var>, offset <var>offset</var>, count
 <var>count</var>, and data the empty string.

 <li>
  If <var>parent</var> is null, run these substeps:

  <ol>
   <li>For each <a>range</a> whose
   <a>start node</a> is
   <var>node</var> and
   <a>start offset</a> is greater
   than <var>offset</var>, set its
   <a>start offset</a> to
   <var>offset</var>.

   <li>For each <a>range</a> whose
   <a>end node</a> is
   <var>node</var> and
   <a>end offset</a> is greater than
   <var>offset</var>, set its
   <a>end offset</a> to
   <var>offset</var>.
  </ol>

 <li>Return <var>new node</var>.
</ol>

The
<dfn method for="Text">splitText(<var>offset</var>)</dfn>
method must <a lt="split a Text node">split</a> the
<a>context object</a> with offset <var>offset</var>.


The <dfn export>contiguous {{Text}} nodes</dfn> of a node are the node
itself, the
<a>previous sibling</a>
{{Text}} node (if any) and its
<a>contiguous <code>Text</code> nodes</a>, and the
<a>next sibling</a> {{Text}}
node (if any) and its <a>contiguous <code>Text</code> nodes</a>,
avoiding any duplicates.

The <dfn attribute for="Text">wholeText</dfn>
attribute must return a concatenation of the
<a>data</a> of the
<a>contiguous <code>Text</code> nodes</a> of the
<a>context object</a>, in
<a>tree order</a>.



<h3 id='interface-processinginstruction'>Interface {{ProcessingInstruction}}</h3>

<pre class=idl>
[Exposed=Window]
interface ProcessingInstruction : CharacterData {
  readonly attribute DOMString target;
};</pre>


{{ProcessingInstruction}} <a>nodes</a>
have an associated <dfn export id=concept-pi-target for=ProcessingInstruction>target</dfn>.

The <dfn attribute for="ProcessingInstruction">target</dfn>
attribute must return the <a for=ProcessingInstruction>target</a>.



<h3 id='interface-comment'>Interface {{Comment}}</h3>

<pre class=idl>
[Constructor(optional DOMString data = ""),
 Exposed=Window]
interface Comment : CharacterData {
};
</pre>

<dl class=domintro>
 <dt><code><var>comment</var> = new <a constructor lt="Comment()">Comment([<var>data</var> = ""])</a></code>
 <dd>Returns a new {{Comment}} <a>node</a> whose
 <a>data</a> is <var>data</var>.
</dl>

The <dfn constructor for=Comment>Comment(<var>data</var>)</dfn>
constructor must return a new {{Comment}} <a>node</a>
whose <a>data</a> is <var>data</var> and
<a>node document</a> is the global object's associated
<a>document</a>.




<h2 id='ranges'>Ranges</h2>

<h3 id='introduction-to-dom-ranges'>
Introduction to "DOM Ranges"</h3>

A {{Range}} object (<a>range</a>)
represents a sequence of content within a
<a>node tree</a>. Each
<a>range</a> has a
<a>start</a> and an
<a>end</a> which are
<a>boundary points</a>. A
<a>boundary point</a> is a tuple consisting of
a <a>node</a> and a non-negative numeric
<a for="boundary point">offset</a>. So in other words, a
<a>range</a> represents a piece of content within
a <a>node tree</a> between two
<a>boundary points</a>.

<a>Ranges</a> are frequently used in editing
for selecting and copying content.

<ul class="domTree">
 <li class="t1">{{Element}}: <code>p</code>
  <ul>
   <li class="t1">{{Element}}: <code class='lang-markup'>&lt;img src="insanity-wolf" alt="Little-ending BOM; decode as big-endian!"></code>
   <li class="t3">{{Text}}: <span>&nbsp;CSS 2.1 syndata is&nbsp;</span>
   <li class="t1">{{Element}}: <code class='lang-markup'>&lt;em></code>
    <ul>
     <li class="t3">{{Text}}: <span>awesome</span>
    </ul>
   <li class="t3">{{Text}}: <span>!</span>
  </ul>
</ul>
<!-- http://w3cmemes.tumblr.com/post/35332222321/css-2-1-syndata-is-awesome -->

In the <a>node tree</a> above, a
<a>range</a> can be used to represent the sequence
“syndata is awes”. Assuming <var>p</var> is assigned to the
<code>p</code> <a for="/">element</a>, and
<var>em</var> to the <code>em</code>
<a for="/">element</a>, this would be done as follows:

<pre class='lang-javascript'><code>
var range = new Range(),
    firstText = p.childNodes[1],
    secondText = em.firstChild
range.setStart(firstText, 9) // do not forget the leading space
range.setEnd(secondText, 4)
// range now stringifies to the aforementioned quote
</code></pre>

<p class="note no-backref"><a>Attributes</a> such as
<code>src</code> and <code>alt</code> in the
<a>node tree</a> above cannot be represented
by a <a>range</a>. The
<a>ranges</a> concept is only useful for
<a>nodes</a>.

<a>Ranges</a> are affected by mutations to the
<a>node tree</a>. Such mutations will not
invalidate a <a>range</a> and will try to ensure
that the <a>range</a> still represents the same
piece of content. Necessarily, a <a>range</a>
might itself be modified as part of the mutation to the
<a>node tree</a> when e.g. part of the content
it represents is mutated.

<p class="note no-backref">See the <a for=Node>insert</a> and
<a>remove</a> algorithms, the
{{Node/normalize()}} method, and the
<a>replace data</a> and
<a lt="split a Text node">split</a> algorithms for the hairy
details.


<h3 id='interface-range'>
Interface {{Range}}</h3>

<pre class=idl>
[Constructor,
 Exposed=Window]
interface Range {
  readonly attribute Node startContainer;
  readonly attribute unsigned long startOffset;
  readonly attribute Node endContainer;
  readonly attribute unsigned long endOffset;
  readonly attribute boolean collapsed;
  readonly attribute Node commonAncestorContainer;

  void setStart(Node node, unsigned long offset);
  void setEnd(Node node, unsigned long offset);
  void setStartBefore(Node node);
  void setStartAfter(Node node);
  void setEndBefore(Node node);
  void setEndAfter(Node node);
  void collapse(optional boolean toStart = false);
  void selectNode(Node node);
  void selectNodeContents(Node node);

  const unsigned short START_TO_START = 0;
  const unsigned short START_TO_END = 1;
  const unsigned short END_TO_END = 2;
  const unsigned short END_TO_START = 3;
  short compareBoundaryPoints(unsigned short how, Range sourceRange);

  [CEReactions] void deleteContents();
  [CEReactions, NewObject] DocumentFragment extractContents();
  [CEReactions, NewObject] DocumentFragment cloneContents();
  [CEReactions] void insertNode(Node node);
  [CEReactions] void surroundContents(Node newParent);

  [NewObject] Range cloneRange();
  void detach();

  boolean isPointInRange(Node node, unsigned long offset);
  short comparePoint(Node node, unsigned long offset);

  boolean intersectsNode(Node node);

  stringifier;
};
</pre>

{{Range}} objects are simply known as
<dfn export id=concept-range lt="range">ranges</dfn>.

A <dfn export for=Range id=concept-range-bp>boundary point</dfn> is a
(<a>node</a>,
<dfn export id=concept-range-bp-offset for="boundary point">offset</dfn>) tuple, where
<a for="boundary point">offset</a> is a non-negative
integer.

<p class="note no-backref">Generally speaking, a
<a>boundary point</a>'s
<a for="boundary point">offset</a> will be between zero and
the <a>boundary point</a>'s
<a>node</a>
<a>length</a>, inclusive. Algorithms that
modify a <a>tree</a> (in particular the
<a for=Node>insert</a>,
<a>remove</a>,
<a>replace data</a>, and
<a lt="split a Text node">split</a> algorithms) also modify
<a>ranges</a> associated with that
<a>tree</a>.

If the two <a>nodes</a> of
<a>boundary points</a>
(<var>node A</var>, <var>offset A</var>) and
(<var>node B</var>, <var>offset B</var>) have the same
<a for=tree>root</a>, the
<dfn export id=concept-range-bp-position for=Range>position</dfn> of the first relative to
the second is either <dfn export id=concept-range-bp-before for=Range>before</dfn>,
<dfn export id=concept-range-bp-equal for=Range>equal</dfn>, or
<dfn export id=concept-range-bp-after for=Range>after</dfn>,
as returned by the following algorithm:

<ol>
 <li>If <var>node A</var> is the same as <var>node B</var>,
 return <a for=Range>equal</a> if
 <var>offset A</var> is the same as <var>offset B</var>,
 <a for=Range>before</a> if
 <var>offset A</var> is less than <var>offset B</var>, and
 <a for=Range>after</a> if
 <var>offset A</var> is greater than <var>offset B</var>.

 <li>If <var>node A</var> is
 <a>following</a>
 <var>node B</var>, compute the
 <a for=Range>position</a> of
 (<var>node B</var>, <var>offset B</var>) relative to
 (<var>node A</var>, <var>offset A</var>). If it is
 <a for=Range>before</a>, return
 <a for=Range>after</a>. If it is
 <a for=Range>after</a>, return
 <a for=Range>before</a>.

 <li>
  If <var>node A</var> is an
  <a>ancestor</a> of
  <var>node B</var>:

  <ol>
   <li>Let <var>child</var> equal <var>node B</var>.

   <li>While <var>child</var> is not a
   <a>child</a> of <var>node A</var>,
   set <var>child</var> to its
   <a>parent</a>.

   <li>If the <a>index</a> of
   <var>child</var> is less than <var>offset A</var>, return
   <a for=Range>after</a>.
  </ol>

 <li>Return <a for=Range>before</a>.
</ol>

Each <a>range</a> has two associated
<a>boundary points</a> — a
<dfn export id=concept-range-start for=Range>start</dfn> and
<dfn export id=concept-range-end for=Range>end</dfn>.

For convenience, <dfn export id=concept-range-start-node for=Range>start node</dfn> is
<a>start</a>'s
<a>node</a>,
<dfn export id=concept-range-start-offset for=Range>start offset</dfn> is
<a>start</a>'s
<a for="boundary point">offset</a>,
<dfn export id=concept-range-end-node for=Range>end node</dfn> is
<a>end</a>'s
<a>node</a>,  and
<dfn export id=concept-range-end-offset for=Range>end offset</dfn> is
<a>end</a>'s
<a for="boundary point">offset</a>.

The <dfn export id=concept-range-root for=Range>root</dfn> of a
<a>range</a> is the
<a for=tree>root</a> of its
<a>start node</a>.
<!-- start and end have an identical root -->

A <a>node</a> <var>node</var> is <dfn export for=Range id=contained>contained</dfn> in a
<a>range</a> <var>range</var> if <var>node</var>'s <a for=tree>root</a> is the same as
<var>range</var>'s <a for=Range>root</a>, and (<var>node</var>, 0) is <a for=Range>after</a>
<var>range</var>'s <a>start</a>, and (<var>node</var>, <a>length</a> of <var>node</var>) is
<a for=Range>before</a> <var>range</var>'s <a>end</a>.

A <a>node</a> is <dfn export for=Range id=partially-contained>partially contained</dfn> in a
<a>range</a> if it is an <a>inclusive ancestor</a> of the <a>range</a>'s <a>start node</a> but not
its <a>end node</a>, or vice versa.

<div class=note>
 Some facts to better understand these definitions:

 <ul>
  <li>The content that one would think of as being within the
  <a>range</a> consists of all
  <a>contained</a> <a>nodes</a>, plus
  possibly some of the contents of the
  <a>start node</a> and
  <a>end node</a> if those are
  {{Text}}, {{ProcessingInstruction}}, or
  {{Comment}} <a>nodes</a>.

  <li>The <a>nodes</a> that are contained in a
  <a>range</a> will generally not be contiguous,
  because the <a>parent</a> of a
  <a>contained</a> <a>node</a> will not
  always be <a>contained</a>.

  <li>However, the <a>descendants</a>
  of a <a>contained</a> <a>node</a> are
  <a>contained</a>, and if two
  <a>siblings</a> are
  <a>contained</a>, so are any
  <a>siblings</a> that lie between them.

  <li>The <a>start node</a> and
  <a>end node</a> of a
  <a>range</a> are never <a>contained</a>
  within it.

  <li>The first <a>contained</a>
  <a>node</a> (if there are any) will always be
  after the <a>start node</a>, and the
  last <a>contained</a> <a>node</a> will
  always be equal to or before the
  <a>end node</a>'s last
  <a>descendant</a>.

  <li>There exists a partially contained
  <a>node</a> if and only if the
  <a>start node</a> and
  <a>end node</a> are different.

  <li>The {{Range/commonAncestorContainer}} attribute value is neither <a>contained</a>
  nor <a>partially contained</a>.

  <li>If the <a>start node</a> is an
  <a>ancestor</a> of the
  <a>end node</a>, the common
  <a>inclusive ancestor</a> will
  be the <a>start node</a>. Exactly one
  of its <a>children</a> will be
  <a>partially contained</a>, and a
  <a>child</a> will be <a>contained</a>
  if and only if it <a lt="preceding">precedes</a> the
  <a>partially contained</a>
  <a>child</a>. If the
  <a>end node</a> is an
  <a>ancestor</a> of the
  <a>start node</a>, the opposite
  holds.

  <li>If the <a>start node</a> is
  not an
  <a>inclusive ancestor</a> of
  the <a>end node</a>, nor vice versa,
  the common
  <a>inclusive ancestor</a> will
  be distinct from both of them. Exactly two of its
  <a>children</a> will be
  <a>partially contained</a>, and a
  <a>child</a> will be contained if and only
  if it lies between those two.
 </ul>
</div>

<hr>

<dl class=domintro>
 <dt><code><var>range</var> = new <a constructor>Range()</a></code>
 <dd>Returns a new <a>range</a>.
</dl>

The <dfn constructor for=Range><code>Range()</code></dfn> constructor must return a new
<a>range</a> with
(global object's associated <a>document</a>, 0) as its
<a>start</a> and
<a>end</a>.

<hr>

<dl class=domintro>
 <dt><var>node</var> = <var>range</var> . {{Range/startContainer}}
 <dd>Returns <var>range</var>'s
 <a>start node</a>.

 <dt><var>offset</var> = <var>range</var> . {{Range/startOffset}}
 <dd>Returns <var>range</var>'s
 <a>start offset</a>.

 <dt><var>node</var> = <var>range</var> . {{Range/endContainer}}
 <dd>Returns <var>range</var>'s
 <a>end node</a>.

 <dt><var>offset</var> = <var>range</var> . {{Range/endOffset}}
 <dd>Returns <var>range</var>'s
 <a>end offset</a>.

 <dt><var>collapsed</var> = <var>range</var> . {{Range/collapsed}}
 <dd>Returns true if <var>range</var>'s
 <a>start</a> and
 <a>end</a> are the same, and false otherwise.

 <dt><var>container</var> = <var>range</var> . {{Range/commonAncestorContainer}}
 <dd>Returns the <a>node</a>, furthest away from
 the <a>document</a>, that is an
 <a>ancestor</a> of both
 <var>range</var>'s
 <a>start node</a> and
 <a>end node</a>.
</dl>

The <dfn attribute for=Range>startContainer</dfn>
attribute must return the
<a>start node</a>.

The <dfn attribute for=Range>startOffset</dfn>
attribute must return the
<a>start offset</a>.

The <dfn attribute for=Range>endContainer</dfn>
attribute must return the
<a>end node</a>.

The <dfn attribute for=Range>endOffset</dfn>
attribute must return the
<a>end offset</a>.

The <dfn attribute for=Range>collapsed</dfn> attribute
must return true if <a>start</a> is the same
as <a>end</a>, and false otherwise.

The
<dfn attribute for=Range>commonAncestorContainer</dfn>
attribute must run these steps:

<ol>
 <li>Let <var>container</var> be
 <a>start node</a>.

 <li>While <var>container</var> is not an
 <a>inclusive ancestor</a> of
 <a>end node</a>, let
 <var>container</var> be <var>container</var>'s
 <a>parent</a>.

 <li>Return <var>container</var>.
</ol>

<hr>

To <dfn export id=concept-range-bp-set lt="set the start|set the end" for=Range>set the start or end</dfn> of a
<var>range</var> to a
<a>boundary point</a>
(<var>node</var>, <var>offset</var>), run these steps:

<ol>
 <li>If <var>node</var> is a <a>doctype</a>, then <a>throw</a> an {{InvalidNodeTypeError}}.

 <li>If <var>offset</var> is greater than <var>node</var>'s <a>length</a>, then <a>throw</a> an
 {{IndexSizeError}}.

 <li>Let <var>bp</var> be the
 <a>boundary point</a>
 (<var>node</var>, <var>offset</var>).

 <li>
  <dl class=switch>
   <dt>If these steps were invoked as "set the start"
   <dd>
    <ol>
     <li>If <var>bp</var> is
     <a for=Range>after</a> the
     <var>range</var>'s <a>end</a>, or
     if <var>range</var>'s
     <a for=Range>root</a> is not equal to
     <var>node</var>'s <a for=tree>root</a>, set
     <var>range</var>'s <a>end</a> to
     <var>bp</var>.

     <li>Set <var>range</var>'s
     <a>start</a> to <var>bp</var>.
    </ol>
   <dt>If these steps were invoked as "set the end"
   <dd>
    <ol>
     <li>If <var>bp</var> is
     <a for=Range>before</a> the
     <var>range</var>'s <a>start</a>,
     or if <var>range</var>'s
     <a for=Range>root</a> is not equal to
     <var>node</var>'s <a for=tree>root</a>, set
     <var>range</var>'s <a>start</a>
     to <var>bp</var>.

     <li>Set <var>range</var>'s
     <a>end</a> to <var>bp</var>.
    </ol>
  </dl>
</ol>

The
<dfn method for=Range>setStart(<var>node</var>, <var>offset</var>)</dfn>
method must <a>set the start</a> of the
<a>context object</a> to
<a>boundary point</a>
(<var>node</var>, <var>offset</var>).

The
<dfn method for=Range>setEnd(<var>node</var>, <var>offset</var>)</dfn>
method must <a>set the end</a> of the
<a>context object</a> to
<a>boundary point</a>
(<var>node</var>, <var>offset</var>).

The
<dfn method for=Range>setStartBefore(<var>node</var>)</dfn>
method must run these steps:

<ol>
 <li>Let <var>parent</var> be <var>node</var>'s
 <a>parent</a>.

 <li>If <var>parent</var> is null, then <a>throw</a> an {{InvalidNodeTypeError}}.

 <li><a>Set the start</a> of the
 <a>context object</a> to
 <a>boundary point</a>
 (<var>parent</var>, <var>node</var>'s
 <a>index</a>).
</ol>

The
<dfn method for=Range>setStartAfter(<var>node</var>)</dfn>
method must run these steps:

<ol>
 <li>Let <var>parent</var> be <var>node</var>'s
 <a>parent</a>.

 <li>If <var>parent</var> is null, then <a>throw</a> an {{InvalidNodeTypeError}}.

 <li><a>Set the start</a> of the
 <a>context object</a> to
 <a>boundary point</a>
 (<var>parent</var>, <var>node</var>'s
 <a>index</a> plus one).
</ol>

The
<dfn method for=Range>setEndBefore(<var>node</var>)</dfn>
method must run these steps:

<ol>
 <li>Let <var>parent</var> be <var>node</var>'s
 <a>parent</a>.

 <li>If <var>parent</var> is null, then <a>throw</a> an {{InvalidNodeTypeError}}.

 <li><a>Set the end</a> of the
 <a>context object</a> to
 <a>boundary point</a>
 (<var>parent</var>, <var>node</var>'s <a>index</a>).
</ol>

The
<dfn method for=Range>setEndAfter(<var>node</var>)</dfn>
method must run these steps:

<ol>
 <li>Let <var>parent</var> be <var>node</var>'s
 <a>parent</a>.

 <li>If <var>parent</var> is null, then <a>throw</a> an {{InvalidNodeTypeError}}.

 <li><a>Set the end</a> of the
 <a>context object</a> to
 <a>boundary point</a>
 (<var>parent</var>, <var>node</var>'s <a>index</a> plus one).
</ol>


The <dfn method for=Range><code>collapse(<var>toStart</var>)</code></dfn> method, when
invoked, must if <var>toStart</var> is true, set <a>end</a> to <a>start</a>, and set
<a>start</a> to <a>end</a> otherwise.

To <dfn export id=concept-range-select for=Range>select</dfn> a <a>node</a>
<var>node</var> within a <a>range</a>
<var>range</var>, run these steps:

<ol>
 <li>Let <var>parent</var> be <var>node</var>'s
 <a>parent</a>.

 <li>If <var>parent</var> is null, <a>throw</a> an
 {{InvalidNodeTypeError}}.

 <li>Let <var>index</var> be <var>node</var>'s
 <a>index</a>.

 <li>Set <var>range</var>'s <a>start</a> to
 <a>boundary point</a>
 (<var>parent</var>, <var>index</var>).

 <li>Set <var>range</var>'s <a>end</a> to
 <a>boundary point</a>
 (<var>parent</var>, <var>index</var> plus one).
</ol>

The <dfn method for=Range>selectNode(<var>node</var>)</dfn>
method must <a for=Range>select</a> <var>node</var> within
<a>context object</a>.

The <dfn method for=Range>selectNodeContents(<var>node</var>)</dfn>
method must run these steps:

<ol>
 <li>If <var>node</var> is a
 <a>doctype</a>,
 <a>throw</a> an
 {{InvalidNodeTypeError}}.

 <li>Let <var>length</var> be the
 <a>length</a> of <var>node</var>.

 <li>Set <a>start</a> to the
 <a>boundary point</a>
 (<var>node</var>, 0).

 <li>Set <a>end</a> to the
 <a>boundary point</a>
 (<var>node</var>, <var>length</var>).
</ol>

<hr>

The <dfn method for=Range>compareBoundaryPoints(<var>how</var>, <var>sourceRange</var>)</dfn>
method must run these steps:

<ol>
 <li>
  <p>If <var>how</var> is not one of

  <ul class=brief>
   <li>{{Range/START_TO_START}},
   <li>{{Range/START_TO_END}},
   <li>{{Range/END_TO_END}}, and
   <li>{{Range/END_TO_START}},
  </ul>

  <p>then <a>throw</a> a {{NotSupportedError}}.
 <!--
 Apparent behaviors from black-box testing:

 IE9: Converts to unsigned short per WebIDL, then throws "Error: Invalid
 argument." if it's not 0-3.

 Firefox 12.0a1: Converts to unsigned short per WebIDL, then throws
 NS_ERROR_ILLEGAL_VALUE if it's not 0-3.

 Chrome 17 dev: Converts to unsigned *long* per WebIDL, and treats bad values
 as 0.  Never throws.

 Opera Next 12.00 alpha: Throws NotSupportedError unless the value is -0, 0, 1,
 2, 3, or an integer equal to one of these modulo 2^32.  (In particular, it
 throws on NaN, Infinity, and -Infinity instead of treating them as 0 per
 WebIDL.)

 The spec follows IE9/Gecko, except that we throw NotSupportedError (like
 Opera) instead of a nonstandard exception type.
 -->

 <li>If <a>context object</a>'s <a for=Range>root</a> is not the same as <var>sourceRange</var>'s
 <a for=Range>root</a>, then <a>throw</a> a {{WrongDocumentError}}.

 <li>
  If <var>how</var> is:
  <dl class=switch>
   <dt>{{Range/START_TO_START}}:
   <dd>
    Let <var>this point</var> be the <a>context object</a>'s
    <a>start</a>.
    Let <var>other point</var> be <var>sourceRange</var>'s
    <a>start</a>.

   <dt>{{Range/START_TO_END}}:
   <dd>
    Let <var>this point</var> be the <a>context object</a>'s
    <a>end</a>.
    Let <var>other point</var> be <var>sourceRange</var>'s
    <a>start</a>.

    <dt>{{Range/END_TO_END}}:
    <dd>
     Let <var>this point</var> be the <a>context object</a>'s
     <a>end</a>.
     Let <var>other point</var> be <var>sourceRange</var>'s
     <a>end</a>.

    <dt>{{Range/END_TO_START}}:
    <dd>
     Let <var>this point</var> be the <a>context object</a>'s
     <a>start</a>.
     Let <var>other point</var> be <var>sourceRange</var>'s
     <a>end</a>.
   </dl>

  <li>
   If the <a for=Range>position</a> of
   <var>this point</var> relative to <var>other point</var> is

   <dl class=switch>
    <dt><a for=Range>before</a>
    <dd>Return &minus;1.

    <dt><a for=Range>equal</a>
    <dd>Return 0.

    <dt><a for=Range>after</a>
    <dd>Return 1.
   </dl>
</ol>

The <dfn method for=Range><code>deleteContents()</code></dfn> method, when invoked, must
run these steps:

<ol>
 <li>If <a>start</a> is <a>end</a>, terminate these steps.
 <!-- This might actually make no difference, but it's not immediately
 obvious what would happen otherwise if the start/end were text/comment:
 are all the substeps of the next step actually no-ops, or could some have
 side effects? -->

 <li>Let <var>original start node</var>,
 <var>original start offset</var>, <var>original end node</var>,
 and <var>original end offset</var> be the
 <a>context object</a>'s
 <a>start node</a>,
 <a>start offset</a>,
 <a>end node</a>, and
 <a>end offset</a>, respectively.

 <li>If <var>original start node</var> and
 <var>original end node</var> are the same, and they are a
 {{Text}}, {{ProcessingInstruction}}, or
 {{Comment}} <a>node</a>,
 <a>replace data</a> with node
 <var>original start node</var>, offset
 <var>original start offset</var>, count
 <var>original end offset</var> minus
 <var>original start offset</var>, and data the empty string, and then
 terminate these steps.

 <li>Let <var>nodes to remove</var> be a list of all the
 <a>nodes</a> that are <a>contained</a> in
 the <a>context object</a>, in
 <a>tree order</a>, omitting any
 <a>node</a> whose
 <a>parent</a> is also
 <a>contained</a> in the <a>context object</a>.

 <li>If <var>original start node</var> is an
 <a>inclusive ancestor</a> of
 <var>original end node</var>, set
 <var>new node</var> to <var>original start node</var> and
 <var>new offset</var> to <var>original start offset</var>.

 <li>
  Otherwise:
  <ol>
   <li>Let <var>reference node</var> equal
   <var>original start node</var>.

   <li>While <var>reference node</var>'s
   <a>parent</a> is not null and is not an
   <a>inclusive ancestor</a> of
   <var>original end node</var>, set <var>reference node</var>
   to its <a>parent</a>.

   <li>
    Set <var>new node</var> to the
    <a>parent</a> of
    <var>reference node</var>, and <var>new offset</var> to one
    plus the <a>index</a> of
    <var>reference node</var>.

    <p class="note no-backref">If <var>reference node</var>'s
    <a>parent</a> were null, it would be the
    <a for=Range>root</a> of the
    <a>context object</a>, so would be an
    <a>inclusive ancestor</a> of
    <var>original end node</var>, and we could not reach this point.
  </ol>

 <li>If <var>original start node</var> is a {{Text}},
 {{ProcessingInstruction}}, or {{Comment}}
 <a>node</a>,
 <a>replace data</a> with node
 <var>original start node</var>, offset
 <var>original start offset</var>, count
 <var>original start node</var>'s
 <a>length</a> minus
 <var>original start offset</var>, data the empty string.

 <li>For each <var>node</var> in <var>nodes to remove</var>,
 in <a>tree order</a>,
 <a>remove</a> <var>node</var> from
 its <a>parent</a>.

 <li>If <var>original end node</var> is a {{Text}},
 {{ProcessingInstruction}}, or {{Comment}}
 <a>node</a>,
 <a>replace data</a> with node
 <var>original end node</var>, offset 0, count
 <var>original end offset</var> and data the empty string.

 <li>Set <a>start</a> and
 <a>end</a> to
 (<var>new node</var>, <var>new offset</var>).
</ol>

To <dfn export id=concept-range-extract lt="extract a range" local-lt="extract">extract</dfn> a
<a>range</a> <var>range</var>, run these steps:

<ol>
 <li>Let <var>fragment</var> be a new {{DocumentFragment}}
 <a>node</a> whose
 <a>node document</a> is <var>range</var>'s
 <a>start node</a>'s
 <a>node document</a>.

 <li>If <var>range</var>'s <a>start</a> is its <a>end</a>, return <var>fragment</var>.
 <!-- This is only really needed when the start and end nodes are
 text/comment, to avoid creating an empty clone as the child of the
 fragment. (Opera 11 actually does include such an empty clone, it seems,
 but Gecko and WebKit do not as of March 2011, so we follow them.)
 Otherwise, the following steps are all no-ops. But it's simplest to include
 this step anyway. -->

 <li>Let <var>original start node</var>, <var>original start offset</var>,
 <var>original end node</var>, and <var>original end offset</var> be
 <var>range</var>'s <a>start node</a>,
 <a>start offset</a>,
 <a>end node</a>, and
 <a>end offset</a>, respectively.

 <li>
  If <var>original start node</var> is <var>original end node</var>, and they are a
  {{Text}}, {{ProcessingInstruction}}, or {{Comment}} <a>node</a>:

  <ol>
   <li>Let <var>clone</var> be a
   <a lt="clone a node">clone</a> of
   <var>original start node</var>.

   <li>Set the <a>data</a> of
   <var>clone</var> to the result of
   <a lt="substring data">substringing data</a> with node
   <var>original start node</var>, offset
   <var>original start offset</var>, and count
   <var>original end offset</var> minus
   <var>original start offset</var>.

   <li><a>Append</a> <var>clone</var>
   to <var>fragment</var>.

   <li><a>Replace data</a> with node
   <var>original start node</var>, offset
   <var>original start offset</var>, count
   <var>original end offset</var> minus
   <var>original start offset</var>, and data the empty string.

   <li>Return <var>fragment</var>.
  </ol>

 <li>Let <var>common ancestor</var> be
 <var>original start node</var>.

 <li>While <var>common ancestor</var> is not an
 <a>inclusive ancestor</a> of
 <var>original end node</var>, set <var>common ancestor</var> to
 its own <a>parent</a>.

 <li>Let <var>first partially contained child</var> be null.

 <li>If <var>original start node</var> is <em>not</em> an
 <a>inclusive ancestor</a> of
 <var>original end node</var>, set <var>first partially contained child</var>
 to the first <a>child</a> of
 <var>common ancestor</var> that is <a>partially contained</a> in
 <var>range</var>.

 <li>Let <var>last partially contained child</var> be null.

 <li>
  If <var>original end node</var> is <em>not</em> an
  <a>inclusive ancestor</a> of
  <var>original start node</var>, set
  <var>last partially contained child</var> to the last
  <a>child</a> of <var>common ancestor</var> that is
  <a>partially contained</a> in <var>range</var>.

  <p class="note no-backref">These variable assignments do actually always make sense.
  For instance, if <var>original start node</var> is not an
  <a>inclusive ancestor</a> of
  <var>original end node</var>, <var>original start node</var> is itself
  <a>partially contained</a> in <var>range</var>, and so are all its
  <a>ancestors</a> up until a
  <a>child</a> of <var>common ancestor</var>.
  <var>common ancestor</var> cannot be <var>original start node</var>, because
  it has to be an <a>inclusive ancestor</a> of
  <var>original end node</var>. The other case is similar. Also, notice that the two
  <a>children</a> will never be equal if both are defined.

 <li>Let <var>contained children</var> be a list of all
 <a>children</a> of
 <var>common ancestor</var> that are <a>contained</a> in
 <var>range</var>, in <a>tree order</a>.

 <li>
  <p>If any member of <var>contained children</var> is a <a>doctype</a>, then <a>throw</a> a
  {{HierarchyRequestError}}.
  <!-- Firefox 4.0 actually removes the non-DocumentType nodes before
  throwing the exception. Opera 11.00 removes the DocumentType too, and
  doesn't throw. I go with IE9 and Chrome 12 dev, which don't remove any
  nodes. DOM 2 Range doesn't specify what exactly happens here, except that
  an exception should be thrown. -->

  <p class="note no-backref">We do not have to worry about the first or last partially
  contained node, because a <a>doctype</a> can never be
  partially contained. It cannot be a boundary point of a range, and it
  cannot be the ancestor of anything.

 <li>If <var>original start node</var> is an
 <a>inclusive ancestor</a> of
 <var>original end node</var>, set <var>new node</var> to
 <var>original start node</var> and <var>new offset</var> to
 <var>original start offset</var>.

 <li>
  Otherwise:
  <ol>
   <li>Let <var>reference node</var> equal <var>original start node</var>.

   <li>While <var>reference node</var>'s
   <a>parent</a> is not null and is not an
   <a>inclusive ancestor</a> of
   <var>original end node</var>, set <var>reference node</var> to its
   <a>parent</a>.

   <li>
    Set <var>new node</var> to the
    <a>parent</a> of <var>reference node</var>, and
    <var>new offset</var> to one plus <var>reference node</var>'s
    <a>index</a>.

    <p class="note no-backref">If <var>reference node</var>'s
    <a>parent</a> is null, it would be the
    <a for=Range>root</a> of <var>range</var>, so would be an
    <a>inclusive ancestor</a> of
    <var>original end node</var>, and we could not reach this point.
  </ol>

  <!-- Now we start with mutations, so we can't refer to the context object
  anymore unless we carefully consider how it will have mutated. -->

 <li>
  If <var>first partially contained child</var> is a
  {{Text}}, {{ProcessingInstruction}}, or
  {{Comment}} <a>node</a>:

  <p class="note no-backref">In this case, <var>first partially contained child</var> is
  <var>original start node</var>.

  <ol>
   <li>Let <var>clone</var> be a
   <a lt="clone a node">clone</a> of
   <var>original start node</var>.

   <li>Set the <a>data</a> of
   <var>clone</var> to the result of
   <a lt="substring data">substringing data</a> with node
   <var>original start node</var>, offset
   <var>original start offset</var>, and count
   <var>original start node</var>'s
   <a>length</a> minus
   <var>original start offset</var>.

   <li><a>Append</a> <var>clone</var>
   to <var>fragment</var>.

   <li><a>Replace data</a> with node
   <var>original start node</var>, offset
   <var>original start offset</var>, count
   <var>original start node</var>'s
   <a>length</a> minus
   <var>original start offset</var>, and data the empty string.
  </ol>

 <li>
  Otherwise, if <var>first partially contained child</var> is not
  null:

  <ol>
   <li>Let <var>clone</var> be a
   <a lt="clone a node">clone</a> of
   <var>first partially contained child</var>.

   <li><a>Append</a> <var>clone</var>
   to <var>fragment</var>.

   <li>Let <var>subrange</var> be a new <a>range</a>
   whose <a>start</a> is
   (<var>original start node</var>, <var>original start offset</var>) and
   whose <a>end</a> is
   (<var>first partially contained child</var>, <var>first partially contained child</var>'s <a>length</a>).

   <li>Let <var>subfragment</var> be the result of
   <a lt="extract a range">extracting</a> <var>subrange</var>.

   <li><a>Append</a> <var>subfragment</var> to
   <var>clone</var>.
  </ol>

 <li>For each <var>contained child</var> in <var>contained children</var>,
 <a>append</a> <var>contained child</var> to
 <var>fragment</var>.

 <li>
  If <var>last partially contained child</var> is a
  {{Text}}, {{ProcessingInstruction}}, or
  {{Comment}} <a>node</a>:

  <p class="note no-backref">In this case, <var>last partially contained child</var> is
  <var>original end node</var>.

  <ol>
   <li>Let <var>clone</var> be a <a lt="clone a node">clone</a> of
   <var>original end node</var>.

   <li>Set the <a>data</a> of
   <var>clone</var> to the result of
   <a lt="substring data">substringing data</a> with node
   <var>original end node</var>, offset 0, and count
   <var>original end offset</var>.

   <li><a>Append</a> <var>clone</var>
   to <var>fragment</var>.

   <li><a>Replace data</a> with node
   <var>original end node</var>, offset 0, count
   <var>original end offset</var>, and data the empty string.
  </ol>

 <li>
  Otherwise, if <var>last partially contained child</var> is not
  null:

  <ol>
   <li>Let <var>clone</var> be a
   <a lt="clone a node">clone</a> of
   <var>last partially contained child</var>.

   <li><a>Append</a> <var>clone</var>
   to <var>fragment</var>.

   <li>Let <var>subrange</var> be a new <a>range</a>
   whose <a>start</a> is
   (<var>last partially contained child</var>, 0) and whose
   <a>end</a> is
   (<var>original end node</var>, <var>original end offset</var>).

   <li>Let <var>subfragment</var> be the result of
   <a lt="extract a range">extracting</a> <var>subrange</var>.

   <li><a>Append</a> <var>subfragment</var> to
   <var>clone</var>.
  </ol>

 <li>Set <var>range</var>'s <a>start</a> and
 <a>end</a> to
 (<var>new node</var>, <var>new offset</var>).

 <li>Return <var>fragment</var>.
</ol>

The <dfn method for=Range>extractContents()</dfn> method
must return the result of <a lt="extract a range">extracting</a>
<a>context object</a>.

<p>To <dfn export id=concept-range-clone lt="clone the contents of a range">clone the contents</dfn>
of a <a>range</a> <var>range</var>, run these steps:

<ol>
 <li>Let <var>fragment</var> be a new {{DocumentFragment}}
 <a>node</a> whose
 <a>node document</a> is <var>range</var>'s
 <a>start node</a>'s
 <a>node document</a>.

 <li>If <var>range</var>'s <a>start</a> is its <a>end</a>, return <var>fragment</var>.
 <!-- This is only really needed when the start and end nodes are
 text/comment, to avoid creating an empty clone as the child of the
 fragment. (Opera 11 actually does include such an empty clone, it seems,
 but Gecko and WebKit do not as of March 2011, so we follow them.)
 Otherwise, the following steps are all no-ops. But it's simplest to include
 this step anyway. -->

 <li>Let <var>original start node</var>, <var>original start offset</var>,
 <var>original end node</var>, and <var>original end offset</var> be
 <var>range</var>'s <a>start node</a>,
 <a>start offset</a>,
 <a>end node</a>, and
 <a>end offset</a>, respectively.

 <li>
  If <var>original start node</var> is <var>original end node</var>, and they are a
  {{Text}}, {{ProcessingInstruction}}, or {{Comment}} <a>node</a>:

  <ol>
   <li>Let <var>clone</var> be a <a lt="clone a node">clone</a> of
   <var>original start node</var>.

   <li>Set the <a>data</a> of
   <var>clone</var> to the result of
   <a lt="substring data">substringing data</a> with node
   <var>original start node</var>, offset
   <var>original start offset</var>, and count
   <var>original end offset</var> minus
   <var>original start offset</var>.

   <li><a>Append</a> <var>clone</var>
   to <var>fragment</var>.

   <li>Return <var>fragment</var>.
  </ol>

 <li>Let <var>common ancestor</var> be
 <var>original start node</var>.

 <li>While <var>common ancestor</var> is not an
 <a>inclusive ancestor</a> of
 <var>original end node</var>, set
 <var>common ancestor</var> to its own
 <a>parent</a>.

 <li>Let <var>first partially contained child</var> be null.

 <li>If <var>original start node</var> is <em>not</em> an
 <a>inclusive ancestor</a> of
 <var>original end node</var>, set <var>first partially contained child</var>
 to the first <a>child</a> of
 <var>common ancestor</var> that is <a>partially contained</a> in
 <var>range</var>.

 <li>Let <var>last partially contained child</var> be null.

 <li>
  If <var>original end node</var> is <em>not</em> an
  <a>inclusive ancestor</a> of
  <var>original start node</var>, set
  <var>last partially contained child</var> to the last
  <a>child</a> of <var>common ancestor</var> that is
  <a>partially contained</a> in <var>range</var>.

  <p class="note no-backref">These variable assignments do actually always make sense.
  For instance, if <var>original start node</var> is not an
  <a>inclusive ancestor</a> of
  <var>original end node</var>, <var>original start node</var> is itself
  <a>partially contained</a> in <var>range</var>, and so are all its
  <a>ancestors</a> up until a
  <a>child</a> of <var>common ancestor</var>.
  <var>common ancestor</var> cannot be <var>original start node</var>, because
  it has to be an <a>inclusive ancestor</a> of
  <var>original end node</var>. The other case is similar. Also, notice that the two
  <a>children</a> will never be equal if both are defined.

 <li>Let <var>contained children</var> be a list of all
 <a>children</a> of
 <var>common ancestor</var> that are <a>contained</a> in
 <var>range</var>, in <a>tree order</a>.

 <li>
  <p>If any member of <var>contained children</var> is a <a>doctype</a>, then <a>throw</a> a
  {{HierarchyRequestError}}.

  <p class="note no-backref">We do not have to worry about the first or last partially
  contained node, because a <a>doctype</a> can never be
  partially contained. It cannot be a boundary point of a range, and it
  cannot be the ancestor of anything.

 <li>
  If <var>first partially contained child</var> is a
  {{Text}}, {{ProcessingInstruction}}, or
  {{Comment}} <a>node</a>:

  <p class="note no-backref">In this case, <var>first partially contained child</var> is
  <var>original start node</var>.

  <ol>
   <li>Let <var>clone</var> be a
   <a lt="clone a node">clone</a> of
   <var>original start node</var>.

   <li>Set the <a>data</a> of
   <var>clone</var> to the result of
   <a lt="substring data">substringing data</a> with node
   <var>original start node</var>, offset
   <var>original start offset</var>, and count
   <var>original start node</var>'s
   <a>length</a> minus
   <var>original start offset</var>.

   <li><a>Append</a> <var>clone</var>
   to <var>fragment</var>.
  </ol>

 <li>
  Otherwise, if <var>first partially contained child</var> is not
  null:

  <ol>
   <li>Let <var>clone</var> be a
   <a lt="clone a node">clone</a> of
   <var>first partially contained child</var>.

   <li><a>Append</a> <var>clone</var>
   to <var>fragment</var>.

   <li>Let <var>subrange</var> be a new <a>range</a>
   whose <a>start</a> is
   (<var>original start node</var>, <var>original start offset</var>) and
   whose <a>end</a> is
   (<var>first partially contained child</var>, <var>first partially contained child</var>'s <a>length</a>).

   <li>Let <var>subfragment</var> be the result of
   <a lt="clone the contents of a range">cloning the contents</a> of <var>subrange</var>.

   <li><a>Append</a> <var>subfragment</var> to
   <var>clone</var>.
  </ol>

 <li>
  For each <var>contained child</var> in
  <var>contained children</var>:

  <ol>
   <li>Let <var>clone</var> be a <a lt="clone a node">clone</a> of
   <var>contained child</var> with the <i>clone children flag</i> set.

   <li><a>Append</a> <var>clone</var> to
   <var>fragment</var>.
  </ol>

 <li>
  If <var>last partially contained child</var> is a
  {{Text}}, {{ProcessingInstruction}}, or
  {{Comment}} <a>node</a>:

  <p class="note no-backref">In this case, <var>last partially contained child</var> is
  <var>original end node</var>.

  <ol>
   <li>Let <var>clone</var> be a <a lt="clone a node">clone</a> of
   <var>original end node</var>.

   <li>Set the <a>data</a> of
   <var>clone</var> to the result of
   <a lt="substring data">substringing data</a> with node
   <var>original end node</var>, offset 0, and count
   <var>original end offset</var>.

   <li><a>Append</a> <var>clone</var> to
   <var>fragment</var>.
  </ol>

 <li>
  Otherwise, if <var>last partially contained child</var> is not
  null:

  <ol>
   <li>Let <var>clone</var> be a
   <a lt="clone a node">clone</a> of
   <var>last partially contained child</var>.

   <li><a>Append</a> <var>clone</var>
   to <var>fragment</var>.

   <li>Let <var>subrange</var> be a new <a>range</a>
   whose <a>start</a> is
   (<var>last partially contained child</var>, 0) and whose
   <a>end</a> is
   (<var>original end node</var>, <var>original end offset</var>).

   <li>Let <var>subfragment</var> be the result of
   <a lt="clone the contents of a range">cloning the contents</a> of <var>subrange</var>.

   <li><a>Append</a> <var>subfragment</var> to
   <var>clone</var>.
  </ol>

 <li>Return <var>fragment</var>.
</ol>

The <dfn method for=Range>cloneContents()</dfn>
method must return the result of <a lt="clone the contents of a range">cloning the contents</a>
of <a>context object</a>.

To <dfn export id=concept-range-insert for=Range>insert</dfn> a <a>node</a>
<var>node</var> into a <a>range</a>
<var>range</var>, run these steps:

<ol>
 <li>If <var>range</var>'s <a>start node</a> is a {{ProcessingInstruction}} or {{Comment}}
 <a>node</a>, is a {{Text}} <a>node</a> whose <a>parent</a> is null, or is <var>node</var>, then
 <a>throw</a> a {{HierarchyRequestError}}.

 <!--
 Behavior for Text node with null parent:

 IE9: Allows it to go through, resulting in the text/comment node having a non-null previousSibling but a null parentNode. (?!)
 Firefox 4.0: Throws non-standard exception
 Chrome 12 dev: Throws "HierarchyRequestError"
 Opera 11.00: Doesn't come up, doesn't allow ranges on detached nodes

 IE is clearly crazy, and non-standard exceptions are no good, so we go with
 WebKit.

 For a Comment node, see https://www.w3.org/Bugs/Public/show_bug.cgi?id=15350.
 IE9, Firefox 12.0a1, and Chrome 17 dev all agree on throwing a
 HierarchyRequestError.  Opera Next 12.00 alpha splits the comment, same as a
 text node.
 -->
 <li>Let <var>referenceNode</var> be null.

 <li>If <var>range</var>'s <a>start node</a>
 is a {{Text}} <a>node</a>,
 set <var>referenceNode</var> to that {{Text}}
 <a>node</a>. <!-- This will change when we split
 it. -->

 <li>Otherwise, set <var>referenceNode</var> to the
 <a>child</a> of
 <a>start node</a> whose
 <a>index</a> is
 <a>start offset</a>, and null if
 there is no such <a>child</a>.

 <li>Let <var>parent</var> be <var>range</var>'s
 <a>start node</a> if <var>referenceNode</var>
 is null, and <var>referenceNode</var>'s
 <a>parent</a> otherwise.

 <!-- IE9 and Chrome 12 dev throw an exception before splitting the text
 node if the insertBefore() is going to throw an exception (at least if the
 new node is the parent of the start node, for instance). Firefox 4.0 and
 Opera 11.00 don't.  Now that we have "ensure pre-insertion validity," we go
 with the IE/Chrome behavior because it's more correct.

 IE9 doesn't call splitText() if the offset is 0. This makes sense, but I go
 with what all other browsers do. -->
 <li><a>Ensure pre-insertion validity</a>
 of <var>node</var> into <var>parent</var> before
 <var>referenceNode</var>.

 <li>If <var>range</var>'s <a>start node</a> is a {{Text}} <a>node</a>, set
 <var>referenceNode</var> to the result of <a lt="split a Text node">splitting</a> it with
 offset <var>range</var>'s <a>start offset</a>.

 <li>If <var>node</var> is <var>referenceNode</var>, set <var>referenceNode</var> to its
 <a>next sibling</a>.
 <!-- Because we're about to remove node from its parent. -->

 <li>If <var>node</var>'s <a>parent</a> is not
 null, <a>remove</a> <var>node</var> from its
 <a>parent</a>.

 <!-- Browsers disagree on how to handle the case where the range is
 collapsed: do you increment the end offset so the node is now included, or
 not?  DOM 2 Range says no, and Firefox 12.0a1 follows that, but IE9, Chrome
 17 dev, and Opera Next 12.00 alpha all do increment.  Apparently this
 traces back to Acid3 at one point requiring the non-standard behavior.
 Previously the spec matched DOM 2 Range, but it changed to match the
 majority of browsers.  See
 https://www.w3.org/Bugs/Public/show_bug.cgi?id=15297.

 We have to be careful here, because if node is a DocumentFragment, we might
 have inserted any number of nodes, including zero.  One corner case is if
 we insert an empty DocumentFragment and the range is collapsed in a text
 node.  In that case, the text node gets split, but browsers disagree on
 what to do with the range's end.  IE9 leaves it in place; Chrome 17 dev
 moves it to the parent element, before the reference node; Opera Next 12.00
 alpha moves it to the beginning of the new text node.  The spec follows
 WebKit just because it happens to be easier for me to spec.

 The logic for how much to increment the position by is copied from the
 "insert" algorithm.  Getting the new offset right was surprisingly tricky.
 -->
 <li>Let <var>newOffset</var> be <var>parent</var>'s
 <a>length</a> if <var>referenceNode</var> is null,
 and <var>referenceNode</var>'s <a>index</a>
 otherwise.

 <li>Increase <var>newOffset</var> by <var>node</var>'s
 <a>length</a> if <var>node</var> is a
 {{DocumentFragment}} <a>node</a>, and one otherwise.

 <li><a>Pre-insert</a>
 <var>node</var> into <var>parent</var> before <var>referenceNode</var>.

 <li>If <var>range</var>'s <a>start</a> and
 <a>end</a> are the same, set <var>range</var>'s
 <a>end</a> to
 (<var>parent</var>, <var>newOffset</var>).
</ol>

The <dfn method for=Range>insertNode(<var>node</var>)</dfn>
method must <a for=Range>insert</a> <var>node</var> into
<a>context object</a>.

The
<dfn method for=Range>surroundContents(<var>newParent</var>)</dfn>
method must run these steps:

<!--
IE9 and Chrome 12 dev throw exceptions before doing any DOM mutations in at
least some cases, so they don't wind up modifying the DOM halfway. Like if you
try surrounding a selection with an ancestor. As with insertNode(), this is
slightly nicer, but Firefox 4.0 and Opera 11.00 don't do this, and their
behavior is slightly easier to spec, so I go with them for exceptions that are
thrown by things we call, like insertNode(). However, for
BAD_BOUNDARYPOINTS_ERR/INVALID_NODE_TYPE_ERR that we throw ourselves, I do the
check first thing, which matches everyone but Firefox.
-->

<ol>
 <li>If a non-{{Text}} <a>node</a> is
 <a>partially contained</a> in the <a>context object</a>,
 then <a>throw</a> an {{InvalidStateError}}.
 <!-- Makes some sense: otherwise we'd clone a bunch of containers, which is
 unexpected. -->
 <!-- XXX Could we rephrase this condition to be more algorithmic and less
 declarative?-->

 <li>If <var>newParent</var> is a {{Document}},
 {{DocumentType}}, or {{DocumentFragment}}
 <a>node</a>,
 then <a>throw</a> an {{InvalidNodeTypeError}}.
 <!-- But for Comment, Text, and ProcessingInstruction, we just fall through
 and throw a HIERARCHY_REQUEST_ERR when we try appendChild(). This makes
 absolutely no sense, but it's what DOM 2 Range specifies, and it's what
 IE9, Chrome 12 dev, and Opera 11.00 implement. Firefox 4.0 only throws
 INVALID_NODE_TYPE_ERR on DocumentFragments, it falls through to
 HIERARCHY_REQUEST_ERR for Documents and DocumentTypes.

 Firefox 4.0 does this check later on, so it will do DOM mutations of some
 type if passed a DocumentFragment. We match IE9, Chrome 12 dev, and Opera
 11.00 in doing the check early.

 If newParent is a Document/DocumentType/DocumentFragment, and some node is
 also partially contained, DOM 2 Range doesn't say whether to throw
 BAD_BOUNDARYPOINTS_ERR or INVALID_NODE_TYPE_ERR. IE9 and Chrome 12 dev
 throw INVALID_NODE_TYPE_ERR, while Firefox 4.0 and Opera 11.00 throw
 BAD_BOUNDARYPOINTS_ERR. I chose the latter because it's the first thing I
 happened to write down and it makes no real difference, with the even
 split. -->

 <li>Let <var>fragment</var> be the result of
 <a lt="extract a range">extracting</a> <a>context object</a>.
 <!-- If the range contains a DocumentType, Firefox 4.0 and Opera 11.00 don't
 immediately throw here. Firefox removes the non-DocumentType nodes and
 throws, Opera removes all nodes and doesn't throw. This applies to
 extractContents() proper, and also affects surroundContents(). I match DOM 2
 Range, IE9, and Chrome 12 dev. -->

 <li>If <var>newParent</var> has
 <a>children</a>,
 <a>replace all</a> with null within
 <var>newParent</var>.

 <li><a for=Range>Insert</a> <var>newParent</var> into
 <a>context object</a>.

 <li><a>Append</a> <var>fragment</var> to
 <var>newParent</var>.

 <li><a for=Range>Select</a> <var>newParent</var> within
 <a>context object</a>.
 <!-- Generally this isn't needed, because insertNode() will already do it,
 but it makes a difference in at least one corner case (when the original
 range lies in a single text node). -->
</ol>

The <dfn method for=Range>cloneRange()</dfn>
method must return a new <a>range</a> with the
same <a>start</a> and
<a>end</a> as the <a>context object</a>.

The <dfn method for=Range>detach()</dfn> method must
do nothing. <span class=note>Its functionality (disabling a
{{Range}} object) was removed, but the method itself is preserved
for compatibility.</span>

<hr>

<dl class=domintro>
 <dt><var>position</var> = <var>range</var> . {{Range/comparePoint(node, offset)}}
 <dd>Returns &minus;1 if the point is before the range, 0 if the point is
 in the range, and 1 if the point is after the range.

 <dt><var>intersects</var> = <var>range</var> . {{Range/intersectsNode(node)}}
 <dd>Returns whether <var>range</var> intersects
 <var>node</var>.
</dl>

<div class=impl>

The
<dfn method for=Range>isPointInRange(<var>node</var>, <var>offset</var>)</dfn>
must run these steps:
<!-- Tested October 2011 on Firefox 9.0a2 and Chrome 16 dev.  IE9 and Opera
11.50 don't support the method. -->

<ol>
 <li>If <var>node</var>'s <a for=tree>root</a> is
 different from the <a>context object</a>'s <a for=Range>root</a>, return false.
 <!-- This happens even if the offset is negative or too large, or if the node
 is a doctype, in both Firefox 9.0a2 and Chrome 16 dev. -->

 <li>If <var>node</var> is a <a>doctype</a>, then <a>throw</a> an {{InvalidNodeTypeError}}.
 <!-- Firefox 9.0a2 doesn't throw.  It ignores the offset and returns true or
 false depending on whether the doctype itself is in the range.  This makes
 some sense, but it doesn't match how other Range APIs handle doctypes, and
 having the second argument mandatory but ignored is just weird.  Thus I go
 with Chrome 16 dev, although I can see the merit in how Gecko works here. -->

 <li>If <var>offset</var> is greater than <var>node</var>'s <a>length</a>, then <a>throw</a> an
 {{IndexSizeError}}.
 <!-- Firefox 9.0a2 doesn't throw.  It seems to return true if the node is
 completely contained in the range, like with selectNode(), and false otherwise -
 even if all boundary points in the node are contained in the range, like
 with selectNodeContents().  This is weird, and inconsistent with other Range
 APIs, so I go with Chrome 16 dev.  This is probably an authoring bug, so it's
 best to throw anyway. -->

 <li>If (<var>node</var>, <var>offset</var>) is
 <a for=Range>before</a>
 <a>start</a> or
 <a for=Range>after</a>
 <a>end</a>, return false.

 <li>Return true.
</ol>


The
<dfn method for=Range>comparePoint(<var>node</var>, <var>offset</var>)</dfn>
method must run these steps:
<!-- IE9 doesn't support this method at all.  Firefox 12.0a1, Chrome 17 dev,
and Opera Next 12.00 alpha all do. -->

<ol>
 <li>If <var>node</var>'s <a for=tree>root</a> is different from the <a>context object</a>'s
 <a for=Range>root</a>, then <a>throw</a> a {{WrongDocumentError}}.
 <!-- Opera Next 12.00 alpha seems to return -1 in this case.  The spec matches
 Firefox 12.0a1 and Chrome 17 dev. -->

 <li>If <var>node</var> is a <a>doctype</a>, then <a>throw</a> an {{InvalidNodeTypeError}}.
 <!-- This matches Chrome 17 dev instead of Firefox 12.0a1 and Opera Next 12.00
 alpha, which don't throw and seem to just ignore the offset instead.  See
 comment for isPointInRange(). -->

 <li>If <var>offset</var> is greater than <var>node</var>'s <a>length</a>, then <a>throw</a> an
 {{IndexSizeError}}.
 <!-- This matches Chrome 17 dev instead of Firefox 12.0a1 and Opera Next 12.00
 alpha, which don't throw.  See comment for isPointInRange(). -->

 <li>If (<var>node</var>, <var>offset</var>) is
 <a for=Range>before</a>
 <a>start</a>, return &minus;1.

 <li>If (<var>node</var>, <var>offset</var>) is
 <a for=Range>after</a>
 <a>end</a>, return 1.

 <li>Return 0.
</ol>

<hr>

The
<dfn method for=Range>intersectsNode(<var>node</var>)</dfn>
method must run these steps:
<!-- Supported by Chrome 17 dev and Opera Next 12.00 alpha, but not IE9 or
Firefox 12.0a1. -->

<ol>
 <li>If <var>node</var>'s <a for=tree>root</a>
 is different from the <a>context object</a>'s
 <a for=Range>root</a>, return false.
 <!-- It seems like for doctypes, Opera Next 12.00 alpha throws
 InvalidNodeTypeError instead of returning false.  The spec follows Chrome
 17 dev. -->

 <li>Let <var>parent</var> be <var>node</var>'s
 <a>parent</a>.

 <li>If <var>parent</var> is null, return true.
 <!-- browsers currently throw, but are willing to change
      https://www.w3.org/Bugs/Public/show_bug.cgi?id=16759 -->

 <li>Let <var>offset</var> be <var>node</var>'s
 <a>index</a>.

 <li>If (<var>parent</var>, <var>offset</var>) is
 <a for=Range>before</a>
 <a>end</a> and (<var>parent</var>,
 <var>offset</var> + 1) is
 <a for=Range>after</a>
 <a>start</a>, return true.

 <li>Return false.
</ol>

</div>

<hr>

The <dfn export for=Range id=dom-range-stringifier>stringification behavior</dfn> must run
these steps:

<ol>
 <li>Let <var>s</var> be the empty string.

 <li>If <a>start node</a> is <a>end node</a>, and it is a
 {{Text}} <a>node</a>, return the
 substring of that {{Text}} <a>node</a>'s <a>data</a> beginning at
 <a>start offset</a> and ending at
 <a>end offset</a>.

 <li>If <a>start node</a> is a
 {{Text}} <a>node</a>, append to
 <var>s</var> the substring of that
 <a>node</a>'s
 <a>data</a> from the
 <a>start offset</a> until the end.

 <li>Append to <var>s</var> the concatenation, in
 <a>tree order</a>, of the
 <a>data</a> of all {{Text}}
 <a>nodes</a> that are <a>contained</a> in
 the <a>context object</a>.

 <li>If <a>end node</a> is a
 {{Text}} <a>node</a>, append to
 <var>s</var> the substring of that
 <a>node</a>'s
 <a>data</a> from its start until the
 <a>end offset</a>.

 <li>Return <var>s</var>.
</ol>

<hr>

<p class="note no-backref">The {{createContextualFragment()}}, {{Range/getClientRects()}},
and {{Range/getBoundingClientRect()}} methods are defined in other specifications.
[[DOM-Parsing]]
[[CSSOM-VIEW]]



<h2 id="traversal">Traversal</h2>

{{NodeIterator}} and {{TreeWalker}} objects can be used
to filter and traverse <a>node</a>
<a>trees</a>.

Each {{NodeIterator}} and {{TreeWalker}} object also
has an associated <dfn export id=concept-traversal-root for="traversal">root</dfn>
<a>node</a>,
<dfn export id=concept-traversal-whattoshow for="traversal">whatToShow</dfn> bitmask, and
<dfn export id=concept-traversal-filter for="traversal">filter</dfn> callback.

To <dfn export id=concept-node-filter for=Node>filter</dfn> <var>node</var> run
these steps:

<ol>
 <li>Let <var>n</var> be <var>node</var>'s
 {{Node/nodeType}} attribute value minus 1.
 <li>If the <var>n</var><sup>th</sup> bit (where 0 is the least
 significant bit) of
 <a for="traversal">whatToShow</a> is not set,
 return {{NodeFilter/FILTER_SKIP}}.
 <!-- !((1 << (node.nodeType - 1)) & whatToShow) -->
 <li>If <a for="traversal">filter</a> is null,
 return {{NodeFilter/FILTER_ACCEPT}}.
 <li>Let <var>result</var> be the return value of calling
 <a for="traversal">filter</a>'s
 {{NodeFilter/acceptNode()}} with <var>node</var> as
 argument. Rethrow any exceptions.
 <!-- no need to pass callback this value; it's undefined which becomes the global object -->
 <li>Return <var>result</var>.
</ol>


<h3 id="interface-nodeiterator">Interface {{NodeIterator}}</h3>

<pre class=idl>
[Exposed=Window]
interface NodeIterator {
  [SameObject] readonly attribute Node root;
  readonly attribute Node referenceNode;
  readonly attribute boolean pointerBeforeReferenceNode;
  readonly attribute unsigned long whatToShow;
  readonly attribute NodeFilter? filter;

  Node? nextNode();
  Node? previousNode();

  void detach();
};
</pre>

<p class="note no-backref">{{NodeIterator}} objects can be created using the
{{createNodeIterator()}} method.

Each {{NodeIterator}} object has an associated
<dfn export for=NodeIterator id="iterator-collection">iterator collection</dfn>, which is a
<a>collection</a> rooted at
<a for="traversal">root</a>, whose filter matches any
<a>node</a>.

<p class="note no-backref">As mentioned earlier, {{NodeIterator}} objects have an
associated
<a for="traversal">root</a> <a>node</a>,
<a for="traversal">whatToShow</a> bitmask, and
<a for="traversal">filter</a> callback as well.

The <dfn><code>NodeIterator</code> pre-removing steps</dfn> given a
<var>nodeIterator</var> and <var>toBeRemovedNode</var>, are as follows:

<ol>
 <li><p>If <var>toBeRemovedNode</var> is not an <a>inclusive ancestor</a> of the
 {{NodeIterator/referenceNode}} attribute value, terminate these steps.

 <li>
  <p>If the {{NodeIterator/pointerBeforeReferenceNode}} attribute value is true, run these
  substeps:

  <ol>
   <li><p>Let <var>next</var> be <var>toBeRemovedNode</var>'s first <a>following</a>
   <a>node</a> that is an <a>inclusive descendant</a> of <var>nodeIterator</var>'s
   <a for=traversal>root</a> and is not an <a>inclusive descendant</a> of
   <var>toBeRemovedNode</var>, and null if there is no such <a>node</a>.

   <li><p>If <var>next</var> is non-null, set <var>nodeIterator</var>'s
   {{NodeIterator/referenceNode}} attribute to <var>next</var> and terminate these steps.

   <li>
    Otherwise, set <var>nodeIterator</var>'s
    {{NodeIterator/pointerBeforeReferenceNode}} attribute to false.

    <p class="note no-backref">Steps are not terminated here.
  </ol>

 <li><p>Set <var>nodeIterator</var>'s {{NodeIterator/referenceNode}} attribute to
 <var>toBeRemovedNode</var>'s <a>parent</a>, if <var>toBeRemovedNode</var>'s <a>previous sibling</a>
 is null, and to the <a>inclusive descendant</a> of <var>toBeRemovedNode</var>'s
 <a>previous sibling</a> that appears last in <a>tree order</a> otherwise.
</ol>

<hr>

The <dfn attribute for="NodeIterator">root</dfn> attribute
must return <a for="traversal">root</a>.

The
<dfn attribute for="NodeIterator">referenceNode</dfn>
and
<dfn attribute for="NodeIterator">pointerBeforeReferenceNode</dfn>
attributes must return what they were initialized to.

The <dfn attribute for="NodeIterator">whatToShow</dfn>
attribute must return
<a for="traversal">whatToShow</a>.

The <dfn attribute for="NodeIterator">filter</dfn>
attribute must return <a for="traversal">filter</a>.

To <dfn export id=concept-nodeiterator-traverse for="NodeIterator">traverse</dfn> in direction
<var>direction</var> run these steps:

<ol>
 <li>Let <var>node</var> be the value of the
 {{NodeIterator/referenceNode}} attribute.

 <li>Let <var>before node</var> be the value of the
 {{NodeIterator/pointerBeforeReferenceNode}}
 attribute.

 <li>
  Run these substeps:
  <ol>
   <li>
    <dl class=switch>
     <dt>If <var>direction</var> is next
     <dd>
      If <var>before node</var> is false, let <var>node</var>
      be the first <a>node</a>
      <a>following</a>
      <var>node</var> in the <a>iterator collection</a>. If
      there is no such <a>node</a> return null.
      If <var>before node</var> is true, set it to false.
     <dt>If <var>direction</var> is previous
     <dd>
      If <var>before node</var> is true, let <var>node</var>
      be the first <a>node</a>
      <a>preceding</a>
      <var>node</var> in the <a>iterator collection</a>. If
      there is no such <a>node</a> return null.
      If <var>before node</var> is false, set it to true.
    </dl>
   <li><a for=Node>Filter</a>
   <var>node</var> and let <var>result</var> be the return
   value.
   <li>
    If <var>result</var> is
    {{NodeFilter/FILTER_ACCEPT}}, go to the
    next step in the overall set of steps.
    Otherwise, run these substeps again.
  </ol>
 <li>Set the
 {{NodeIterator/referenceNode}} attribute
 to <var>node</var>, set the
 {{NodeIterator/pointerBeforeReferenceNode}}
 attribute to <var>before node</var>, and return
 <var>node</var>.
</ol>

The <dfn method for="NodeIterator">nextNode()</dfn>
method must <a for="NodeIterator">traverse</a> in
direction next.

The
<dfn method for="NodeIterator">previousNode()</dfn>
method must <a for="NodeIterator">traverse</a> in
direction previous.

The <dfn method for="NodeIterator">detach()</dfn>
method must do nothing. <span class=note>Its functionality (disabling a
{{NodeIterator}} object) was removed, but the method itself is preserved
for compatibility.</span>


<h3 id='interface-treewalker'>Interface {{TreeWalker}}</h3>

<pre class=idl>
[Exposed=Window]
interface TreeWalker {
  [SameObject] readonly attribute Node root;
  readonly attribute unsigned long whatToShow;
  readonly attribute NodeFilter? filter;
           attribute Node currentNode;

  Node? parentNode();
  Node? firstChild();
  Node? lastChild();
  Node? previousSibling();
  Node? nextSibling();
  Node? previousNode();
  Node? nextNode();
};</pre>


<p class="note no-backref">{{TreeWalker}} objects can be created using the
{{createTreeWalker()}} method.

<p class="note no-backref">As mentioned earlier {{TreeWalker}} objects have an
associated <a for="traversal">root</a>
<a>node</a>,
<a for="traversal">whatToShow</a> bitmask, and
<a for="traversal">filter</a> callback.

The <dfn attribute for="TreeWalker">root</dfn> attribute must
return <a for="traversal">root</a>.

The <dfn attribute for="TreeWalker">whatToShow</dfn>
attribute must return
<a for="traversal">whatToShow</a>.

The <dfn attribute for="TreeWalker">filter</dfn> attribute
must return <a for="traversal">filter</a>.

The <dfn attribute for="TreeWalker">currentNode</dfn>
attribute must return what it was initialized to.

Setting the {{TreeWalker/currentNode}}
attribute must set it to the new value.


The <dfn method for="TreeWalker">parentNode()</dfn>
method must run these steps:

<ol>
 <li>Let <var>node</var> be the value of the
 {{TreeWalker/currentNode}} attribute.

 <li>
  While <var>node</var> is not null and is not
  <a for="traversal">root</a>, run these substeps:

  <ol>
   <li>Let <var>node</var> be <var>node</var>'s
   <a>parent</a>.

   <li>If <var>node</var> is not null and
   <a for=Node>filtering</a> <var>node</var>
   returns {{NodeFilter/FILTER_ACCEPT}},
   then set the {{TreeWalker/currentNode}}
   attribute to <var>node</var>, return <var>node</var>.
  </ol>

 <li>Return null.
</ol>

To <dfn export for=TreeWalker id=concept-traverse-children>traverse children</dfn> of type
<var>type</var>, run these steps:

<ol>
 <li>Let <var>node</var> be the value
 of the {{TreeWalker/currentNode}} attribute.

 <li>Set <var>node</var> to <var>node</var>'s
 <a>first child</a> if
 <var>type</var> is first, and <var>node</var>'s
 <a>last child</a> if
 <var>type</var> is last.

 <li>If <var>node</var> is null, return null.

 <li>
  <dfn export id=concept-traverse-children-main lt="Traverse children main step">Main</dfn>:
  Repeat these substeps:

  <ol>
   <li><a for=Node>Filter</a>
   <var>node</var> and let <var>result</var> be the return
   value.

   <li>If <var>result</var> is
   {{NodeFilter/FILTER_ACCEPT}}, then set
   the {{TreeWalker/currentNode}}
   attribute to <var>node</var> and return <var>node</var>.

   <li>
    If <var>result</var> is
    {{NodeFilter/FILTER_SKIP}}, run these
    subsubsteps:

    <ol>
     <li>Let <var>child</var> be <var>node</var>'s
     <a>first child</a> if
     <var>type</var> is first, and <var>node</var>'s
     <a>last child</a> if
     <var>type</var> is last.

     <li>If <var>child</var> is not null, set <var>node</var>
     to <var>child</var> and goto
     <a lt="Traverse children main step">Main</a>.
    </ol>

   <li>
    Repeat these subsubsteps:

    <ol>
     <li>Let <var>sibling</var> be <var>node</var>'s
     <a>next sibling</a> if
     <var>type</var> is first, and <var>node</var>'s
     <a>previous sibling</a> if
     <var>type</var> is last.

     <li>If <var>sibling</var> is not null, set
     <var>node</var> to <var>sibling</var> and goto
     <a lt="Traverse children main step">Main</a>.

     <li>Let <var>parent</var> be <var>node</var>'s
     <a>parent</a>.

     <li>If <var>parent</var> is null, <var>parent</var> is
     <a for="traversal">root</a>, or
     <var>parent</var> is
     {{TreeWalker/currentNode}} attribute's
     value, return null.

     <li>Otherwise, set <var>node</var> to <var>parent</var>.
    </ol>
  </ol>
</ol>

The <dfn method for="TreeWalker">firstChild()</dfn>
method must <a>traverse children</a>
of type first.

The <dfn method for="TreeWalker">lastChild()</dfn>
method must <a>traverse children</a>
of type last.

To <dfn export id=concept-traverse-siblings>traverse siblings</dfn> of type
<var>type</var> run these steps:

<ol>
 <li>Let <var>node</var> be the value of the
 {{TreeWalker/currentNode}} attribute.

 <li>If <var>node</var> is
 <a for="traversal">root</a>, return null.

 <li>
  Run these substeps:

  <ol>
   <li>Let <var>sibling</var> be <var>node</var>'s
   <a>next sibling</a> if
   <var>type</var> is next, and <var>node</var>'s
   <a>previous sibling</a> if
   <var>type</var> is previous.

   <li>
    While <var>sibling</var> is not null, run these subsubsteps:

    <ol>
     <li>Set <var>node</var> to <var>sibling</var>.

     <li><a for=Node>Filter</a>
     <var>node</var> and let <var>result</var> be the return
     value.

     <li>If <var>result</var> is
     {{NodeFilter/FILTER_ACCEPT}}, then set
     the {{TreeWalker/currentNode}}
     attribute to <var>node</var> and return <var>node</var>.

     <li>Set <var>sibling</var> to <var>node</var>'s
     <a>first child</a> if
     <var>type</var> is next, and <var>node</var>'s
     <a>last child</a> if
     <var>type</var> is previous.

     <li>If <var>result</var> is
     {{NodeFilter/FILTER_REJECT}} or
     <var>sibling</var> is null, then set <var>sibling</var> to
     <var>node</var>'s
     <a>next sibling</a> if
     <var>type</var> is next, and <var>node</var>'s
     <a>previous sibling</a> if
     <var>type</var> is previous.
    </ol>

   <li>Set <var>node</var> to its
   <a>parent</a>.

   <li>If <var>node</var> is null or is
   <a for="traversal">root</a>, return null.

   <li><a for=Node>Filter</a>
   <var>node</var> and if the return value is
   {{NodeFilter/FILTER_ACCEPT}}, then
   return null.
   <!-- XXX WTF? -->

   <li>Run these substeps again.
  </ol>
</ol>

The
<dfn method for="TreeWalker">nextSibling()</dfn>
method must <a>traverse siblings</a>
of type next.

The
<dfn method for="TreeWalker">previousSibling()</dfn>
method must <a>traverse siblings</a>
of type previous.

The
<dfn method for="TreeWalker">previousNode()</dfn>
method must run these steps:

<ol>
 <li>Let <var>node</var> be the value of the
 {{TreeWalker/currentNode}} attribute.

 <li>
  While <var>node</var> is not
  <a for="traversal">root</a>, run these substeps:

  <ol>
   <li>Let <var>sibling</var> be the
   <a>previous sibling</a> of
   <var>node</var>.

   <li>
    While <var>sibling</var> is not null, run these subsubsteps:

    <ol>
     <li>Set <var>node</var> to <var>sibling</var>.

     <li><a for=Node>Filter</a>
     <var>node</var> and let <var>result</var> be the return
     value.

     <li>While <var>result</var> is not
     {{NodeFilter/FILTER_REJECT}} and
     <var>node</var> has a
     <a>child</a>, set <var>node</var>
     to its <a>last child</a> and then
     <a for=Node>filter</a> <var>node</var> and
     set <var>result</var> to the return value.

     <li>If <var>result</var> is
     {{NodeFilter/FILTER_ACCEPT}}, then set
     the {{TreeWalker/currentNode}}
     attribute to <var>node</var> and return <var>node</var>.

     <li>Set <var>sibling</var> to the
     <a>previous sibling</a> of
     <var>node</var>.
    </ol>

   <li>If <var>node</var> is
   <a for="traversal">root</a> or <var>node</var>'s
   <a>parent</a> is null, return null.

   <li>Set <var>node</var> to its
   <a>parent</a>.

   <li><a for=Node>Filter</a>
   <var>node</var> and if the return value is
   {{NodeFilter/FILTER_ACCEPT}}, then set
   the {{TreeWalker/currentNode}} attribute
   to <var>node</var> and return <var>node</var>.
  </ol>

 <li>Return null.
</ol>

The <dfn method for="TreeWalker">nextNode()</dfn>
method must run these steps:

<ol>
 <li>Let <var>node</var> be the value of the
 {{TreeWalker/currentNode}} attribute.

 <li>Let <var>result</var> be
 {{NodeFilter/FILTER_ACCEPT}}.

 <li>
  Run these substeps:

  <ol>
   <li>
    While <var>result</var> is not
    {{NodeFilter/FILTER_REJECT}} and
    <var>node</var> has a <a>child</a>,
    run these subsubsteps:

    <ol>
     <li>Set <var>node</var> to its
     <a>first child</a>.

     <li><a for=Node>Filter</a>
     <var>node</var> and set <var>result</var> to the return
     value.

     <li>If <var>result</var> is
     {{NodeFilter/FILTER_ACCEPT}}, then set
     the {{TreeWalker/currentNode}} attribute
     to <var>node</var> and return <var>node</var>.
    </ol>

   <li>
    If a <a>node</a> is
    <a>following</a>
    <var>node</var> and is not
    <a>following</a>
    <a for="traversal">root</a>, set
    <var>node</var> to the first such
    <a>node</a>.
    Otherwise, return null.
    <!-- Implemented as iterating over parent/nextSibling -->

   <li><a for=Node>Filter</a>
   <var>node</var> and set <var>result</var> to the return
   value.

   <li>If <var>result</var> is
   {{NodeFilter/FILTER_ACCEPT}}, then set
   the {{TreeWalker/currentNode}} attribute
   to <var>node</var> and return <var>node</var>.

   <li>Run these substeps again.
  </ol>
</ol>



<h3 id="interface-nodefilter">Interface {{NodeFilter}}</h3>

<pre class=idl>
[Exposed=Window]
callback interface NodeFilter {
  // Constants for acceptNode()
  const unsigned short FILTER_ACCEPT = 1;
  const unsigned short FILTER_REJECT = 2;
  const unsigned short FILTER_SKIP = 3;

  // Constants for whatToShow
  const unsigned long SHOW_ALL = 0xFFFFFFFF;
  const unsigned long SHOW_ELEMENT = 0x1;
  const unsigned long SHOW_ATTRIBUTE = 0x2; // historical
  const unsigned long SHOW_TEXT = 0x4;
  const unsigned long SHOW_CDATA_SECTION = 0x8; // historical
  const unsigned long SHOW_ENTITY_REFERENCE = 0x10; // historical
  const unsigned long SHOW_ENTITY = 0x20; // historical
  const unsigned long SHOW_PROCESSING_INSTRUCTION = 0x40;
  const unsigned long SHOW_COMMENT = 0x80;
  const unsigned long SHOW_DOCUMENT = 0x100;
  const unsigned long SHOW_DOCUMENT_TYPE = 0x200;
  const unsigned long SHOW_DOCUMENT_FRAGMENT = 0x400;
  const unsigned long SHOW_NOTATION = 0x800; // historical

  unsigned short acceptNode(Node node);
};
</pre>

{{NodeFilter}} objects can be used as
<a for="traversal">filter</a> callback and provide
constants for the <a for="traversal">whatToShow</a>
bitmask.

<p class="note no-backref">It is typically implemented as a JavaScript function.

These constants can be used as callback return value:

<ul class="brief">
 <li><dfn const for="NodeFilter">FILTER_ACCEPT</dfn> (1);
 <li><dfn const for="NodeFilter">FILTER_REJECT</dfn> (2);
 <li><dfn const for="NodeFilter">FILTER_SKIP</dfn> (3).
</ul>

These constants can be used for the
<a for="traversal">whatToShow</a> bitmask:

<ul class="brief">
 <li><dfn const for="NodeFilter">SHOW_ALL</dfn> (4294967295, FFFFFFFF in hexadecimal);
 <li><dfn const for="NodeFilter">SHOW_ELEMENT</dfn> (1);
 <!-- AttrExodus
 <li><dfn const for="NodeFilter">SHOW_ATTRIBUTE</dfn> (2, historical);
 -->
 <li><dfn const for="NodeFilter">SHOW_TEXT</dfn> (4);
 <!-- XXX still questionable
 <li><dfn const for="NodeFilter">SHOW_CDATA_SECTION</dfn> (8; historical);
 -->
 <li><dfn const for="NodeFilter">SHOW_PROCESSING_INSTRUCTION</dfn> (64, 40 in hexadecimal);
 <li><dfn const for="NodeFilter">SHOW_COMMENT</dfn> (128, 80 in hexadecimal);
 <li><dfn const for="NodeFilter">SHOW_DOCUMENT</dfn> (256, 100 in hexadecimal);
 <li><dfn const for="NodeFilter">SHOW_DOCUMENT_TYPE</dfn> (512, 200 in hexadecimal);
 <li><dfn const for="NodeFilter">SHOW_DOCUMENT_FRAGMENT</dfn> (1024, 400 in hexadecimal).
</ul>



<h2 id="sets">Sets</h2>

<p class="note no-backref">Yes, the name {{DOMTokenList}} is an unfortunate legacy mishap.

<h3 id="interface-domtokenlist">Interface {{DOMTokenList}}</h3>

<pre class="idl">
interface DOMTokenList {
  readonly attribute unsigned long length;
  getter DOMString? item(unsigned long index);
  boolean contains(DOMString token);
  [CEReactions] void add(DOMString... tokens);
  [CEReactions] void remove(DOMString... tokens);
  [CEReactions] boolean toggle(DOMString token, optional boolean force);
  [CEReactions] void replace(DOMString token, DOMString newToken);
  boolean supports(DOMString token);
  [CEReactions] attribute DOMString value;
  stringifier;
  iterable&lt;DOMString>;
};
</pre>

<p>A {{DOMTokenList}} object has an associated ordered set of
<dfn export id=concept-dtl-tokens for="DOMTokenList">tokens</dfn>, which is initially empty.

<p>A {{DOMTokenList}} object also has an associated <a for="/">element</a> and an <a>attribute</a>'s
<a for=Attr>local name</a>.

<a lt="Other applicable specifications">Specifications</a> may define
<dfn export for=Node id=concept-supported-tokens>supported tokens</dfn> for a {{DOMTokenList}}'s
associated <a>attribute</a>'s <a for=Attr>local name</a>.

<p>A {{DOMTokenList}} object's
<dfn export id=concept-domtokenlist-validation for="DOMString">validation steps</dfn> for a given
<var>token</var> are:

<ol>
 <li><p>If the associated <a>attribute</a>'s <a for=Attr>local name</a> does not define
 <a>supported tokens</a>, <a>throw</a> a <code>TypeError</code>.

 <li><p>Let <var>lowercase token</var> be a copy of <var>token</var>,
 <a>converted to ASCII lowercase</a>.

 <li><p>If <var>lowercase token</var> is present in <a>supported tokens</a>, return true.

 <li><p>Return false.
</ol>

<p>A {{DOMTokenList}} object's <dfn id=concept-dtl-update for="DOMTokenList">update steps</dfn> are
to <a>set an attribute value</a> for the associated <a for="/">element</a> using associated
<a>attribute</a>'s <a for=Attr>local name</a> and the result of running the
<a>ordered set serializer</a> for <a>tokens</a>.

<p>A {{DOMTokenList}} object's <dfn id=concept-dtl-serialize for=DOMTokenList>serialize steps</dfn>
are to return the result of running <a>get an attribute value</a> given the associated
<a for=/>element</a> and the associated <a>attribute</a>'s <a for=Attr>local name</a>.</p>

<hr>

<p>A {{DOMTokenList}} object has these <a>attribute change steps</a> for its associated
<a for=/>element</a>:

<ol>
 <li><p>If <var>localName</var> is associated attribute's <a for=Attr>local name</a>,
 <var>namespace</var> is null, and <var>value</var> is null, then set <a>tokens</a> to the empty
 set.

 <li><p>Otherwise, <var>localName</var> is associated attribute's <a for=Attr>local name</a>,
 <var>namespace</var> is null, then set <a>tokens</a> to <var>value</var>,
 <a lt="ordered set parser">parsed</a>.
</ol>

<p>When a {{DOMTokenList}} object is created, run these substeps:

<ol>
 <li><p>Let <var>element</var> be associated <a for=/>element</a>.

 <li><p>Let <var>localName</var> be associated attribute's <a for=Attr>local name</a>.

 <li><p>Let <var>value</var> be the result of
 <a lt="get an attribute by namespace and local name">getting an attribute</a> given null,
 <var>localName</var>, and <var>element</var>.

 <li><p>Run the <a>attribute change steps</a> for <var>element</var>, <var>localName</var>,
 <var>value</var>, <var>value</var>, and null.
</ol>

<dl class="domintro">
 <dt><code><var>tokenlist</var> . {{DOMTokenList/length}}</code>
 <dd><p>Returns the number of tokens.

 <dt><code><var>tokenlist</var> . {{DOMTokenList/item(index)}}</code>
 <dt><code><var>tokenlist</var>[<var>index</var>]</code>
 <dd><p>Returns the token with index <var>index</var>.

 <dt><code><var>tokenlist</var> . {{DOMTokenList/contains(token)}}</code>
 <dd><p>Returns true if <var>token</var> is present, and false otherwise.

 <dt><code><var>tokenlist</var> . <a for=DOMTokenList lt="add()">add(<var>tokens</var>&hellip;)</a></code>
 <dd>
  <p>Adds all arguments passed, except those already present.
  <p>Throws a {{SyntaxError}} if one of the arguments is the empty string.
  <p>Throws an {{InvalidCharacterError}} if one of the arguments contains any
  <a>ASCII whitespace</a>.

 <dt><code><var>tokenlist</var> . <a for=DOMTokenList lt="remove()">remove(<var>tokens</var>&hellip;)</a></code>
 <dd>
  <p>Removes arguments passed, if they are present.
  <p>Throws a {{SyntaxError}} if one of the arguments is the empty string.
  <p>Throws an {{InvalidCharacterError}} if one of the arguments contains any
  <a>ASCII whitespace</a>.

 <dt><code><var>tokenlist</var> . <a method for=DOMTokenList lt="toggle()">toggle(<var>token</var> [, <var>force</var>])</a></code>
 <dd>
  <p>If <var>force</var> is not given, "toggles" <var>token</var>, removing it if it's present and
  adding it if it's not present. If <var>force</var> is true, adds <var>token</var>
  (same as {{add()}}). If <var>force</var> is false, removes <var>token</var> (same
  as {{DOMTokenList/remove()}}).
  <p>Returns true if <var>token</var> is now present, and false otherwise.
  <p>Throws a {{SyntaxError}} if <var>token</var> is empty.
  <p>Throws an {{InvalidCharacterError}} if <var>token</var> contains any spaces.

 <dt><code><var>tokenlist</var> . <a method for=DOMTokenList lt=replace()>replace(<var>token</var>, <var>newToken</var>)</a></code>
 <dd>
  <p>Replaces <var>token</var> with <var>newToken</var>.
  <p>Throws a {{SyntaxError}} if one of the arguments is the empty string.
  <p>Throws an {{InvalidCharacterError}} if one of the arguments contains any
  <a>ASCII whitespace</a>.

 <dt><code><var>tokenlist</var> . <a method for=DOMTokenList lt="supports()">supports(<var>token</var>)</a></code>
 <dd>
  <p>Returns true if <var>token</var> is in the associated attribute's supported tokens. Returns
  false otherwise.
  <p>Throws a <code>TypeError</code> if the associated attribute has no supported tokens defined.

 <dt><code><var>tokenlist</var> . {{DOMTokenList/value}}</code>
 <dd>
  <p>Returns the associated set as string.
  <p>Can be set, to change the associated attribute.
</dl>

<p>The <dfn attribute for=DOMTokenList><code>length</code></dfn> attribute' getter must return the
number of tokens in the <a>tokens</a>.

<p>The object's <a>supported property indices</a> are the numbers in the range zero to the number of
tokens in <a>tokens</a> minus one, unless <a>tokens</a> is  empty, in which case there are no
<a>supported property indices</a>.

<p>The <dfn method for="DOMTokenList"><code>item(<var>index</var>)</code></dfn> method, when
invoked, must run these steps:

<ol>
 <li><p>If <var>index</var> is equal to or greater than the number of tokens in <a>tokens</a>,
 return null.

 <li><p>Return the <var>index</var><sup>th</sup> token in <a>tokens</a>.
</ol>

<p>The <dfn method for="DOMTokenList"><code>contains(<var>token</var>)</code></dfn> method, when
invoked, must return true if <var>token</var> is in <a>tokens</a>, and false otherwise.</p>

<p>The
<dfn method for="DOMTokenList" lt="add(tokens)|add()"><code>add(<var>tokens</var>&hellip;)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li>
  <p>For each <var>token</var> in <var>tokens</var>, run these substeps:

  <ol>
   <li><p>If <var>token</var> is the empty string, then <a>throw</a> a {{SyntaxError}}.

   <li><p>If <var>token</var> contains any <a>ASCII whitespace</a>, then <a>throw</a> an
   {{InvalidCharacterError}}.
  </ol>

 <li><p>For each <var>token</var> in <var>tokens</var>, in given order, that is not in
 <a>tokens</a>, append <var>token</var> to <a>tokens</a>.

 <li><p>Run the <a>update steps</a>.
</ol>

<p>The
<dfn method for="DOMTokenList" lt="remove(tokens)|remove()"><code>remove(<var>tokens</var>&hellip;)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li>
  <p>For each <var>token</var> in <var>tokens</var>, run these substeps:

  <ol>
   <li><p>If <var>token</var> is the empty string, then <a>throw</a> a {{SyntaxError}}.

   <li><p>If <var>token</var> contains any <a>ASCII whitespace</a>, then <a>throw</a> an
   {{InvalidCharacterError}}.
  </ol>

 <li><p>For each <var>token</var> in <var>tokens</var>, remove <var>token</var> from <a>tokens</a>.

 <li><p>Run the <a>update steps</a>.
</ol>

<p>The <dfn method for=DOMTokenList><code>toggle(<var>token</var>, <var>force</var>)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li><p>If <var>token</var> is the empty string, then <a>throw</a> a {{SyntaxError}}.

 <li><p>If <var>token</var> contains any <a>ASCII whitespace</a>, then <a>throw</a> an
 {{InvalidCharacterError}}.

 <li>
  <p>If <var>token</var> is in <a>tokens</a>, run these substeps:

  <ol>
   <li><p>If <var>force</var> is either not passed or is false, then remove <var>token</var> from
   <a>tokens</a>, run the <a>update steps</a>, and return false.

   <li><p>Otherwise, return true.
  </ol>

 <li>
  <p>Otherwise, run these substeps:

  <ol>
   <li><p>If <var>force</var> is passed and is false, return false.

   <li><p>Otherwise, append <var>token</var> to <a>tokens</a>, run the <a>update steps</a>, and
   return true.
  </ol>
</ol>

<p>The
<dfn method for=DOMTokenList><code>replace(<var>token</var>, <var>newToken</var>)</code></dfn>
method, when invoked, must run these steps:
<!-- Argument order based on String.prototype.replace(), not replaceChild() -->

<ol>
 <li><p>If either <var>token</var> or <var>newToken</var> is the empty string, then <a>throw</a> a
 {{SyntaxError}}.

 <li><p>If either <var>token</var> or <var>newToken</var> contains any <a>ASCII whitespace</a>, then
 <a>throw</a> an {{InvalidCharacterError}}.

 <li><p>If <var>token</var> is not in <a>tokens</a>, terminate these steps.

 <li><p>Replace <var>token</var> in <a>tokens</a> with <var>newToken</var>.

 <li><p>Run the <a>update steps</a>.
</ol>

<p>The
<dfn method for="DOMTokenList" lt="supports(token)"><code>supports(<var>token</var>)</code></dfn>
method, when invoked, must run these steps:

<ol>
 <li><p>Let <var>result</var> be the return value of <a>validation steps</a> called with
 <var>token</var>. Rethrow any exceptions.

 <li><p>Return <var>result</var>.
</ol>

<p>The <dfn attribute for=DOMTokenList><code>value</code></dfn> attribute must return the
result of running <a>context object</a>'s <a>serialize steps</a>.

<p>Setting the {{DOMTokenList/value}} attribute must <a>set an attribute value</a> for the
associated <a for="/">element</a> using associated <a>attribute</a>'s <a for=Attr>local name</a> and
the given value.

<p>The <dfn export for=DOMTokenList id=dom-domtokenlist-stringifier>stringification behavior</dfn>
must return the result of running <a>context object</a>'s <a>serialize steps</a>.


<h2 id='historical'>Historical</h2>

As explained in <a href="#goals">goals</a> this specification is a
significant revision of various DOM specifications. This section attempts to
enumerate the changes.


<h3 id='dom-events-changes'>DOM Events</h3>

These are the changes made to the features described in the
"DOM Event Architecture", "Basic Event Interfaces", "Mutation Events", and
"Mutation Name Event Types" chapters of <cite>DOM Level 3 Events</cite>. The
other chapters are defined by the <cite>UI Events</cite> specification.
[[!UIEVENTS]]

<ul class=brief>
 <li>Events have constructors now.
 <li>Removes <dfn interface>MutationEvent</dfn>, and
 <dfn interface>MutationNameEvent</dfn>.
 <li>Fire is no longer synonymous with dispatch, but includes initializing
 an event.
 <li>The propagation and canceled flags are unset when invoking
 {{Event/initEvent()}} rather than after
 dispatch.
</ul>


<h3 id='dom-core-changes'>DOM Core</h3>

These are the changes made to the features described in
<cite>DOM Level 3 Core</cite>.

{{DOMString}}, {{DOMException}}, and
{{DOMTimeStamp}} are now defined in Web IDL.

{{Node}} now inherits from {{EventTarget}}.

<a>Nodes</a> are implicitly
<a>adopted</a> across
<a>document</a> boundaries.

<a>Doctypes</a> now always have a
<a>node document</a> and can be moved
across <a>document</a> boundaries.

{{ProcessingInstruction}} now inherits from
{{CharacterData}}.

<dfn method for=Node>hasAttributes()</dfn> and
<dfn attribute for=Node>attributes</dfn> moved from {{Node}}
to {{Element}}.

<dfn attribute for=Node>namespaceURI</dfn>,
<dfn attribute for=Node>prefix</dfn>, and
<dfn attribute for=Node>localName</dfn> moved from {{Node}} to
{{Element}} and {{Attr}}.

The remainder of interfaces and interface members listed in this section
were removed to simplify the DOM platform. Implementations conforming to
this specification will not support them.

<p class=warning>It is not yet clear if it would be web-compatible to
remove all the following features. The editors welcome any data showing that
some of these features should be reintroduced.

Interfaces:
<ul class=brief dfn-type="interface">
 <li><dfn><code>CDATASection</code></dfn>
 <li><dfn><code>DOMConfiguration</code></dfn>
 <li><dfn><code>DOMError</code></dfn>
 <li><dfn><code>DOMErrorHandler</code></dfn>
 <li><dfn><code>DOMImplementationList</code></dfn>
 <li><dfn><code>DOMImplementationSource</code></dfn>
 <li><dfn><code>DOMLocator</code></dfn>
 <li><dfn><code>DOMObject</code></dfn>
 <li><dfn><code>DOMStringList</code></dfn>
 <li><dfn><code>DOMUserData</code></dfn>
 <li><dfn><code>Entity</code></dfn>
 <li><dfn><code>EntityReference</code></dfn>
 <li><dfn><code>NameList</code></dfn>
 <li><dfn><code>Notation</code></dfn>
 <li><dfn><code>TypeInfo</code></dfn>
 <li><dfn><code>UserDataHandler</code></dfn>
</ul>

Interface members:
<dl>
 <dt>{{Node}}
 <dd>
  <ul class=brief>
   <li><dfn attribute for=Node>isSupported</dfn>
   <li><dfn method for=Node>getFeature()</dfn>
   <li><dfn method for=Node>getUserData()</dfn>
   <li><dfn method for=Node>setUserData()</dfn>
  </ul>

 <dt>{{Document}}
 <dd>
  <ul class=brief>
   <li><dfn method for=Document>createCDATASection()</dfn>
   <li><dfn method for=Document>createEntityReference()</dfn>
   <li><dfn attribute for=Document>xmlEncoding</dfn>
   <li><dfn attribute for=Document>xmlStandalone</dfn>
   <li><dfn attribute for=Document>xmlVersion</dfn>
   <li><dfn attribute for=Document>strictErrorChecking</dfn>
   <li><dfn attribute for=Document>domConfig</dfn>
   <li><dfn method for=Document>normalizeDocument()</dfn>
   <li><dfn method for=Document>renameNode()</dfn>
  </ul>

 <dt>{{DOMImplementation}}
 <dd>
  <ul class=brief>
   <li><dfn method for="DOMImplementation">getFeature()</dfn>
  </ul>

 <dt>{{Attr}}
 <dd>
  No longer inherits from {{Node}} and therefore completely
  changed.
  <!--AttrExodus
  <dfn attribute for="Attr">schemaTypeInfo</dfn>
  <dfn attribute for="Attr">isId</dfn>
  -->

 <dt>{{Element}}
 <dd>
  <ul class=brief>
   <li><dfn attribute for="Element">schemaTypeInfo</dfn>
   <li><dfn method for="Element">setIdAttribute()</dfn>
   <li><dfn method for="Element">setIdAttributeNS()</dfn>
   <li><dfn method for="Element">setIdAttributeNode()</dfn>
  </ul>

 <dt>{{DocumentType}}
 <dd>
  <ul class=brief>
   <li><dfn attribute for="DocumentType">entities</dfn>
   <li><dfn attribute for="DocumentType">notations</dfn>
   <li><dfn attribute for="DocumentType">internalSubset</dfn>
  </ul>

 <dt>{{Text}}
 <dd>
  <ul class=brief>
   <li><dfn attribute for="Text">isElementContentWhitespace</dfn>
   <li><dfn method for="Text">replaceWholeText()</dfn>
  </ul>
</dl>

<h3 id='dom-ranges-changes'>DOM Ranges</h3>

These are the changes made to the features described in the
"Document Object Model Range" chapter of
<cite>DOM Level 2 Traversal and Range</cite>.

<ul>
 <li><dfn interface>RangeException</dfn> has been removed.

 <li>{{Range}} objects can now be moved between
 <a>documents</a> and used on
 <a>nodes</a> that are not <a>in a document</a>.

 <li>A wild {{Range/Range()}} constructor appeared.

 <li>New methods {{Range/comparePoint()}},
 {{Range/intersectsNode()}}, and
 {{Range/isPointInRange()}} have been added.

 <li>{{Range/detach()}} is now a no-op.

 <li><a dfn for=Range lt="stringification behavior"><code>toString</code></a> is now
 defined through IDL.
</ul>


<h3 id='dom-traversal-changes'>DOM Traversal</h3>

These are the changes made to the features described in the
"Document Object Model Traversal" chapter of
<cite>DOM Level 2 Traversal and Range</cite>.

<ul>
 <li>{{createNodeIterator()}} and
 {{createTreeWalker()}} now have optional
 arguments and lack a fourth argument which is no longer relevant given entity references
 never made it into the DOM.

 <li>The <dfn for="NodeIterator, TreeWalker" attribute>expandEntityReferences</dfn> attribute has been removed from the
 {{NodeIterator}} and {{TreeWalker}} interfaces for the aforementioned
 reason.

 <li>The {{NodeIterator/referenceNode}} and
 {{NodeIterator/pointerBeforeReferenceNode}}
 attributes have been added to {{NodeIterator}} objects to align with proprietary
 extensions of implementations.

 <li>{{NodeIterator/nextNode()}} and
 {{NodeIterator/previousNode()}} now throw
 when invoked from a {{NodeFilter}} to align with user agents.

 <li>{{NodeIterator/detach()}} is now a no-op.
</ul>


<h2 class=no-num id="acks">Acknowledgments</h2>

There have been a lot of people that have helped make DOM more interoperable over the
years and thereby furthered the goals of this standard. Likewise many people have helped
making this standard what it is today.

With that, many thanks to
Adam Klein,
Adrian Bateman,
Aleksey Shvayka,
Alex Komoroske,
Alex Russell,
Anthony Ramine,
Arkadiusz Michalski,
Arnaud Le Hors,
Arun Ranganathan,
Björn Höhrmann,
Boris Zbarsky,
Brandon Payton,
Brandon Slade,
Brandon Wallace,
Brian Kardell,
Cameron McCormack,
Chris Dumez,
Chris Paris,
Chris Rebert,
Daniel Glazman,
Darin Fisher,
David Bruant,
David Flanagan,
David Håsäther,
David Hyatt,
Deepak Sherveghar,
Dethe Elza,
Dimitri Glazkov,
Domenic Denicola,
Dominic Cooney,
Dominique Hazaël-Massieux,
Don Jordan,
Doug Schepers,
Edward O'Connor,
Elisée Maurer
Elliott Sprehn,
Eric Bidelman,
Erik Arvidsson,
Gavin Nicol,
Geoffrey Sneddon,
Giorgio Liscio,
Glen Huang,
Glenn Adams,
Glenn Maynard,
Hajime Morrita,
Harald Alvestrand,
Hayato Ito,
Henri Sivonen,
Hunan Rostomyan,
Ian Hickson,
Igor Bukanov,
Jacob Rossi,
Jake Archibald<!-- technically B.J. Archibald -->,
Jake Verbaten,
James Graham,
James Greene,
James Robinson,
Jeffrey Yasskin,
Jens Lindström,
Jesse McCarthy,
João Eiras,
Joe Kesselman,
John Atkins,
Jonas Sicking,
Jonathan Robie,
Joris van der Wel,
Joshua Bell,
Jungkee Song,
Justin Summerlin,
呂康豪 (Kang-Hao Lu),
Kevin Sweeney,
Koji Ishii,
Lachlan Hunt,
Lauren Wood,
Malte Ubl,
Manish Goregaokar,
Manish Tripathi,
Marcos Caceres,
Mark Miller,
Mats Palmgren,
Mounir Lamouri,
Michael™ Smith,
Mike Champion,
Mike Taylor,
Ojan Vafai,
Oliver Nightingale,
Olli Pettay,
Ondřej Žára,
Peter Sharpe,
Philip Jägenstedt,
Philippe Le Hégaret,
Rafael Weinstein,
Richard Bradshaw,
Rick Byers,
Rick Waldron,
Robbert Broersma,
Robin Berjon,
Roland Steiner,
Rune <span title=Fabulous>F.</span> Halvorsen,
Ruud Steltenpool,
Ryosuke Niwa,
Sam Dutton,
Samuel Giles,
Sebastian Mayr,
Seo Sanghyeon,
Sergey G. Grekhov,
Shiki Okasaka,
Shinya Kawanaka,
Simon Pieters,
Steve Byrne,
Stig Halvorsen,
Tab Atkins,
Takashi Sakamoto,
Takayoshi Kochi,
<i>timeless</i>,
Timo Tijhof,
Tobie Langel,
Tom Pixley,
Travis Leithead,
<i>triple-underscore</i>,<!--GitHub-->
Veli Şenol,
Vidur Apparao,
Warren He,
Yehuda Katz,
Yoav Weiss,
Yoichi Osato,
Yoshinori Sano, and
Zack Weinberg
for being awesome!

This standard is written by
<a lang=nl href=//annevankesteren.nl/>Anne van Kesteren</a>
(<a href=//www.mozilla.org/>Mozilla</a>,
<a href=mailto:annevk@annevk.nl>annevk@annevk.nl</a>) with substantial contributions from
Aryeh Gregor (<a href="//www.mozilla.org/">Mozilla</a>,
<a href=mailto:ayg@aryeh.name>ayg@aryeh.name</a>)
and Ms2ger (<a href="//www.mozilla.org/">Mozilla</a>,
<a href="mailto:ms2ger@gmail.com">ms2ger@gmail.com</a>).

Part of the revision history of the integration points related to <a>custom</a> elements can be
found in <a href="https://github.com/w3c/webcomponents">the w3c/webcomponents repository</a>, which
is available under the
<a href="https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document">W3C Permissive Document License</a>.

Per <a rel="license" href="//creativecommons.org/publicdomain/zero/1.0/">CC0</a>, to
the extent possible under law, the editors have waived all copyright and related or
neighboring rights to this work.

<!-- vim: set expandtab shiftwidth=1 tabstop=1 textwidth=76 -->