From 2a7630f0570013aa65fd3d5dfe9a407b0c014af6 Mon Sep 17 00:00:00 2001
From: James Browning <thejamesernator@gmail.com>
Date: Wed, 26 Nov 2025 14:40:50 +1300
Subject: [PATCH 1/5] Add declarative shadow dom support

---
 .../lib/index.ts                              |  8 ++
 packages/parse5/lib/common/html.ts            |  5 ++
 packages/parse5/lib/common/token.ts           |  4 +
 packages/parse5/lib/parser/index.ts           | 48 +++++++++-
 packages/parse5/lib/serializer/index.ts       | 87 ++++++++++++++++---
 packages/parse5/lib/tree-adapters/default.ts  | 57 +++++++++++-
 .../parse5/lib/tree-adapters/interface.ts     | 43 ++++++++-
 test/data/serialization/tests.json            |  4 +-
 8 files changed, 238 insertions(+), 18 deletions(-)

diff --git a/packages/parse5-htmlparser2-tree-adapter/lib/index.ts b/packages/parse5-htmlparser2-tree-adapter/lib/index.ts
index f99782d16..552096b32 100644
--- a/packages/parse5-htmlparser2-tree-adapter/lib/index.ts
+++ b/packages/parse5-htmlparser2-tree-adapter/lib/index.ts
@@ -289,4 +289,12 @@ export const adapter: TreeAdapter<Htmlparser2TreeAdapterMap> = {
             ...endLocation,
         };
     },
+
+    // Shadow roots
+    attachDeclarativeShadowRoot(): never {
+        throw new Error('not supported');
+    },
+    getShadowRoot(): never {
+        throw new Error('not supported');
+    },
 };
diff --git a/packages/parse5/lib/common/html.ts b/packages/parse5/lib/common/html.ts
index d9d341243..f4a10905f 100644
--- a/packages/parse5/lib/common/html.ts
+++ b/packages/parse5/lib/common/html.ts
@@ -17,6 +17,11 @@ export enum ATTRS {
     COLOR = 'color',
     FACE = 'face',
     SIZE = 'size',
+    SHADOWROOTMODE = 'shadowrootmode',
+    SHADOWROOTCLONABLE = 'shadowrootclonable',
+    SHADOWROOTSERIALIZABLE = 'shadowrootserializable',
+    SHADOWROOTDELEGATESFOCUS = 'shadowrootdelegatesfocus',
+    SHADOWROOTCUSTOMELEMENTREGISTRY = 'shadowrootcustomelementregistry',
 }
 
 /**
diff --git a/packages/parse5/lib/common/token.ts b/packages/parse5/lib/common/token.ts
index 4b1a1283d..637d2ad8c 100644
--- a/packages/parse5/lib/common/token.ts
+++ b/packages/parse5/lib/common/token.ts
@@ -87,6 +87,10 @@ export function getTokenAttr(token: TagToken, attrName: string): string | null {
     return null;
 }
 
+export function hasTokenAttr(token: TagToken, attrName: string): boolean {
+    return getTokenAttr(token, attrName) !== null;
+}
+
 export interface CommentToken extends TokenBase {
     readonly type: TokenType.COMMENT;
     data: string;
diff --git a/packages/parse5/lib/parser/index.ts b/packages/parse5/lib/parser/index.ts
index 9779f68f3..a3fe22cbc 100644
--- a/packages/parse5/lib/parser/index.ts
+++ b/packages/parse5/lib/parser/index.ts
@@ -28,6 +28,7 @@ import {
     type EOFToken,
     type LocationWithAttributes,
     type ElementLocation,
+    hasTokenAttr,
 } from '../common/token.js';
 
 //Misc constants
@@ -96,6 +97,13 @@ export interface ParserOptions<T extends TreeAdapterTypeMap> {
      */
     sourceCodeLocationInfo?: boolean;
 
+    /**
+     * Whether declarative shadow roots should be parsed or treated as ordinary templates.
+     *
+     * @default `false`
+     */
+    allowDeclarativeShadowRoots?: boolean;
+
     /**
      * Specifies the resulting tree format.
      *
@@ -114,6 +122,7 @@ export interface ParserOptions<T extends TreeAdapterTypeMap> {
 const defaultParserOptions: Required<ParserOptions<DefaultTreeAdapterMap>> = {
     scriptingEnabled: true,
     sourceCodeLocationInfo: false,
+    allowDeclarativeShadowRoots: false,
     treeAdapter: defaultTreeAdapter,
     onParseError: null,
 };
@@ -453,14 +462,17 @@ export class Parser<T extends TreeAdapterTypeMap> implements TokenHandler, Stack
     }
 
     /** @protected */
