Addressed annevk's comments

Author: mfreed7

source

@@ -2900,6 +2900,11 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
      <li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-element"><code>Element</code></dfn> interface</li>
      <li><dfn data-x="dom-Element-attachShadow" data-x-href="https://dom.spec.whatwg.org/#dom-element-attachshadow"><code>attachShadow()</code></dfn> method.</li>
      <li>An element's <dfn data-x="concept-element-shadow-root" data-x-href="https://dom.spec.whatwg.org/#concept-element-shadow-root">shadow root</dfn></li>
+     <li>A <span data-x="concept-element-shadow-root">shadow root</span>'s <dfn data-x="concept-shadow-root-mode" data-x-href="https://dom.spec.whatwg.org/#shadowroot-mode">mode</dfn></li>
+     <li>A <span data-x="concept-element-shadow-root">shadow root</span>'s <dfn data-x="concept-is-declarative-shadow-root" data-x-href="https://dom.spec.whatwg.org/#dom-is-declarative-shadow-root">is declarative shadow root</dfn> flag</li>
+     <li>The <dfn data-x="concept-attach-a-shadow-root" data-x-href="https://dom.spec.whatwg.org/#concept-attach-a-shadow-root">attach a
+     shadow root</dfn> algorithm</li>
+     <li>The <dfn data-x="dom-element-shadowroot" data-x-href="https://dom.spec.whatwg.org/#dom-element-shadowroot">shadowRoot</dfn> attribute</li>
      <li>The <dfn data-x="dom-retarget" data-x-href="https://dom.spec.whatwg.org/#retarget">retargeting algorithm</dfn></li>
      <li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-node"><code>Node</code></dfn> interface</li>
      <li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-nodelist"><code>NodeList</code></dfn> interface</li>
@@ -2910,7 +2915,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
      <li><dfn data-x-href="https://dom.spec.whatwg.org/#concept-node-document">node document</dfn> concept</li>
      <li><dfn data-x="concept-document-type" data-x-href="https://dom.spec.whatwg.org/#concept-document-type">document type</dfn> concept</li>
      <li><dfn data-x="concept-DocumentFragment-host" data-x-href="https://dom.spec.whatwg.org/#concept-documentfragment-host">host</dfn> concept</li>
-     <li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-root">shadow root</dfn> concept, and its <dfn data-x-href="https://dom.spec.whatwg.org/#shadowroot-delegates-focus">delegates focus</dfn></li>
+     <li>The <dfn data-x="concept-shadow-root" data-x-href="https://dom.spec.whatwg.org/#concept-shadow-root">shadow root</dfn> concept, and its <dfn data-x-href="https://dom.spec.whatwg.org/#shadowroot-delegates-focus">delegates focus</dfn></li>
      <li>The <dfn data-x-href="https://dom.spec.whatwg.org/#element-shadow-host">shadow host</dfn> concept</li>
      <li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-htmlcollection"><code>HTMLCollection</code></dfn> interface, its
          <dfn data-x="dom-HTMLCollection-length" data-x-href="https://dom.spec.whatwg.org/#dom-htmlcollection-length"><code>length</code></dfn> attribute, and its
