From 1691f94d25b3e3caca5acf2552ae6ce6366b8fe9 Mon Sep 17 00:00:00 2001
From: Hamish Willee <hamishwillee@gmail.com>
Date: Tue, 14 May 2024 13:38:52 +1000
Subject: [PATCH 1/8] Add docs for shadow root serializable property
 (everywhere)

---
 .../web/api/element/attachshadow/index.md     |  6 +++
 files/en-us/web/api/element/gethtml/index.md  | 11 ++++--
 .../web/api/htmltemplateelement/index.md      |  4 ++
 .../shadowrootserializable/index.md           | 32 +++++++++++++++
 .../en-us/web/api/shadowroot/gethtml/index.md |  9 +++--
 files/en-us/web/api/shadowroot/index.md       |  8 +++-
 .../web/api/shadowroot/serializable/index.md  | 39 +++++++++++++++++++
 .../en-us/web/html/element/template/index.md  | 11 ++++--
 8 files changed, 108 insertions(+), 12 deletions(-)
 create mode 100644 files/en-us/web/api/htmltemplateelement/shadowrootserializable/index.md
 create mode 100644 files/en-us/web/api/shadowroot/serializable/index.md

diff --git a/files/en-us/web/api/element/attachshadow/index.md b/files/en-us/web/api/element/attachshadow/index.md
index e6fdc1be2e45f1d..ea37a4648496c86 100644
--- a/files/en-us/web/api/element/attachshadow/index.md
+++ b/files/en-us/web/api/element/attachshadow/index.md
@@ -83,6 +83,12 @@ attachShadow(options)
       - : A boolean that, when set to `true`, specifies behavior that mitigates custom element issues around focusability.
         When a non-focusable part of the shadow DOM is clicked, the first focusable part is given focus, and the shadow host is given any available `:focus` styling. Its default value is `false`.
 
+    - `serializable` {{Optional_Inline}}
+
+      - : A boolean that, when set to `true`, indicates that the shadow root is serializable.
+        Its default value is `false`.
+        If set, the shadow root may be serialized by calling the {{DOMxRef('Element.getHTML()')}} or {{DOMxRef('ShadowRoot.getHTML()')}} methods with the `options.serializableShadowRoots` parameter set `true`.
+
     - `slotAssignment` {{Optional_inline}}
 
       - : A string specifying the _slot assignment mode_ for the shadow DOM tree. This can be one of:
diff --git a/files/en-us/web/api/element/gethtml/index.md b/files/en-us/web/api/element/gethtml/index.md
index 133d548ca0b4091..7d4fbdf49691ab1 100644
--- a/files/en-us/web/api/element/gethtml/index.md
+++ b/files/en-us/web/api/element/gethtml/index.md
@@ -12,10 +12,12 @@ browser-compat: api.Element.getHTML
 
 The **`getHTML()`** method of the {{domxref("Element")}} interface is used to serialize an element's DOM to an HTML string.
 
+The serialized HTML does not include shadow trees by default, but options can be used to include shadow roots that have been set as {{domxref("ShadowRoot/serializable","serializable")}}, and/or a specified array of {{domxref("ShadowRoot")}} objects.
+
 ## Syntax
 
 ```js-nolint
-const html = element.getHTML(options)
+getHTML(options)
 ```
 
 ### Parameters
@@ -25,10 +27,11 @@ const html = element.getHTML(options)
   - : An options object with the following optional parameters:
 
     - `serializableShadowRoots`
-      - : A boolean value that specifies whether to include serializable shadow roots. The default value is `false`.
+      - : A boolean value that specifies whether to include {{domxref("ShadowRoot/serializable","serializable")}} shadow roots.
+        The default value is `false`.
     - `shadowRoots`
-      - : An array of {{domxref("ShadowRoot")}} objects to serialize. These are included regardless of whether they
-        are marked as serializable. The default value is an empty array.
+      - : An array of {{domxref("ShadowRoot")}} objects to serialize. These are included regardless of whether they are marked as `serializable`.
+        The default value is an empty array.
 
 ### Return value
 
diff --git a/files/en-us/web/api/htmltemplateelement/index.md b/files/en-us/web/api/htmltemplateelement/index.md
index 4a0af007a0e9000..35a156ed47d0f78 100644
--- a/files/en-us/web/api/htmltemplateelement/index.md
+++ b/files/en-us/web/api/htmltemplateelement/index.md
@@ -20,6 +20,7 @@ The **`HTMLTemplateElement`** interface enables access to the contents of an HTM
 _This interface inherits the properties of {{domxref("HTMLElement")}}._
 
 - {{domxref("HTMLTemplateElement.content", "content")}} {{ReadOnlyInline}}
