@webtides/element-js 1.2.12 → 1.3.0

package/docs/features/templates.md

@@ -158,27 +158,36 @@ const attributeString = spreadAttributes(attrs);
 
 ##### Writing custom directives
 
-Directives in `element-js` are just functions. They accept parameters and return values that manipulate or produce templates or strings.
+The built-in directives above are plain functions that return a value for an attribute or a child position. A directive that works on the element itself sits inside the opening tag, between the attributes. It is a class that extends `Directive`, wrapped with `defineDirective()`:
 
-To write a custom directive:
-
-    Define a Function: This function will describe what your directive does. The function should return either a template, string, or another function based on its parameters.
+- `update(...values)` runs in the browser on every render, `this.node` is the element the directive sits on.
+- `stringify(...values)` runs when the template is rendered to a string, for example on the server, and returns what is written into the opening tag.
 
 ```javascript
-const visibility = (isVisible) => {
-    return isVisible ? '' : 'style="display: none;"';
-};
+import { Directive, defineDirective } from '@webtides/element-js';
+
+class HighlightDirective extends Directive {
+    update(active) {
+        this.node.toggleAttribute('data-highlight', active);
+    }
+
+    stringify(active) {
+        return active ? 'data-highlight' : '';
+    }
+}
+
+const highlight = defineDirective(HighlightDirective);
 ```
 
-Use your custom directive in your templates.
+`defineDirective()` returns the function to call in templates, its arguments are passed on to `update()` and `stringify()`:
 
 ```javascript
 function template() {
-    return html` <div ${visibility(false)}>This div will be hidden.</div> `;
+    return html` <div ${highlight(this.active)}>Highlighted while active.</div> `;
 }
 ```
 
-Remember, the power of directives is in their simplicity. They allow you to encapsulate logic in a function and reuse that logic across multiple templates.
+A plain function at this position throws, the renderer only accepts a directive created with `defineDirective()`. The `about` tab of `examples/showcase/` uses this directive.
 
 #### Slots
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@webtides/element-js",
-    "version": "1.2.12",
+    "version": "1.3.0",
     "module": "index.js",
     "main": "index.js",
     "type": "module",
@@ -36,12 +36,12 @@
         "element-js",
         "shadow-dom"
     ],