-    _insertTemplate(token: TagToken): void {
+    _insertTemplate(token: TagToken, onlyAddElementToStack: boolean = false): T['element'] {
         const tmpl = this.treeAdapter.createElement(token.tagName, NS.HTML, token.attrs);
         const content = this.treeAdapter.createDocumentFragment();
 
         this.treeAdapter.setTemplateContent(tmpl, content);
-        this._attachElementToTree(tmpl, token.location);
+        if (!onlyAddElementToStack) {
+            this._attachElementToTree(tmpl, token.location);
+        }
         this.openElements.push(tmpl, token.tagID);
         if (this.options.sourceCodeLocationInfo) this.treeAdapter.setNodeSourceCodeLocation(content, null);
+        return tmpl;
     }
 
     /** @protected */
@@ -1723,11 +1735,41 @@ function startTagInHead<T extends TreeAdapterTypeMap>(p: Parser<T>, token: TagTo
             break;
         }
         case $.TEMPLATE: {
-            p._insertTemplate(token);
             p.activeFormattingElements.insertMarker();
             p.framesetOk = false;
             p.insertionMode = InsertionMode.IN_TEMPLATE;
             p.tmplInsertionModeStack.unshift(InsertionMode.IN_TEMPLATE);
+
+            const mode = getTokenAttr(token, ATTRS.SHADOWROOTMODE);
+            if (
+                !p.options.allowDeclarativeShadowRoots ||
+                (mode !== 'open' && mode !== 'closed') ||
+                p._getAdjustedCurrentElement() !== p.openElements.current
+            ) {
+                p._insertTemplate(token);
+            } else {
+                const declarativeShadowHostElement = p._getAdjustedCurrentElement();
+                const shadowRoot = p.treeAdapter.getShadowRoot(declarativeShadowHostElement);
+                if (shadowRoot) {
+                    p._insertTemplate(token);
+                } else {
+                    const template = p._insertTemplate(token, true);
+                    const clonable = hasTokenAttr(token, ATTRS.SHADOWROOTCLONABLE);
+                    const serializable = hasTokenAttr(token, ATTRS.SHADOWROOTSERIALIZABLE);
+                    const delegatesFocus = hasTokenAttr(token, ATTRS.SHADOWROOTDELEGATESFOCUS);
+                    const customElementRegistry = getTokenAttr(token, ATTRS.SHADOWROOTCUSTOMELEMENTREGISTRY);
+                    const shadowRoot = p.treeAdapter.attachDeclarativeShadowRoot(declarativeShadowHostElement, {
+                        mode,
+                        clonable,
+                        serializable,
+                        delegatesFocus,
+                        customElementRegistry,
+                        declarativeTemplateAttributes: token.attrs,
+                    });
+                    p.treeAdapter.setTemplateContentForDeclarativeShadowRootParsing(template, shadowRoot);
+                }
+            }
+
             break;
         }
         case $.HEAD: {
diff --git a/packages/parse5/lib/serializer/index.ts b/packages/parse5/lib/serializer/index.ts
index ef7326abb..fa350c172 100644
--- a/packages/parse5/lib/serializer/index.ts
+++ b/packages/parse5/lib/serializer/index.ts
@@ -1,7 +1,8 @@
-import { TAG_NAMES as $, NS, hasUnescapedText } from '../common/html.js';
+import { TAG_NAMES as $, ATTRS, NS, hasUnescapedText } from '../common/html.js';
 import { escapeText, escapeAttribute } from 'entities/escape';
 import type { TreeAdapter, TreeAdapterTypeMap } from '../tree-adapters/interface.js';
 import { defaultTreeAdapter, type DefaultTreeAdapterMap } from '../tree-adapters/default.js';
+import type { Attribute } from '../common/token.js';
 
 // Sets
 const VOID_ELEMENTS = new Set<string>([
@@ -33,6 +34,21 @@ function isVoidElement<T extends TreeAdapterTypeMap>(node: T['node'], options: I
     );
 }
 
+const KNOWN_DECLARATIVE_SHADOW_ROOT_ATTRIBUTES = new Set<string>([
+    ATTRS.SHADOWROOTCLONABLE,
+    ATTRS.SHADOWROOTCUSTOMELEMENTREGISTRY,
+    ATTRS.SHADOWROOTDELEGATESFOCUS,
+    ATTRS.SHADOWROOTMODE,
+    ATTRS.SHADOWROOTSERIALIZABLE,
+]);
+
+function isKnownDeclarativeShadowRootAttribute(attr: Attribute): boolean {
+    if (attr.namespace !== undefined) {
+        return false;
+    }
+    return KNOWN_DECLARATIVE_SHADOW_ROOT_ATTRIBUTES.has(attr.name);
+}
+
 export interface SerializerOptions<T extends TreeAdapterTypeMap> {
     /**
      * Specifies input tree format.
@@ -47,11 +63,29 @@ export interface SerializerOptions<T extends TreeAdapterTypeMap> {
      *  @default `true`
      */
     scriptingEnabled?: boolean;
+    /**
+     * Whether to serialize shadow roots.
+     *
+     * @default `false`
+     */
+    serializableShadowRoots?: boolean;
+
+    /**
+     * Shadow roots to always serialize.
+     *
+     * @default `[]`
+     */
+    shadowRoots?: Array<T['shadowRoot']>;
 }
 
 type InternalOptions<T extends TreeAdapterTypeMap> = Required<SerializerOptions<T>>;
 
-const defaultOpts: InternalOptions<DefaultTreeAdapterMap> = { treeAdapter: defaultTreeAdapter, scriptingEnabled: true };
+const defaultOpts: InternalOptions<DefaultTreeAdapterMap> = {
+    treeAdapter: defaultTreeAdapter,
+    scriptingEnabled: true,
+    serializableShadowRoots: false,
+    shadowRoots: [],
+};
 
 /**
  * Serializes an AST node to an HTML string.
@@ -158,17 +192,50 @@ function serializeNode<T extends TreeAdapterTypeMap>(node: T['node'], options: I
 function serializeElement<T extends TreeAdapterTypeMap>(node: T['element'], options: InternalOptions<T>): string {
     const tn = options.treeAdapter.getTagName(node);
 
-    return `<${tn}${serializeAttributes(node, options)}>${
-        isVoidElement(node, options) ? '' : `${serializeChildNodes(node, options)}</${tn}>`
-    }`;
+    let html = `<${tn}${serializeAttributes(options.treeAdapter.getAttrList(node))}>`;
+    if (isVoidElement(node, options)) {
+        return html;
+    }
+    const shadowRoot = options.treeAdapter.getShadowRoot(node);
+    if (shadowRoot !== null) {
+        const shadowRootInit = options.treeAdapter.getShadowRootInit(shadowRoot);
+
+        if (
+            (options.serializableShadowRoots && shadowRootInit.serializable) ||
+            options.shadowRoots.includes(shadowRoot)
+        ) {
+            const declarativeTemplateAttrs: Attribute[] = [];
+            declarativeTemplateAttrs.push({ name: ATTRS.SHADOWROOTMODE, value: shadowRootInit.mode });
+            if (shadowRootInit.delegatesFocus) {
+                declarativeTemplateAttrs.push({ name: ATTRS.SHADOWROOTMODE, value: '' });
+            }
+            if (shadowRootInit.serializable) {
+                declarativeTemplateAttrs.push({ name: ATTRS.SHADOWROOTSERIALIZABLE, value: '' });
+            }
+            if (shadowRootInit.clonable) {
+                declarativeTemplateAttrs.push({ name: ATTRS.SHADOWROOTCLONABLE, value: '' });
+            }
+            if (shadowRootInit.customElementRegistry !== null) {
+                declarativeTemplateAttrs.push({ name: ATTRS.SHADOWROOTCUSTOMELEMENTREGISTRY, value: '' });
+            }
+
+            declarativeTemplateAttrs.push(
+                ...shadowRootInit.declarativeTemplateAttributes.filter(
+                    (attr) => !isKnownDeclarativeShadowRootAttribute(attr),
+                ),
+            );
+
+            html += `<template${serializeAttributes(declarativeTemplateAttrs)}>${serializeChildNodes(options.treeAdapter.getChildNodes(shadowRoot), options)}</template>`;
+        }
+    }
+
+    html += `</${tn}>`;
+    return html;
 }
 
-function serializeAttributes<T extends TreeAdapterTypeMap>(
-    node: T['element'],
-    { treeAdapter }: InternalOptions<T>,
-): string {
+function serializeAttributes(attrs: Attribute[]): string {
     let html = '';
-    for (const attr of treeAdapter.getAttrList(node)) {
+    for (const attr of attrs) {
         html += ' ';
 
         if (attr.namespace) {
diff --git a/packages/parse5/lib/tree-adapters/default.ts b/packages/parse5/lib/tree-adapters/default.ts
index 415a9d79c..4beb76a88 100644
--- a/packages/parse5/lib/tree-adapters/default.ts
+++ b/packages/parse5/lib/tree-adapters/default.ts
@@ -1,6 +1,6 @@
 import { DOCUMENT_MODE, type NS } from '../common/html.js';
 import type { Attribute, Location, ElementLocation } from '../common/token.js';
-import type { TreeAdapter, TreeAdapterTypeMap } from './interface.js';
+import type { ShadowRootInit, TreeAdapter, TreeAdapterTypeMap } from './interface.js';
 
 export interface Document {
     /** The name of the node. */
@@ -18,13 +18,30 @@ export interface Document {
 
 export interface DocumentFragment {
     /** The name of the node. */
-    nodeName: '#document-fragment';
+    nodeName: '#document-fragment' | '#shadow-root';
     /** The node's children. */
     childNodes: ChildNode[];
     /** Comment source code location info. Available if location info is enabled. */
     sourceCodeLocation?: Location | null;
 }
 
+export interface ShadowRoot extends DocumentFragment {
+    /** The name of the node. */
+    nodeName: '#shadow-root';
+    /** The shadow root mode. */
+    mode: 'open' | 'closed';
+    /** Whether the shadow root delegates focus. */
+    delegatesFocus: boolean;
+    /** Whether the shadow root is clonable or not. */
+    clonable: boolean;
+    /** Whether the shadow root is clonable or not. */
+    serializable: boolean;
+    /** The custom element registry this node belongs to. */
+    customElementRegistry: string | null;
+    /** Attributes that appear on the <template> element when serialized as a declarative shadow root. */
+    declarativeTemplateAttributes: Attribute[];
+}
+
 export interface Element {
     /** Element tag name. Same as {@link tagName}. */
     nodeName: string;
@@ -38,6 +55,8 @@ export interface Element {
     sourceCodeLocation?: ElementLocation | null;
     /** Parent node. */
     parentNode: ParentNode | null;
+    /** Shadow root if present. */
+    shadowRoot: ShadowRoot | null;
     /** The node's children. */
     childNodes: ChildNode[];
 }
@@ -85,7 +104,7 @@ export interface DocumentType {
     sourceCodeLocation?: Location | null;
 }
 
-export type ParentNode = Document | DocumentFragment | Element | Template;
+export type ParentNode = Document | DocumentFragment | ShadowRoot | Element | Template;
 export type ChildNode = Element | Template | CommentNode | TextNode | DocumentType;
 export type Node = ParentNode | ChildNode;
 
@@ -127,6 +146,7 @@ export const defaultTreeAdapter: TreeAdapter<DefaultTreeAdapterMap> = {
             namespaceURI,
             childNodes: [],
             parentNode: null,
+            shadowRoot: null,
         };
     },
 
@@ -311,4 +331,35 @@ export const defaultTreeAdapter: TreeAdapter<DefaultTreeAdapterMap> = {
     updateNodeSourceCodeLocation(node: Node, endLocation: ElementLocation): void {
         node.sourceCodeLocation = { ...node.sourceCodeLocation, ...endLocation };
     },
+
+    // Shadow roots
+    attachDeclarativeShadowRoot(
+        element: Element,
+        { mode, clonable, serializable, delegatesFocus, customElementRegistry, declarativeTemplateAttributes },
+    ): ShadowRoot {
+        const shadowRoot: ShadowRoot = {
+            nodeName: '#shadow-root',
+            childNodes: [],
+            mode,
+            clonable,
+            serializable,
+            delegatesFocus,
+            customElementRegistry,
+            declarativeTemplateAttributes,
+        };
+        element.shadowRoot = shadowRoot;
+        return shadowRoot;
+    },
+
+    getShadowRoot(element: Element): ShadowRoot | null {
+        return element.shadowRoot;
+    },
+
+    getShadowRootInit(shadowRoot: ShadowRoot): ShadowRootInit {
+        return shadowRoot;
+    },
+
+    setTemplateContentForDeclarativeShadowRootParsing(template: Template, shadowRoot: ShadowRoot): void {
+        template.content = shadowRoot;
+    },
 };
diff --git a/packages/parse5/lib/tree-adapters/interface.ts b/packages/parse5/lib/tree-adapters/interface.ts
index 3d43d20e3..0a1386426 100644
--- a/packages/parse5/lib/tree-adapters/interface.ts
+++ b/packages/parse5/lib/tree-adapters/interface.ts
@@ -12,6 +12,7 @@ export interface TreeAdapterTypeMap<
     TextNode = unknown,
     Template = unknown,
     DocumentType = unknown,
+    ShadowRoot = unknown,
 > {
     node: Node;
     parentNode: ParentNode;
@@ -23,8 +24,18 @@ export interface TreeAdapterTypeMap<
     textNode: TextNode;
     template: Template;
     documentType: DocumentType;
+    shadowRoot: ShadowRoot;
 }
 
+export type ShadowRootInit = {
+    mode: 'open' | 'closed';
+    clonable: boolean;
+    serializable: boolean;
+    delegatesFocus: boolean;
+    customElementRegistry: string | null;
+    declarativeTemplateAttributes: Attribute[];
+};
+
 /**
  * Tree adapter is a set of utility functions that provides minimal required abstraction layer beetween parser and a specific AST format.
  * Note that `TreeAdapter` is not designed to be a general purpose AST manipulation library. You can build such library
@@ -285,7 +296,7 @@ export interface TreeAdapter<T extends TreeAdapterTypeMap = TreeAdapterTypeMap>
      * @param templateElement - `<template>` element.
      * @param contentElement -  Content element.
      */
-    setTemplateContent(templateElement: T['template'], contentElement: T['documentFragment']): void;
+    setTemplateContent(templateElement: T['template'], contentElement: T['documentFragment'] | T['shadowRoot']): void;
 
     /**
      * Optional callback for elements being pushed to the stack of open elements.
@@ -300,4 +311,34 @@ export interface TreeAdapter<T extends TreeAdapterTypeMap = TreeAdapterTypeMap>
      * @param item The element being popped.
      */
     onItemPop?: (item: T['element'], newTop: T['parentNode']) => void;
+
+    /**
+     * Attaches a declarative shadow root to the given element.
+     *
+     * @param element - Element
+     *
+     */
+    attachDeclarativeShadowRoot(element: T['element'], shadowRootInit: ShadowRootInit): T['shadowRoot'];
+
+    /**
+     * Returns the element's shadow root if it has one.
+     *
+     * @param element - Element
+     */
+    getShadowRoot(element: T['element']): T['shadowRoot'] | null;
+
+    /**
+     * Returns an object with the neccessary properties to initialize the given shadow root.
+     *
+     * @param shadowRoot - Shadow root
+     */
+    getShadowRootInit(shadowRoot: T['shadowRoot']): ShadowRootInit;
+
+    /**
+     * Sets the template's content to the given shadow root. Unlike setTemplateContent this must not change the shadow root's host.
+     *
+     * @param template - The template to attach to
+     * @param shadowRoot - The shadow root to attach
+     */
+    setTemplateContentForDeclarativeShadowRootParsing(template: T['template'], shadowRoot: T['shadowRoot']): void;
 }
diff --git a/test/data/serialization/tests.json b/test/data/serialization/tests.json
index 35affb1bc..0ae9eacf0 100644
--- a/test/data/serialization/tests.json
+++ b/test/data/serialization/tests.json
@@ -101,7 +101,9 @@
     },
     {
         "name": "Text nodes escaping - <noscript> with scripting disabled (GH-332)",
-        "options": { "scriptingEnabled": false },
+        "options": {
+            "scriptingEnabled": false
+        },
         "input": "<body><noscript>& ><</noscript></body>",
         "expected": "<html><head></head><body><noscript>&amp; &gt;&lt;</noscript></body></html>"
     },

From 019f59bf6d0ea39e16cf7ff5c82abb7f4533b6a2 Mon Sep 17 00:00:00 2001
From: James Browning <thejamesernator@gmail.com>
Date: Wed, 26 Nov 2025 14:48:32 +1300
Subject: [PATCH 2/5] Add stubs for htmlparser2 tree adapter

---
 packages/parse5-htmlparser2-tree-adapter/lib/index.ts | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/packages/parse5-htmlparser2-tree-adapter/lib/index.ts b/packages/parse5-htmlparser2-tree-adapter/lib/index.ts
index 552096b32..cfd54186a 100644
--- a/packages/parse5-htmlparser2-tree-adapter/lib/index.ts
+++ b/packages/parse5-htmlparser2-tree-adapter/lib/index.ts
@@ -292,9 +292,15 @@ export const adapter: TreeAdapter<Htmlparser2TreeAdapterMap> = {
 
     // Shadow roots
     attachDeclarativeShadowRoot(): never {
-        throw new Error('not supported');
+        throw new Error("htmlparser2 doesn't support declarative shadow roots");
     },
     getShadowRoot(): never {
-        throw new Error('not supported');
+        throw new Error("htmlparser2 doesn't support declarative shadow roots");
+    },
+    getShadowRootInit(): never {
+        throw new Error("htmlparser2 doesn't support declarative shadow roots");
+    },
+    setTemplateContentForDeclarativeShadowRootParsing(): never {
+        throw new Error("htmlparser2 doesn't support declarative shadow roots");
     },
 };

From 7bf0766918cf34deb0b7726eda854ad95d891b10 Mon Sep 17 00:00:00 2001
From: James Browning <thejamesernator@gmail.com>
Date: Wed, 26 Nov 2025 14:57:11 +1300
Subject: [PATCH 3/5] Undo accidental format change to tests.json

---
 test/data/serialization/tests.json | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/test/data/serialization/tests.json b/test/data/serialization/tests.json
index 0ae9eacf0..35affb1bc 100644
--- a/test/data/serialization/tests.json
+++ b/test/data/serialization/tests.json
@@ -101,9 +101,7 @@
     },
     {
         "name": "Text nodes escaping - <noscript> with scripting disabled (GH-332)",
-        "options": {
-            "scriptingEnabled": false
-        },
+        "options": { "scriptingEnabled": false },
         "input": "<body><noscript>& ><</noscript></body>",
         "expected": "<html><head></head><body><noscript>&amp; &gt;&lt;</noscript></body></html>"
     },

From c2dbd00655dcd7c4c34a35c7329ae62768bbfbc9 Mon Sep 17 00:00:00 2001
From: James Browning <thejamesernator@gmail.com>
Date: Wed, 26 Nov 2025 15:13:53 +1300
Subject: [PATCH 4/5] Make shadow root support optional

---
 .../lib/index.ts                              | 14 -----
 packages/parse5/lib/parser/index.ts           | 31 +++++++---
 packages/parse5/lib/serializer/index.ts       | 18 +++++-
 .../parse5/lib/tree-adapters/interface.ts     | 61 ++++++++++---------
 4 files changed, 70 insertions(+), 54 deletions(-)

diff --git a/packages/parse5-htmlparser2-tree-adapter/lib/index.ts b/packages/parse5-htmlparser2-tree-adapter/lib/index.ts
index cfd54186a..f99782d16 100644
--- a/packages/parse5-htmlparser2-tree-adapter/lib/index.ts
+++ b/packages/parse5-htmlparser2-tree-adapter/lib/index.ts
@@ -289,18 +289,4 @@ export const adapter: TreeAdapter<Htmlparser2TreeAdapterMap> = {
             ...endLocation,
         };
     },