+
   - : A read-only {{domxref("DocumentFragment")}} which contains the DOM subtree representing the {{HTMLElement("template")}} element's template contents.
 - {{domxref("HTMLTemplateElement.shadowRootMode", "shadowRootMode")}}
   - : A string that reflects the value of the [`shadowrootmode`](/en-US/docs/Web/HTML/Element/template#shadowrootmode) attribute of the associated `<template>` element.
@@ -28,6 +29,9 @@ _This interface inherits the properties of {{domxref("HTMLElement")}}._
 - {{domxref("HTMLTemplateElement.shadowRootClonable", "shadowRootClonable")}}
   - : A boolean that reflects the value of the [`shadowrootclonable`](/en-US/docs/Web/HTML/Element/template#shadowrootclonable) attribute of the associated `<template>` element.
 
+- {{domxref("HTMLTemplateElement.shadowRootSerializable", "shadowRootSerializable")}}
+  - : A boolean that reflects the value of the [`shadowrootserializable`](/en-US/docs/Web/HTML/Element/template#shadowrootserializable) attribute of the associated `<template>` element.
+
 ## Instance methods
 
 _This interface inherits the methods of {{domxref("HTMLElement")}}._
diff --git a/files/en-us/web/api/htmltemplateelement/shadowrootserializable/index.md b/files/en-us/web/api/htmltemplateelement/shadowrootserializable/index.md
new file mode 100644
index 000000000000000..4fcbddb99afadcd
--- /dev/null
+++ b/files/en-us/web/api/htmltemplateelement/shadowrootserializable/index.md
@@ -0,0 +1,32 @@
+---
+title: "HTMLTemplateElement: shadowRootSerializable property"
+short-title: content
+slug: Web/API/HTMLTemplateElement/shadowRootSerializable
+page-type: web-api-instance-property
+browser-compat: api.HTMLTemplateElement.shadowRootSerializable
+---
+
+{{APIRef("Web Components")}}
+
+The **`shadowRootSerializable`** property reflects the value of the [`shadowrootserializable`](/en-US/docs/Web/HTML/Element/template#shadowrootserializable) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Element/template) element.
+
+Note that this property is not useful for developers.
+If a `<template>` element is used to declaratively create a [`ShadowRoot`](/en-US/docs/Web/API/ShadowRoot), then this object and property do not exist.
+Otherwise, if an `HTMLTemplateElement` is created, the value of this property is irrelevant because the object is not a shadow root and cannot subsequently be changed to a shadow root.
+
+## Value
+
+Reflects the value of the [`shadowrootserializable`](/en-US/docs/Web/HTML/Element/template#shadowrootserializable) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Element/template) element.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`shadowrootserializable`](/en-US/docs/Web/HTML/Element/template#shadowrootserializable) attribute of the `<template>` element
+- [`ShadowRoot.serializable`](/en-US/docs/Web/API/ShadowRoot/serializable)
diff --git a/files/en-us/web/api/shadowroot/gethtml/index.md b/files/en-us/web/api/shadowroot/gethtml/index.md
index a836d643309e809..f662a4f50225631 100644
--- a/files/en-us/web/api/shadowroot/gethtml/index.md
+++ b/files/en-us/web/api/shadowroot/gethtml/index.md
@@ -25,10 +25,12 @@ const html = shadowRoot.getHTML(options)
   - : An options object with the following optional parameters:
 
     - `serializableShadowRoots`
-      - : A boolean value that specifies whether to include serializable shadow roots. The default value is `false`.
+      - : A boolean value that specifies whether to include [serializable](/en-US/docs/Web/API/ShadowRoot/serializable) shadow roots.
+        The default value is `false`.
     - `shadowRoots`
-      - : An array of {{domxref("ShadowRoot")}} objects to serialize. These are included regardless of whether they
-        are marked as serializable. The default value is an empty array.
+      - : An array of {{domxref("ShadowRoot")}} objects to serialize.
+        These are included regardless of whether they are marked as `serializable`.
+        The default value is an empty array.
 
 ### Return value
 
@@ -48,4 +50,5 @@ None.
 
 ## See Also
 
+- {{domxref("Element.getHTML()")}}
 - {{domxref("ShadowRoot.innerHTML")}}
diff --git a/files/en-us/web/api/shadowroot/index.md b/files/en-us/web/api/shadowroot/index.md
index 06a09dd5ade7579..4493d1ebb4f9620 100644
--- a/files/en-us/web/api/shadowroot/index.md
+++ b/files/en-us/web/api/shadowroot/index.md
@@ -21,9 +21,9 @@ You can retrieve a reference to an element's shadow root using its {{domxref("El
   - : Add an array of constructed stylesheets to be used by the shadow DOM subtree.
     These may be shared with other DOM subtrees that share the same parent {{domxref("Document")}} node, and the document itself.
 - {{domxref("ShadowRoot.clonable")}} {{ReadOnlyInline}}
-  - : Returns a boolean that indicates whether the shadow root is clonable, which can be set via the {{domxref("Element.attachShadow()")}} `clonable` option.
+  - : A boolean that indicates whether the shadow root is clonable.
 - {{domxref("ShadowRoot.delegatesFocus")}} {{ReadOnlyInline}}
-  - : Returns a boolean that indicates whether `delegatesFocus` was set when the shadow was attached (see {{domxref("Element.attachShadow()")}}).
+  - : A boolean that indicates whether the shadow root delegates focus if a non-focusable node is selected.
 - {{DOMxRef("ShadowRoot.fullscreenElement")}} {{ReadOnlyInline}}
   - : The element that's currently in full screen mode for this shadow tree.
 - {{domxref("ShadowRoot.host")}} {{ReadOnlyInline}}
@@ -38,6 +38,10 @@ You can retrieve a reference to an element's shadow root using its {{domxref("El
 - {{DOMxRef("ShadowRoot.pointerLockElement")}} {{ReadOnlyInline}}
   - : Returns the {{DOMxRef('Element')}} set as the target for mouse events while the pointer is locked.
     `null` if lock is pending, pointer is unlocked, or if the target is in another tree.
+- {{DOMxRef("ShadowRoot.serializable")}} {{ReadOnlyInline}}
+  - : A boolean that indicates whether the shadow root is serializable.
+    A serializable shadow root inside an element will be serialized by {{DOMxRef('Element.getHTML()')}} or {{DOMxRef('ShadowRoot.getHTML()')}} when its [`options.serializableShadowRoots`](/en-US/docs/Web/API/Element/getHTML#serializableshadowroots) parameter is set `true`.
+    This is set when the shadow root is created.
 - {{DOMxRef("ShadowRoot.slotAssignment")}} {{ReadOnlyInline}}
   - : Returns a string containing the type of slot assignment, either `manual` or `named`.
 - {{domxref("ShadowRoot.styleSheets")}} {{ReadOnlyInline}}
diff --git a/files/en-us/web/api/shadowroot/serializable/index.md b/files/en-us/web/api/shadowroot/serializable/index.md
new file mode 100644
index 000000000000000..189793fbfacd1e1
--- /dev/null
+++ b/files/en-us/web/api/shadowroot/serializable/index.md
@@ -0,0 +1,39 @@
+---
+title: "ShadowRoot: serializable property"
+short-title: serializable
+slug: Web/API/ShadowRoot/serializable
+page-type: web-api-instance-property
+browser-compat: api.ShadowRoot.serializable
+---
+
+{{APIRef("Shadow DOM")}}
+
+The **`serializable`** read-only property of the {{domxref("ShadowRoot")}} interface returns `true` if the shadow root is serializable.
+
+If set, the shadow root may be serialized by calling the {{DOMxRef('Element.getHTML()')}} or {{DOMxRef('ShadowRoot.getHTML()')}} methods with the `options.serializableShadowRoots` parameter set `true`.
+
+The serializable property of a shadow root is specified when the shadow root is created, either declaratively by adding the [`shadowrootserializable`](/en-US/docs/Web/HTML/Element/template#shadowrootserializable) attribute on a `<template>` element (along with an allowed [`shadowrootmode`](/en-US/docs/Web/HTML/Element/template#shadowrootmode) value), or by setting the [`options.serializable`](/en-US/docs/Web/API/Element/attachShadow#serializable) parameter to `true` when using [`Element.attachShadow()`](/en-US/docs/Web/API/Element/attachShadow).
+
+## Value
+
+`true` if the shadow root is serializable; `false` otherwise.
+
+## Examples
+
+```js
+let customElem = document.querySelector("my-shadow-dom-element");
+let shadow = customElem.shadowRoot;
+
+// ...
+
+// Is it serializable?
+let hostElem = shadow.serializable;
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
diff --git a/files/en-us/web/html/element/template/index.md b/files/en-us/web/html/element/template/index.md
index 9c8ed0e1e5d3f0a..1619ae377803a9a 100644
--- a/files/en-us/web/html/element/template/index.md
+++ b/files/en-us/web/html/element/template/index.md
@@ -32,16 +32,21 @@ This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attrib
 
     > **Note:** You may find the non-standard `shadowroot` attribute in older tutorials and examples that used to be supported in Chrome 90-110. This attribute has since been removed and replaced by the standard `shadowrootmode` attribute.
 
+- `shadowrootclonable`
+
+  - : Sets the value of the [`clonable`](/en-US/docs/Web/API/ShadowRoot/clonable) property of a [`ShadowRoot`](/en-US/docs/Web/API/ShadowRoot) created using this element to `true`.
+    If set, a clone of the shadow host (the parent element of this `<template>`) created with {{domxref("Node.cloneNode()")}} or {{domxref("Document.importNode()")}} will include a shadow root in the copy.
+
 - `shadowrootdelegatesfocus`
 
   - : Sets the value of the [`delegatesFocus`](/en-US/docs/Web/API/ShadowRoot/delegatesFocus) property of a [`ShadowRoot`](/en-US/docs/Web/API/ShadowRoot) created using this element to `true`.
     If this is set and a non-focusable element in the shadow tree is selected, then focus is delegated to the first focusable element in the tree.
     The value defaults to `false`.
 
-- `shadowrootclonable`
+- `shadowrootserializable`
 
-  - : Sets the value of the [`clonable`](/en-US/docs/Web/API/ShadowRoot/clonable) property of a [`ShadowRoot`](/en-US/docs/Web/API/ShadowRoot) created using this element to `true`.
-    If set, a clone of the shadow host (the parent element of this `<template>`) created with {{domxref("Node.cloneNode()")}} or {{domxref("Document.importNode()")}} will include a shadow root in the copy.
+  - : Sets the value of the [`serializable`](/en-US/docs/Web/API/ShadowRoot/serializable) property of a [`ShadowRoot`](/en-US/docs/Web/API/ShadowRoot) created using this element to `true`.
+    If set, the shadow root may be serialized by calling the {{DOMxRef('Element.getHTML()')}} or {{DOMxRef('ShadowRoot.getHTML()')}} methods with the `options.serializableShadowRoots` parameter set `true`.
     The value defaults to `false`.
 
 ## Usage notes

From 9bdacd1b21f9366d1d1adb24f05546aba44beb3e Mon Sep 17 00:00:00 2001
From: Hamish Willee <hamishwillee@gmail.com>
Date: Fri, 17 May 2024 13:48:54 +1000
Subject: [PATCH 2/8] innerHTML - formatting only

---
 .../en-us/web/api/element/innerhtml/index.md  | 46 +++++++------------
 1 file changed, 16 insertions(+), 30 deletions(-)

diff --git a/files/en-us/web/api/element/innerhtml/index.md b/files/en-us/web/api/element/innerhtml/index.md
index d6a6adee7aafa9a..3eab9060eb1c3a4 100644
--- a/files/en-us/web/api/element/innerhtml/index.md
+++ b/files/en-us/web/api/element/innerhtml/index.md
@@ -8,28 +8,21 @@ browser-compat: api.Element.innerHTML
 
 {{APIRef("DOM")}}
 
-The {{domxref("Element")}} property
-**`innerHTML`** gets or sets the HTML or XML markup contained
-within the element.
+The {{domxref("Element")}} property **`innerHTML`** gets or sets the HTML or XML markup contained within the element.
 
-To insert the HTML into the document rather than replace the contents of an element,
-use the method {{domxref("Element.insertAdjacentHTML", "insertAdjacentHTML()")}}.
+To insert the HTML into the document rather than replace the contents of an element, use the method {{domxref("Element.insertAdjacentHTML", "insertAdjacentHTML()")}}.
 
 ## Value
 
-A string containing the HTML serialization of the element's
-descendants. Setting the value of `innerHTML` removes all of the element's
-descendants and replaces them with nodes constructed by parsing the HTML given in the
-string _htmlString_.
+A string containing the HTML serialization of the element's descendants.
+Setting the value of `innerHTML` removes all of the element's descendants and replaces them with nodes constructed by parsing the HTML given in the string _htmlString_.
 
 ### Exceptions
 
 - `SyntaxError` {{domxref("DOMException")}}
-  - : Thrown if an attempt was made to set the value of `innerHTML` using a string which
-    is not properly-formed HTML.
+  - : Thrown if an attempt was made to set the value of `innerHTML` using a string which is not properly-formed HTML.
 - `NoModificationAllowedError` {{domxref("DOMException")}}
-  - : Thrown if an attempt was made to insert the HTML into a node whose parent is a
-    {{domxref("Document")}}.
+  - : Thrown if an attempt was made to insert the HTML into a node whose parent is a {{domxref("Document")}}.
 
 ## Usage notes
 
@@ -37,7 +30,8 @@ The `innerHTML` property can be used to examine the current HTML source of the p
 
 ### Reading the HTML contents of an element
 
-Reading `innerHTML` causes the user agent to serialize the HTML or XML fragment comprised of the element's descendants. The resulting string is returned.
+Reading `innerHTML` causes the user agent to serialize the HTML or XML fragment comprised of the element's descendants.
+The resulting string is returned.
 
 ```js
 let contents = myElement.innerHTML;
@@ -45,8 +39,7 @@ let contents = myElement.innerHTML;
 
 This lets you look at the HTML markup of the element's content nodes.
 
-> **Note:** The returned HTML or XML fragment is generated based on the current contents of the element, so the markup and formatting of the returned fragment
-> is likely not to match the original page markup.
+> **Note:** The returned HTML or XML fragment is generated based on the current contents of the element, so the markup and formatting of the returned fragment is likely not to match the original page markup.
 
 ### Replacing the contents of an element
 
@@ -69,7 +62,7 @@ As a result, the document contents are replaced with a display of the page's ent
 ```js
 document.documentElement.innerHTML = `<pre>${document.documentElement.innerHTML.replace(
   /</g,
-  "&lt;",
+  "&lt;"
 )}</pre>`;
 ```
 
@@ -78,10 +71,8 @@ document.documentElement.innerHTML = `<pre>${document.documentElement.innerHTML.
 What exactly happens when you set value of `innerHTML`?
 Doing so causes the user agent to follow these steps:
 
-1. The specified value is parsed as HTML or XML (based on the document type),
-   resulting in a {{domxref("DocumentFragment")}} object representing the new set of DOM nodes for the new elements.
-2. If the element whose contents are being replaced is a {{HTMLElement("template")}} element,
-   then the `<template>` element's {{domxref("HTMLTemplateElement.content", "content")}} attribute is replaced with the new `DocumentFragment` created in step 1.
+1. The specified value is parsed as HTML or XML (based on the document type), resulting in a {{domxref("DocumentFragment")}} object representing the new set of DOM nodes for the new elements.
+2. If the element whose contents are being replaced is a {{HTMLElement("template")}} element, then the `<template>` element's {{domxref("HTMLTemplateElement.content", "content")}} attribute is replaced with the new `DocumentFragment` created in step 1.
 3. For all other elements, the element's contents are replaced with the nodes in the new `DocumentFragment`.
 
 ### Appending HTML to an element
@@ -127,12 +118,9 @@ name = "<script>alert('I am John in an annoying alert!')</script>";
 el.innerHTML = name; // harmless in this case
 ```
 
-Although this may look like a [cross-site scripting](https://en.wikipedia.org/wiki/Cross-site_scripting)
-attack, the result is harmless. HTML specifies that a {{HTMLElement("script")}} tag
-inserted with `innerHTML` [should not execute](https://www.w3.org/TR/2008/WD-html5-20080610/dom.html#innerhtml0).
+Although this may look like a [cross-site scripting](https://en.wikipedia.org/wiki/Cross-site_scripting) attack, the result is harmless. HTML specifies that a {{HTMLElement("script")}} tag inserted with `innerHTML` [should not execute](https://www.w3.org/TR/2008/WD-html5-20080610/dom.html#innerhtml0).
 
-However, there are ways to execute JavaScript without using {{HTMLElement("script")}} elements,
-so there is still a security risk whenever you use `innerHTML` to set strings over which you have no control.
+However, there are ways to execute JavaScript without using {{HTMLElement("script")}} elements, so there is still a security risk whenever you use `innerHTML` to set strings over which you have no control.
 For example:
 
 ```js
@@ -167,12 +155,10 @@ function log(msg) {
 log("Logging mouse events inside this container…");
 ```
 
-The `log()` function creates the log output by getting the current time from a {{jsxref("Date")}} object using
-{{jsxref("Date.toLocaleTimeString", "toLocaleTimeString()")}}, and building a string with the timestamp and the message text.
+The `log()` function creates the log output by getting the current time from a {{jsxref("Date")}} object using {{jsxref("Date.toLocaleTimeString", "toLocaleTimeString()")}}, and building a string with the timestamp and the message text.
 Then the message is appended to the box with the class `"log"`.
 
-We add a second method that logs information about {{domxref("MouseEvent")}} based events
-(such as {{domxref("Element/mousedown_event", "mousedown")}}, {{domxref("Element/click_event", "click")}}, and {{domxref("Element/mouseenter_event", "mouseenter")}}):
+We add a second method that logs information about {{domxref("MouseEvent")}} based events (such as {{domxref("Element/mousedown_event", "mousedown")}}, {{domxref("Element/click_event", "click")}}, and {{domxref("Element/mouseenter_event", "mouseenter")}}):
 
 ```js
 function logEvent(event) {

From 5ab52984aad113ba0ce771afb49c2eb0ce5b8232 Mon Sep 17 00:00:00 2001
From: Hamish Willee <hamishwillee@gmail.com>
Date: Fri, 17 May 2024 14:35:22 +1000
Subject: [PATCH 3/8] Tidy HTMLTemplateElement

---
 files/en-us/web/api/htmltemplateelement/index.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/files/en-us/web/api/htmltemplateelement/index.md b/files/en-us/web/api/htmltemplateelement/index.md
index 35a156ed47d0f78..1109df982f458e5 100644
--- a/files/en-us/web/api/htmltemplateelement/index.md
+++ b/files/en-us/web/api/htmltemplateelement/index.md
@@ -20,7 +20,6 @@ The **`HTMLTemplateElement`** interface enables access to the contents of an HTM
 _This interface inherits the properties of {{domxref("HTMLElement")}}._
 
 - {{domxref("HTMLTemplateElement.content", "content")}} {{ReadOnlyInline}}
-
   - : A read-only {{domxref("DocumentFragment")}} which contains the DOM subtree representing the {{HTMLElement("template")}} element's template contents.
 - {{domxref("HTMLTemplateElement.shadowRootMode", "shadowRootMode")}}
   - : A string that reflects the value of the [`shadowrootmode`](/en-US/docs/Web/HTML/Element/template#shadowrootmode) attribute of the associated `<template>` element.
@@ -28,7 +27,6 @@ _This interface inherits the properties of {{domxref("HTMLElement")}}._
   - : A boolean that reflects the value of the [`shadowrootdelegatesfocus`](/en-US/docs/Web/HTML/Element/template#shadowrootdelegatesfocus) attribute of the associated `<template>` element.
 - {{domxref("HTMLTemplateElement.shadowRootClonable", "shadowRootClonable")}}
   - : A boolean that reflects the value of the [`shadowrootclonable`](/en-US/docs/Web/HTML/Element/template#shadowrootclonable) attribute of the associated `<template>` element.
-
 - {{domxref("HTMLTemplateElement.shadowRootSerializable", "shadowRootSerializable")}}
   - : A boolean that reflects the value of the [`shadowrootserializable`](/en-US/docs/Web/HTML/Element/template#shadowrootserializable) attribute of the associated `<template>` element.
 

From ceffdf3bff745b776e1077cca4e856662a2cc5f0 Mon Sep 17 00:00:00 2001
From: Hamish Willee <hamishwillee@gmail.com>
Date: Fri, 17 May 2024 14:36:00 +1000
Subject: [PATCH 4/8] Charify what getHTML is for and update innerHTML

---
 files/en-us/web/api/element/gethtml/index.md    | 10 ++++++++--
 files/en-us/web/api/element/innerhtml/index.md  | 14 ++++++++++++--
 files/en-us/web/api/shadowroot/gethtml/index.md | 11 +++++++++--
 3 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/files/en-us/web/api/element/gethtml/index.md b/files/en-us/web/api/element/gethtml/index.md
index 7d4fbdf49691ab1..d00223564f14f37 100644
--- a/files/en-us/web/api/element/gethtml/index.md
+++ b/files/en-us/web/api/element/gethtml/index.md
@@ -12,7 +12,10 @@ browser-compat: api.Element.getHTML
 
 The **`getHTML()`** method of the {{domxref("Element")}} interface is used to serialize an element's DOM to an HTML string.
 
-The serialized HTML does not include shadow trees by default, but options can be used to include shadow roots that have been set as {{domxref("ShadowRoot/serializable","serializable")}}, and/or a specified array of {{domxref("ShadowRoot")}} objects.
+The method provides an options argument that enables the serialization of child nodes that are shadow roots.
+The options can be used to include nested shadow roots that have been set as {{domxref("ShadowRoot/serializable","serializable")}}, and/or a specified array of {{domxref("ShadowRoot")}} objects, which may be either open or closed.
+
+Without arguments, child nodes that are shadow roots are not serialized, and this method behaves in the same way as reading the value of {{domxref("Element.innerHTML")}}.
 
 ## Syntax
 
@@ -30,7 +33,8 @@ getHTML(options)
       - : A boolean value that specifies whether to include {{domxref("ShadowRoot/serializable","serializable")}} shadow roots.
         The default value is `false`.
     - `shadowRoots`
-      - : An array of {{domxref("ShadowRoot")}} objects to serialize. These are included regardless of whether they are marked as `serializable`.
+      - : An array of {{domxref("ShadowRoot")}} objects to serialize.
+        These are included regardless of whether they are marked as `serializable`, or if they are open or closed.
         The default value is an empty array.
 
 ### Return value
@@ -53,3 +57,5 @@ None.
 
 - {{domxref("ShadowRoot.getHTML()")}}
 - {{domxref("Element.innerHTML")}}
+- {{domxref("Element.setHTMLUnsafe()")}}
+- {{domxref("ShadowRoot.setHTMLUnsafe()")}}
diff --git a/files/en-us/web/api/element/innerhtml/index.md b/files/en-us/web/api/element/innerhtml/index.md
index 3eab9060eb1c3a4..5ce879eb0d0c76d 100644
--- a/files/en-us/web/api/element/innerhtml/index.md
+++ b/files/en-us/web/api/element/innerhtml/index.md
@@ -10,8 +10,16 @@ browser-compat: api.Element.innerHTML
 
 The {{domxref("Element")}} property **`innerHTML`** gets or sets the HTML or XML markup contained within the element.
 
+More precisely, `innerHTML` gets a serialization of the nested child DOM elements within the element, or sets HTML or XML that should be parsed to replace the DOM tree within the element.
+
 To insert the HTML into the document rather than replace the contents of an element, use the method {{domxref("Element.insertAdjacentHTML", "insertAdjacentHTML()")}}.
 
+The serialization of the DOM tree read from the property does not include {{glossary("shadow tree", "shadow roots")}} — if you want to get a HTML string that includes shadow roots, you must instead use the {{domxref("Element.getHTML()")}} or {{domxref("ShadowRoot.getHTML()")}} methods.
+Similarly, when setting element content using `innerHTML`, the HTML string is parsed into DOM elements that does not contain shadow roots.
+
+So for example [`<template>`](/en-US/docs/Web/HTML/Element/template) is parsed into as {{domxref("HTMLTemplateElement")}}, whether or not the [`shadowrootmode`](/en-US/docs/Web/HTML/Element/template#shadowrootmode) attribute is specfied
+In order to set an element's contents from an HTML string that includes declarative shadow roots, you must use either {{domxref("Element.setHTMLUnsafe()")}} or {{domxref("ShadowRoot.setHTMLUnsafe()")}}.
+
 ## Value
 
 A string containing the HTML serialization of the element's descendants.
@@ -26,8 +34,6 @@ Setting the value of `innerHTML` removes all of the element's descendants and re
 
 ## Usage notes
 
-The `innerHTML` property can be used to examine the current HTML source of the page, including any changes that have been made since the page was initially loaded.
-
 ### Reading the HTML contents of an element
 
 Reading `innerHTML` causes the user agent to serialize the HTML or XML fragment comprised of the element's descendants.
@@ -235,3 +241,7 @@ You can see output into the log by moving the mouse in and out of the box, click
 - {{domxref("Element.outerHTML")}}
 - Parsing HTML or XML into a DOM tree: {{domxref("DOMParser")}}
 - Serializing a DOM tree into an XML string: {{domxref("XMLSerializer")}}
+- {{domxref("Element.getHTML()")}}
+- {{domxref("ShadowRoot.getHTML()")}}
+- {{domxref("Element.setHTMLUnsafe()")}}
+- {{domxref("ShadowRoot.setHTMLUnsafe()")}}
diff --git a/files/en-us/web/api/shadowroot/gethtml/index.md b/files/en-us/web/api/shadowroot/gethtml/index.md
index f662a4f50225631..4fef58708f60ace 100644
--- a/files/en-us/web/api/shadowroot/gethtml/index.md
+++ b/files/en-us/web/api/shadowroot/gethtml/index.md
@@ -12,6 +12,11 @@ browser-compat: api.ShadowRoot.getHTML
 
 The **`getHTML()`** method of the {{domxref("ShadowRoot")}} interface is used to serialize a shadow root's DOM to an HTML string.
 
+The method provides an options argument that enables the serialization of child nodes that are shadow roots.
+The options can be used to include nested shadow roots that have been set as {{domxref("ShadowRoot/serializable","serializable")}}, and/or a specified array of {{domxref("ShadowRoot")}} objects, which may be either open or closed.
+
+Without arguments, child nodes that are shadow roots are not serialized, and this method behaves in the same way as reading the value of {{domxref("Element.innerHTML")}}.
+
 ## Syntax
 
 ```js-nolint
@@ -29,7 +34,7 @@ const html = shadowRoot.getHTML(options)
         The default value is `false`.
     - `shadowRoots`
       - : An array of {{domxref("ShadowRoot")}} objects to serialize.
-        These are included regardless of whether they are marked as `serializable`.
+        These are included regardless of whether they are marked as `serializable`, or if they are open or closed.
         The default value is an empty array.
 
 ### Return value
@@ -51,4 +56,6 @@ None.
 ## See Also
 
 - {{domxref("Element.getHTML()")}}
-- {{domxref("ShadowRoot.innerHTML")}}
+- {{domxref("Element.innerHTML")}}
+- {{domxref("ShadowRoot.setHTMLUnsafe()")}}
+- {{domxref("Element.setHTMLUnsafe()")}}
\ No newline at end of file

From d30025c8e935270601d1e71f58f97bfc10fde475 Mon Sep 17 00:00:00 2001
From: Hamish Willee <hamishwillee@gmail.com>
Date: Fri, 17 May 2024 14:37:24 +1000
Subject: [PATCH 5/8] Update files/en-us/web/api/element/attachshadow/index.md

---
 files/en-us/web/api/element/attachshadow/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/api/element/attachshadow/index.md b/files/en-us/web/api/element/attachshadow/index.md
index ea37a4648496c86..f28cbe2073891e4 100644
--- a/files/en-us/web/api/element/attachshadow/index.md
+++ b/files/en-us/web/api/element/attachshadow/index.md
@@ -86,8 +86,8 @@ attachShadow(options)
     - `serializable` {{Optional_Inline}}
 
       - : A boolean that, when set to `true`, indicates that the shadow root is serializable.
-        Its default value is `false`.
         If set, the shadow root may be serialized by calling the {{DOMxRef('Element.getHTML()')}} or {{DOMxRef('ShadowRoot.getHTML()')}} methods with the `options.serializableShadowRoots` parameter set `true`.
+        Its default value is `false`.
 
     - `slotAssignment` {{Optional_inline}}
 

From 44e1f7d9e24fd1da01da4bda8dde055727ae32c4 Mon Sep 17 00:00:00 2001
From: Hamish Willee <hamishwillee@gmail.com>
Date: Fri, 17 May 2024 14:38:54 +1000
Subject: [PATCH 6/8] Update files/en-us/web/api/element/innerhtml/index.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
---
 files/en-us/web/api/element/innerhtml/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/api/element/innerhtml/index.md b/files/en-us/web/api/element/innerhtml/index.md
index 5ce879eb0d0c76d..2672f2af23cd334 100644
--- a/files/en-us/web/api/element/innerhtml/index.md
+++ b/files/en-us/web/api/element/innerhtml/index.md
@@ -68,7 +68,7 @@ As a result, the document contents are replaced with a display of the page's ent
 ```js
 document.documentElement.innerHTML = `<pre>${document.documentElement.innerHTML.replace(
   /</g,
-  "&lt;"
+  "&lt;",
 )}</pre>`;
 ```
 

From 7278d9ca5d538687a32f97e718ae3b22ee527505 Mon Sep 17 00:00:00 2001
From: Hamish Willee <hamishwillee@gmail.com>
Date: Fri, 17 May 2024 14:57:04 +1000
Subject: [PATCH 7/8] Try fix lint errors

---
 files/en-us/web/api/shadowroot/gethtml/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/api/shadowroot/gethtml/index.md b/files/en-us/web/api/shadowroot/gethtml/index.md
index 4fef58708f60ace..70b3f7e4d83a7f6 100644
--- a/files/en-us/web/api/shadowroot/gethtml/index.md
+++ b/files/en-us/web/api/shadowroot/gethtml/index.md
@@ -58,4 +58,4 @@ None.
 - {{domxref("Element.getHTML()")}}
 - {{domxref("Element.innerHTML")}}
 - {{domxref("ShadowRoot.setHTMLUnsafe()")}}
-- {{domxref("Element.setHTMLUnsafe()")}}
\ No newline at end of file
+- {{domxref("Element.setHTMLUnsafe()")}}

From 7748d0f62096f7303254d9402147d7759cffdd0c Mon Sep 17 00:00:00 2001
From: sideshowbarker <mike@w3.org>
Date: Fri, 17 May 2024 18:09:26 +0900
Subject: [PATCH 8/8] Update files/en-us/web/api/element/innerhtml/index.md

---
 files/en-us/web/api/element/innerhtml/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/api/element/innerhtml/index.md b/files/en-us/web/api/element/innerhtml/index.md
index 2672f2af23cd334..6c21690218d9de3 100644
--- a/files/en-us/web/api/element/innerhtml/index.md
+++ b/files/en-us/web/api/element/innerhtml/index.md
@@ -15,7 +15,7 @@ More precisely, `innerHTML` gets a serialization of the nested child DOM element
 To insert the HTML into the document rather than replace the contents of an element, use the method {{domxref("Element.insertAdjacentHTML", "insertAdjacentHTML()")}}.
 
 The serialization of the DOM tree read from the property does not include {{glossary("shadow tree", "shadow roots")}} — if you want to get a HTML string that includes shadow roots, you must instead use the {{domxref("Element.getHTML()")}} or {{domxref("ShadowRoot.getHTML()")}} methods.
-Similarly, when setting element content using `innerHTML`, the HTML string is parsed into DOM elements that does not contain shadow roots.
+Similarly, when setting element content using `innerHTML`, the HTML string is parsed into DOM elements that do not contain shadow roots.
 
 So for example [`<template>`](/en-US/docs/Web/HTML/Element/template) is parsed into as {{domxref("HTMLTemplateElement")}}, whether or not the [`shadowrootmode`](/en-US/docs/Web/HTML/Element/template#shadowrootmode) attribute is specfied
 In order to set an element's contents from an HTML string that includes declarative shadow roots, you must use either {{domxref("Element.setHTMLUnsafe()")}} or {{domxref("ShadowRoot.setHTMLUnsafe()")}}.