-    "dependencies": {},
     "devDependencies": {
         "@babel/eslint-parser": "^7.23.3",
         "@open-wc/testing": "^4.0.0",
         "@web/dev-server": "^0.4.6",
         "@web/test-runner": "^0.19.0",
+        "@web/test-runner-commands": "^0.9.0",
         "babel-eslint": "^10.1.0",
         "eslint": "8.55.0",
         "eslint-config-prettier": "^9.1.0",
@@ -60,6 +60,9 @@
     "scripts": {
         "lint": "eslint index.js 'src/**/*.js'",
         "test": "web-test-runner test/**/*.test.{html,js} --node-resolve",
+        "bench": "node benchmark/run.mjs",
+        "bench:compare": "node benchmark/run.mjs --base main",
+        "bench:ui": "web-dev-server --root-dir . --open /benchmark/",
         "test:coverage": "web-test-runner test/**/*.test.{html,js} --node-resolve --coverage",
         "test:watch": "web-test-runner test/**/*.test.{html,js} --node-resolve --watch",
         "start": "web-dev-server --config web-dev-server.config.mjs"

package/src/TemplateElement.js

@@ -55,10 +55,12 @@ class TemplateElement extends StyledElement {
      * This will attach a shadow DOM if the element is supposed to render in shadow DOM.
      */
     renderTemplate() {
-        const firstRender = this._options.shadowRender && !this.shadowRoot;
-        if (firstRender) {
+        if (this._options.shadowRender && !this.shadowRoot) {
             this.attachShadow({ mode: 'open' });
-            // init external stylesheets
+        }
+        // the first render adopts the style sheets, also into a declarative shadow root that the parser attached
+        if (this._options.shadowRender && !this._stylesAdopted) {
+            this._stylesAdopted = true;
             this.initStyleAdoption();
         }
 

package/src/dom-parts/AttributePart.js

@@ -1,16 +1,30 @@
 import { Part } from './Part.js';
 
+// marks the first update: it compares with the attribute in the DOM once, so a fresh clone, which carries the
+// placeholder, gets written and server rendered markup that fits already is left alone
+const NOT_SET = Symbol('not set');
+
 /**
  * @param {Element} node
  * @param {String} name
- * @param {Boolean} oldValue
  * @return {(function(*): void)|*}
  */
-const processBooleanAttribute = (node, name, oldValue) => {
+const processBooleanAttribute = (node, name) => {
+    let oldValue = NOT_SET;
     return (newValue) => {
         const value = !!newValue?.valueOf() && newValue !== 'false';
+        if (oldValue === NOT_SET && node.getAttribute(name) === (value ? '' : null)) {
+            oldValue = value;
+            return;
+        }
         if (oldValue !== value) {
-            node.toggleAttribute(name, (oldValue = !!value));
+            oldValue = value;
+            // not toggleAttribute(): server rendered markup may carry `name="false"`, true has to become `name=""`
+            if (value) {
+                node.setAttribute(name, '');
+            } else {
+                node.removeAttribute(name);
+            }
         }
     };
 };
@@ -49,9 +63,13 @@ const processEventAttribute = (node, name) => {
  * @return {(function(*): void)|*}
  */
 const processAttribute = (node, name) => {
-    let oldValue;
+    let oldValue = NOT_SET;
     return (newValue) => {
         const value = newValue?.valueOf();
+        if (oldValue === NOT_SET && node.getAttribute(name) === (value == null ? null : String(value))) {
+            oldValue = value;
+            return;
+        }
         if (oldValue !== value) {
             oldValue = value;
             if (value == null) {
@@ -74,7 +92,7 @@ const attributePartsCache = new WeakMap();
 export const processAttributePart = (node, name) => {
     // boolean attribute: ?boolean=${...}
     if (name.startsWith('?')) {
-        return processBooleanAttribute(node, name.slice(1), false);
+        return processBooleanAttribute(node, name.slice(1));
     }
 
     // property attribute: .property=${...}
@@ -82,11 +100,23 @@ export const processAttributePart = (node, name) => {
         return processPropertyAttribute(node, name.slice(1));
     }
 
-    // event attribute: @event=${...} || "old school" event attribute: onevent=${...}
-    if (name.startsWith('@') || name.startsWith('on')) {
+    // event attribute: @event=${...}
+    if (name.startsWith('@')) {
         return processEventAttribute(node, name);
     }
 
+    // "old school" event attribute: onevent=${...}. A function is the listener, any other value is written as an
+    // attribute: `on="${state}"` or `once="${flag}"` are attributes of the element that happen to start with "on"
+    if (name.startsWith('on')) {
+        const listener = processEventAttribute(node, name);
+        const attribute = processAttribute(node, name);
+        return (value) => {
+            const isListener = typeof value === 'function';
+            listener(isListener ? value : undefined);
+            attribute(isListener ? undefined : value);
+        };
+    }
+
     // normal "string" attribute: attribute=${...}
     return processAttribute(node, name);
 };

package/src/dom-parts/ChildNodePart.js

@@ -1,4 +1,4 @@
-import { COMMENT_NODE, ELEMENT_NODE } from '../util/DOMHelper.js';
+import { COMMENT_NODE, TEXT_NODE } from '../util/DOMHelper.js';
 import { Part } from './Part.js';
 import { TemplateResult } from './TemplateResult.js';
 import { TemplatePart } from './TemplatePart.js';
@@ -69,42 +69,54 @@ export const getNodesBetweenComments = (commentNode, includeComments = false) =>
 };
 
 /**
- * @param {Node[]} newChildNodes
- * @param {Comment} anchorNode
+ * A node that is not in the DOM yet takes over an equal node that is in place: a fresh text node leaves the text node
+ * that is there alone. The nodes of a template clone still sit in their fragment and never take over, they replace
+ * what the server rendered in their place.
+ * @param {Node} node
+ * @param {Node} newChildNode
+ * @return {boolean}
  */
-const diffChildNodes = function (newChildNodes, anchorNode) {
-    const parentNode = anchorNode.parentNode;
-    const oldChildNodes = getNodesBetweenComments(anchorNode);
-
-    const length = Math.max(oldChildNodes.length, newChildNodes.length);
-    // Diff each node in the child node lists
-    for (let index = 0; index < length; index++) {
-        let oldChildNode = oldChildNodes[index];
-        let newChildNode = newChildNodes[index];
+const takesOver = (node, newChildNode) => !newChildNode.parentNode && node.isEqualNode(newChildNode);
 
-        if (newChildNode && !newChildNode.nodeType) {
+/**
+ * Brings the nodes between the markers in line with newChildNodes, in that order. Walks the live DOM with a cursor:
+ * a node that is at the cursor already stays, stale nodes at the cursor are removed, anything else is inserted in
+ * front of the cursor, which moves a node that is in the DOM further back, for example a hydrated template behind a
+ * server rendered text. Nodes that are in place are never touched, so focus and element lifecycles survive.
+ * @param {Node[]} newChildNodes
+ * @param {Comment} startNode - the start marker
+ * @param {Comment} endNode - the end marker
+ */
+const diffChildNodes = (newChildNodes, startNode, endNode) => {
+    const parentNode = endNode.parentNode;
+    // the set of new nodes tells a stale node from one that is needed further on. It is only built when the nodes
+    // deviate from what is there, a list whose nodes are all in place never pays for it
+    let keep;
+    let current = startNode.nextSibling;
+    for (let index = 0; index < newChildNodes.length; index++) {
+        const newChildNode = newChildNodes[index];
+        if (!newChildNode?.nodeType) {
             throw new Error('ChildNodePart: newChildNode is not a node');
         }
-
-        // If the DOM node doesn't exist, append/copy the new node
-        if (oldChildNode === undefined) {
-            parentNode.insertBefore(newChildNode, anchorNode);
-            continue;
-        }
-
-        // If the new node doesn't exist, remove the node in the DOM
-        if (newChildNode === undefined) {
-            parentNode.removeChild(oldChildNode);
-            continue;
+        if (current !== newChildNode && current !== endNode) {
+            keep ??= new Set(newChildNodes);
+            while (current !== endNode && !keep.has(current) && !takesOver(current, newChildNode)) {
+                const next = current.nextSibling;
+                parentNode.removeChild(current);
+                current = next;
+            }
         }
-
-        // If DOM node is equal to the new node, don't do anything in the DOM
-        if (oldChildNode === newChildNode || oldChildNode.isEqualNode(newChildNode)) {
-            continue;
+        if (current === newChildNode || (current !== endNode && !keep.has(current))) {
+            // in place already, or a stale node the new one takes over
+            current = current.nextSibling;
+        } else {
+            parentNode.insertBefore(newChildNode, current);
         }
-
-        // Everything else is somehow different and can be replaced
-        parentNode.replaceChild(newChildNode, oldChildNode);
+    }
+    while (current !== endNode) {
+        const next = current.nextSibling;
+        parentNode.removeChild(current);
+        current = next;
     }
 };
 
@@ -116,16 +128,13 @@ function getType(value) {
     return 'text';
 }
 
-// TODO: handle funcitons?! Should be handled in parseArray!!!
+// the parsed items of an array as the child nodes to diff: template parts contribute their nodes, primitives become
+// text nodes, DOM nodes pass through
 const unwrapArray = (nodes) => {
-    // we have to unwrap any complex objects inside the array so that we can diff arrays of childNodes
     return nodes.flatMap((value) => {
         if (value instanceof TemplatePart) {
             return value.childNodes;
         }
-        if (Array.isArray(value)) {
-            return unwrapArray(value);
-        }
         if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {
             return document.createTextNode(value);
         }
@@ -134,76 +143,72 @@ const unwrapArray = (nodes) => {
 };
 
 /**
- * @param {Comment} comment
- * @param {TemplatePart | any[] | any} initialValue
- * @param {boolean} serverSideRendered
- * @return {(function(*): void)|*}
+ * Array items get the same treatment as a single value: functions are resolved completely, arrays nested in the array
+ * are flattened and null or undefined items are dropped, which is the list the server renders. An array that needs
+ * none of it is returned as is.
+ * @param {any[]} values
+ * @return {any[]}
+ */
+const resolveArrayItems = (values) => {
+    if (!values.some((value) => typeof value === 'function' || Array.isArray(value) || value == null)) {
+        return values;
+    }
+    return values.flatMap((item) => {
+        let value = item;
+        while (typeof value === 'function') value = value();
+        if (Array.isArray(value)) return resolveArrayItems(value);
+        return value == null ? [] : [value];
+    });
+};
+
+/**
+ * Creates the processor that writes a parsed value between the markers of a child node part.
+ * @param {PartMarkers} markers - the start and end marker of the part
+ * @return {(function(TemplatePart | any[] | any, boolean=): void)}
  */
-export const processNodePart = (comment, initialValue, serverSideRendered = false) => {
+export const processNodePart = ({ startNode, endNode }) => {
     let oldValueType = 'empty';
     let oldValue = undefined;
-    // this is for string values to be inserted into the DOM. A cached TextNode will be used so that we don't have to constantly create new DOM nodes.
-    // TODO: when server side rendered, we need to get the text node from the DOM no?!
+    // string values are rendered into one text node that is reused across updates. Hydration takes over the server
+    // rendered text node as that node
     let cachedTextNode = globalThis.document?.createTextNode('');
 
-    if (serverSideRendered) {
-        oldValueType = getType(initialValue);
-        oldValue = initialValue instanceof TemplatePart ? initialValue.strings : initialValue;
-    }
-
-    const processNodeValue = (newValue) => {
-        let newValueType = getType(newValue);
+    return (newValue, hydrate = false) => {
+        const newValueType = getType(newValue);
 
         if (oldValueType === newValueType && oldValue === newValue) return;
 
-        if (oldValueType !== newValueType) {
-            if (newValueType === 'empty') {
-                removeNodesBetweenComments(comment);
+        if (newValueType === 'empty') {
+            removeNodesBetweenComments(endNode);
+        } else if (newValueType === 'text') {
+            if (oldValueType !== 'text') {
+                const serverTextNode = startNode.nextSibling;
+                if (hydrate && serverTextNode.nodeType === TEXT_NODE && serverTextNode.nextSibling === endNode) {
+                    cachedTextNode = serverTextNode;
+                } else {
+                    replaceNodesBetweenComments(endNode, [cachedTextNode]);
+                }
+            }
+            if (cachedTextNode.data !== String(newValue)) cachedTextNode.data = newValue;
+        } else if (newValueType === 'templatePart') {
+            // a template part bound to server rendered DOM (hydration) is in place already and is left alone
+            if (newValue.childNodes[0].parentNode !== endNode.parentNode) {
+                replaceNodesBetweenComments(endNode, newValue.childNodes);
+            }
+        } else {
+            const nodes = newValueType === 'array' ? unwrapArray(newValue) : [newValue];
+            // a type change replaces what is there. Server rendered nodes (hydration) go through the diff instead,
+            // nodes that are in place already, for example a focused input, stay untouched
+            if (oldValueType !== newValueType && !hydrate) {
+                replaceNodesBetweenComments(endNode, nodes);
             } else {
-                const getNodesForType = (value, type) => {
-                    if (type === 'templatePart') return value.childNodes;
-                    if (type === 'array') return unwrapArray(value);
-                    if (type === 'node') return [value];
-
-                    // Every else falls back to rendering a text node
-                    cachedTextNode.data = value;
-                    return [cachedTextNode];
-                };
-                replaceNodesBetweenComments(comment, getNodesForType(newValue, newValueType));
+                diffChildNodes(nodes, startNode, endNode);
             }
-
-            oldValueType = newValueType;
-            oldValue = newValue;
-            return;
-        }
-
-        if (newValueType === 'text') {
-            cachedTextNode.data = newValue;
-
-            oldValue = newValue;
-            return;
-        }
-
-        if (newValueType === 'array') {
-            diffChildNodes(unwrapArray(newValue), comment);
-
-            oldValue = newValue;
-            return;
         }
 
-        if (newValueType === 'node') {
-            diffChildNodes([newValue], comment);
-
-            oldValue = newValue;
-        }
+        oldValueType = newValueType;
+        oldValue = newValue;
     };
-
-    if (!serverSideRendered) {
-        // initial rendering
-        processNodeValue(initialValue);
-    }
-
-    return processNodeValue;
 };
 
 /**
@@ -216,17 +221,16 @@ export class ChildNodePart extends Part {
     /** @type {TemplatePart|undefined} */
     templatePart;
 
-    /** @type {Part[]} */
+    /** @type {TemplatePart[]} indexed like the items of an array value, only template items have a part */
     arrayParts = [];
 
     /**
      * @param {Node} startNode - the start comment marker node
-     * @param {any | any[]} value
      */
-    constructor(startNode, value) {
+    constructor(startNode) {
         if (!startNode || startNode?.nodeType !== COMMENT_NODE) {
             throw new Error(
-                startNode ? 'ChildNodePart: startNode is undefined' : 'ChildNodePart: startNode is not a comment node',
+                startNode ? 'ChildNodePart: startNode is not a comment node' : 'ChildNodePart: startNode is undefined',
             );
         }
 
@@ -234,70 +238,63 @@ export class ChildNodePart extends Part {
 
         startNode.__part = this; // add Part to comment node for debugging in the browser
         this.markers = PartMarkers.createFromStartNode(startNode);
-
-        // value can become array | TemplatePart | any
-        const initialValue = this.parseValue(value);
-
-        this.processor = processNodePart(this.markers?.endNode, initialValue, this.markers?.serverSideRendered);
+        this.processor = processNodePart(this.markers);
     }
 
     /**
-     * @param {any} value
-     * @return {*}
+     * @param {TemplateResult | any[] | any} value
+     * @param {boolean} [hydrate] - bind nested template parts to the server rendered markers instead of cloning
      */
-    update(value) {
-        const parsedValue = this.parseValue(value);
-
-        if (value instanceof TemplateResult || Array.isArray(value)) {
-            this.updateParts(value);
-        }
-
-        this.processor?.(parsedValue);
+    update(value, hydrate = false) {
+        // functions are resolved completely and array items are normalized, parsing and updating have to work on the
+        // same value
+        let resolvedValue = value;
+        while (typeof resolvedValue === 'function') resolvedValue = resolvedValue();
+        if (Array.isArray(resolvedValue)) resolvedValue = resolveArrayItems(resolvedValue);
+        const parsedValue = this.parseValue(resolvedValue, hydrate);
+        this.updateParts(resolvedValue, hydrate);
+        this.processor(parsedValue, hydrate);
     }
 
     /**
-     * @param {TemplateResult | any[]} value
+     * @param {TemplateResult | any[] | any} value
+     * @param {boolean} [hydrate]
      */
-    updateParts(value) {
+    updateParts(value, hydrate = false) {
         if (value instanceof TemplateResult) {
-            this.templatePart.update(value);
+            this.templatePart.update(value, hydrate);
         }
         if (Array.isArray(value)) {
             for (let index = 0; index < value.length; index++) {
-                this.arrayParts[index]?.update(value[index]);
+                if (value[index] instanceof TemplateResult) this.arrayParts[index].update(value[index], hydrate);
             }
         }
     }
 
     /**
+     * Creates the nested parts for a value. When hydrating, nested template parts are bound to the server rendered
+     * template-part markers between this part's markers.
      * @param {TemplateResult | any[] | any} value
+     * @param {boolean} hydrate
      * @return {TemplatePart | Node | string | Array<TemplatePart | Node | string>}
      */
-    parseValue(value) {
+    parseValue(value, hydrate = false) {
         if (value instanceof TemplateResult) {
             if (!this.templatePart) {
-                this.templatePart = new TemplatePart(this.markers?.findNestedStartNode('template-part'), value);
-                if (!this.markers?.serverSideRendered) {
-                    // INFO: this is similar to TemplateResult#237
-                    replaceNodesBetweenComments(this.markers?.endNode, this.templatePart.childNodes);
-                }
+                const startNode = hydrate ? this.markers.findNestedStartNode('template-part') : undefined;
+                this.templatePart = new TemplatePart(startNode, value);
             } else if (this.templatePart.strings !== value.strings) {
                 // this means we have a different TemplateResult here with maybe different parts also
                 this.templatePart = new TemplatePart(undefined, value);
-                // INFO: this is similar to TemplateResult#237
-                replaceNodesBetweenComments(this.markers?.endNode, this.templatePart.childNodes);
             }
             return this.templatePart;
         }
         if (Array.isArray(value)) {
-            return this.parseArray(value);
+            return this.parseArray(value, hydrate);
         }
         if (value?.nodeType) {
             return value;
         }
-        if (typeof value === 'function') {
-            return this.parseValue(value());
-        }
         if (value === null || value === undefined) {
             return value;
         }
@@ -306,44 +303,32 @@ export class ChildNodePart extends Part {
     }
 
     /**
-     * Nested TemplateResults values need to be unrolled in order for update functions to be able to process them
+     * Creates the template parts for the template items of an array, indexed like the items. A different template at
+     * an index gets a new part, the nodes of the part that was there go away with the diff. Other items (text, nodes)
+     * pass through, functions and nested arrays are resolved before, see update().
      * @param {any[]} values
-     * @return {any[]}
+     * @param {boolean} hydrate
+     * @return {Array<TemplatePart | Node | string>}
      */
-    parseArray(values) {
+    parseArray(values, hydrate = false) {
         const parsedValues = [];
-        for (let index = 0; index < values.length; index++) {
-            let value = values[index];
-
-            // TODO: it would be better to use this.parseValue() here!!!
+        // the server rendered template-part markers directly between this part's markers, one per nested template.
+        // Other values (text, nodes) have no marker, so the templates are counted separately
+        const nestedStartNodes = hydrate ? this.markers.findNestedStartNodes('template-part') : [];
+        let nestedIndex = 0;
 
+        for (let index = 0; index < values.length; index++) {
+            const value = values[index];
             if (value instanceof TemplateResult) {
-                // TODO this is probably wrong. Should only be taken from parts cache if it has the same type (eg. template vs string, mixed types arrays)
                 let templatePart = this.arrayParts[index];
-                if (!templatePart) {
-                    const templatePartCommentNodes = this.markers?.childNodes?.filter(
-                        (node) => node && node.nodeType === COMMENT_NODE && node.data === 'template-part',
-                    );
-                    const startNode = templatePartCommentNodes[index];
-                    templatePart = new TemplatePart(startNode, value);
+                if (!templatePart || templatePart.strings !== value.strings) {
+                    templatePart = new TemplatePart(nestedStartNodes[nestedIndex], value);
                     this.arrayParts[index] = templatePart;
                 }
+                nestedIndex++;
                 parsedValues[index] = templatePart;
-            } else if (Array.isArray(value)) {
-                let childNodePart = this.arrayParts[index];
-                if (!childNodePart) {
-                    // TODO: this seems not correct :( (maybe Template vs DOM Parts !?)
-                    const templatePartCommentNodes = this.markers?.childNodes?.filter(
-                        (node) => node && node.nodeType === COMMENT_NODE && node.data === 'template-part',
-                    );
-                    const startNode = templatePartCommentNodes[index];
-                    childNodePart = new ChildNodePart(startNode, value);
-                    this.arrayParts[index] = childNodePart;
-                }
-                parsedValues[index] = childNodePart;
             } else {
-                // TODO: what if the value from the function is a TemplatePart or an array?! Should we do this first thing?!
-                parsedValues[index] = typeof value === 'function' ? value() : value;
+                parsedValues[index] = value;
             }
         }
 

package/src/dom-parts/Part.js

@@ -5,8 +5,10 @@ export class Part {
     processor = undefined;
 
     /**
+     * Applies a value to the DOM.
      * @abstract
      * @param {TemplateResult | any[] | any} value
+     * @param {boolean} [hydrate] - first update of server rendered DOM, nested parts bind to the server rendered markers
      */
-    update(value) {}
+    update(value, hydrate = false) {}
 }

package/src/dom-parts/PartMarkers.js

@@ -1,5 +1,42 @@
 import { COMMENT_NODE } from '../util/DOMHelper.js';
 
+const SHOW_COMMENT = 128; // NodeFilter.SHOW_COMMENT
+const SLASH = 47; // '/'
+const PART_MARKER_PREFIX = 'dom-part-';
+const TEMPLATE_MARKER = 'template-part';
+
+/**
+ * Walks the comment markers of one template instance in document order, starting at its `<!--template-part-->`
+ * comment, and calls back for every top level part marker with the marker node and the index of its part. Closing
+ * markers and everything inside nested templates (between their own template-part comments) are skipped.
+ *
+ * Works on a freshly cloned template fragment as well as on live, server rendered DOM: there the values sit between
+ * the markers, but they are not comments, so the walk sees the same sequence of markers in both cases.
+ *
+ * @param {Comment} startNode - the `<!--template-part-->` comment of the instance
+ * @param {(node: Comment, index: number) => void} [onPartMarker]
+ * @return {Comment} the matching `<!--/template-part-->` comment
+ */
+export const walkPartMarkers = (startNode, onPartMarker) => {
+    const walker = globalThis.document.createTreeWalker(startNode.parentNode, SHOW_COMMENT);
+    walker.currentNode = startNode;
+    let depth = 1;
+    let node;
+    while ((node = walker.nextNode())) {
+        const data = node.data;
+        if (data === TEMPLATE_MARKER) {
+            depth++;
+        } else if (data === `/${TEMPLATE_MARKER}`) {
+            depth--;
+            if (depth === 0) return node;
+        } else if (depth === 1 && data.charCodeAt(0) !== SLASH && data.startsWith(PART_MARKER_PREFIX)) {
+            // 'dom-part-12?type=attribute&…' → 12, parseInt stops at the '?'
+            onPartMarker?.(node, parseInt(data.slice(PART_MARKER_PREFIX.length), 10));
+        }
+    }
+    throw new Error('PartMarkers: missing closing template-part marker');
+};
+
 export class PartMarkers {
     /** @type {Comment} */
     startNode;
@@ -7,56 +44,77 @@ export class PartMarkers {
     /** @type {Comment} */
     endNode;
 
-    /** @type {Node[]} */
+    /** @type {Node[]} all sibling nodes from the start to the end marker, both included */
     childNodes = [];
 
-    /** @type {boolean} */
-    serverSideRendered = false;
-
     /**
      * @param {Comment} start
      * @param {Comment} end
      * @param {Node[]} childNodes
-     * @return {void}
      */
     constructor(start, end, childNodes) {
         this.startNode = start;
         this.endNode = end;
         this.childNodes = childNodes;
+    }
 
-        // if not SSRed, childNodes will only ever have two comment nodes, the start and the end marker
-        if (childNodes.length > 2) {
-            this.serverSideRendered = true;
+    /**
+     * The start comments of the nested parts directly between the markers, in document order. Markers inside those
+     * nested parts are not included.
+     * @param {string} partType - the marker name to search for. Defaults to 'template-part'.
+     * @return {Comment[]}
+     */
+    findNestedStartNodes(partType = TEMPLATE_MARKER) {
+        const closing = `/${partType}`;
+        const startNodes = [];
+        let depth = 0;
+        for (const node of this.childNodes.slice(1, -1)) {
+            if (node.nodeType !== COMMENT_NODE) continue;
+            if (node.data === partType) {
+                if (depth === 0) startNodes.push(node);
+                depth++;
+            } else if (node.data === closing) {
+                depth--;
+            }
         }
+        return startNodes;
     }
 
     /**
-     * @param {string} partType The type of the node to search for. Defaults to 'template-part'.
-     * @return {Node|undefined} The first comment node matching the specified type, or undefined if no match is found.
+     * @param {string} partType - the marker name to search for. Defaults to 'template-part'.
+     * @return {Comment|undefined} the first nested start comment, or undefined if there is none
      */
-    findNestedStartNode(partType = 'template-part') {
-        return this.childNodes.filter((node) => node.nodeType === COMMENT_NODE).find((node) => node.data === partType);
+    findNestedStartNode(partType = TEMPLATE_MARKER) {
+        return this.findNestedStartNodes(partType)[0];
     }
 
     /**
-     * Creates a new instance of PartMarkers from the given start node.
-     * @param {Comment} startNode - The starting comment node that marks the beginning of the section.
-     * @return {PartMarkers} A new instance of the PartMarkers class encapsulating the start and end nodes.
+     * Creates markers from a start comment by walking its siblings to the matching end comment. Nested markers with
+     * the same name, for example a nested template at the root of a template, are skipped.
+     * @param {Comment} startNode - the start comment that marks the beginning of the section
+     * @return {PartMarkers}
      */
     static createFromStartNode(startNode) {
-        let endNode;
-
         const placeholder = startNode.data;
+        const closing = `/${placeholder}`;
         const childNodes = [startNode];
-        let childNode = startNode.nextSibling;
-        while (childNode && childNode.data !== `/${placeholder}`) {
-            childNodes.push(childNode);
-            childNode = childNode.nextSibling;
+        let depth = 1;
+        let node = startNode.nextSibling;
+        while (node) {
+            childNodes.push(node);
+            if (node.nodeType === COMMENT_NODE) {
+                if (node.data === placeholder) {
+                    depth++;
+                } else if (node.data === closing) {
+                    depth--;
+                    if (depth === 0) break;
+                }
+            }
+            node = node.nextSibling;
         }
-
-        endNode = childNode;
-        childNodes.push(endNode);
-
-        return new PartMarkers(startNode, endNode, childNodes);
+        if (!node) {
+            throw new Error(`PartMarkers: missing closing marker for "${placeholder}"`);
+        }
+        return new PartMarkers(startNode, node, childNodes);
     }
 }

package/src/dom-parts/TemplatePart.js

@@ -1,38 +1,79 @@
 import { COMMENT_NODE, convertStringToTemplate } from '../util/DOMHelper.js';
 import { Part } from './Part.js';
-import { TemplateResult } from './TemplateResult.js';
 import { AttributePart } from './AttributePart.js';
 import { ChildNodePart, getNodesBetweenComments, replaceNodesBetweenComments } from './ChildNodePart.js';
 import { NodePart } from './NodePart.js';
 import { RawTextNodePart } from './RawTextNodePart.js';
-import { PartMarkers } from './PartMarkers.js';
-
-/** @type {WeakMap<TemplateStringsArray, Part[]>} */
-const partsCache = new WeakMap();
+import { PartMarkers, walkPartMarkers } from './PartMarkers.js';
 
 /** @type {WeakMap<TemplateStringsArray, DocumentFragment>} */
 const fragmentsCache = new WeakMap();
 
+/** @type {WeakMap<TemplateStringsArray, {descriptors: object[], markerData: string[], hasRootNodeParts: boolean}>} */
+const partsCache = new WeakMap();
+
+/**
+ * The parsed template for a `strings` array: the fragment to clone, the part descriptors in part order, the comment
+ * data of each part marker and whether a node part sits at the root of the template. All computed once per literal.
+ * @param {TemplateResult} templateResult
+ * @return {{fragment: DocumentFragment, descriptors: object[], markerData: string[], hasRootNodeParts: boolean}}
+ */
+const parseTemplate = (templateResult) => {
+    let fragment = fragmentsCache.get(templateResult.strings);
+    if (!fragment) {
+        fragment = convertStringToTemplate(templateResult.templateString);
+        fragmentsCache.set(templateResult.strings, fragment);
+    }
+    let parts = partsCache.get(templateResult.strings);
+    if (!parts) {
+        const descriptors = templateResult.parseParts(fragment.childNodes);
+        const markerData = [];
+        let hasRootNodeParts = false;
+        walkPartMarkers(fragment.firstChild, (node, index) => {
+            markerData[index] = node.data;
+            if (descriptors[index].type === 'node' && node.parentNode === fragment) hasRootNodeParts = true;
+        });
+        parts = { descriptors, markerData, hasRootNodeParts };
+        partsCache.set(templateResult.strings, parts);
+    }
+    return { fragment, ...parts };
+};
+
+/**
+ * One rendered instance of a template. Binds the parts of the template to DOM nodes: either to a fresh clone of the
+ * template fragment, or, when hydrating, to the markers in server rendered DOM. Both bindings walk the same comment
+ * markers, see walkPartMarkers(). Construction only binds, values flow through update().
+ */
 export class TemplatePart extends Part {
-    /** @type {PartMarkers|undefined} */
+    /** @type {PartMarkers} */
     markers;
 
-    /** @type {Part[]} */
+    /** @type {Part[]} indexed like the values of the template */
     parts = [];
 
     /** @type {TemplateStringsArray} */
     strings = undefined;
 
-    /** @type {Node[]} */
+    /**
+     * The top level nodes of this instance, including its template-part markers and the content of parts at the root
+     * of the template. Refreshed after every update while the nodes are attached, kept as is while they are detached
+     * so that a removed instance can be inserted again.
+     * @type {Node[]}
+     */
     childNodes = [];
-    // TODO: there is childNodes here and also in this.markers now...
+
+    /** @type {boolean} true when the parts are bound to server rendered DOM */
+    hydrated = false;
+
+    /** @type {boolean} true when a node part at the root of the template can change the top level nodes */
+    hasRootNodeParts = false;
 
     /**
-     * @param {Node|undefined} startNode - the start comment marker node
-     * @param {TemplateResult} value
+     * @param {Comment|undefined} startNode - the `<!--template-part-->` comment of server rendered DOM to hydrate, or undefined to render client side
+     * @param {TemplateResult} templateResult
      */
-    constructor(startNode, value) {
-        if (startNode && startNode?.nodeType !== COMMENT_NODE) {
+    constructor(startNode, templateResult) {
+        if (startNode && startNode.nodeType !== COMMENT_NODE) {
             throw new Error('TemplatePart: startNode is not a comment node');
         }
 
@@ -40,86 +81,136 @@ export class TemplatePart extends Part {
 
         if (startNode) {
             startNode.__part = this; // add Part to comment node for debugging in the browser
-            this.markers = PartMarkers.createFromStartNode(startNode);
-            this.childNodes = this.markers.childNodes;
+            this.hydrated = this.bindLive(startNode, templateResult);
         }
-
-        this.parseValue(value);
-
-        if (!this.markers?.serverSideRendered) {
-            // TODO: this is causing double diffing because of the this.parseValue() before, ChildNode parts will be constructed + processed
-            // TODO: I think that maybe ChildNode Parts work, but Other Parts like Attributes are not set initially otherwise...
-            this.updateParts(value.values);
+        if (!this.hydrated) {
+            this.bindClone(templateResult);
         }
-
-        // TODO: this is somewhat strange that we are creating this twice...
-        this.markers = PartMarkers.createFromStartNode(this.childNodes[0]);
     }
 
     /**
      * @param {TemplateResult} templateResult
+     * @param {boolean} [hydrate] - first update of server rendered DOM: nested parts bind to the server rendered
+     *   markers instead of cloning, see ChildNodePart.parseValue(). Nodes that are in place already stay untouched.
      */
-    update(templateResult) {
-        const shouldUpdateDOM = this.strings !== templateResult.strings;
-        if (shouldUpdateDOM) {
-            this.parseValue(templateResult);
-            // TODO: this is a strange way of replacing the childnodes...
-            const endNode = this.childNodes[this.childNodes.length - 1];
-            // INFO: this is similar to TemplateResult#237
-            replaceNodesBetweenComments(this.markers?.endNode, getNodesBetweenComments(endNode));
+    update(templateResult, hydrate = false) {
+        if (this.strings !== templateResult.strings) {
+            // a different template: render it fresh and swap the content between the existing markers
+            const { startNode, endNode } = this.markers;
+            this.bindClone(templateResult);
+            const innerNodes = this.childNodes.slice(1, -1);
+            replaceNodesBetweenComments(endNode, innerNodes);
+            this.markers = new PartMarkers(startNode, endNode, [startNode, ...innerNodes, endNode]);
+            this.childNodes = this.markers.childNodes;
+            this.hydrated = false;
         }
-        this.updateParts(templateResult.values);
+        // an instance that could not be bound to server DOM is a fresh clone, its parts clone as well
+        this.updateParts(templateResult.values, hydrate && this.hydrated);
+        if (this.hasRootNodeParts) this.refreshChildNodes();
     }
 
     /**
      * @param {any[]} values
+     * @param {boolean} [hydrate]
      */
-    updateParts(values) {
+    updateParts(values, hydrate = false) {
         for (let index = 0; index < values.length; index++) {
-            this.parts[index]?.update(values[index]);
+            this.parts[index]?.update(values[index], hydrate);
         }
     }
 
     /**
-     * @param {TemplateResult} templateResult
+     * Re-reads the top level nodes between the markers. Parts at the root of the template insert and remove their
+     * content there, so the list is only known after an update. Detached nodes have no siblings to walk, the last
+     * known list is kept in that case.
      */
-    parseValue(templateResult) {
-        let fragment = fragmentsCache.get(templateResult.strings);
-        if (!fragment) {
-            fragment = convertStringToTemplate(templateResult.templateString);
-            fragmentsCache.set(templateResult.strings, fragment);
+    refreshChildNodes() {
+        const { startNode, endNode } = this.markers;
+        if (startNode.parentNode) {
+            this.childNodes = [startNode, ...getNodesBetweenComments(endNode), endNode];
         }
-        const importedFragment = globalThis.document?.importNode(fragment, true);
-        this.childNodes = importedFragment.childNodes;
+    }
 
-        let parts = partsCache.get(templateResult.strings);
-        if (!parts) {
-            parts = templateResult.parseParts(this.childNodes);
-            partsCache.set(templateResult.strings, parts);
-        }
+    /**
+     * Clones the template fragment and binds the parts to the markers in the clone.
+     * @param {TemplateResult} templateResult
+     */
+    bindClone(templateResult) {
+        const { fragment, descriptors, hasRootNodeParts } = parseTemplate(templateResult);
+        const clone = globalThis.document.importNode(fragment, true);
+        const startNode = clone.firstChild;
+        startNode.__part = this; // add Part to comment node for debugging in the browser
+        const parts = [];
+        const endNode = walkPartMarkers(startNode, (node, index) => {
+            parts[index] = this.createPart(descriptors[index], node, templateResult.values[index]);
+        });
+        this.parts = parts;
+        this.strings = templateResult.strings;
+        this.hasRootNodeParts = hasRootNodeParts;
+        this.childNodes = [...clone.childNodes];
+        this.markers = new PartMarkers(startNode, endNode, this.childNodes);
+    }
 
-        this.parts = parts
-            .map((part) => {
-                // We currently need the path because the fragment will be cloned via importNode and therefore the node will be a different one
-                part.node = part.path.reduceRight(({ childNodes }, i) => childNodes[i], this);
-                return part;
-            })
-            .map((part, index) => {
-                if (part.type === 'node') {
-                    return new ChildNodePart(part.node, templateResult.values[index]);
-                }
-                if (part.type === 'attribute') {
-                    return new AttributePart(part.node, part.name, part.initialValue);
-                }
-                if (part.type === 'raw-text-node') {
-                    return new RawTextNodePart(part.node, part.initialValue);
-                }
-                if (part.type === 'directive') {
-                    return new NodePart(part.node, templateResult.values[index]);
+    /**
+     * Binds the parts to the markers of server rendered DOM.
+     * @param {Comment} startNode - the live `<!--template-part-->` comment
+     * @param {TemplateResult} templateResult
+     * @return {boolean} false if the markers do not match the template, nothing is bound in that case
+     */
+    bindLive(startNode, templateResult) {
+        const { descriptors, markerData, hasRootNodeParts } = parseTemplate(templateResult);
+        const values = templateResult.values;
+        const parts = [];
+        let found = 0;
+        let endNode;
+        try {
+            endNode = walkPartMarkers(startNode, (node, index) => {
+                found++;
+                // the marker must be the one the template would render at this position: same type, name and
+                // static attribute content. Differences in the static markup around the markers are not detected.
+                if (descriptors[index] && node.data === markerData[index]) {
+                    parts[index] = this.createPart(descriptors[index], node, values[index]);
                 }
-                throw `cannot map part: ${part}`;
             });
+        } catch (error) {
+            endNode = undefined;
+        }
+
+        const complete = found === descriptors.length && descriptors.every((_, index) => parts[index] !== undefined);
+        if (!endNode || !complete) {
+            console.warn(
+                'element-js: the server rendered markers do not match the template, rendering client side instead.',
+                { template: templateResult.templateString, startNode },
+            );
+            return false;
+        }
+
+        this.parts = parts;
         this.strings = templateResult.strings;
-        this.childNodes = [...this.childNodes];
+        this.hasRootNodeParts = hasRootNodeParts;
+        this.markers = PartMarkers.createFromStartNode(startNode);
+        this.childNodes = this.markers.childNodes;
+        return true;
+    }
+
+    /**
+     * @param {{type: string, name?: string, initialValue?: string}} descriptor
+     * @param {Comment} node - the marker comment
+     * @param {any} value - the first value, only needed for directives
+     * @return {Part}
+     */
+    createPart(descriptor, node, value) {
+        switch (descriptor.type) {
+            case 'node':
+                return new ChildNodePart(node);
+            case 'attribute':
+                return new AttributePart(node, descriptor.name, descriptor.initialValue);
+            case 'raw-text-node':
+                return new RawTextNodePart(node, descriptor.initialValue);
+            case 'directive':
+                return new NodePart(node, value);
+            default:
+                throw new Error(`TemplatePart: cannot create a part for type "${descriptor.type}"`);
+        }
     }
 }

package/src/dom-parts/TemplateResult.js

@@ -1,6 +1,7 @@
-import { COMMENT_NODE, getNodePath, encodeHTML } from '../util/DOMHelper.js';
-import { encodeAttribute, isObjectLike } from '../util/AttributeParser.js';
+import { COMMENT_NODE, encodeHTML } from '../util/DOMHelper.js';
+import { camelToDash, encodeAttribute, isObjectLike } from '../util/AttributeParser.js';
 import { TemplatePart } from './TemplatePart.js';
+import { walkPartMarkers } from './PartMarkers.js';
 
 const voidElements = /^(?:area|base|br|col|embed|hr|img|input|link|meta|source|track|wbr)$/i;
 const rawTextElements = /<(script|style|textarea|title)([^>]*)>(.*?)<\/\1>/i;
@@ -203,6 +204,39 @@ const ssrUpdatesCache = new WeakMap();
 /** @type {Map<Element, TemplatePart>} */
 const templatePartsCache = new WeakMap();
 
+/**
+ * @param {Node[] | NodeList} childNodes
+ * @return {Comment|undefined} the first `<!--template-part-->` comment among the nodes
+ */
+const findTemplatePartStartNode = (childNodes) =>
+    Array.from(childNodes).find((node) => node.nodeType === COMMENT_NODE && node.data === 'template-part');
+
+/**
+ * Parses the descriptor of a part from the data of its comment marker.
+ * For html`<div id="${'foo'}" class="${'bar'}">${'baz'}</div>` the markers are:
+ * <!--dom-part-0?type=attribute&name=id&initialValue=\x03--><!--dom-part-1?type=attribute&name=class&initialValue=\x03--><div><!--dom-part-2-->
+ * @param {string} data
+ * @return {{type: string, name?: string, initialValue?: string}}
+ */
+const parsePartDescriptor = (data) => {
+    const query = data.indexOf('?');
+    if (query === -1) {
+        return { type: 'node' };
+    }
+    const searchParams = new URLSearchParams(data.slice(query + 1));
+    const type = searchParams.get('type');
+    if (type === 'attribute') {
+        return { type, name: searchParams.get('name'), initialValue: searchParams.get('initialValue') };
+    }
+    if (type === 'raw-text-node') {
+        return { type, initialValue: searchParams.get('initialValue') };
+    }
+    if (type === 'directive') {
+        return { type };
+    }
+    throw new Error(`TemplateResult: unknown part type "${type}" in marker "${data}"`);
+};
+
 export class TemplateResult {
     /**
      * @param {TemplateStringsArray} strings
@@ -214,30 +248,26 @@ export class TemplateResult {
     }
 
     /**
+     * Renders into a DOM node. A node that already holds a rendered instance of this template is updated, a node with
+     * server rendered markup (a `<!--template-part-->` marker) is hydrated, anything else is replaced by a fresh render.
      * @param {Element} domNode
      */
     renderInto(domNode) {
-        const startNode = Array.from(domNode.childNodes)
-            .filter((node) => node.nodeType === COMMENT_NODE)
-            .find((node) => node.data === 'template-part');
-
-        let serverSideRendered = startNode !== undefined;
+        const startNode = findTemplatePartStartNode(domNode.childNodes);
 
         let templatePart = templatePartsCache.get(domNode);
+        if (templatePart && startNode) {
+            templatePart.update(this);
+            return;
+        }
 
-        if (!templatePart || !startNode) {
-            if (!startNode) {
-                domNode.replaceChildren();
-            }
-
-            templatePart = new TemplatePart(startNode, this);
-            templatePartsCache.set(domNode, templatePart);
+        templatePart = new TemplatePart(startNode, this);
+        templatePartsCache.set(domNode, templatePart);
 
-            if (!serverSideRendered) {
-                domNode.replaceChildren(...templatePart.childNodes);
-            }
-        } else {
-            templatePart.update(this);
+        const hydrated = templatePart.hydrated;
+        templatePart.update(this, hydrated);
+        if (!hydrated) {
+            domNode.replaceChildren(...templatePart.childNodes);
         }
     }
 
@@ -281,7 +311,9 @@ export class TemplateResult {
                     }
 
                     if (name.startsWith('.')) {
-                        const propertyName = name.replace('.', '');
+                        // a property cannot be set in a string, the value is written as the attribute that
+                        // BaseElement maps back to the property on upgrade: camelCase becomes dash-case
+                        const attributeName = camelToDash(name.replace('.', ''));
                         return [
                             {
                                 type: 'attribute',
@@ -291,13 +323,13 @@ export class TemplateResult {
                                         return '';
                                     }
                                     // in all other cases, just escape it in quotes
-                                    return attribute(propertyName, value, quotes);
+                                    return attribute(attributeName, value, quotes);
                                 },
                             },
                         ];
                     }
 
-                    if (name.startsWith('@') || name.startsWith('on')) {
+                    if (name.startsWith('@')) {
                         return [
                             {
                                 type: 'attribute',
@@ -333,7 +365,13 @@ export class TemplateResult {
                             // Note: this will coarse the values into strings, but it's probably ok since there can only be multiple values in string attributes?!
                             const parsedValue = initialValue.replace(/\x03/g, () => values[replaceIndex++]);
                             values = [];
-                            return attribute(searchParams.get('name'), parsedValue, quotes);
+                            // an attribute whose sole value is null or undefined is left out, the DOM renderer
+                            // removes it as well
+                            if (initialValue === '\x03' && value == null) return '';
+                            // a listener on an "old school" event attribute (onevent=${...}) has nothing to do on
+                            // the server side, any other value of an attribute that starts with "on" is written
+                            if (name.startsWith('on') && typeof value === 'function') return '';
+                            return attribute(name, parsedValue, quotes);
                         },
                     });
                     return attributeUpdates;
@@ -369,72 +407,22 @@ export class TemplateResult {
     }
 
     /**
-     * @param {Node[]} childNodes
-     * @return {object[]}
+     * Parses the part descriptors of this template from the comment markers of its rendered or cloned nodes.
+     * The descriptors are indexed like the values of the template.
+     * @param {Node[] | NodeList} childNodes - the top level nodes of a template instance, including the template-part markers
+     * @return {{type: string, name?: string, initialValue?: string}[]}
      */
     parseParts(childNodes) {
-        // we always create a template fragment so that we can start at the root for traversing the node path
-        const range = globalThis.document?.createRange();
-        range.setStartBefore(childNodes[0]);
-        range.setEndAfter(childNodes[childNodes.length - 1]);
-        const template = range.cloneContents();
-
-        const treeWalker = globalThis.document?.createTreeWalker(template, 128);
-        let node = treeWalker.nextNode(); //to skip the root template-part
+        const startNode = findTemplatePartStartNode(childNodes);
         const parts = [];
-
-        let nestedLevel = 0;
-        // search for parts through numbered comment nodes with placeholders
-        while ((node = treeWalker.nextNode())) {
-            if (/^template-part$/.test(node.data)) {
-                nestedLevel++;
-                continue;
-            }
-            if (/^\/template-part$/.test(node.data)) {
-                if (nestedLevel > 0) {
-                    nestedLevel--;
-                }
-                continue;
-            }
-            if (nestedLevel > 0) {
-                continue;
-            }
-            if (/^dom-part-\d+$/.test(node.data)) {
-                parts.push({ type: 'node', path: getNodePath(node) });
-                continue;
-            }
-            if (/^dom-part-\d+\?type=attribute&(.*?)$/.test(node.data)) {
-                // For html`<div id="${'foo'}" class="${'bar'}"></div>` we will get:
-                // <!--dom-part-0?type=attribute&name=id&initialValue=\x03--><!--dom-part-1?type=attribute&name=class&initialValue=\x03-->
-                const [_, paramsString] = node.data.split('?');
-                const searchParams = new URLSearchParams(paramsString);
-                parts.push({
-                    type: 'attribute',
-                    path: getNodePath(node),
-                    name: searchParams.get('name'),
-                    initialValue: searchParams.get('initialValue'),
-                });
-                continue;
-            }
-            if (/^dom-part-\d+\?type=raw-text-node&(.*?)$/.test(node.data)) {
-                // For html`<textarea>${'foo'} bar</textarea>` we will get:
-                // <!--dom-part-0?type=raw-text-node&initialValue=\x03 bar-->
-                const [_, paramsString] = node.data.split('?');
-                const searchParams = new URLSearchParams(paramsString);
-                parts.push({
-                    type: 'raw-text-node',
-                    path: getNodePath(node),
-                    initialValue: searchParams.get('initialValue'),
-                });
-                continue;
-            }
-            if (/^dom-part-\d+\?type=directive$/.test(node.data)) {
-                parts.push({ type: 'directive', path: getNodePath(node) });
-            }
+        if (startNode) {
+            walkPartMarkers(startNode, (node, index) => {
+                parts[index] = parsePartDescriptor(node.data);
+            });
         }
 
         // We couldn't correctly parse parts from the template
-        if (parts.length !== this.strings.length - 1) {
+        if (parts.length !== this.strings.length - 1 || parts.includes(undefined)) {
             throw {
                 name: 'ParseTemplateError',
                 message:
@@ -443,7 +431,6 @@ export class TemplateResult {
                         strings: this.strings,
                         templateString: this.templateString,
                         childNodes,
-                        template,
                         parts,
                     }),
             };

package/src/util/GlobalStylesStore.js

@@ -16,12 +16,11 @@ class GlobalStylesStore extends Store {
     }
 
     initMutationObserver() {
-        const mutationObserver = new MutationObserver(async (mutationRecord) => {
-            if (!mutationRecord[0]) return;
-
-            const filteredNodes = Array.from(mutationRecord[0].addedNodes).filter(
-                (node) => node.tagName === 'STYLE' || node.tagName === 'LINK',
-            );
+        const mutationObserver = new MutationObserver((mutationRecords) => {
+            // a batch holds every mutation since the last callback, the styles can sit in any of its records
+            const filteredNodes = mutationRecords
+                .flatMap((record) => Array.from(record.addedNodes))
+                .filter((node) => node.tagName === 'STYLE' || node.tagName === 'LINK');
 
             filteredNodes.forEach((styleNode) => {
                 if (styleNode.tagName === 'LINK') {