@@ -14943,7 +14948,7 @@ interface <dfn>HTMLStyleElement</dfn> : <span>HTMLElement</span> {
    <li><p>If <var>element</var> has an <span>associated CSS style sheet</span>, <span
    data-x="remove a CSS style sheet">remove the CSS style sheet</span> in question.</p></li>
 
-   <li><p>If <var>element</var>'s <span>root</span> is neither a <span>shadow root</span> nor a
+   <li><p>If <var>element</var>'s <span>root</span> is neither a <span data-x="concept-element-shadow-root">shadow root</span> nor a
    <span>document</span>, then return.</p></li>
    <!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2740
         Also, per https://github.com/w3c/webcomponents/issues/56 stylesheets should work in
@@ -54178,7 +54183,7 @@ MIT Room 32-G524
   <p>A user agent prefilling a form control must not discriminate between form controls that are
   <span>in a document tree</span> and those that are <span>connected</span>; that is, it is not
   conforming to make the decision on whether or not to autofill based on whether the element's
-  <span>root</span> is a <span>shadow root</span> versus a <code>Document</code>.</p>
+  <span>root</span> is a <span data-x="concept-element-shadow-root">shadow root</span> versus a <code>Document</code>.</p>
 
   <p>A user agent prefilling a form control's <span data-x="concept-fe-value">value</span> must not
   cause that control to <span data-x="suffering from a type mismatch">suffer from a type
@@ -58285,8 +58290,8 @@ o............A....e
        set.</p></li>
 
        <li>
-        <p>If <var>scriptElement</var>'s <span>root</span> is <em>not</em> a <span>shadow
-        root</span>, then set <var>document</var>'s <code
+        <p>If <var>scriptElement</var>'s <span>root</span> is <em>not</em> a
+        <span data-x="concept-element-shadow-root">shadow root</span>, then set <var>document</var>'s <code
         data-x="dom-document-currentScript">currentScript</code> attribute to
         <var>scriptElement</var>. Otherwise, set it to null.</p>
 
@@ -58777,7 +58782,8 @@ interface <dfn>HTMLTemplateElement</dfn> : <span>HTMLElement</span> {
   [<span>HTMLConstructor</span>] constructor();
 
   readonly attribute <span>DocumentFragment</span> <span data-x="dom-template-content">content</span>;
-  readonly attribute ShadowRoot? <span data-x="dom-template-shadowroot">shadowRoot</span>;
+  readonly attribute <span data-x="concept-shadow-root">ShadowRoot</span>? <span data-x="dom-template-shadowroot">shadowRoot</span>;
+
 };</code></pre>
 </dd>
    <dd w-dev>Uses <code>HTMLTemplateElement</code>.</dd>
@@ -58927,16 +58933,23 @@ interface <dfn>HTMLTemplateElement</dfn> : <span>HTMLElement</span> {
   </ol>
 
   <p>The <dfn><code data-x="dom-template-content">content</code></dfn> IDL attribute must return the
-  <code>template</code> element's <span>template contents</span>. If the <code>template</code>'s
-  <a href="https://dom.spec.whatwg.org/#dom-is-declarative-shadow-root">is declarative shadow root</a>
-  property is true, then the <code data-x="dom-template-content">content</code> attribute must return
-  null instead.</p>
+  result of running the <span>get template contents algorithm</span>.</p>
 
   <p>The <dfn><code data-x="dom-template-shadowroot">shadowroot</code></dfn> IDL attribute must return
-  its base Element's <a href="https://dom.spec.whatwg.org/#dom-element-shadowroot">shadowroot</a> value.
+  the value of the <code>template</code> element's <span data-x="dom-element-shadowroot">shadowRoot</span> attribute.
 
   <hr>
 
+  <p>The <dfn>get template contents algorithm</dfn>, which is passed a <var>template</var> (a
+  <code>template</code> element) consists of running these steps:</p>
+
+  <ol>
+   <li><p>If the <code>template</code>'s <span data-x="concept-is-declarative-shadow-root">is declarative shadow root</span>
+   property is true, then return null.</p></li>
+
+   <li><p>Otherwise, return <code>template</code>'s <span>template contents</span>.</p></li>
+  </ol>
+
   <p>The <span data-x="concept-node-clone-ext">cloning steps</span> for a <code>template</code>
   element <var>node</var> being cloned to a copy <var>copy</var> must run the
   following steps:</p>
@@ -65752,7 +65765,7 @@ console.log(plasticButton.outerHTML); // will output '&lt;button is="plastic-but
    is truly one-time will need a guard to prevent it from running twice.</p></li>
 
    <li><p>In general, the constructor should be used to set up initial state and default values, and
-   to set up event listeners and possibly a <span>shadow root</span>.</p></li>
+   to set up event listeners and possibly a <span data-x="concept-element-shadow-root">shadow root</span>.</p></li>
   </ul>
 
   <p>Several of these requirements are checked during <span data-x="create an element">element
@@ -72457,7 +72470,7 @@ END:VCARD</pre>
    <li><p>If <var>element</var>'s parent is a <span>shadow host</span>, then return
    <var>element</var>'s <span>assigned slot</span>.</p></li>
 
-   <li><p>If <var>element</var>'s parent is a <span>shadow root</span>, then return the parent's
+   <li><p>If <var>element</var>'s parent is a <span data-x="concept-element-shadow-root">shadow root</span>, then return the parent's
    <span data-x="concept-DocumentFragment-host">host</span>.</p></li>
 
    <li><p>If <var>element</var>'s parent is the <span>document element</span>, then return the
@@ -108164,24 +108177,24 @@ document.body.appendChild(text);
 
      <li><p>If the start tag for the <span data-x="concept-declarative-template-element">declarative template element</span> had an attribute with the name "shadowrootdelegatesfocus", then let <dfn><var data-x="concept-declarative-shadow-delegates-focus">declarative shadow delegates focus</var></dfn> be true. Otherwise let it be false.</p></li>
 
-     <li><p>Run <a href="https://dom.spec.whatwg.org/#concept-attach-a-shadow-root">attach a shadow root</a> with <var>shadow host</var>
+     <li><p>Run <span data-x="concept-attach-a-shadow-root">attach a shadow root</span> with <var>shadow host</var>
      equal to <span data-x="concept-declarative-shadow-host-element">declarative shadow host element</span>,
      <var>mode</var> equal to <span data-x="concept-declarative-shadow-mode">declarative shadow mode</span>, and
      <span>delegates focus</span> equal to <span data-x="concept-declarative-shadow-delegates-focus">declarative shadow delegates focus</span>.</p></li>
 
-     <p>If an exception was thrown by <a href="https://dom.spec.whatwg.org/#concept-attach-a-shadow-root">attach a shadow root</a>,
-     catch it, and <span>report the exception</span>.</p>
+     <p>If an exception was thrown by <span data-x="concept-attach-a-shadow-root">attach a shadow root</span>, catch it.
+     The exception may be reported to a developer console.</p>
 
      <li><p>Otherwise, run these steps:</p>
 
      <ol>
+       <li><p>Set <span data-x="concept-declarative-shadow-host-element">declarative shadow host element</span>'s
+       <span data-x="concept-element-shadow-root">shadow root</span>'s
+       <span data-x="concept-is-declarative-shadow-root">is declarative shadow root</span> property to true.</p></li>
 
-       <li><p>Set <span data-x="concept-declarative-shadow-host-element">declarative shadow host element</span>'s <a href="https://dom.spec.whatwg.org/#concept-element-shadow-root">shadow host</a>'s
-       <a href="https://dom.spec.whatwg.org/#dom-is-declarative-shadow-root">is declarative shadow root</a> property to true.</p></li>
-
-       <li><p><a href="https://dom.spec.whatwg.org/#concept-node-append">Append</a> the <span data-x="concept-declarative-template-element">declarative template element</span>'s DocumentFragment to the newly-created shadow root.</p></li>
+       <li><p><span data-x="concept-node-append">Append</span> the <span data-x="concept-declarative-template-element">declarative template element</span>'s DocumentFragment to the newly-created shadow root.</p></li>
 
-       <li><p><a href="https://dom.spec.whatwg.org/#concept-node-remove">Remove</a> the <span data-x="concept-declarative-template-element">declarative template element</span> from the document.</p></li>
+       <li><p><span data-x="concept-node-remove">Remove</span> the <span data-x="concept-declarative-template-element">declarative template element</span> from the document.</p></li>
      </ol>
      </li>
 
@@ -111675,7 +111688,8 @@ document.body.appendChild(text);
   <p>The following steps form the <!--en-GB--><dfn id="html-fragment-serialisation-algorithm"
   data-export="">HTML fragment serialization algorithm</dfn>. The algorithm takes as input a DOM
   <code>Element</code>, <code>Document</code>, or <code>DocumentFragment</code> referred to as
-  <var>the node</var>, and a boolean referred to as <var>include shadow roots</var> whose default value is false, and returns a string.</p>
+  <var>the node</var>, a boolean referred to as <var>include shadow roots</var>, and a
+  sequence&lt;ShadowRoot> referred to as <var>closed shadow roots</var>, and returns a string.</p>
 
   <p class="note">This algorithm serializes the <em>children</em> of the node being serialized, not
   the node itself.</p>
@@ -111848,39 +111862,36 @@ document.body.appendChild(text);
      true, then:
 
      <ol>
-       <li><p>Append the literal string "<code data-x="">&lt;template shadowroot=&quot;</code>" (U+003C LESS-THAN SIGN,
-         U+0074 LATIN SMALL LETTER T, U+0065 LATIN SMALL LETTER E, U+006D LATIN SMALL LETTER M,
-         U+0070 LATIN SMALL LETTER P, U+006C LATIN SMALL LETTER L, U+0061 LATIN SMALL LETTER A,
-         U+0074 LATIN SMALL LETTER T, U+0065 LATIN SMALL LETTER E, U+0020 SPACE,
-         U+0073 LATIN SMALL LETTER S, U+0068 LATIN SMALL LETTER H, U+0061 LATIN SMALL LETTER A,
-         U+0064 LATIN SMALL LETTER D, U+006F LATIN SMALL LETTER O, U+0077 LATIN SMALL LETTER W,
-         U+003D EQUALS SIGN, U+0022 QUOTATION MARK).</p></li>
-
-       <li><p>If <var>shadow root</var>'s <a href="https://dom.spec.whatwg.org/#shadowroot-mode">mode</a>
-       is "open", then append the literal
-       string "<code data-x="">open</code>" (U+006F LATIN SMALL LETTER O, U+0070 LATIN SMALL LETTER P,
-       U+0065 LATIN SMALL LETTER E, U+006E LATIN SMALL LETTER N).</p></li>
-
-       <li><p>If <var>shadow root</var>'s <a href="https://dom.spec.whatwg.org/#shadowroot-mode">mode</a>
-       is "closed", then append the literal
-       string "<code data-x="">closed</code>" (U+0063 LATIN SMALL LETTER C, U+006C LATIN SMALL LETTER L,
-       U+006F LATIN SMALL LETTER O, U+0073 LATIN SMALL LETTER S, U+0065 LATIN SMALL LETTER E,
-       U+0064 LATIN SMALL LETTER D).</p></li>
-
-       <li><p>Append the literal string "<code data-x="">&quot;&gt;</code>" (U+0022 QUOTATION MARK,
-       U+003E GREATER-THAN SIGN).</p></li>
-
-       <li><p>Append the value of running the <span>HTML fragment serialization algorithm</span> on the
-        <var>shadow root</var> element (thus recursing into this algorithm for that
-        element).</p></li>
-
-       <li><p>Append the literal string "<code data-x="">&lt;/template&gt;</code>" (U+003C LESS-THAN SIGN, U+002F SOLIDUS,
-         U+0074 LATIN SMALL LETTER T, U+0065 LATIN SMALL LETTER E, U+006D LATIN SMALL LETTER M,
-         U+0070 LATIN SMALL LETTER P, U+006C LATIN SMALL LETTER L, U+0061 LATIN SMALL LETTER A,
-         U+0074 LATIN SMALL LETTER T, U+0065 LATIN SMALL LETTER E, U+003E GREATER-THAN SIGN).</p></li>
+       <li><p>Let <var>shadow root</var> be equal to <var>the node</var>'s <span data-x="concept-element-shadow-root">shadow root</span>.
+
+       <li><p>If <var>shadow root</var>'s <span data-x="concept-shadow-root-mode">mode</span>
+       is "closed", and <var>shadow root</var> is <b>not</b> contained in <var>closed shadow roots</var>,
+       then skip the next step.
 
+       <li><p>Otherwise:
+
+       <ol>
+         <li><p>Append the literal string "<code data-x="">&lt;template shadowroot=&quot;</code>".</p></li>
+
+         <li><p>If <var>shadow root</var>'s <span data-x="concept-shadow-root-mode">mode</span>
+         is "open", then append the literal
+         string "<code data-x="">open</code>".</p></li>
+
+         <li><p>If <var>shadow root</var>'s <span data-x="concept-shadow-root-mode">mode</span>
+         is "closed", then append the literal
+         string "<code data-x="">closed</code>".</p></li>
+
+         <li><p>Append the literal string "<code data-x="">&quot;&gt;</code>".</p></li>
+
+         <li><p>Append the value of running the <span>HTML fragment serialization algorithm</span> on the
+          <var>shadow root</var> <code>DocumentFragment</code> (thus recursing into this algorithm for that
+          element).</p></li>
+
+         <li><p>Append the literal string "<code data-x="">&lt;/template&gt;</code>".</p></li>
+
+       </ol>
      </ol>
-   </li>
+     </li>
 
    <li><p>Return <var>s</var>.</p></li>
   </ol>