-
-    // Shadow roots
-    attachDeclarativeShadowRoot(): never {
-        throw new Error("htmlparser2 doesn't support declarative shadow roots");
-    },
-    getShadowRoot(): never {
-        throw new Error("htmlparser2 doesn't support declarative shadow roots");
-    },
-    getShadowRootInit(): never {
-        throw new Error("htmlparser2 doesn't support declarative shadow roots");
-    },
-    setTemplateContentForDeclarativeShadowRootParsing(): never {
-        throw new Error("htmlparser2 doesn't support declarative shadow roots");
-    },
 };
diff --git a/packages/parse5/lib/parser/index.ts b/packages/parse5/lib/parser/index.ts
index a3fe22cbc..4c1f1a489 100644
--- a/packages/parse5/lib/parser/index.ts
+++ b/packages/parse5/lib/parser/index.ts
@@ -152,6 +152,10 @@ export class Parser<T extends TreeAdapterTypeMap> implements TokenHandler, Stack
         this.treeAdapter = this.options.treeAdapter;
         this.onParseError = this.options.onParseError;
 
+        if (this.options.allowDeclarativeShadowRoots && !this.treeAdapter.declarativeShadowRootAdapter) {
+            throw new TypeError(`the given tree adapter does not have declarative shadow dom support`);
+        }
+
         // Always enable location info if we report parse errors.
         if (this.onParseError) {
             this.options.sourceCodeLocationInfo = true;
@@ -1749,7 +1753,8 @@ function startTagInHead<T extends TreeAdapterTypeMap>(p: Parser<T>, token: TagTo
                 p._insertTemplate(token);
             } else {
                 const declarativeShadowHostElement = p._getAdjustedCurrentElement();
-                const shadowRoot = p.treeAdapter.getShadowRoot(declarativeShadowHostElement);
+                const shadowRoot =
+                    p.treeAdapter.declarativeShadowRootAdapter!.getShadowRoot(declarativeShadowHostElement);
                 if (shadowRoot) {
                     p._insertTemplate(token);
                 } else {
@@ -1758,15 +1763,21 @@ function startTagInHead<T extends TreeAdapterTypeMap>(p: Parser<T>, token: TagTo
                     const serializable = hasTokenAttr(token, ATTRS.SHADOWROOTSERIALIZABLE);
                     const delegatesFocus = hasTokenAttr(token, ATTRS.SHADOWROOTDELEGATESFOCUS);
                     const customElementRegistry = getTokenAttr(token, ATTRS.SHADOWROOTCUSTOMELEMENTREGISTRY);
-                    const shadowRoot = p.treeAdapter.attachDeclarativeShadowRoot(declarativeShadowHostElement, {
-                        mode,
-                        clonable,
-                        serializable,
-                        delegatesFocus,
-                        customElementRegistry,
-                        declarativeTemplateAttributes: token.attrs,
-                    });
-                    p.treeAdapter.setTemplateContentForDeclarativeShadowRootParsing(template, shadowRoot);
+                    const shadowRoot = p.treeAdapter.declarativeShadowRootAdapter!.attachDeclarativeShadowRoot(
+                        declarativeShadowHostElement,
+                        {
+                            mode,
+                            clonable,
+                            serializable,
+                            delegatesFocus,
+                            customElementRegistry,
+                            declarativeTemplateAttributes: token.attrs,
+                        },
+                    );
+                    p.treeAdapter.declarativeShadowRootAdapter!.setTemplateContentForDeclarativeShadowRootParsing(
+                        template,
+                        shadowRoot,
+                    );
                 }
             }
 
diff --git a/packages/parse5/lib/serializer/index.ts b/packages/parse5/lib/serializer/index.ts
index fa350c172..9dc5ff1be 100644
--- a/packages/parse5/lib/serializer/index.ts
+++ b/packages/parse5/lib/serializer/index.ts
@@ -87,6 +87,17 @@ const defaultOpts: InternalOptions<DefaultTreeAdapterMap> = {
     shadowRoots: [],
 };
 
+function validateDeclarativeShadowRootSupport<T extends TreeAdapterTypeMap = DefaultTreeAdapterMap>(
+    opts: InternalOptions<T>,
+): void {
+    if (
+        (opts.serializableShadowRoots || opts.shadowRoots.length > 0) &&
+        !opts.treeAdapter.declarativeShadowRootAdapter
+    ) {
+        throw new TypeError(`the given tree adapter does not support serializing shadow roots`);
+    }
+}
+
 /**
  * Serializes an AST node to an HTML string.
  *
@@ -115,6 +126,8 @@ export function serialize<T extends TreeAdapterTypeMap = DefaultTreeAdapterMap>(
 ): string {
     const opts = { ...defaultOpts, ...options } as InternalOptions<T>;
 
+    validateDeclarativeShadowRootSupport(opts);
+
     if (isVoidElement(node, opts)) {
         return '';
     }
@@ -146,6 +159,7 @@ export function serializeOuter<T extends TreeAdapterTypeMap = DefaultTreeAdapter
     options?: SerializerOptions<T>,
 ): string {
     const opts = { ...defaultOpts, ...options } as InternalOptions<T>;
+    validateDeclarativeShadowRootSupport(opts);
     return serializeNode(node, opts);
 }
 
@@ -196,9 +210,9 @@ function serializeElement<T extends TreeAdapterTypeMap>(node: T['element'], opti
     if (isVoidElement(node, options)) {
         return html;
     }
-    const shadowRoot = options.treeAdapter.getShadowRoot(node);
+    const shadowRoot = options.treeAdapter.declarativeShadowRootAdapter!.getShadowRoot(node);
     if (shadowRoot !== null) {
-        const shadowRootInit = options.treeAdapter.getShadowRootInit(shadowRoot);
+        const shadowRootInit = options.treeAdapter.declarativeShadowRootAdapter!.getShadowRootInit(shadowRoot);
 
         if (
             (options.serializableShadowRoots && shadowRootInit.serializable) ||
diff --git a/packages/parse5/lib/tree-adapters/interface.ts b/packages/parse5/lib/tree-adapters/interface.ts
index 0a1386426..5b02f9f8b 100644
--- a/packages/parse5/lib/tree-adapters/interface.ts
+++ b/packages/parse5/lib/tree-adapters/interface.ts
@@ -313,32 +313,37 @@ export interface TreeAdapter<T extends TreeAdapterTypeMap = TreeAdapterTypeMap>
     onItemPop?: (item: T['element'], newTop: T['parentNode']) => void;
 
     /**
-     * Attaches a declarative shadow root to the given element.
-     *
-     * @param element - Element
-     *
-     */
-    attachDeclarativeShadowRoot(element: T['element'], shadowRootInit: ShadowRootInit): T['shadowRoot'];
-
-    /**
-     * Returns the element's shadow root if it has one.
-     *
-     * @param element - Element
-     */
-    getShadowRoot(element: T['element']): T['shadowRoot'] | null;
-
-    /**
-     * Returns an object with the neccessary properties to initialize the given shadow root.
-     *
-     * @param shadowRoot - Shadow root
-     */
-    getShadowRootInit(shadowRoot: T['shadowRoot']): ShadowRootInit;
-
-    /**
-     * Sets the template's content to the given shadow root. Unlike setTemplateContent this must not change the shadow root's host.
-     *
-     * @param template - The template to attach to
-     * @param shadowRoot - The shadow root to attach
-     */
-    setTemplateContentForDeclarativeShadowRootParsing(template: T['template'], shadowRoot: T['shadowRoot']): void;
+     * Adapter methods for supporting declarative shadow roots. If not provided then the associated options for declarative shadow roots will cause an error to be thrown.
+     */
+    declarativeShadowRootAdapter?: {
+        /**
+         * Attaches a declarative shadow root to the given element.
+         *
+         * @param element - Element
+         *
+         */
+        attachDeclarativeShadowRoot(element: T['element'], shadowRootInit: ShadowRootInit): T['shadowRoot'];
+
+        /**
+         * Returns the element's shadow root if it has one.
+         *
+         * @param element - Element
+         */
+        getShadowRoot(element: T['element']): T['shadowRoot'] | null;
+
+        /**
+         * Returns an object with the neccessary properties to initialize the given shadow root.
+         *
+         * @param shadowRoot - Shadow root
+         */
+        getShadowRootInit(shadowRoot: T['shadowRoot']): ShadowRootInit;
+
+        /**
+         * Sets the template's content to the given shadow root. Unlike setTemplateContent this must not change the shadow root's host.
+         *
+         * @param template - The template to attach to
+         * @param shadowRoot - The shadow root to attach
+         */
+        setTemplateContentForDeclarativeShadowRootParsing(template: T['template'], shadowRoot: T['shadowRoot']): void;
+    };
 }

From d11116bf4a05d4474d6955dbcc1fc051fe12a6eb Mon Sep 17 00:00:00 2001
From: James Browning <thejamesernator@gmail.com>
Date: Wed, 26 Nov 2025 15:24:08 +1300
Subject: [PATCH 5/5] Make default tree adapter use optional shadow root
 support

---
 packages/parse5/lib/tree-adapters/default.ts | 61 +++++++++++---------
 1 file changed, 35 insertions(+), 26 deletions(-)

diff --git a/packages/parse5/lib/tree-adapters/default.ts b/packages/parse5/lib/tree-adapters/default.ts
index 4beb76a88..ac36c10c9 100644
--- a/packages/parse5/lib/tree-adapters/default.ts
+++ b/packages/parse5/lib/tree-adapters/default.ts
@@ -332,34 +332,43 @@ export const defaultTreeAdapter: TreeAdapter<DefaultTreeAdapterMap> = {
         node.sourceCodeLocation = { ...node.sourceCodeLocation, ...endLocation };
     },
 
-    // Shadow roots
-    attachDeclarativeShadowRoot(
-        element: Element,
-        { mode, clonable, serializable, delegatesFocus, customElementRegistry, declarativeTemplateAttributes },
-    ): ShadowRoot {
-        const shadowRoot: ShadowRoot = {
-            nodeName: '#shadow-root',
-            childNodes: [],
-            mode,
-            clonable,
-            serializable,
-            delegatesFocus,
-            customElementRegistry,
-            declarativeTemplateAttributes,
-        };
-        element.shadowRoot = shadowRoot;
-        return shadowRoot;
-    },
+    declarativeShadowRootAdapter: {
+        // Shadow roots
+        attachDeclarativeShadowRoot(
+            element: Element,
+            {
+                mode,
+                clonable,
+                serializable,
+                delegatesFocus,
+                customElementRegistry,
+                declarativeTemplateAttributes,
+            }: ShadowRootInit,
+        ): ShadowRoot {
+            const shadowRoot: ShadowRoot = {
+                nodeName: '#shadow-root',
+                childNodes: [],
+                mode,
+                clonable,
+                serializable,
+                delegatesFocus,
+                customElementRegistry,
+                declarativeTemplateAttributes,
+            };
+            element.shadowRoot = shadowRoot;
+            return shadowRoot;
+        },
 
-    getShadowRoot(element: Element): ShadowRoot | null {
-        return element.shadowRoot;
-    },
+        getShadowRoot(element: Element): ShadowRoot | null {
+            return element.shadowRoot;
+        },
 
-    getShadowRootInit(shadowRoot: ShadowRoot): ShadowRootInit {
-        return shadowRoot;
-    },
+        getShadowRootInit(shadowRoot: ShadowRoot): ShadowRootInit {
+            return shadowRoot;
+        },
 
-    setTemplateContentForDeclarativeShadowRootParsing(template: Template, shadowRoot: ShadowRoot): void {
-        template.content = shadowRoot;
+        setTemplateContentForDeclarativeShadowRootParsing(template: Template, shadowRoot: ShadowRoot): void {
+            template.content = shadowRoot;
+        },
     },
 };