From e8441da5357d1bf846ea4ad751208aa49859eb8a Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Thu, 28 Jul 2022 16:39:31 -0700
Subject: [PATCH 01/76] Add
 <https://github.com/perry-mitchell/css-selector-splitter>

---
 .../src/patches/css-selector-splitter.js      | 140 ++++++++++++++++++
 1 file changed, 140 insertions(+)
 create mode 100644 packages/shadydom/src/patches/css-selector-splitter.js

diff --git a/packages/shadydom/src/patches/css-selector-splitter.js b/packages/shadydom/src/patches/css-selector-splitter.js
new file mode 100644
index 000000000..7fe5dacec
--- /dev/null
+++ b/packages/shadydom/src/patches/css-selector-splitter.js
@@ -0,0 +1,140 @@
+/**
+@license
+
+MIT License
+
+Copyright (c) 2016 Perry Mitchell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+
+const BRACES = {
+  '(': ')',
+  '[': ']',
+  '"': '"',
+  "'": "'",
+};
+
+const CLOSING_BRACES = {
+  ')': '(',
+  ']': '[',
+};
+
+function splitSelector(selector, splitCharacters = [',']) {
+  let currentBraces = [],
+    selectorLen = selector.length,
+    selectors = [],
+    joiners = [],
+    currentSelector = '',
+    closingBraces = {};
+  for (var i = 0; i < selectorLen; i += 1) {
+    let char = selector[i];
+    if (BRACES.hasOwnProperty(char)) {
+      if (currentBraces.length === 0) {
+        currentBraces.push(char);
+      } else {
+        let lastBrace = currentBraces[currentBraces.length - 1];
+        if (lastBrace === '"' || lastBrace === "'") {
+          // within quotes
+          if (char === lastBrace) {
+            // closing quote
+            currentBraces.pop();
+          }
+        } else {
+          // inside brackets or square brackets
+          currentBraces.push(char);
+        }
+      }
+      currentSelector += char;
+    } else if (CLOSING_BRACES.hasOwnProperty(char)) {
+      let lastBrace = currentBraces[currentBraces.length - 1],
+        matchingOpener = CLOSING_BRACES[char];
+      if (lastBrace === matchingOpener) {
+        currentBraces.pop();
+      }
+      currentSelector += char;
+    } else if (splitCharacters.indexOf(char) >= 0) {
+      if (currentBraces.length <= 0) {
+        // we're not inside another block, so we can split using the comma/splitter
+        let lastJoiner = joiners[joiners.length - 1];
+        if (lastJoiner === ' ' && currentSelector.length <= 0) {
+          // we just split by a space, but there seems to be another split character, so use
+          // this new one instead of the previous space
+          joiners[joiners.length - 1] = char;
+        } else if (currentSelector.length <= 0) {
+          // skip this character, as it's just padding
+        } else {
+          // split by this character
+          let newLength = selectors.push(currentSelector.trim());
+          joiners[newLength - 1] = char;
+          currentSelector = '';
+        }
+      } else {
+        // we're inside another block, so ignore the comma/splitter
+        currentSelector += char;
+      }
+    } else {
+      // just add this character
+      currentSelector += char;
+    }
+  }
+  selectors.push(currentSelector.trim());
+  return {
+    selectors: selectors.filter((cssSelector) => cssSelector.length > 0),
+    joiners: joiners,
+  };
+}
+
+// output:
+
+function extractSelectors(selector, splitChars) {
+  let split = splitSelector(selector, splitChars);
+  return split.selectors;
+}
+
+function extractSelectorBlocks(selector) {
+  return splitSelector(selector, ['+', '~', '>', ' ']);
+}
+
+function joinParts(selectors, joiners) {
+  let selector = '',
+    selectorCount = selectors.length;
+  selectors.forEach(function (part, index) {
+    let suffix = joiners[index];
+    if (!suffix) {
+      if (selectorCount - 1 === index) {
+        suffix = '';
+      } else {
+        throw new Error(`No joiner for index: ${index}`);
+      }
+    } else {
+      if (suffix !== ' ') {
+        suffix = ` ${suffix} `;
+      }
+    }
+    selector += part + suffix;
+  });
+  return selector;
+}
+
+extractSelectors.splitSelectorBlocks = extractSelectorBlocks;
+
+extractSelectors.joinSelector = joinParts;
+
+export default extractSelectors;

From 7ed74e4d917ce44793bf2db152a67a15e342d2c8 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Fri, 29 Jul 2022 13:23:22 -0700
Subject: [PATCH 02/76] css-selector-parser: Make the API minification safe;
 use real exports.

---
 packages/shadydom/src/patches/css-selector-splitter.js | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/shadydom/src/patches/css-selector-splitter.js b/packages/shadydom/src/patches/css-selector-splitter.js
index 7fe5dacec..484c4cc37 100644
--- a/packages/shadydom/src/patches/css-selector-splitter.js
+++ b/packages/shadydom/src/patches/css-selector-splitter.js
@@ -96,8 +96,8 @@ function splitSelector(selector, splitCharacters = [',']) {
   }
   selectors.push(currentSelector.trim());
   return {
-    selectors: selectors.filter((cssSelector) => cssSelector.length > 0),
-    joiners: joiners,
+    'selectors': selectors.filter((cssSelector) => cssSelector.length > 0),
+    'joiners': joiners,
   };
 }
 
@@ -133,8 +133,8 @@ function joinParts(selectors, joiners) {
   return selector;
 }
 
-extractSelectors.splitSelectorBlocks = extractSelectorBlocks;
+export {extractSelectorBlocks as splitSelectorBlocks};
 
-extractSelectors.joinSelector = joinParts;
+export {joinParts as joinSelector};
 
 export default extractSelectors;

From 0432af98711986aeaf61a5af715d146c6dc0777d Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Fri, 29 Jul 2022 13:26:13 -0700
Subject: [PATCH 03/76] Add `logicalQuerySelectorAll` and use in
 `querySelector` and `querySelectorAll` wrappers.

---
 packages/shadydom/src/patches/ParentNode.js | 103 +++++++++++++++++---
 1 file changed, 89 insertions(+), 14 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index 9cd4149f6..07ec253a8 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -10,6 +10,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 
 import * as utils from '../utils.js';
 import {shadyDataForNode} from '../shady-data.js';
+import {splitSelectorBlocks} from './css-selector-splitter.js';
 
 /**
  * @param {Node} node
@@ -128,6 +129,92 @@ export const ParentNodePatches = utils.getOwnPropertyDescriptors({
   },
 });
 
+/**
+ * @param {!Element} contextElement
+ * @param {string} selector
+ * @return {!Array<!Element>}
+ */
+const logicalQuerySelectorAll = (contextElement, selector) => {
+  const {
+    'selectors': simpleSelectors,
+    'joiners': combinators,
+  } = splitSelectorBlocks(selector);
+
+  if (simpleSelectors.length < 1) {
+    return [];
+  }
+
+  let cursors = query(
+    contextElement[utils.SHADY_PREFIX + 'getRootNode'](),
+    (node) => {
+      return utils.matchesSelector(node, simpleSelectors[0]);
+    }
+  );
+
+  for (let i = 0; i < combinators.length; i++) {
+    const combinator = combinators[i];
+    const simpleSelector = simpleSelectors[i + 1];
+
+    if (combinator === ' ') {
+      // Descendant combinator
+      cursors = cursors.flatMap((cursor) => {
+        return query(cursor, (descendant) => {
+          return utils.matchesSelector(descendant, simpleSelector);
+        });
+      });
+    } else if (combinator === '>') {
+      // Child combinator
+      cursors = cursors.flatMap((cursor) => {
+        for (
+          let child = cursor[utils.SHADY_PREFIX + 'firstElementChild']();
+          child;
+          child = child[utils.SHADY_PREFIX + 'nextElementSibling']()
+        ) {
+          if (utils.matchesSelector(child, simpleSelector)) {
+            return [child];
+          } else {
+            return [];
+          }
+        }
+      });
+    } else if (combinator === '+') {
+      // Next-sibling combinator
+      cursors = cursors.flatMap((cursor) => {
+        let nextElementSibling = cursor[
+          utils.SHADY_PREFIX + 'nextElementSibling'
+        ]();
+        if (
+          nextElementSibling &&
+          utils.matchesSelector(nextElementSibling, simpleSelector)
+        ) {
+          return [nextElementSibling];
+        } else {
+          return [];
+        }
+      });
+    } else if (combinator === '~') {
+      // Subsequent-sibling combinator
+      cursors = cursors.flatMap((cursor) => {
+        for (
+          let sibling = cursor[utils.SHADY_PREFIX + 'nextElementSibling']();
+          sibling;
+          sibling = sibling[utils.SHADY_PREFIX + 'nextElementSibling']()
+        ) {
+          if (utils.matchesSelector(sibling, simpleSelector)) {
+            return [sibling];
+          } else {
+            return [];
+          }
+        }
+      });
+    } else {
+      throw new Error(`Unrecognized combinator: '${combinator}'.`);
+    }
+  }
+
+  return cursors;
+};
+
 export const QueryPatches = utils.getOwnPropertyDescriptors({
   // TODO(sorvell): consider doing native QSA and filtering results.
   /**
@@ -135,17 +222,7 @@ export const QueryPatches = utils.getOwnPropertyDescriptors({
    * @param  {string} selector
    */
   querySelector(selector) {
-    // match selector and halt on first result.
-    let result = query(
-      this,
-      function (n) {
-        return utils.matchesSelector(n, selector);
-      },
-      function (n) {
-        return Boolean(n);
-      }
-    )[0];
-    return result || null;
+    return logicalQuerySelectorAll(this, selector)[0] || null;
   },
 
   /**
@@ -167,9 +244,7 @@ export const QueryPatches = utils.getOwnPropertyDescriptors({
       );
     }
     return utils.createPolyfilledHTMLCollection(
-      query(this, function (n) {
-        return utils.matchesSelector(n, selector);
-      })
+      logicalQuerySelectorAll(this, selector)
     );
   },
 });

From cf213983d990c14194a79788902cdebae592a9cb Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Fri, 29 Jul 2022 13:50:14 -0700
Subject: [PATCH 04/76] css-selector-splitter: Fix another minification error.

---
 packages/shadydom/src/patches/css-selector-splitter.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/shadydom/src/patches/css-selector-splitter.js b/packages/shadydom/src/patches/css-selector-splitter.js
index 484c4cc37..9e2685f2b 100644
--- a/packages/shadydom/src/patches/css-selector-splitter.js
+++ b/packages/shadydom/src/patches/css-selector-splitter.js
@@ -105,7 +105,7 @@ function splitSelector(selector, splitCharacters = [',']) {
 
 function extractSelectors(selector, splitChars) {
   let split = splitSelector(selector, splitChars);
-  return split.selectors;
+  return split['selectors'];
 }
 
 function extractSelectorBlocks(selector) {

From d112b0738c09acb29eba4b9f4223597d0df90407 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Fri, 29 Jul 2022 14:20:09 -0700
Subject: [PATCH 05/76] Deduplicate results and filter to only those within the
 same root.

---
 packages/shadydom/src/patches/ParentNode.js | 56 ++++++++++++++++++---
 1 file changed, 49 insertions(+), 7 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index 07ec253a8..3e4663296 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -10,7 +10,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 
 import * as utils from '../utils.js';
 import {shadyDataForNode} from '../shady-data.js';
-import {splitSelectorBlocks} from './css-selector-splitter.js';
+import extractSelectors, {
+  splitSelectorBlocks,
+} from './css-selector-splitter.js';
 
 /**
  * @param {Node} node
@@ -129,16 +131,56 @@ export const ParentNodePatches = utils.getOwnPropertyDescriptors({
   },
 });
 
+/**
+ * @param {!Array<T>} array
+ * @return {!Array<T>}
+ * @template T
+ */
+const deduplicateArray = (array) => {
+  const results = [];
+  for (const item of array) {
+    if (!results.includes(item)) {
+      results.push(item);
+    }
+  }
+  return results;
+};
+
+/**
+ * @param {!Element} contextElement
+ * @param {!Array<!Element>} elements
+ * @return {!Array<!Element>}
+ */
+const deduplicateAndFilterToContextRoot = (contextElement, elements) => {
+  const getRoot = (e) => e[utils.SHADY_PREFIX + 'getRootNode']();
+  const contextRoot = getRoot(contextElement);
+  return deduplicateArray(elements).filter((e) => getRoot(e) === contextRoot);
+};
+
+/**
+ * @param {!Element} contextElement
+ * @param {string} selectorList
+ * @return {!Array<!Element>}
+ */
+const logicalQuerySelectorList = (contextElement, selectorList) => {
+  return deduplicateAndFilterToContextRoot(
+    contextElement,
+    extractSelectors(selectorList).flatMap((selector) => {
+      return logicalQuerySingleSelector(contextElement, selector);
+    })
+  );
+};
+
 /**
  * @param {!Element} contextElement
- * @param {string} selector
+ * @param {string} complexSelector
  * @return {!Array<!Element>}
  */
-const logicalQuerySelectorAll = (contextElement, selector) => {
+const logicalQuerySingleSelector = (contextElement, complexSelector) => {
   const {
     'selectors': simpleSelectors,
     'joiners': combinators,
-  } = splitSelectorBlocks(selector);
+  } = splitSelectorBlocks(complexSelector);
 
   if (simpleSelectors.length < 1) {
     return [];
@@ -212,7 +254,7 @@ const logicalQuerySelectorAll = (contextElement, selector) => {
     }
   }
 
-  return cursors;
+  return deduplicateAndFilterToContextRoot(contextElement, cursors);
 };
 
 export const QueryPatches = utils.getOwnPropertyDescriptors({
@@ -222,7 +264,7 @@ export const QueryPatches = utils.getOwnPropertyDescriptors({
    * @param  {string} selector
    */
   querySelector(selector) {
-    return logicalQuerySelectorAll(this, selector)[0] || null;
+    return logicalQuerySelectorList(this, selector)[0] || null;
   },
 
   /**
@@ -244,7 +286,7 @@ export const QueryPatches = utils.getOwnPropertyDescriptors({
       );
     }
     return utils.createPolyfilledHTMLCollection(
-      logicalQuerySelectorAll(this, selector)
+      logicalQuerySelectorList(this, selector)
     );
   },
 });

From ed4caf3a1b88aa5bc7aeafddf7d844d3dcedf4fa Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Fri, 29 Jul 2022 15:31:51 -0700
Subject: [PATCH 06/76] Use `Set` to simplify `deduplicateArray`.

---
 packages/shadydom/src/patches/ParentNode.js | 10 +---------
 1 file changed, 1 insertion(+), 9 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index 3e4663296..d42b7ed42 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -136,15 +136,7 @@ export const ParentNodePatches = utils.getOwnPropertyDescriptors({
  * @return {!Array<T>}
  * @template T
  */
-const deduplicateArray = (array) => {
-  const results = [];
-  for (const item of array) {
-    if (!results.includes(item)) {
-      results.push(item);
-    }
-  }
-  return results;
-};
+const deduplicateArray = (array) => Array.from(new Set(array));
 
 /**
  * @param {!Element} contextElement

From 0a04a1c8d69f8d81cb6e27b65e181100085e865f Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Fri, 29 Jul 2022 15:34:27 -0700
Subject: [PATCH 07/76] Fix attempts to call properties that are getters, not
 functions.

---
 packages/shadydom/src/patches/ParentNode.js | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index d42b7ed42..857e9205d 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -200,9 +200,9 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
       // Child combinator
       cursors = cursors.flatMap((cursor) => {
         for (
-          let child = cursor[utils.SHADY_PREFIX + 'firstElementChild']();
+          let child = cursor[utils.SHADY_PREFIX + 'firstElementChild'];
           child;
-          child = child[utils.SHADY_PREFIX + 'nextElementSibling']()
+          child = child[utils.SHADY_PREFIX + 'nextElementSibling']
         ) {
           if (utils.matchesSelector(child, simpleSelector)) {
             return [child];
@@ -214,9 +214,8 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
     } else if (combinator === '+') {
       // Next-sibling combinator
       cursors = cursors.flatMap((cursor) => {
-        let nextElementSibling = cursor[
-          utils.SHADY_PREFIX + 'nextElementSibling'
-        ]();
+        let nextElementSibling =
+          cursor[utils.SHADY_PREFIX + 'nextElementSibling'];
         if (
           nextElementSibling &&
           utils.matchesSelector(nextElementSibling, simpleSelector)
@@ -230,9 +229,9 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
       // Subsequent-sibling combinator
       cursors = cursors.flatMap((cursor) => {
         for (
-          let sibling = cursor[utils.SHADY_PREFIX + 'nextElementSibling']();
+          let sibling = cursor[utils.SHADY_PREFIX + 'nextElementSibling'];
           sibling;
-          sibling = sibling[utils.SHADY_PREFIX + 'nextElementSibling']()
+          sibling = sibling[utils.SHADY_PREFIX + 'nextElementSibling']
         ) {
           if (utils.matchesSelector(sibling, simpleSelector)) {
             return [sibling];

From 3697e0897acbcdd225d08d763389ca8f7bc9d1e4 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Fri, 29 Jul 2022 15:36:39 -0700
Subject: [PATCH 08/76] Fix filtering so that results are always exclusive
 descendants of the context element.

---
 packages/shadydom/src/patches/ParentNode.js | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index 857e9205d..731fdbc96 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -139,14 +139,14 @@ export const ParentNodePatches = utils.getOwnPropertyDescriptors({
 const deduplicateArray = (array) => Array.from(new Set(array));
 
 /**
- * @param {!Element} contextElement
+ * @param {!Element} ancestor
  * @param {!Array<!Element>} elements
  * @return {!Array<!Element>}
  */
-const deduplicateAndFilterToContextRoot = (contextElement, elements) => {
-  const getRoot = (e) => e[utils.SHADY_PREFIX + 'getRootNode']();
-  const contextRoot = getRoot(contextElement);
-  return deduplicateArray(elements).filter((e) => getRoot(e) === contextRoot);
+const deduplicateAndFilterToDescendants = (ancestor, elements) => {
+  return deduplicateArray(elements).filter((e) => {
+    return e !== ancestor && ancestor.contains(e);
+  });
 };
 
 /**
@@ -155,7 +155,7 @@ const deduplicateAndFilterToContextRoot = (contextElement, elements) => {
  * @return {!Array<!Element>}
  */
 const logicalQuerySelectorList = (contextElement, selectorList) => {
-  return deduplicateAndFilterToContextRoot(
+  return deduplicateAndFilterToDescendants(
     contextElement,
     extractSelectors(selectorList).flatMap((selector) => {
       return logicalQuerySingleSelector(contextElement, selector);
@@ -245,7 +245,7 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
     }
   }
 
-  return deduplicateAndFilterToContextRoot(contextElement, cursors);
+  return deduplicateAndFilterToDescendants(contextElement, cursors);
 };
 
 export const QueryPatches = utils.getOwnPropertyDescriptors({

From 3695eebdbce4253beeb59bf978a1d6babbc5db16 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Fri, 29 Jul 2022 15:46:43 -0700
Subject: [PATCH 09/76] Fix early returns in descendant and child combinators.

---
 packages/shadydom/src/patches/ParentNode.js | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index 731fdbc96..49b319cff 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -199,17 +199,19 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
     } else if (combinator === '>') {
       // Child combinator
       cursors = cursors.flatMap((cursor) => {
+        const results = [];
+
         for (
           let child = cursor[utils.SHADY_PREFIX + 'firstElementChild'];
           child;
           child = child[utils.SHADY_PREFIX + 'nextElementSibling']
         ) {
           if (utils.matchesSelector(child, simpleSelector)) {
-            return [child];
-          } else {
-            return [];
+            results.push(child);
           }
         }
+
+        return results;
       });
     } else if (combinator === '+') {
       // Next-sibling combinator
@@ -221,24 +223,26 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
           utils.matchesSelector(nextElementSibling, simpleSelector)
         ) {
           return [nextElementSibling];
-        } else {
-          return [];
         }
+
+        return [];
       });
     } else if (combinator === '~') {
       // Subsequent-sibling combinator
       cursors = cursors.flatMap((cursor) => {
+        const results = [];
+
         for (
           let sibling = cursor[utils.SHADY_PREFIX + 'nextElementSibling'];
           sibling;
           sibling = sibling[utils.SHADY_PREFIX + 'nextElementSibling']
         ) {
           if (utils.matchesSelector(sibling, simpleSelector)) {
-            return [sibling];
-          } else {
-            return [];
+            results.push(sibling);
           }
         }
+
+        return results;
       });
     } else {
       throw new Error(`Unrecognized combinator: '${combinator}'.`);

From b569f0b47c235fc2379e5c6ba78c25827677eaf5 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Fri, 29 Jul 2022 16:15:24 -0700
Subject: [PATCH 10/76] Fix `contains` call to use the Shady DOM wrapper.

---
 packages/shadydom/src/patches/ParentNode.js | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index 49b319cff..f2fb39253 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -144,8 +144,10 @@ const deduplicateArray = (array) => Array.from(new Set(array));
  * @return {!Array<!Element>}
  */
 const deduplicateAndFilterToDescendants = (ancestor, elements) => {
-  return deduplicateArray(elements).filter((e) => {
-    return e !== ancestor && ancestor.contains(e);
+  return deduplicateArray(elements).filter((element) => {
+    return (
+      element !== ancestor && ancestor[utils.SHADY_PREFIX + 'contains'](element)
+    );
   });
 };
 

From c4edbf4d994c61271575c73ee2ed484004d94829 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Fri, 29 Jul 2022 16:33:57 -0700
Subject: [PATCH 11/76] Simple selectors containing `:scope` should only match
 if the candidate is the context element.

---
 packages/shadydom/src/patches/ParentNode.js | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index f2fb39253..b5a008ce9 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -187,6 +187,18 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
     }
   );
 
+  /**
+   * @param {!Element} element
+   * @param {string} simpleSelector
+   * @return {boolean}
+   */
+  const matchesSimpleSelector = (element, simpleSelector) => {
+    return (
+      utils.matchesSelector(element, simpleSelector) &&
+      (!simpleSelector.includes(':scope') || element === contextElement)
+    );
+  };
+
   for (let i = 0; i < combinators.length; i++) {
     const combinator = combinators[i];
     const simpleSelector = simpleSelectors[i + 1];
@@ -195,7 +207,7 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
       // Descendant combinator
       cursors = cursors.flatMap((cursor) => {
         return query(cursor, (descendant) => {
-          return utils.matchesSelector(descendant, simpleSelector);
+          return matchesSimpleSelector(descendant, simpleSelector);
         });
       });
     } else if (combinator === '>') {
@@ -208,7 +220,7 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
           child;
           child = child[utils.SHADY_PREFIX + 'nextElementSibling']
         ) {
-          if (utils.matchesSelector(child, simpleSelector)) {
+          if (matchesSimpleSelector(child, simpleSelector)) {
             results.push(child);
           }
         }
@@ -222,7 +234,7 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
           cursor[utils.SHADY_PREFIX + 'nextElementSibling'];
         if (
           nextElementSibling &&
-          utils.matchesSelector(nextElementSibling, simpleSelector)
+          matchesSimpleSelector(nextElementSibling, simpleSelector)
         ) {
           return [nextElementSibling];
         }
@@ -239,7 +251,7 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
           sibling;
           sibling = sibling[utils.SHADY_PREFIX + 'nextElementSibling']
         ) {
-          if (utils.matchesSelector(sibling, simpleSelector)) {
+          if (matchesSimpleSelector(sibling, simpleSelector)) {
             results.push(sibling);
           }
         }

From bc11939de6cc6c9682e91ccb1a43b67944aea5cd Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Fri, 29 Jul 2022 17:38:38 -0700
Subject: [PATCH 12/76] Add a default parameter value to satisfy Closure.

---
 packages/shadydom/src/patches/css-selector-splitter.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/shadydom/src/patches/css-selector-splitter.js b/packages/shadydom/src/patches/css-selector-splitter.js
index 9e2685f2b..e56e89e2d 100644
--- a/packages/shadydom/src/patches/css-selector-splitter.js
+++ b/packages/shadydom/src/patches/css-selector-splitter.js
@@ -103,7 +103,7 @@ function splitSelector(selector, splitCharacters = [',']) {
 
 // output:
 
-function extractSelectors(selector, splitChars) {
+function extractSelectors(selector, splitChars = [',']) {
   let split = splitSelector(selector, splitChars);
   return split['selectors'];
 }

From b23f0dbce8f6102f762afc45a4ff95a20281006c Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Mon, 1 Aug 2022 11:42:48 -0700
Subject: [PATCH 13/76] `Array`'s `flatMap` is not compiled out by Closure, so
 implement it manually.

---
 packages/shadydom/src/patches/ParentNode.js | 10 +++----
 packages/shadydom/src/utils.js              | 30 +++++++++++++++++++++
 2 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index b5a008ce9..4963639bc 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -159,7 +159,7 @@ const deduplicateAndFilterToDescendants = (ancestor, elements) => {
 const logicalQuerySelectorList = (contextElement, selectorList) => {
   return deduplicateAndFilterToDescendants(
     contextElement,
-    extractSelectors(selectorList).flatMap((selector) => {
+    utils.flatMap(extractSelectors(selectorList), (selector) => {
       return logicalQuerySingleSelector(contextElement, selector);
     })
   );
@@ -205,14 +205,14 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
 
     if (combinator === ' ') {
       // Descendant combinator
-      cursors = cursors.flatMap((cursor) => {
+      cursors = utils.flatMap(cursors, (cursor) => {
         return query(cursor, (descendant) => {
           return matchesSimpleSelector(descendant, simpleSelector);
         });
       });
     } else if (combinator === '>') {
       // Child combinator
-      cursors = cursors.flatMap((cursor) => {
+      cursors = utils.flatMap(cursors, (cursor) => {
         const results = [];
 
         for (
@@ -229,7 +229,7 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
       });
     } else if (combinator === '+') {
       // Next-sibling combinator
-      cursors = cursors.flatMap((cursor) => {
+      cursors = utils.flatMap(cursors, (cursor) => {
         let nextElementSibling =
           cursor[utils.SHADY_PREFIX + 'nextElementSibling'];
         if (
@@ -243,7 +243,7 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
       });
     } else if (combinator === '~') {
       // Subsequent-sibling combinator
-      cursors = cursors.flatMap((cursor) => {
+      cursors = utils.flatMap(cursors, (cursor) => {
         const results = [];
 
         for (
diff --git a/packages/shadydom/src/utils.js b/packages/shadydom/src/utils.js
index 9de04d6a8..a7e40da47 100644
--- a/packages/shadydom/src/utils.js
+++ b/packages/shadydom/src/utils.js
@@ -291,3 +291,33 @@ export const convertNodesIntoANode = (...args) => {
   }
   return fragment;
 };
+
+/**
+ * @template T
+ * @param {!Array<!T | !Array<!T>>} array
+ * @param {number} depth
+ * @return {!Array<!T>}
+ */
+const flat = (array, depth = 1) => {
+  for (; depth > 0; depth--) {
+    array = array.reduce((acc, item) => {
+      if (Array.isArray(item)) {
+        acc.push(...item);
+      } else {
+        acc.push(item);
+      }
+      return acc;
+    }, []);
+  }
+
+  return array;
+};
+
+/**
+ * @template A
+ * @template B
+ * @param {!Array<!A>} array
+ * @param {function(!A): (!B | !Array<!B>)} mapFn
+ * @return {!Array<!B>}
+ */
+export const flatMap = (array, mapFn) => flat(array.map(mapFn), 1);

From 028d03e513a5e7e1e615cbd7b1e2d83d771cc50f Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Mon, 1 Aug 2022 13:27:23 -0700
Subject: [PATCH 14/76] Evaluate selectors in reverse to avoid walking entire
 descendant trees for the descendant combinator.

---
 packages/shadydom/src/patches/ParentNode.js | 73 +++++++++++++--------
 1 file changed, 46 insertions(+), 27 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index 4963639bc..594b649a2 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -180,12 +180,21 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
     return [];
   }
 
+  /**
+   * @type {!Array<!{
+   *   position: !Element,
+   *   target: !Element,
+   * }>}
+   */
   let cursors = query(
     contextElement[utils.SHADY_PREFIX + 'getRootNode'](),
     (node) => {
-      return utils.matchesSelector(node, simpleSelectors[0]);
+      return utils.matchesSelector(
+        node,
+        simpleSelectors[simpleSelectors.length - 1]
+      );
     }
-  );
+  ).map((element) => ({position: element, target: element}));
 
   /**
    * @param {!Element} element
@@ -199,44 +208,50 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
     );
   };
 
-  for (let i = 0; i < combinators.length; i++) {
+  for (let i = combinators.length - 1; i >= 0; i--) {
     const combinator = combinators[i];
-    const simpleSelector = simpleSelectors[i + 1];
+    const simpleSelector = simpleSelectors[i];
 
     if (combinator === ' ') {
       // Descendant combinator
-      cursors = utils.flatMap(cursors, (cursor) => {
-        return query(cursor, (descendant) => {
-          return matchesSimpleSelector(descendant, simpleSelector);
-        });
-      });
-    } else if (combinator === '>') {
-      // Child combinator
       cursors = utils.flatMap(cursors, (cursor) => {
         const results = [];
 
         for (
-          let child = cursor[utils.SHADY_PREFIX + 'firstElementChild'];
-          child;
-          child = child[utils.SHADY_PREFIX + 'nextElementSibling']
+          let ancestor = cursor.position[utils.SHADY_PREFIX + 'parentNode'];
+          ancestor && ancestor instanceof Element;
+          ancestor = ancestor[utils.SHADY_PREFIX + 'parentNode']
         ) {
-          if (matchesSimpleSelector(child, simpleSelector)) {
-            results.push(child);
+          if (matchesSimpleSelector(ancestor, simpleSelector)) {
+            results.push({position: ancestor, target: cursor.target});
           }
         }
 
         return results;
       });
-    } else if (combinator === '+') {
-      // Next-sibling combinator
+    } else if (combinator === '>') {
+      // Child combinator
       cursors = utils.flatMap(cursors, (cursor) => {
-        let nextElementSibling =
-          cursor[utils.SHADY_PREFIX + 'nextElementSibling'];
+        const parent = cursor.position[utils.SHADY_PREFIX + 'parentNode'];
+
         if (
-          nextElementSibling &&
-          matchesSimpleSelector(nextElementSibling, simpleSelector)
+          parent &&
+          parent instanceof Element &&
+          matchesSimpleSelector(parent, simpleSelector)
         ) {
-          return [nextElementSibling];
+          return [{position: parent, target: cursor.target}];
+        }
+
+        return [];
+      });
+    } else if (combinator === '+') {
+      // Next-sibling combinator
+      cursors = utils.flatMap(cursors, (cursor) => {
+        const sibling =
+          cursor.position[utils.SHADY_PREFIX + 'previousElementSibling'];
+
+        if (sibling && matchesSimpleSelector(sibling, simpleSelector)) {
+          return [{position: sibling, target: cursor.target}];
         }
 
         return [];
@@ -247,12 +262,13 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
         const results = [];
 
         for (
-          let sibling = cursor[utils.SHADY_PREFIX + 'nextElementSibling'];
+          let sibling =
+            cursor.position[utils.SHADY_PREFIX + 'previousElementSibling'];
           sibling;
-          sibling = sibling[utils.SHADY_PREFIX + 'nextElementSibling']
+          sibling = sibling[utils.SHADY_PREFIX + 'previousElementSibling']
         ) {
           if (matchesSimpleSelector(sibling, simpleSelector)) {
-            results.push(sibling);
+            results.push({position: sibling, target: cursor.target});
           }
         }
 
@@ -263,7 +279,10 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
     }
   }
 
-  return deduplicateAndFilterToDescendants(contextElement, cursors);
+  return deduplicateAndFilterToDescendants(
+    contextElement,
+    cursors.map((cursor) => cursor.target)
+  );
 };
 
 export const QueryPatches = utils.getOwnPropertyDescriptors({

From 569d6d38f204491c28ead956b3dbdea4d1819b30 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Mon, 1 Aug 2022 13:39:36 -0700
Subject: [PATCH 15/76] Closure isn't compiling out `includes`; replace with
 `indexOf`.

---
 packages/shadydom/src/patches/ParentNode.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index 594b649a2..57a7c02f4 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -204,7 +204,7 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
   const matchesSimpleSelector = (element, simpleSelector) => {
     return (
       utils.matchesSelector(element, simpleSelector) &&
-      (!simpleSelector.includes(':scope') || element === contextElement)
+      (simpleSelector.indexOf(':scope') === -1 || element === contextElement)
     );
   };
 

From bf1897e6d4a48ee104949874489d100ccea15070 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Mon, 1 Aug 2022 13:49:23 -0700
Subject: [PATCH 16/76] Remove `utils.flatMap`; use `utils.flat` directly.

---
 packages/shadydom/src/patches/ParentNode.js | 112 +++++++++++---------
 packages/shadydom/src/utils.js              |  11 +-
 2 files changed, 62 insertions(+), 61 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index 57a7c02f4..d974203b1 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -159,9 +159,11 @@ const deduplicateAndFilterToDescendants = (ancestor, elements) => {
 const logicalQuerySelectorList = (contextElement, selectorList) => {
   return deduplicateAndFilterToDescendants(
     contextElement,
-    utils.flatMap(extractSelectors(selectorList), (selector) => {
-      return logicalQuerySingleSelector(contextElement, selector);
-    })
+    utils.flat(
+      extractSelectors(selectorList).map((selector) => {
+        return logicalQuerySingleSelector(contextElement, selector);
+      })
+    )
   );
 };
 
@@ -214,66 +216,74 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
 
     if (combinator === ' ') {
       // Descendant combinator
-      cursors = utils.flatMap(cursors, (cursor) => {
-        const results = [];
-
-        for (
-          let ancestor = cursor.position[utils.SHADY_PREFIX + 'parentNode'];
-          ancestor && ancestor instanceof Element;
-          ancestor = ancestor[utils.SHADY_PREFIX + 'parentNode']
-        ) {
-          if (matchesSimpleSelector(ancestor, simpleSelector)) {
-            results.push({position: ancestor, target: cursor.target});
+      cursors = utils.flat(
+        cursors.map((cursor) => {
+          const results = [];
+
+          for (
+            let ancestor = cursor.position[utils.SHADY_PREFIX + 'parentNode'];
+            ancestor && ancestor instanceof Element;
+            ancestor = ancestor[utils.SHADY_PREFIX + 'parentNode']
+          ) {
+            if (matchesSimpleSelector(ancestor, simpleSelector)) {
+              results.push({position: ancestor, target: cursor.target});
+            }
           }
-        }
 
-        return results;
-      });
+          return results;
+        })
+      );
     } else if (combinator === '>') {
       // Child combinator
-      cursors = utils.flatMap(cursors, (cursor) => {
-        const parent = cursor.position[utils.SHADY_PREFIX + 'parentNode'];
-
-        if (
-          parent &&
-          parent instanceof Element &&
-          matchesSimpleSelector(parent, simpleSelector)
-        ) {
-          return [{position: parent, target: cursor.target}];
-        }
-
-        return [];
-      });
+      cursors = utils.flat(
+        cursors.map((cursor) => {
+          const parent = cursor.position[utils.SHADY_PREFIX + 'parentNode'];
+
+          if (
+            parent &&
+            parent instanceof Element &&
+            matchesSimpleSelector(parent, simpleSelector)
+          ) {
+            return [{position: parent, target: cursor.target}];
+          }
+
+          return [];
+        })
+      );
     } else if (combinator === '+') {
       // Next-sibling combinator
-      cursors = utils.flatMap(cursors, (cursor) => {
-        const sibling =
-          cursor.position[utils.SHADY_PREFIX + 'previousElementSibling'];
+      cursors = utils.flat(
+        cursors.map((cursor) => {
+          const sibling =
+            cursor.position[utils.SHADY_PREFIX + 'previousElementSibling'];
 
-        if (sibling && matchesSimpleSelector(sibling, simpleSelector)) {
-          return [{position: sibling, target: cursor.target}];
-        }
+          if (sibling && matchesSimpleSelector(sibling, simpleSelector)) {
+            return [{position: sibling, target: cursor.target}];
+          }
 
-        return [];
-      });
+          return [];
+        })
+      );
     } else if (combinator === '~') {
       // Subsequent-sibling combinator
-      cursors = utils.flatMap(cursors, (cursor) => {
-        const results = [];
-
-        for (
-          let sibling =
-            cursor.position[utils.SHADY_PREFIX + 'previousElementSibling'];
-          sibling;
-          sibling = sibling[utils.SHADY_PREFIX + 'previousElementSibling']
-        ) {
-          if (matchesSimpleSelector(sibling, simpleSelector)) {
-            results.push({position: sibling, target: cursor.target});
+      cursors = utils.flat(
+        cursors.map((cursor) => {
+          const results = [];
+
+          for (
+            let sibling =
+              cursor.position[utils.SHADY_PREFIX + 'previousElementSibling'];
+            sibling;
+            sibling = sibling[utils.SHADY_PREFIX + 'previousElementSibling']
+          ) {
+            if (matchesSimpleSelector(sibling, simpleSelector)) {
+              results.push({position: sibling, target: cursor.target});
+            }
           }
-        }
 
-        return results;
-      });
+          return results;
+        })
+      );
     } else {
       throw new Error(`Unrecognized combinator: '${combinator}'.`);
     }
diff --git a/packages/shadydom/src/utils.js b/packages/shadydom/src/utils.js
index a7e40da47..9558701cb 100644
--- a/packages/shadydom/src/utils.js
+++ b/packages/shadydom/src/utils.js
@@ -298,7 +298,7 @@ export const convertNodesIntoANode = (...args) => {
  * @param {number} depth
  * @return {!Array<!T>}
  */
-const flat = (array, depth = 1) => {
+export const flat = (array, depth = 1) => {
   for (; depth > 0; depth--) {
     array = array.reduce((acc, item) => {
       if (Array.isArray(item)) {
@@ -312,12 +312,3 @@ const flat = (array, depth = 1) => {
 
   return array;
 };
-
-/**
- * @template A
- * @template B
- * @param {!Array<!A>} array
- * @param {function(!A): (!B | !Array<!B>)} mapFn
- * @return {!Array<!B>}
- */
-export const flatMap = (array, mapFn) => flat(array.map(mapFn), 1);

From c0d92e98eaf9ca7dc074cf10666204721130a42d Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Tue, 2 Aug 2022 15:05:14 -0700
Subject: [PATCH 17/76] Replace "simple selector" with "compound selector"
 where appropriate.

---
 packages/shadydom/src/patches/ParentNode.js | 24 ++++++++++-----------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index d974203b1..93b752458 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -174,11 +174,11 @@ const logicalQuerySelectorList = (contextElement, selectorList) => {
  */
 const logicalQuerySingleSelector = (contextElement, complexSelector) => {
   const {
-    'selectors': simpleSelectors,
+    'selectors': compoundSelectors,
     'joiners': combinators,
   } = splitSelectorBlocks(complexSelector);
 
-  if (simpleSelectors.length < 1) {
+  if (compoundSelectors.length < 1) {
     return [];
   }
 
@@ -193,26 +193,26 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
     (node) => {
       return utils.matchesSelector(
         node,
-        simpleSelectors[simpleSelectors.length - 1]
+        compoundSelectors[compoundSelectors.length - 1]
       );
     }
   ).map((element) => ({position: element, target: element}));
 
   /**
    * @param {!Element} element
-   * @param {string} simpleSelector
+   * @param {string} compoundSelector
    * @return {boolean}
    */
-  const matchesSimpleSelector = (element, simpleSelector) => {
+  const matchesCompoundSelector = (element, compoundSelector) => {
     return (
-      utils.matchesSelector(element, simpleSelector) &&
-      (simpleSelector.indexOf(':scope') === -1 || element === contextElement)
+      utils.matchesSelector(element, compoundSelector) &&
+      (compoundSelector.indexOf(':scope') === -1 || element === contextElement)
     );
   };
 
   for (let i = combinators.length - 1; i >= 0; i--) {
     const combinator = combinators[i];
-    const simpleSelector = simpleSelectors[i];
+    const compoundSelector = compoundSelectors[i];
 
     if (combinator === ' ') {
       // Descendant combinator
@@ -225,7 +225,7 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
             ancestor && ancestor instanceof Element;
             ancestor = ancestor[utils.SHADY_PREFIX + 'parentNode']
           ) {
-            if (matchesSimpleSelector(ancestor, simpleSelector)) {
+            if (matchesCompoundSelector(ancestor, compoundSelector)) {
               results.push({position: ancestor, target: cursor.target});
             }
           }
@@ -242,7 +242,7 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
           if (
             parent &&
             parent instanceof Element &&
-            matchesSimpleSelector(parent, simpleSelector)
+            matchesCompoundSelector(parent, compoundSelector)
           ) {
             return [{position: parent, target: cursor.target}];
           }
@@ -257,7 +257,7 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
           const sibling =
             cursor.position[utils.SHADY_PREFIX + 'previousElementSibling'];
 
-          if (sibling && matchesSimpleSelector(sibling, simpleSelector)) {
+          if (sibling && matchesCompoundSelector(sibling, compoundSelector)) {
             return [{position: sibling, target: cursor.target}];
           }
 
@@ -276,7 +276,7 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
             sibling;
             sibling = sibling[utils.SHADY_PREFIX + 'previousElementSibling']
           ) {
-            if (matchesSimpleSelector(sibling, simpleSelector)) {
+            if (matchesCompoundSelector(sibling, compoundSelector)) {
               results.push({position: sibling, target: cursor.target});
             }
           }

From 8f1ebdaa2d9f3f7411fad2a254fa59d131f1e62f Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Tue, 2 Aug 2022 17:38:00 -0700
Subject: [PATCH 18/76] Add documentation.

---
 packages/shadydom/src/patches/ParentNode.js   |  58 +++++++-
 .../src/patches/logicalQuerySingleSelector.md | 132 ++++++++++++++++++
 packages/shadydom/src/utils.js                |   4 +
 3 files changed, 192 insertions(+), 2 deletions(-)
 create mode 100644 packages/shadydom/src/patches/logicalQuerySingleSelector.md

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index 93b752458..bb7872f21 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -132,6 +132,8 @@ export const ParentNodePatches = utils.getOwnPropertyDescriptors({
 });
 
 /**
+ * Deduplicates items in an array.
+ *
  * @param {!Array<T>} array
  * @return {!Array<T>}
  * @template T
@@ -139,6 +141,9 @@ export const ParentNodePatches = utils.getOwnPropertyDescriptors({
 const deduplicateArray = (array) => Array.from(new Set(array));
 
 /**
+ * Deduplicates an array of elements and removes any that are not exclusive
+ * descendants of `ancestor`.
+ *
  * @param {!Element} ancestor
  * @param {!Array<!Element>} elements
  * @return {!Array<!Element>}
@@ -152,6 +157,9 @@ const deduplicateAndFilterToDescendants = (ancestor, elements) => {
 };
 
 /**
+ * Performs the equivalent of `querySelectorAll` within Shady DOM's logical
+ * model of the tree for a selector list.
+ *
  * @param {!Element} contextElement
  * @param {string} selectorList
  * @return {!Array<!Element>}
@@ -168,6 +176,11 @@ const logicalQuerySelectorList = (contextElement, selectorList) => {
 };
 
 /**
+ * Performs the equivalent of `querySelectorAll` within Shady DOM's logical
+ * model of the tree for a single complex selector.
+ *
+ * See <./logicalQuerySingleSelector.md> for implementation details.
+ *
  * @param {!Element} contextElement
  * @param {string} complexSelector
  * @return {!Array<!Element>}
@@ -183,10 +196,31 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
   }
 
   /**
-   * @type {!Array<!{
+   * An object used to track the current position of a potential selector match.
+   *
+   * - `position` is the element that matches the compound selector last reached
+   * by the selector engine.
+   *
+   * - `target` is the element that matches the selector if the cursor
+   * eventually results in a complete match.
+   *
+   * @typedef {{
    *   position: !Element,
    *   target: !Element,
-   * }>}
+   * }}
+   */
+  let SelectorMatchingCursor;
+
+  /**
+   * The list of selector matching cursors, initialized to point at all
+   * descendants of `contextElement`'s root node that match the last compound
+   * selector in `complexSelector`.
+   *
+   * For example, if `complexSelector` is `a > b + c`, then this list is
+   * initialized to all descendants of `contextElement.getRootNode()` that match
+   * the compound selector `c`.
+   *
+   * @type {!Array<!SelectorMatchingCursor>}
    */
   let cursors = query(
     contextElement[utils.SHADY_PREFIX + 'getRootNode'](),
@@ -199,6 +233,10 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
   ).map((element) => ({position: element, target: element}));
 
   /**
+   * Determines if a single compound selector matches an element. If the
+   * selector contains `:scope` (as a substring), then `element` must be
+   * `contextElement`.
+   *
    * @param {!Element} element
    * @param {string} compoundSelector
    * @return {boolean}
@@ -210,6 +248,8 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
     );
   };
 
+  // Iterate backwards through the remaining combinators and compound selectors,
+  // updating the cursors at each step.
   for (let i = combinators.length - 1; i >= 0; i--) {
     const combinator = combinators[i];
     const compoundSelector = compoundSelectors[i];
@@ -220,6 +260,9 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
         cursors.map((cursor) => {
           const results = [];
 
+          // For `a b`, where existing cursors have `position`s matching `b`,
+          // the candidates to test against `a` are all ancestors each cursor's
+          // `position`.
           for (
             let ancestor = cursor.position[utils.SHADY_PREFIX + 'parentNode'];
             ancestor && ancestor instanceof Element;
@@ -239,6 +282,9 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
         cursors.map((cursor) => {
           const parent = cursor.position[utils.SHADY_PREFIX + 'parentNode'];
 
+          // For `a > b`, where existing cursors have `position`s matching `b`,
+          // the candidates to test against `a` are the parents of each cursor's
+          // `position`.
           if (
             parent &&
             parent instanceof Element &&
@@ -257,6 +303,9 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
           const sibling =
             cursor.position[utils.SHADY_PREFIX + 'previousElementSibling'];
 
+          // For `a + b`, where existing cursors have `position`s matching `b`,
+          // the candidates to test against `a` are the immediately preceding
+          // siblings of each cursor's `position`.
           if (sibling && matchesCompoundSelector(sibling, compoundSelector)) {
             return [{position: sibling, target: cursor.target}];
           }
@@ -270,6 +319,9 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
         cursors.map((cursor) => {
           const results = [];
 
+          // For `a ~ b`, where existing cursors have `position`s matching `b`,
+          // the candidates to test against `a` are all preceding siblings of
+          // each cursor's `position`.
           for (
             let sibling =
               cursor.position[utils.SHADY_PREFIX + 'previousElementSibling'];
@@ -285,6 +337,8 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
         })
       );
     } else {
+      // As of writing, there are no other combinators:
+      // <https://drafts.csswg.org/selectors/#combinators>
       throw new Error(`Unrecognized combinator: '${combinator}'.`);
     }
   }
diff --git a/packages/shadydom/src/patches/logicalQuerySingleSelector.md b/packages/shadydom/src/patches/logicalQuerySingleSelector.md
new file mode 100644
index 000000000..30d51e8c9
--- /dev/null
+++ b/packages/shadydom/src/patches/logicalQuerySingleSelector.md
@@ -0,0 +1,132 @@
+`logicalQuerySingleSelector` emulates `querySelectorAll` for a single complex
+selector within Shady DOM's logical tree by implementing the tree-traversal
+portion of a selector engine. It does so by (a) finding all elements in the root
+that match the final compound selector to create the initial set of 'cursors';
+(b) iterating backwards through the combinators and remaining compound
+selectors, checking if the candidates implied by each combinator for each
+cursor's `position` element would match the compound selector preceding them and
+updating the cursors accordingly; and (c) deduplicating the set of `target`
+elements of all remaining cursors and filtering out any that aren't exclusive
+descendants of the context element.
+
+For example, consider querying for `a > b ~ c` within this tree:
+
+```html
+<a>
+  <b></b>
+  <x></x>
+  <c id="c_1"></c>
+  <d>
+    <x></x>
+    <b></b>
+    <c id="c_2"></c>
+  </d>
+</a>
+```
+
+First, all elements in the root are tested against the final compound selector
+(`c`) to create the initial set of cursors:
+
+```html
+<a>
+  <b></b>
+  <x></x>
+  <c id="c_1"></c>
+  <!-- cursor 1: target=#c_1 -->
+  <d>
+    <x></x>
+    <b></b>
+    <c id="c_2"></c>
+    <!-- cursor 2: target=#c_2 -->
+  </d>
+</a>
+```
+
+Next, the combinators and the remaining compound selectors are iterated
+backwards. Each combinator determines the set of candidate elements that must be
+tested against the preceding compound selector.
+
+Moving backwards, the next combinator and compound selector in `a > b ~ c` are
+`~` and `b`, so the next set of candidate elements are the preceding siblings of
+the current cursors' `position` elements:
+
+```html
+<a>
+  <b></b>
+  <!-- candidate for cursor 1 -->
+  <x></x>
+  <!-- candidate for cursor 1 -->
+  <c id="c_1"></c>
+  <!-- cursor 1: target=#c_1 -->
+  <d>
+    <x></x>
+    <!-- candidate for cursor 2 -->
+    <b></b>
+    <!-- candidate for cursor 2 -->
+    <c id="c_2"></c>
+    <!-- cursor 2: target=#c_2 -->
+  </d>
+</a>
+```
+
+These candidates are filtered to those that match `b` and these matching
+elements become the `position`s of the new set of cursors, with their `target`
+set to the same `target` as the cursor for which they were previously a
+candidate:
+
+```html
+<a>
+  <b></b>
+  <!-- cursor 3: target=#c_1 -->
+  <x></x>
+  <c id="c_1"></c>
+  <d>
+    <x></x>
+    <b></b>
+    <!-- cursor 4: target=#c_2 -->
+    <c id="c_2"></c>
+  </d>
+</a>
+```
+
+The process repeats again for the next combinator and compound selector: `>` and
+`a`. First, the combinator (`>`) determines the candidates:
+
+```html
+<a>
+  <!-- candidate for cursor 3 -->
+  <b></b>
+  <!-- cursor 3: target=#c_1 -->
+  <x></x>
+  <c id="c_1"></c>
+  <d>
+    <!-- candidate for cursor 4 -->
+    <x></x>
+    <b></b>
+    <!-- cursor 4: target=#c_2 -->
+    <c id="c_2"></c>
+  </d>
+</a>
+```
+
+Then, the candidates are filtered by matching against the compound selector
+(`a`), which determines the new cursors:
+
+```html
+<a>
+  <!-- cursor 5: target=#c_1 -->
+  <b></b>
+  <x></x>
+  <c id="c_1"></c>
+  <d>
+    <x></x>
+    <b></b>
+    <c id="c_2"></c>
+  </d>
+</a>
+```
+
+Once all combinators and compound selectors have been iterated, the remaining
+cursors' `target` elements are known to match the given selector. These elements
+are then deduplicated and filtered to remove any that are not exclusive
+descendants of the context element.
diff --git a/packages/shadydom/src/utils.js b/packages/shadydom/src/utils.js
index 9558701cb..55d4b94d4 100644
--- a/packages/shadydom/src/utils.js
+++ b/packages/shadydom/src/utils.js
@@ -293,6 +293,10 @@ export const convertNodesIntoANode = (...args) => {
 };
 
 /**
+ * Equivalent to `Array.prototype.flat`. Closure does not compile out this
+ * function, so we need an implementation for browsers that don't natively
+ * support it.
+ *
  * @template T
  * @param {!Array<!T | !Array<!T>>} array
  * @param {number} depth

From 5b9a11f69a948ba0142c62308cfd80eb73ff6762 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Tue, 2 Aug 2022 17:43:35 -0700
Subject: [PATCH 19/76] Prevent the formatter from breaking the
 `logicalQuerySingleSelector` doc examples. (...)

The formatter wants to format HTML snippets, but it keeps putting the comments
in the examples on their own line, which makes it harder to tell what element
they're referring to. To avoid this, I've stopped marking these snippets as
HTML.
---
 .../src/patches/logicalQuerySingleSelector.md | 57 +++++++------------
 1 file changed, 21 insertions(+), 36 deletions(-)

diff --git a/packages/shadydom/src/patches/logicalQuerySingleSelector.md b/packages/shadydom/src/patches/logicalQuerySingleSelector.md
index 30d51e8c9..3cbf7ed98 100644
--- a/packages/shadydom/src/patches/logicalQuerySingleSelector.md
+++ b/packages/shadydom/src/patches/logicalQuerySingleSelector.md
@@ -11,7 +11,7 @@ descendants of the context element.
 
 For example, consider querying for `a > b ~ c` within this tree:
 
-```html
+```
 <a>
   <b></b>
   <x></x>
@@ -27,17 +27,15 @@ For example, consider querying for `a > b ~ c` within this tree:
 First, all elements in the root are tested against the final compound selector
 (`c`) to create the initial set of cursors:
 
-```html
+```
 <a>
   <b></b>
   <x></x>
-  <c id="c_1"></c>
-  <!-- cursor 1: target=#c_1 -->
+  <c id="c_1"></c> <!-- cursor 1: target=#c_1 -->
   <d>
     <x></x>
     <b></b>
-    <c id="c_2"></c>
-    <!-- cursor 2: target=#c_2 -->
+    <c id="c_2"></c> <!-- cursor 2: target=#c_2 -->
   </d>
 </a>
 ```
@@ -50,21 +48,15 @@ Moving backwards, the next combinator and compound selector in `a > b ~ c` are
 `~` and `b`, so the next set of candidate elements are the preceding siblings of
 the current cursors' `position` elements:
 
-```html
+```
 <a>
-  <b></b>
-  <!-- candidate for cursor 1 -->
-  <x></x>
-  <!-- candidate for cursor 1 -->
-  <c id="c_1"></c>
-  <!-- cursor 1: target=#c_1 -->
+  <b></b> <!-- candidate for cursor 1 -->
+  <x></x> <!-- candidate for cursor 1 -->
+  <c id="c_1"></c> <!-- cursor 1: target=#c_1 -->
   <d>
-    <x></x>
-    <!-- candidate for cursor 2 -->
-    <b></b>
-    <!-- candidate for cursor 2 -->
-    <c id="c_2"></c>
-    <!-- cursor 2: target=#c_2 -->
+    <x></x> <!-- candidate for cursor 2 -->
+    <b></b> <!-- candidate for cursor 2 -->
+    <c id="c_2"></c> <!-- cursor 2: target=#c_2 -->
   </d>
 </a>
 ```
@@ -74,16 +66,14 @@ elements become the `position`s of the new set of cursors, with their `target`
 set to the same `target` as the cursor for which they were previously a
 candidate:
 
-```html
+```
 <a>
-  <b></b>
-  <!-- cursor 3: target=#c_1 -->
+  <b></b> <!-- cursor 3: target=#c_1 -->
   <x></x>
   <c id="c_1"></c>
   <d>
     <x></x>
-    <b></b>
-    <!-- cursor 4: target=#c_2 -->
+    <b></b> <!-- cursor 4: target=#c_2 -->
     <c id="c_2"></c>
   </d>
 </a>
@@ -92,18 +82,14 @@ candidate:
 The process repeats again for the next combinator and compound selector: `>` and
 `a`. First, the combinator (`>`) determines the candidates:
 
-```html
-<a>
-  <!-- candidate for cursor 3 -->
-  <b></b>
-  <!-- cursor 3: target=#c_1 -->
+```
+<a> <!-- candidate for cursor 3 -->
+  <b></b> <!-- cursor 3: target=#c_1 -->
   <x></x>
   <c id="c_1"></c>
-  <d>
-    <!-- candidate for cursor 4 -->
+  <d> <!-- candidate for cursor 4 -->
     <x></x>
-    <b></b>
-    <!-- cursor 4: target=#c_2 -->
+    <b></b> <!-- cursor 4: target=#c_2 -->
     <c id="c_2"></c>
   </d>
 </a>
@@ -112,9 +98,8 @@ The process repeats again for the next combinator and compound selector: `>` and
 Then, the candidates are filtered by matching against the compound selector
 (`a`), which determines the new cursors:
 
-```html
-<a>
-  <!-- cursor 5: target=#c_1 -->
+```
+<a> <!-- cursor 5: target=#c_1 -->
   <b></b>
   <x></x>
   <c id="c_1"></c>

From 603e00fcd13895225bf13fc7bed19c4fa86ce22f Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 3 Aug 2022 17:07:34 -0700
Subject: [PATCH 20/76] Match all selectors in a selector list simultaneously.

---
 packages/shadydom/src/patches/ParentNode.js   | 280 +++++++++---------
 .../src/patches/logicalQuerySelectorAll.md    | 204 +++++++++++++
 .../src/patches/logicalQuerySingleSelector.md | 117 --------
 3 files changed, 352 insertions(+), 249 deletions(-)
 create mode 100644 packages/shadydom/src/patches/logicalQuerySelectorAll.md
 delete mode 100644 packages/shadydom/src/patches/logicalQuerySingleSelector.md

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index bb7872f21..1e29de201 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -131,106 +131,48 @@ export const ParentNodePatches = utils.getOwnPropertyDescriptors({
   },
 });
 
-/**
- * Deduplicates items in an array.
- *
- * @param {!Array<T>} array
- * @return {!Array<T>}
- * @template T
- */
-const deduplicateArray = (array) => Array.from(new Set(array));
-
-/**
- * Deduplicates an array of elements and removes any that are not exclusive
- * descendants of `ancestor`.
- *
- * @param {!Element} ancestor
- * @param {!Array<!Element>} elements
- * @return {!Array<!Element>}
- */
-const deduplicateAndFilterToDescendants = (ancestor, elements) => {
-  return deduplicateArray(elements).filter((element) => {
-    return (
-      element !== ancestor && ancestor[utils.SHADY_PREFIX + 'contains'](element)
-    );
-  });
-};
-
 /**
  * Performs the equivalent of `querySelectorAll` within Shady DOM's logical
  * model of the tree for a selector list.
  *
- * @param {!Element} contextElement
- * @param {string} selectorList
- * @return {!Array<!Element>}
- */
-const logicalQuerySelectorList = (contextElement, selectorList) => {
-  return deduplicateAndFilterToDescendants(
-    contextElement,
-    utils.flat(
-      extractSelectors(selectorList).map((selector) => {
-        return logicalQuerySingleSelector(contextElement, selector);
-      })
-    )
-  );
-};
-
-/**
- * Performs the equivalent of `querySelectorAll` within Shady DOM's logical
- * model of the tree for a single complex selector.
- *
- * See <./logicalQuerySingleSelector.md> for implementation details.
+ * See <./logicalQuerySelectorAll.md> for implementation details.
  *
  * @param {!Element} contextElement
- * @param {string} complexSelector
+ * @param {string} selectorList
  * @return {!Array<!Element>}
  */
-const logicalQuerySingleSelector = (contextElement, complexSelector) => {
-  const {
-    'selectors': compoundSelectors,
-    'joiners': combinators,
-  } = splitSelectorBlocks(complexSelector);
-
-  if (compoundSelectors.length < 1) {
-    return [];
-  }
-
+const logicalQuerySelectorAll = (contextElement, selectorList) => {
   /**
-   * An object used to track the current position of a potential selector match.
-   *
-   * - `position` is the element that matches the compound selector last reached
-   * by the selector engine.
-   *
-   * - `target` is the element that matches the selector if the cursor
-   * eventually results in a complete match.
+   * A key-renamed version of the return value of `extractSelectors`, which
+   * describes a single complex selector.
    *
    * @typedef {{
-   *   position: !Element,
-   *   target: !Element,
+   *   compoundSelectors: !Array<string>,
+   *   combinators: !Array<string>,
    * }}
    */
-  let SelectorMatchingCursor;
+  let ComplexSelectorParts;
 
   /**
-   * The list of selector matching cursors, initialized to point at all
-   * descendants of `contextElement`'s root node that match the last compound
-   * selector in `complexSelector`.
-   *
-   * For example, if `complexSelector` is `a > b + c`, then this list is
-   * initialized to all descendants of `contextElement.getRootNode()` that match
-   * the compound selector `c`.
-   *
-   * @type {!Array<!SelectorMatchingCursor>}
+   * @type {!Array<!ComplexSelectorParts>}
    */
-  let cursors = query(
-    contextElement[utils.SHADY_PREFIX + 'getRootNode'](),
-    (node) => {
-      return utils.matchesSelector(
-        node,
-        compoundSelectors[compoundSelectors.length - 1]
-      );
-    }
-  ).map((element) => ({position: element, target: element}));
+  const complexSelectors = extractSelectors(selectorList)
+    .map((complexSelector) => {
+      const {
+        'selectors': compoundSelectors,
+        'joiners': combinators,
+      } = splitSelectorBlocks(complexSelector);
+
+      return {
+        compoundSelectors,
+        combinators,
+      };
+    })
+    .filter(({compoundSelectors}) => compoundSelectors.length > 0);
+
+  if (complexSelectors.length < 1) {
+    return [];
+  }
 
   /**
    * Determines if a single compound selector matches an element. If the
@@ -248,39 +190,106 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
     );
   };
 
-  // Iterate backwards through the remaining combinators and compound selectors,
-  // updating the cursors at each step.
-  for (let i = combinators.length - 1; i >= 0; i--) {
-    const combinator = combinators[i];
-    const compoundSelector = compoundSelectors[i];
+  /**
+   * An object used to track the current position of a potential selector match.
+   *
+   * - `target` is the element that matches the selector if the cursor
+   * eventually results in a complete match.
+   *
+   * - `complexSelectorParts` is the decomposed version of the selector that
+   * this cursor is attempting to match.
+   *
+   * - `position` is an element that matches a compound selector in
+   * `complexSelectorParts`.
+   *
+   * - `index` is the index of the compound selector in `complexSelectorParts`
+   * that matched `position`.
+   *
+   * @typedef {{
+   *   target: !Element,
+   *   complexSelectorParts: !ComplexSelectorParts,
+   *   position: !Element,
+   *   index: number,
+   * }}
+   */
+  let SelectorMatchingCursor;
+
+  /**
+   * The list of `SelectorMatchingCursor`s, initialized with cursors pointing at
+   * all descendants of `contextElement` that match the last compound selector
+   * in any complex selector in `selectorList`.
+   *
+   * @type {!Array<!SelectorMatchingCursor>}
+   */
+  let cursors = utils.flat(
+    query(contextElement, (_element) => true).map((element) => {
+      return utils.flat(
+        complexSelectors.map((complexSelectorParts) => {
+          const {compoundSelectors} = complexSelectorParts;
+          const index = compoundSelectors.length - 1;
+          if (matchesCompoundSelector(element, compoundSelectors[index])) {
+            return [
+              {
+                target: element,
+                complexSelectorParts,
+                position: element,
+                index,
+              },
+            ];
+          } else {
+            return [];
+          }
+        })
+      );
+    })
+  );
 
-    if (combinator === ' ') {
-      // Descendant combinator
-      cursors = utils.flat(
-        cursors.map((cursor) => {
+  // At each step, any remaining cursors that have not finished matching (i.e.
+  // with `cursor.index > 0`) should be replaced with new cursors for any valid
+  // candidates that match the next compound selector.
+  while (cursors.length > 0 && cursors.some((cursor) => cursor.index > 0)) {
+    cursors = utils.flat(
+      cursors.map((cursor) => {
+        // Cursors with `index` of 0 have already matched and should not be
+        // replaced or removed.
+        if (cursor.index <= 0) {
+          return cursor;
+        }
+
+        const {
+          target,
+          position,
+          complexSelectorParts,
+          index: lastIndex,
+        } = cursor;
+        const index = lastIndex - 1;
+        const combinator = complexSelectorParts.combinators[index];
+        const compoundSelector = complexSelectorParts.compoundSelectors[index];
+
+        if (combinator === ' ') {
           const results = [];
 
           // For `a b`, where existing cursors have `position`s matching `b`,
           // the candidates to test against `a` are all ancestors each cursor's
           // `position`.
           for (
-            let ancestor = cursor.position[utils.SHADY_PREFIX + 'parentNode'];
+            let ancestor = position[utils.SHADY_PREFIX + 'parentNode'];
             ancestor && ancestor instanceof Element;
             ancestor = ancestor[utils.SHADY_PREFIX + 'parentNode']
           ) {
             if (matchesCompoundSelector(ancestor, compoundSelector)) {
-              results.push({position: ancestor, target: cursor.target});
+              results.push({
+                target,
+                complexSelectorParts,
+                position: ancestor,
+                index,
+              });
             }
           }
 
           return results;
-        })
-      );
-    } else if (combinator === '>') {
-      // Child combinator
-      cursors = utils.flat(
-        cursors.map((cursor) => {
-          const parent = cursor.position[utils.SHADY_PREFIX + 'parentNode'];
+        } else if (combinator === '>') {
+          const parent = position[utils.SHADY_PREFIX + 'parentNode'];
 
           // For `a > b`, where existing cursors have `position`s matching `b`,
           // the candidates to test against `a` are the parents of each cursor's
@@ -290,33 +299,37 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
             parent instanceof Element &&
             matchesCompoundSelector(parent, compoundSelector)
           ) {
-            return [{position: parent, target: cursor.target}];
+            return [
+              {
+                target,
+                complexSelectorParts,
+                position: parent,
+                index,
+              },
+            ];
           }
 
           return [];
-        })
-      );
-    } else if (combinator === '+') {
-      // Next-sibling combinator
-      cursors = utils.flat(
-        cursors.map((cursor) => {
+        } else if (combinator === '+') {
           const sibling =
-            cursor.position[utils.SHADY_PREFIX + 'previousElementSibling'];
+            position[utils.SHADY_PREFIX + 'previousElementSibling'];
 
           // For `a + b`, where existing cursors have `position`s matching `b`,
           // the candidates to test against `a` are the immediately preceding
           // siblings of each cursor's `position`.
           if (sibling && matchesCompoundSelector(sibling, compoundSelector)) {
-            return [{position: sibling, target: cursor.target}];
+            return [
+              {
+                target,
+                complexSelectorParts,
+                position: sibling,
+                index,
+              },
+            ];
           }
 
           return [];
-        })
-      );
-    } else if (combinator === '~') {
-      // Subsequent-sibling combinator
-      cursors = utils.flat(
-        cursors.map((cursor) => {
+        } else if (combinator === '~') {
           const results = [];
 
           // For `a ~ b`, where existing cursors have `position`s matching `b`,
@@ -324,29 +337,32 @@ const logicalQuerySingleSelector = (contextElement, complexSelector) => {
           // each cursor's `position`.
           for (
             let sibling =
-              cursor.position[utils.SHADY_PREFIX + 'previousElementSibling'];
+              position[utils.SHADY_PREFIX + 'previousElementSibling'];
             sibling;
             sibling = sibling[utils.SHADY_PREFIX + 'previousElementSibling']
           ) {
             if (matchesCompoundSelector(sibling, compoundSelector)) {
-              results.push({position: sibling, target: cursor.target});
+              results.push({
+                target,
+                complexSelectorParts,
+                position: sibling,
+                index,
+              });
             }
           }
 
           return results;
-        })
-      );
-    } else {
-      // As of writing, there are no other combinators:
-      // <https://drafts.csswg.org/selectors/#combinators>
-      throw new Error(`Unrecognized combinator: '${combinator}'.`);
-    }
+        } else {
+          // As of writing, there are no other combinators:
+          // <https://drafts.csswg.org/selectors/#combinators>
+          throw new Error(`Unrecognized combinator: '${combinator}'.`);
+        }
+      })
+    );
   }
 
-  return deduplicateAndFilterToDescendants(
-    contextElement,
-    cursors.map((cursor) => cursor.target)
-  );
+  // Map remaining cursors to their `target` and deduplicate.
+  return Array.from(new Set(cursors.map(({target}) => target)));
 };
 
 export const QueryPatches = utils.getOwnPropertyDescriptors({
@@ -356,7 +372,7 @@ export const QueryPatches = utils.getOwnPropertyDescriptors({
    * @param  {string} selector
    */
   querySelector(selector) {
-    return logicalQuerySelectorList(this, selector)[0] || null;
+    return logicalQuerySelectorAll(this, selector)[0] || null;
   },
 
   /**
@@ -378,7 +394,7 @@ export const QueryPatches = utils.getOwnPropertyDescriptors({
       );
     }
     return utils.createPolyfilledHTMLCollection(
-      logicalQuerySelectorList(this, selector)
+      logicalQuerySelectorAll(this, selector)
     );
   },
 });
diff --git a/packages/shadydom/src/patches/logicalQuerySelectorAll.md b/packages/shadydom/src/patches/logicalQuerySelectorAll.md
new file mode 100644
index 000000000..518649489
--- /dev/null
+++ b/packages/shadydom/src/patches/logicalQuerySelectorAll.md
@@ -0,0 +1,204 @@
+`logicalQuerySelectorAll` emulates `querySelectorAll` within Shady DOM's logical
+tree by implementing the tree-traversal portion of a selector engine.
+
+Consider querying for `a > b ~ c, d e` within this tree:
+
+```
+<a>
+  <b></b>
+  <x></x>
+  <c id="c_1"></c>
+  <d>
+    <x>
+      <e id="e_1"></e>
+    </x>
+    <b></b>
+    <c id="c_2"></c>
+  </d>
+  <e id="e_2"></e>
+</a>
+```
+
+First, the given selector list is split into complex selectors, which are each
+split into compound selectors and combinators:
+
+`'a > b ~ c, d e'` &rarr; `['a > b ~ c', 'd e']` &rarr;
+
+```
+[{
+  compoundSelectors: ['a', 'b', 'c'],
+  combinators: ['>', '~'],
+}, {
+  compoundSelectors: ['d', 'e'],
+  combinators: [' '],
+}]
+```
+
+Next, all exclusive descendants of the context element are tested against the
+final compound selectors in each complex selector - in this example, `c` and
+`e`. Any matches create an initial 'cursor', which tracks the progress of a
+potential match. Cursors consist of a handful of properties:
+
+- `target`: the element that would be considered matching if the cursor
+  eventually results in a complete match
+
+- `complexSelectorParts`: the split complex selector which the cursor is
+  attempting to match
+
+- `index`: the index into `.complexSelectorParts.compoundSelectors` of the last
+  successfully matched compound selector
+
+- `position`: the element which successfully matched the compound selector at
+  `index`
+
+This initial walk through the descendants of the context element results in an
+initial list of cursors with `target`s which are in _document order_.
+
+(The cursor 'properties' shown below are written in shorthand for compactness.)
+
+```
+cursors = [
+  {target: #c_1, selector: 'a > b ~ c', index: 2, position: ...},
+  {target: #e_1, selector: 'd e', index: 1, position: ...},
+  {target: #c_2, selector: 'a > b ~ c', index: 2, position: ...},
+  {target: #e_2, selector: 'd e', index: 1, position: ...},
+]
+```
+
+```
+<a>
+  <b></b>
+  <x></x>
+  <c id="c_1"></c> <!-- cursors[0].position -->
+  <d>
+    <x>
+      <e id="e_1"></e> <!-- cursors[1].position -->
+    </x>
+    <b></b>
+    <c id="c_2"></c> <!-- cursors[2].position -->
+  </d>
+  <e id="e_2"></e> <!-- cursors[3].position -->
+</a>
+```
+
+Next, the `position` and next combinator (iterating backwards) of each cursor
+with `.index > 0` ('source' cursors) are used to determine the candidate
+elements to test against that cursor's next compound selector.
+
+```
+cursors = [
+  {target: #c_1, selector: 'a > b ~ c', index: 2, position: ...},
+  {target: #e_1, selector: 'd e', index: 1, position: ...},
+  {target: #c_2, selector: 'a > b ~ c', index: 2, position: ...},
+  {target: #e_2, selector: 'd e', index: 1, position: ...},
+]
+```
+
+```
+<a> <!-- candidate: cursors[1], cursors[3] -->
+  <b></b> <!-- candidate: cursors[0] -->
+  <x></x> <!-- candidate: cursors[0] -->
+  <c id="c_1"></c>
+  <d> <!-- candidate: cursors[1] -->
+    <x> <!-- candidate: cursors[1], cursors[2] -->
+      <e id="e_1"></e>
+    </x>
+    <b></b> <!-- candidate: cursors[2] -->
+    <c id="c_2"></c>
+  </d>
+  <e id="e_2"></e>
+</a>
+```
+
+Candidates that do not match the next compound selector in the source cursor's
+complex selector are filtered out. Those that do match result in a new cursor
+being created with `position` set to the matching element and `index`
+decremented by one, but with the same `target`, `complexSelectorParts` as the
+source cursor. Then, source cursors are each replaced by any new cursors created
+by their matching candidates. Specifically, all new cursors must maintain the
+relative order of their source cursors so that their `target`s remain in
+_document order_. Source cursors that had `.index === 0` remain in their
+position in the list unchanged.
+
+```
+cursors = [
+  {target: #c_1, selector: 'a > b ~ c', index: 1, position: ...},
+  {target: #e_1, selector: 'd e', index: 0, position: ...},
+  {target: #c_2, selector: 'a > b ~ c', index: 1, position: ...},
+]
+```
+
+```
+<a>
+  <b></b> <!-- cursors[0].position -->
+  <x></x>
+  <c id="c_1"></c>
+  <d> <!-- cursors[1].position -->
+    <x>
+      <e id="e_1"></e>
+    </x>
+    <b></b> <!-- cursors[2].position -->
+    <c id="c_2"></c>
+  </d>
+  <e id="e_2"></e>
+</a>
+```
+
+This process repeats until all (potentially zero) remaining cursors have `.index === 0`.
+
+Again, candidates for cursors with `.index > 0` are selected.
+
+```
+cursors = [
+  {target: #c_1, selector: 'a > b ~ c', index: 1, position: ...},
+  {target: #e_1, selector: 'd e', index: 0, position: ...},
+  {target: #c_2, selector: 'a > b ~ c', index: 1, position: ...},
+]
+```
+
+```
+<a> <!-- candidate: cursors[0] -->
+  <b></b>
+  <x></x>
+  <c id="c_1"></c>
+  <d> <!-- candidate: cursors[2] -->
+    <x>
+      <e id="e_1"></e>
+    </x>
+    <b></b>
+    <c id="c_2"></c>
+  </d>
+  <e id="e_2"></e>
+</a>
+```
+
+Again, the candidates are tested against their source cursors' next compound
+selector to produce new cursors that replace the source cursors.
+
+```
+cursors = [
+  {target: #c_1, selector: 'a > b ~ c', index: 0, position: ...},
+  {target: #e_1, selector: 'd e', index: 0, position: ...},
+]
+```
+
+```
+<a> <!-- cursors[0].position -->
+  <b></b>
+  <x></x>
+  <c id="c_1"></c>
+  <d> <!-- cursors[1].position -->
+    <x>
+      <e id="e_1"></e>
+    </x>
+    <b></b>
+    <c id="c_2"></c>
+  </d>
+  <e id="e_2"></e>
+</a>
+```
+
+Once all remaining cursors have `.index === 0`, their `target`s are the set of
+matching elements, in document order. This list is then deduplicated as a single
+`target` element may match a single complex selector in many ways and may match
+multiple complex selectors, which would result in multiple cursors.
diff --git a/packages/shadydom/src/patches/logicalQuerySingleSelector.md b/packages/shadydom/src/patches/logicalQuerySingleSelector.md
deleted file mode 100644
index 3cbf7ed98..000000000
--- a/packages/shadydom/src/patches/logicalQuerySingleSelector.md
+++ /dev/null
@@ -1,117 +0,0 @@
-`logicalQuerySingleSelector` emulates `querySelectorAll` for a single complex
-selector within Shady DOM's logical tree by implementing the tree-traversal
-portion of a selector engine. It does so by (a) finding all elements in the root
-that match the final compound selector to create the initial set of 'cursors';
-(b) iterating backwards through the combinators and remaining compound
-selectors, checking if the candidates implied by each combinator for each
-cursor's `position` element would match the compound selector preceding them and
-updating the cursors accordingly; and (c) deduplicating the set of `target`
-elements of all remaining cursors and filtering out any that aren't exclusive
-descendants of the context element.
-
-For example, consider querying for `a > b ~ c` within this tree:
-
-```
-<a>
-  <b></b>
-  <x></x>
-  <c id="c_1"></c>
-  <d>
-    <x></x>
-    <b></b>
-    <c id="c_2"></c>
-  </d>
-</a>
-```
-
-First, all elements in the root are tested against the final compound selector
-(`c`) to create the initial set of cursors:
-
-```
-<a>
-  <b></b>
-  <x></x>
-  <c id="c_1"></c> <!-- cursor 1: target=#c_1 -->
-  <d>
-    <x></x>
-    <b></b>
-    <c id="c_2"></c> <!-- cursor 2: target=#c_2 -->
-  </d>
-</a>
-```
-
-Next, the combinators and the remaining compound selectors are iterated
-backwards. Each combinator determines the set of candidate elements that must be
-tested against the preceding compound selector.
-
-Moving backwards, the next combinator and compound selector in `a > b ~ c` are
-`~` and `b`, so the next set of candidate elements are the preceding siblings of
-the current cursors' `position` elements:
-
-```
-<a>
-  <b></b> <!-- candidate for cursor 1 -->
-  <x></x> <!-- candidate for cursor 1 -->
-  <c id="c_1"></c> <!-- cursor 1: target=#c_1 -->
-  <d>
-    <x></x> <!-- candidate for cursor 2 -->
-    <b></b> <!-- candidate for cursor 2 -->
-    <c id="c_2"></c> <!-- cursor 2: target=#c_2 -->
-  </d>
-</a>
-```
-
-These candidates are filtered to those that match `b` and these matching
-elements become the `position`s of the new set of cursors, with their `target`
-set to the same `target` as the cursor for which they were previously a
-candidate:
-
-```
-<a>
-  <b></b> <!-- cursor 3: target=#c_1 -->
-  <x></x>
-  <c id="c_1"></c>
-  <d>
-    <x></x>
-    <b></b> <!-- cursor 4: target=#c_2 -->
-    <c id="c_2"></c>
-  </d>
-</a>
-```
-
-The process repeats again for the next combinator and compound selector: `>` and
-`a`. First, the combinator (`>`) determines the candidates:
-
-```
-<a> <!-- candidate for cursor 3 -->
-  <b></b> <!-- cursor 3: target=#c_1 -->
-  <x></x>
-  <c id="c_1"></c>
-  <d> <!-- candidate for cursor 4 -->
-    <x></x>
-    <b></b> <!-- cursor 4: target=#c_2 -->
-    <c id="c_2"></c>
-  </d>
-</a>
-```
-
-Then, the candidates are filtered by matching against the compound selector
-(`a`), which determines the new cursors:
-
-```
-<a> <!-- cursor 5: target=#c_1 -->
-  <b></b>
-  <x></x>
-  <c id="c_1"></c>
-  <d>
-    <x></x>
-    <b></b>
-    <c id="c_2"></c>
-  </d>
-</a>
-```
-
-Once all combinators and compound selectors have been iterated, the remaining
-cursors' `target` elements are known to match the given selector. These elements
-are then deduplicated and filtered to remove any that are not exclusive
-descendants of the context element.

From 0b5467a2a484a493fe86ff07bf716337deff73c6 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Mon, 8 Aug 2022 16:29:34 -0700
Subject: [PATCH 21/76] Avoid `Set` iterable constructor and `Array.from`
 during deduplication for IE 11 compatibility.

---
 packages/shadydom/src/patches/ParentNode.js |  2 +-
 packages/shadydom/src/utils.js              | 26 +++++++++++++++++++++
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index 1e29de201..b02cc4518 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -362,7 +362,7 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
   }
 
   // Map remaining cursors to their `target` and deduplicate.
-  return Array.from(new Set(cursors.map(({target}) => target)));
+  return utils.deduplicate(cursors.map(({target}) => target));
 };
 
 export const QueryPatches = utils.getOwnPropertyDescriptors({
diff --git a/packages/shadydom/src/utils.js b/packages/shadydom/src/utils.js
index 55d4b94d4..3eef44944 100644
--- a/packages/shadydom/src/utils.js
+++ b/packages/shadydom/src/utils.js
@@ -316,3 +316,29 @@ export const flat = (array, depth = 1) => {
 
   return array;
 };
+
+/**
+ * Deduplicates items in an array.
+ *
+ * This function could normally be implemented as merely `Array.from(new
+ * Set(...))`. However, in IE 11, `Set` does not support being constructed with
+ * an iterable. Further, some polyfills for `Array.from` effectively default to
+ * `Array.prototype.slice.call(...)` when they are unable to find
+ * `[Symbol.iterator]`; this is incompatible with `Set` which has no `length` or
+ * indexable properties.
+ *
+ * @template T
+ * @param {!Array<!T>} array
+ * @return {!Array<!T>}
+ */
+export const deduplicate = (array) => {
+  const results = [];
+  const set = new Set();
+  for (const item of array) {
+    if (!set.has(item)) {
+      results.push(item);
+      set.add(item);
+    }
+  }
+  return results;
+};

From 9fa797687d05f064341ccffe818c8fa004222543 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Mon, 8 Aug 2022 17:23:46 -0700
Subject: [PATCH 22/76] Add a new `querySelectorImplementation` setting.

---
 packages/shadydom/externs/shadydom.d.ts     |  1 +
 packages/shadydom/src/patches/ParentNode.js | 60 ++++++++++++++++++---
 2 files changed, 54 insertions(+), 7 deletions(-)

diff --git a/packages/shadydom/externs/shadydom.d.ts b/packages/shadydom/externs/shadydom.d.ts
index 4bc596888..a3a273115 100644
--- a/packages/shadydom/externs/shadydom.d.ts
+++ b/packages/shadydom/externs/shadydom.d.ts
@@ -22,6 +22,7 @@ declare global {
     };
     noPatch: boolean | string;
     patchElementProto: (node: Object) => void;
+    querySelectorImplementation?: 'native' | 'selectorEngine';
     wrap: (node: Node) => Node;
   }
 
diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index b02cc4518..07cf7692a 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -365,6 +365,9 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
   return utils.deduplicate(cursors.map(({target}) => target));
 };
 
+const querySelectorImplementation =
+  utils.settings['querySelectorImplementation'];
+
 export const QueryPatches = utils.getOwnPropertyDescriptors({
   // TODO(sorvell): consider doing native QSA and filtering results.
   /**
@@ -372,7 +375,36 @@ export const QueryPatches = utils.getOwnPropertyDescriptors({
    * @param  {string} selector
    */
   querySelector(selector) {
-    return logicalQuerySelectorAll(this, selector)[0] || null;
+    if (querySelectorImplementation === 'native') {
+      const candidates = Array.prototype.slice.call(
+        this[utils.NATIVE_PREFIX + 'querySelector'](selector)
+      );
+      const root = this[utils.SHADY_PREFIX + 'getRootNode']();
+      return utils.createPolyfilledHTMLCollection(
+        candidates.filter(
+          (e) => e[utils.SHADY_PREFIX + 'getRootNode']() == root
+        )
+      );
+    } else if (querySelectorImplementation === 'selectorEngine') {
+      return logicalQuerySelectorAll(this, selector)[0] || null;
+    } else if (querySelectorImplementation === undefined) {
+      // match selector and halt on first result.
+      let result = query(
+        this,
+        function (n) {
+          return utils.matchesSelector(n, selector);
+        },
+        function (n) {
+          return Boolean(n);
+        }
+      )[0];
+      return result || null;
+    } else {
+      throw new Error(
+        'Unrecognized value of ShadyDOM.querySelectorImplementation: ' +
+          `'${querySelectorImplementation}'`
+      );
+    }
   },
 
   /**
@@ -384,18 +416,32 @@ export const QueryPatches = utils.getOwnPropertyDescriptors({
   // misses distributed nodes, see
   // https://github.com/webcomponents/shadydom/pull/210#issuecomment-361435503
   querySelectorAll(selector, useNative) {
-    if (useNative) {
-      const o = Array.prototype.slice.call(
+    if (useNative || querySelectorImplementation === 'native') {
+      const candidates = Array.prototype.slice.call(
         this[utils.NATIVE_PREFIX + 'querySelectorAll'](selector)
       );
       const root = this[utils.SHADY_PREFIX + 'getRootNode']();
       return utils.createPolyfilledHTMLCollection(
-        o.filter((e) => e[utils.SHADY_PREFIX + 'getRootNode']() == root)
+        candidates.filter(
+          (e) => e[utils.SHADY_PREFIX + 'getRootNode']() == root
+        )
+      );
+    } else if (querySelectorImplementation === 'selectorEngine') {
+      return utils.createPolyfilledHTMLCollection(
+        logicalQuerySelectorAll(this, selector)
+      );
+    } else if (querySelectorImplementation === undefined) {
+      return utils.createPolyfilledHTMLCollection(
+        query(this, function (n) {
+          return utils.matchesSelector(n, selector);
+        })
+      );
+    } else {
+      throw new Error(
+        'Unrecognized value of ShadyDOM.querySelectorImplementation: ' +
+          `'${querySelectorImplementation}'`
       );
     }
-    return utils.createPolyfilledHTMLCollection(
-      logicalQuerySelectorAll(this, selector)
-    );
   },
 });
 

From f8706be6e4f57799f5178d8f967d243e7b5e19ea Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Mon, 8 Aug 2022 17:39:22 -0700
Subject: [PATCH 23/76] Run all Shady DOM tests with
 `querySelectorImplementation === 'selectorEngine'`.

---
 packages/tests/shadydom/loader.js   | 8 ++++++++
 packages/tests/shadydom/runner.html | 7 ++++++-
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/packages/tests/shadydom/loader.js b/packages/tests/shadydom/loader.js
index 6a03ef1b0..69c4cc363 100644
--- a/packages/tests/shadydom/loader.js
+++ b/packages/tests/shadydom/loader.js
@@ -6,6 +6,14 @@ ShadyDOM = {
   preferPerformance: !!window.location.search.match('preferPerformance'),
 };
 
+if (
+  window.location.search.match('querySelectorImplementation=selectorEngine')
+) {
+  ShadyDOM.querySelectorImplementation = 'selectorEngine';
+} else if (window.location.search.match('querySelectorImplementation=native')) {
+  ShadyDOM.querySelectorImplementation = 'native';
+}
+
 // TODO(sorvell): noPatching does not work with the custom elements polyfill.
 // IF the polyfill used `ShadyDOM.wrap` throughout, it could be made to work.
 if (window.customElements) {
diff --git a/packages/tests/shadydom/runner.html b/packages/tests/shadydom/runner.html
index e60224af6..47f1177e5 100644
--- a/packages/tests/shadydom/runner.html
+++ b/packages/tests/shadydom/runner.html
@@ -74,7 +74,12 @@
     'filter-mutations.html',
     'native-access.html',
     'prefer-performance.html',
-  ];
+  ].reduce((acc, item) => {
+    acc.push(item);
+    const joiner = item.indexOf('?') !== -1 ? '&' : '?';
+    acc.push(item + joiner + 'querySelectorImplementation=selectorEngine');
+    return acc;
+  }, []);
 
   // test only under native custom elements.
   if (window.customElements) {

From 8feea2455b98fb88347b451a31308ed8f6380642 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 10 Aug 2022 15:00:36 -0700
Subject: [PATCH 24/76] Add docs for `querySelectorImplementation` and expose
 on the non-settings `ShadyDOM` global object.

---
 packages/shadydom/src/shadydom.js | 50 +++++++++++++++++++++++++++++++
 packages/shadydom/src/utils.js    |  8 +++++
 2 files changed, 58 insertions(+)

diff --git a/packages/shadydom/src/shadydom.js b/packages/shadydom/src/shadydom.js
index 8557ca55b..abffbef1c 100644
--- a/packages/shadydom/src/shadydom.js
+++ b/packages/shadydom/src/shadydom.js
@@ -118,6 +118,56 @@ if (utils.settings.inUse) {
     'nativeMethods': nativeMethods,
     'nativeTree': nativeTree,
     'patchElementProto': patchElementProto,
+    // Use this setting to choose the implementation of `querySelector` and
+    // `querySelectorAll`. The logical tree exposed by Shady DOM via the DOM
+    // APIs it wraps doesn't match the structure of the tree seen by the browser
+    // (the 'real tree'), so the level to which the browser itself is used to
+    // match selectors (which always happens against the real tree) affects the
+    // accuracy and performance of these wrappers.
+    //
+    // - `undefined` (default): Shady DOM will walk the logical descendants of
+    // the context element and call `matches` with the given selector to find
+    // matching elements.
+    //
+    //   This option is a balance between accuracy and performance. This option
+    //   will be able to match all logical descendants of the context element
+    //   (i.e. including descendants of unassigned nodes) but selectors are
+    //   matched against the real tree, so complex selectors may fail to match
+    //   since their combinators will attempt to match against the structure of
+    //   the real tree. Generally, you should only pass compound selectors when
+    //   using the default implementation. This implementation also breaks the
+    //   semantics of `:scope` because the wrapped `querySelector` call is
+    //   translated into many `matches` calls on different elements.
+    //
+    // - `'native'`: Shady DOM's wrapper for (e.g.) `querySelector` will call
+    // into the native `querySelector` function and then filter out results that
+    // are not in the same shadow root in the logical tree.
+    //
+    //   This is the fastest option. This option will not match elements that
+    //   are logical descendants of unassigned nodes because they will not be in
+    //   the real tree, against which the browser matches the selector. Like the
+    //   default option, this option may not correctly match complex selectors
+    //   (i.e. those with combinators) due to the structural differences between
+    //   the real tree and the logical tree. This option preserves the semantics
+    //   of `:scope` because the context element of the call to the wrapper is
+    //   also the context element of the call to the native function.
+    //
+    // - `'selectorEngine'`: Shady DOM's wrapper for (e.g.) `querySelector` will
+    // partially parse the given selector list and perform the tree-traversal
+    // steps of a selector engine against the logical tree.
+    //
+    //   This is the slowest and most accurate option. This option is able to
+    //   find all logical descendants of the context element by manually walking
+    //   the tree. This option is also able to correctly match complex selectors
+    //   because it does not rely on the browser to handle combinators. Despite
+    //   using `matches` to match compound selectors during selector evaluation,
+    //   this option preserves the semantics of `:scope` by only considering
+    //   compound selectors containing `:scope` to be matching if the context
+    //   element of the `matches` call is also the context element of the
+    //   wrapper call. (Note that this implementation detects `:scope` by simple
+    //   substring inclusion.)
+    'querySelectorImplementation':
+      utils.settings['querySelectorImplementation'],
   };
 
   window['ShadyDOM'] = ShadyDOM;
diff --git a/packages/shadydom/src/utils.js b/packages/shadydom/src/utils.js
index 3eef44944..bdb02022d 100644
--- a/packages/shadydom/src/utils.js
+++ b/packages/shadydom/src/utils.js
@@ -36,6 +36,14 @@ settings.noPatch = /** @type {string|boolean} */ (settings['noPatch'] || false);
 // eslint-disable-next-line no-self-assign
 settings.preferPerformance = settings['preferPerformance'];
 settings.patchOnDemand = settings.noPatch === 'on-demand';
+settings.querySelectorImplementation = (() => {
+  const acceptedValues = ['native', 'selectorEngine'];
+  const userValue = settings['querySelectorImplementation'];
+  if (acceptedValues.indexOf(userValue) > -1) {
+    return userValue;
+  }
+  return undefined;
+})();
 
 const IS_IE = navigator.userAgent.match('Trident');
 settings.IS_IE = IS_IE;

From b4cd3606b165bed0f8ffe05337cc1b1130f8764c Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 10 Aug 2022 15:14:42 -0700
Subject: [PATCH 25/76] Remove an unnecessary `filter` and some wrapper arrays.

---
 packages/shadydom/src/patches/ParentNode.js | 50 +++++++++------------
 1 file changed, 22 insertions(+), 28 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index 07cf7692a..60f0eeb56 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -156,8 +156,8 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
   /**
    * @type {!Array<!ComplexSelectorParts>}
    */
-  const complexSelectors = extractSelectors(selectorList)
-    .map((complexSelector) => {
+  const complexSelectors = extractSelectors(selectorList).map(
+    (complexSelector) => {
       const {
         'selectors': compoundSelectors,
         'joiners': combinators,
@@ -167,8 +167,8 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
         compoundSelectors,
         combinators,
       };
-    })
-    .filter(({compoundSelectors}) => compoundSelectors.length > 0);
+    }
+  );
 
   if (complexSelectors.length < 1) {
     return [];
@@ -228,14 +228,12 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
           const {compoundSelectors} = complexSelectorParts;
           const index = compoundSelectors.length - 1;
           if (matchesCompoundSelector(element, compoundSelectors[index])) {
-            return [
-              {
-                target: element,
-                complexSelectorParts,
-                position: element,
-                index,
-              },
-            ];
+            return {
+              target: element,
+              complexSelectorParts,
+              position: element,
+              index,
+            };
           } else {
             return [];
           }
@@ -299,14 +297,12 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
             parent instanceof Element &&
             matchesCompoundSelector(parent, compoundSelector)
           ) {
-            return [
-              {
-                target,
-                complexSelectorParts,
-                position: parent,
-                index,
-              },
-            ];
+            return {
+              target,
+              complexSelectorParts,
+              position: parent,
+              index,
+            };
           }
 
           return [];
@@ -318,14 +314,12 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
           // the candidates to test against `a` are the immediately preceding
           // siblings of each cursor's `position`.
           if (sibling && matchesCompoundSelector(sibling, compoundSelector)) {
-            return [
-              {
-                target,
-                complexSelectorParts,
-                position: sibling,
-                index,
-              },
-            ];
+            return {
+              target,
+              complexSelectorParts,
+              position: sibling,
+              index,
+            };
           }
 
           return [];

From bf48a44af1fbc5af59be8b37de61ff9eb9570a38 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 10 Aug 2022 15:19:25 -0700
Subject: [PATCH 26/76] `Array::some` always returns `false` when the array is
 empty.

---
 packages/shadydom/src/patches/ParentNode.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index 60f0eeb56..4b398e3da 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -245,7 +245,7 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
   // At each step, any remaining cursors that have not finished matching (i.e.
   // with `cursor.index > 0`) should be replaced with new cursors for any valid
   // candidates that match the next compound selector.
-  while (cursors.length > 0 && cursors.some((cursor) => cursor.index > 0)) {
+  while (cursors.some((cursor) => cursor.index > 0)) {
     cursors = utils.flat(
       cursors.map((cursor) => {
         // Cursors with `index` of 0 have already matched and should not be

From 0cc92da49281741d625017682ffbbcc6fc7da7ff Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 10 Aug 2022 16:52:25 -0700
Subject: [PATCH 27/76] Test that `>` works across shadow root boundaries.

---
 packages/tests/shadydom/shady-dynamic.html | 36 ++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/packages/tests/shadydom/shady-dynamic.html b/packages/tests/shadydom/shady-dynamic.html
index f618f592d..ed0c7d9e0 100644
--- a/packages/tests/shadydom/shady-dynamic.html
+++ b/packages/tests/shadydom/shady-dynamic.html
@@ -358,6 +358,15 @@
       });
     </script>
 
+    <template id="x-slot-inside-div">
+      <div>
+        <slot></slot>
+      </div>
+    </template>
+    <script>
+      defineTestElement('x-slot-inside-div');
+    </script>
+
     <script>
       'use strict';
 
@@ -2906,6 +2915,33 @@
           document.body.removeChild(d);
         });
       });
+
+      suite('querySelectorImplementation', function () {
+        const querySelectorImplementation =
+          ShadyDOM.querySelectorImplementation;
+
+        test('The `>` combinator can match shadow root hosts with their children.', function () {
+          const layer1 = createEnabledElement('x-slot-inside-div');
+          const layer2 = createEnabledElement('x-slot-inside-div');
+          layer1.appendChild(layer2);
+          const target = document.createElement('div');
+          layer2.appendChild(target);
+
+          const results = layer1.querySelectorAll(
+            'x-slot-inside-div > x-slot-inside-div > div'
+          );
+
+          if (!querySelectorImplementation) {
+            // The default implementation can't find the target because of the
+            // `<div>`s from the logical shadow roots are in the same root in
+            // the real tree.
+            assert.equal(results.length, 0);
+          } else if (querySelectorImplementation === 'selectorEngine') {
+            assert.equal(results.length, 1);
+            assert.equal(results[0], target);
+          }
+        });
+      });
     </script>
   </body>
 </html>

From 712d1166835e3c75ebda7d29373e4c9ee84f8477 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 10 Aug 2022 17:06:34 -0700
Subject: [PATCH 28/76] Test that the semantics of `:scope` are preserved.

---
 packages/tests/shadydom/shady-dynamic.html | 30 ++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/packages/tests/shadydom/shady-dynamic.html b/packages/tests/shadydom/shady-dynamic.html
index ed0c7d9e0..421b0264c 100644
--- a/packages/tests/shadydom/shady-dynamic.html
+++ b/packages/tests/shadydom/shady-dynamic.html
@@ -367,6 +367,17 @@
       defineTestElement('x-slot-inside-div');
     </script>
 
+    <template id="x-query-selector-scope">
+      <div>
+        <div id="contextElement">
+          <div id="target"></div>
+        </div>
+      </div>
+    </template>
+    <script>
+      defineTestElement('x-query-selector-scope');
+    </script>
+
     <script>
       'use strict';
 
@@ -2941,6 +2952,25 @@
             assert.equal(results[0], target);
           }
         });
+
+        test('The semantics of `:scope` are preserved.', function () {
+          const host = createEnabledElement('x-query-selector-scope');
+          const contextElement = ShadyDOM.wrapIfNeeded(
+            host
+          ).shadowRoot.getElementById('contextElement');
+
+          const results = contextElement.querySelectorAll('div:scope > div');
+
+          if (!querySelectorImplementation) {
+            // The default implementation can't find the target because it
+            // attempts to match it by calling `matches` on the element with the
+            // full selector, which breaks the semantics of `:scope`.
+            assert.equal(results.length, 0);
+          } else if (querySelectorImplementation === 'selectorEngine') {
+            assert.equal(results.length, 1);
+            assert.equal(results[0].id, 'target');
+          }
+        });
       });
     </script>
   </body>

From 8ff99b7d01c13bb71a6087308f2784ffa8fe878c Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 10 Aug 2022 17:29:02 -0700
Subject: [PATCH 29/76] Add tests for combinators in scenarios without shadow
 trees or `:scope`.

---
 packages/tests/shadydom/shady-dynamic.html | 141 +++++++++++++++++++++
 1 file changed, 141 insertions(+)

diff --git a/packages/tests/shadydom/shady-dynamic.html b/packages/tests/shadydom/shady-dynamic.html
index 421b0264c..fbb503245 100644
--- a/packages/tests/shadydom/shady-dynamic.html
+++ b/packages/tests/shadydom/shady-dynamic.html
@@ -358,6 +358,81 @@
       });
     </script>
 
+    <template id="x-query-selector-descendant-combinator">
+      <div id="contextElement">
+        <div match id="a">
+          <div>
+            <div match id="b"></div>
+          </div>
+        </div>
+        <div>
+          <div></div>
+          <div match id="c"></div>
+        </div>
+      </div>
+    </template>
+    <script>
+      defineTestElement('x-query-selector-descendant-combinator');
+    </script>
+
+    <template id="x-query-selector-child-combinator">
+      <div id="contextElement">
+        <div id="a">
+          <div>
+            <div></div>
+          </div>
+        </div>
+        <div id="b"></div>
+        <div id="c">
+          <div></div>
+          <div></div>
+        </div>
+      </div>
+    </template>
+    <script>
+      defineTestElement('x-query-selector-child-combinator');
+    </script>
+
+    <template id="x-query-selector-next-sibling-combinator">
+      <div id="contextElement">
+        <div before>
+          <div before></div>
+          <div id="a">
+            <div></div>
+          </div>
+        </div>
+        <div id="b"></div>
+        <div>
+          <div before></div>
+          <div id="c"></div>
+          <div></div>
+        </div>
+      </div>
+    </template>
+    <script>
+      defineTestElement('x-query-selector-next-sibling-combinator');
+    </script>
+
+    <template id="x-query-selector-subsequent-sibling-combinator">
+      <div id="contextElement">
+        <div before>
+          <div before></div>
+          <div id="a">
+            <div></div>
+          </div>
+        </div>
+        <div id="b"></div>
+        <div id="c">
+          <div before></div>
+          <div id="d"></div>
+          <div id="e"></div>
+        </div>
+      </div>
+    </template>
+    <script>
+      defineTestElement('x-query-selector-subsequent-sibling-combinator');
+    </script>
+
     <template id="x-slot-inside-div">
       <div>
         <slot></slot>
@@ -2931,6 +3006,72 @@
         const querySelectorImplementation =
           ShadyDOM.querySelectorImplementation;
 
+        test('The ` ` combinator finds descendants.', function () {
+          const host = createEnabledElement('x-query-selector-descendant-combinator');
+          const contextElement = ShadyDOM.wrapIfNeeded(
+            host
+          ).shadowRoot.getElementById('contextElement');
+
+          const results = contextElement.querySelectorAll('#contextElement [match]');
+
+          // No shadow root hosts below #contextElement or use of `:scope`, so
+          // the results are the same for all implementations.
+          assert.equal(results.length, 3);
+          assert.equal(results[0].id, 'a');
+          assert.equal(results[1].id, 'b');
+          assert.equal(results[2].id, 'c');
+        });
+
+        test('The `>` combinator finds children.', function () {
+          const host = createEnabledElement('x-query-selector-child-combinator');
+          const contextElement = ShadyDOM.wrapIfNeeded(
+            host
+          ).shadowRoot.getElementById('contextElement');
+
+          const results = contextElement.querySelectorAll('#contextElement > *');
+
+          // No shadow root hosts below #contextElement or use of `:scope`, so
+          // the results are the same for all implementations.
+          assert.equal(results.length, 3);
+          assert.equal(results[0].id, 'a');
+          assert.equal(results[1].id, 'b');
+          assert.equal(results[2].id, 'c');
+        });
+
+        test('The `+` combinator finds next siblings.', function () {
+          const host = createEnabledElement('x-query-selector-next-sibling-combinator');
+          const contextElement = ShadyDOM.wrapIfNeeded(
+            host
+          ).shadowRoot.getElementById('contextElement');
+
+          const results = contextElement.querySelectorAll('[before] + *');
+
+          // No shadow root hosts below #contextElement or use of `:scope`, so
+          // the results are the same for all implementations.
+          assert.equal(results.length, 3);
+          assert.equal(results[0].id, 'a');
+          assert.equal(results[1].id, 'b');
+          assert.equal(results[2].id, 'c');
+        });
+
+        test('The `~` combinator finds subsequent siblings.', function () {
+          const host = createEnabledElement('x-query-selector-subsequent-sibling-combinator');
+          const contextElement = ShadyDOM.wrapIfNeeded(
+            host
+          ).shadowRoot.getElementById('contextElement');
+
+          const results = contextElement.querySelectorAll('[before] ~ *');
+
+          // No shadow root hosts below #contextElement or use of `:scope`, so
+          // the results are the same for all implementations.
+          assert.equal(results.length, 5);
+          assert.equal(results[0].id, 'a');
+          assert.equal(results[1].id, 'b');
+          assert.equal(results[2].id, 'c');
+          assert.equal(results[3].id, 'd');
+          assert.equal(results[4].id, 'e');
+        });
+
         test('The `>` combinator can match shadow root hosts with their children.', function () {
           const layer1 = createEnabledElement('x-slot-inside-div');
           const layer2 = createEnabledElement('x-slot-inside-div');

From 919ade71412a16fc7de1d0f43da199fa9056eb2b Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 10 Aug 2022 17:53:29 -0700
Subject: [PATCH 30/76] format

---
 packages/tests/shadydom/shady-dynamic.html | 24 ++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/packages/tests/shadydom/shady-dynamic.html b/packages/tests/shadydom/shady-dynamic.html
index fbb503245..aa624f0ee 100644
--- a/packages/tests/shadydom/shady-dynamic.html
+++ b/packages/tests/shadydom/shady-dynamic.html
@@ -3007,12 +3007,16 @@
           ShadyDOM.querySelectorImplementation;
 
         test('The ` ` combinator finds descendants.', function () {
-          const host = createEnabledElement('x-query-selector-descendant-combinator');
+          const host = createEnabledElement(
+            'x-query-selector-descendant-combinator'
+          );
           const contextElement = ShadyDOM.wrapIfNeeded(
             host
           ).shadowRoot.getElementById('contextElement');
 
-          const results = contextElement.querySelectorAll('#contextElement [match]');
+          const results = contextElement.querySelectorAll(
+            '#contextElement [match]'
+          );
 
           // No shadow root hosts below #contextElement or use of `:scope`, so
           // the results are the same for all implementations.
@@ -3023,12 +3027,16 @@
         });
 
         test('The `>` combinator finds children.', function () {
-          const host = createEnabledElement('x-query-selector-child-combinator');
+          const host = createEnabledElement(
+            'x-query-selector-child-combinator'
+          );
           const contextElement = ShadyDOM.wrapIfNeeded(
             host
           ).shadowRoot.getElementById('contextElement');
 
-          const results = contextElement.querySelectorAll('#contextElement > *');
+          const results = contextElement.querySelectorAll(
+            '#contextElement > *'
+          );
 
           // No shadow root hosts below #contextElement or use of `:scope`, so
           // the results are the same for all implementations.
@@ -3039,7 +3047,9 @@
         });
 
         test('The `+` combinator finds next siblings.', function () {
-          const host = createEnabledElement('x-query-selector-next-sibling-combinator');
+          const host = createEnabledElement(
+            'x-query-selector-next-sibling-combinator'
+          );
           const contextElement = ShadyDOM.wrapIfNeeded(
             host
           ).shadowRoot.getElementById('contextElement');
@@ -3055,7 +3065,9 @@
         });
 
         test('The `~` combinator finds subsequent siblings.', function () {
-          const host = createEnabledElement('x-query-selector-subsequent-sibling-combinator');
+          const host = createEnabledElement(
+            'x-query-selector-subsequent-sibling-combinator'
+          );
           const contextElement = ShadyDOM.wrapIfNeeded(
             host
           ).shadowRoot.getElementById('contextElement');

From 419b87c82ac8c9c7d309782e3c4d919e6534896a Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 10 Aug 2022 17:53:38 -0700
Subject: [PATCH 31/76] Use `wrapIfNeeded` and `wrap` as necessary for
 `noPatch` modes.

---
 packages/tests/shadydom/shady-dynamic.html | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/packages/tests/shadydom/shady-dynamic.html b/packages/tests/shadydom/shady-dynamic.html
index aa624f0ee..0d201bdda 100644
--- a/packages/tests/shadydom/shady-dynamic.html
+++ b/packages/tests/shadydom/shady-dynamic.html
@@ -3087,11 +3087,11 @@
         test('The `>` combinator can match shadow root hosts with their children.', function () {
           const layer1 = createEnabledElement('x-slot-inside-div');
           const layer2 = createEnabledElement('x-slot-inside-div');
-          layer1.appendChild(layer2);
+          ShadyDOM.wrapIfNeeded(layer1).appendChild(layer2);
           const target = document.createElement('div');
-          layer2.appendChild(target);
+          ShadyDOM.wrapIfNeeded(layer2).appendChild(target);
 
-          const results = layer1.querySelectorAll(
+          const results = ShadyDOM.wrapIfNeeded(layer1).querySelectorAll(
             'x-slot-inside-div > x-slot-inside-div > div'
           );
 
@@ -3112,7 +3112,9 @@
             host
           ).shadowRoot.getElementById('contextElement');
 
-          const results = contextElement.querySelectorAll('div:scope > div');
+          const results = ShadyDOM.wrap(contextElement).querySelectorAll(
+            'div:scope > div'
+          );
 
           if (!querySelectorImplementation) {
             // The default implementation can't find the target because it

From 25a79af25440108814b70f62ee5be8fa81ca0b2b Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Mon, 15 Aug 2022 14:17:14 -0700
Subject: [PATCH 32/76] Skip `:scope` test if `:scope` isn't natively
 supported.

---
 packages/tests/shadydom/shady-dynamic.html | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/packages/tests/shadydom/shady-dynamic.html b/packages/tests/shadydom/shady-dynamic.html
index 0d201bdda..394ad350f 100644
--- a/packages/tests/shadydom/shady-dynamic.html
+++ b/packages/tests/shadydom/shady-dynamic.html
@@ -3107,6 +3107,16 @@
         });
 
         test('The semantics of `:scope` are preserved.', function () {
+          // Skip if `:scope` isn't natively supported.
+          try {
+            ShadyDOM.nativeMethods.querySelectorAll.call(
+              document,
+              'body:scope'
+            );
+          } catch (e) {
+            this.skip();
+          }
+
           const host = createEnabledElement('x-query-selector-scope');
           const contextElement = ShadyDOM.wrapIfNeeded(
             host

From 080210a17599fde29bf35d6e4428bdb971d7ea88 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 17 Aug 2022 18:10:34 -0700
Subject: [PATCH 33/76] Use a custom CSS selector parser.

---
 packages/shadydom/src/patches/ParentNode.js   |  29 +---
 .../shadydom/src/patches/selector-parser.js   | 125 ++++++++++++++++++
 2 files changed, 127 insertions(+), 27 deletions(-)
 create mode 100644 packages/shadydom/src/patches/selector-parser.js

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index 4b398e3da..f75fec197 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -10,9 +10,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 
 import * as utils from '../utils.js';
 import {shadyDataForNode} from '../shady-data.js';
-import extractSelectors, {
-  splitSelectorBlocks,
-} from './css-selector-splitter.js';
+import {ComplexSelectorParts, parseSelectorList} from './selector-parser.js';
 
 /**
  * @param {Node} node
@@ -142,33 +140,10 @@ export const ParentNodePatches = utils.getOwnPropertyDescriptors({
  * @return {!Array<!Element>}
  */
 const logicalQuerySelectorAll = (contextElement, selectorList) => {
-  /**
-   * A key-renamed version of the return value of `extractSelectors`, which
-   * describes a single complex selector.
-   *
-   * @typedef {{
-   *   compoundSelectors: !Array<string>,
-   *   combinators: !Array<string>,
-   * }}
-   */
-  let ComplexSelectorParts;
-
   /**
    * @type {!Array<!ComplexSelectorParts>}
    */
-  const complexSelectors = extractSelectors(selectorList).map(
-    (complexSelector) => {
-      const {
-        'selectors': compoundSelectors,
-        'joiners': combinators,
-      } = splitSelectorBlocks(complexSelector);
-
-      return {
-        compoundSelectors,
-        combinators,
-      };
-    }
-  );
+  const complexSelectors = parseSelectorList(selectorList);
 
   if (complexSelectors.length < 1) {
     return [];
diff --git a/packages/shadydom/src/patches/selector-parser.js b/packages/shadydom/src/patches/selector-parser.js
new file mode 100644
index 000000000..360138060
--- /dev/null
+++ b/packages/shadydom/src/patches/selector-parser.js
@@ -0,0 +1,125 @@
+/**
+ * Arrays of compound selectors and combinators that form a complex selector
+ * when interleaved.
+ *
+ * @typedef {{
+ *   compoundSelectors: !Array<string>,
+ *   combinators: !Array<string>,
+ * }}
+ */
+export let ComplexSelectorParts;
+
+const PARENS = {
+  '(': ')',
+  '[': ']',
+};
+
+const STRINGS = {
+  '"': '"',
+  "'": "'",
+};
+
+const findNext = (str, queryChars, withGroupings = true) => {
+  let before = '';
+  for (let i = 0; i < str.length; i++) {
+    if (str[i] === '\\' && i < str.length - 1 && str[i + 1] !== '\n') {
+      // Skip escaped character.
+      i++;
+    } else if (queryChars.includes(str[i])) {
+      return i;
+    } else if (withGroupings && PARENS[str[i]]) {
+      i += findNext(str.substring(i + 1), [PARENS[str[i]]], withGroupings);
+      continue;
+    } else if (withGroupings && STRINGS[str[i]]) {
+      i += findNext(str.substring(i + 1), [STRINGS[str[i]]], false);
+      continue;
+    }
+
+    // Do nothing, let `i++` happen.
+  }
+
+  // Reached the end of the string without finding a final char.
+  return str.length;
+};
+
+const COMBINATORS = [' ', '>', '~', '+'];
+
+/**
+ * @param str {string}
+ * @return {!ComplexSelectorParts}
+ */
+const parseComplexSelector = (str) => {
+  /**
+   * @type {!Array<string>}
+   */
+  let chunks = [];
+
+  while (str.length) {
+    const index = findNext(str, COMBINATORS);
+    if (index === 0) {
+      chunks.push(str[0]);
+      str = str.substring(1);
+    } else {
+      chunks.push(str.substring(0, index));
+      str = str.substring(index);
+    }
+  }
+
+  // Remove leading whitespace.
+  while (chunks[0] === ' ') {
+    chunks.shift();
+  }
+
+  // Remove trailing whitespace.
+  while (chunks[chunks.length - 1] === ' ') {
+    chunks.pop();
+  }
+
+  // Remove whitespace next to combinators.
+  chunks = chunks.filter((x, i) => {
+    return !(
+      x === ' ' &&
+      (COMBINATORS.includes(chunks[i - 1]) ||
+        COMBINATORS.includes(chunks[i + 1]))
+    );
+  });
+
+  /**
+   * @type {!Array<string>}
+   */
+  const compoundSelectors = [];
+
+  /**
+   * @type {!Array<string>}
+   */
+  const combinators = [];
+
+  for (let i = 0; i < chunks.length; i++) {
+    if (i % 2 === 0) {
+      compoundSelectors.push(chunks[i]);
+    } else {
+      combinators.push(chunks[i]);
+    }
+  }
+
+  return {
+    compoundSelectors,
+    combinators,
+  };
+};
+
+/**
+ * @param str {string}
+ * @return {!Array<!ComplexSelectorParts>}
+ */
+export const parseSelectorList = (str) => {
+  const results = [];
+
+  while (str.length) {
+    const index = findNext(str, [',']);
+    results.push(parseComplexSelector(str.substring(0, index)));
+    str = str.substring(index + 1);
+  }
+
+  return results;
+};

From 27cbd49c524508397d7802c0a0570f55c258a943 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 17 Aug 2022 18:20:08 -0700
Subject: [PATCH 34/76] Remove `css-selector-splitter`.

---
 .../src/patches/css-selector-splitter.js      | 140 ------------------
 1 file changed, 140 deletions(-)
 delete mode 100644 packages/shadydom/src/patches/css-selector-splitter.js

diff --git a/packages/shadydom/src/patches/css-selector-splitter.js b/packages/shadydom/src/patches/css-selector-splitter.js
deleted file mode 100644
index e56e89e2d..000000000
--- a/packages/shadydom/src/patches/css-selector-splitter.js
+++ /dev/null
@@ -1,140 +0,0 @@
-/**
-@license
-
-MIT License
-
-Copyright (c) 2016 Perry Mitchell
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-*/
-
-const BRACES = {
-  '(': ')',
-  '[': ']',
-  '"': '"',
-  "'": "'",
-};
-
-const CLOSING_BRACES = {
-  ')': '(',
-  ']': '[',
-};
-
-function splitSelector(selector, splitCharacters = [',']) {
-  let currentBraces = [],
-    selectorLen = selector.length,
-    selectors = [],
-    joiners = [],
-    currentSelector = '',
-    closingBraces = {};
-  for (var i = 0; i < selectorLen; i += 1) {
-    let char = selector[i];
-    if (BRACES.hasOwnProperty(char)) {
-      if (currentBraces.length === 0) {
-        currentBraces.push(char);
-      } else {
-        let lastBrace = currentBraces[currentBraces.length - 1];
-        if (lastBrace === '"' || lastBrace === "'") {
-          // within quotes
-          if (char === lastBrace) {
-            // closing quote
-            currentBraces.pop();
-          }
-        } else {
-          // inside brackets or square brackets
-          currentBraces.push(char);
-        }
-      }
-      currentSelector += char;
-    } else if (CLOSING_BRACES.hasOwnProperty(char)) {
-      let lastBrace = currentBraces[currentBraces.length - 1],
-        matchingOpener = CLOSING_BRACES[char];
-      if (lastBrace === matchingOpener) {
-        currentBraces.pop();
-      }
-      currentSelector += char;
-    } else if (splitCharacters.indexOf(char) >= 0) {
-      if (currentBraces.length <= 0) {
-        // we're not inside another block, so we can split using the comma/splitter
-        let lastJoiner = joiners[joiners.length - 1];
-        if (lastJoiner === ' ' && currentSelector.length <= 0) {
-          // we just split by a space, but there seems to be another split character, so use
-          // this new one instead of the previous space
-          joiners[joiners.length - 1] = char;
-        } else if (currentSelector.length <= 0) {
-          // skip this character, as it's just padding
-        } else {
-          // split by this character
-          let newLength = selectors.push(currentSelector.trim());
-          joiners[newLength - 1] = char;
-          currentSelector = '';
-        }
-      } else {
-        // we're inside another block, so ignore the comma/splitter
-        currentSelector += char;
-      }
-    } else {
-      // just add this character
-      currentSelector += char;
-    }
-  }
-  selectors.push(currentSelector.trim());
-  return {
-    'selectors': selectors.filter((cssSelector) => cssSelector.length > 0),
-    'joiners': joiners,
-  };
-}
-
-// output:
-
-function extractSelectors(selector, splitChars = [',']) {
-  let split = splitSelector(selector, splitChars);
-  return split['selectors'];
-}
-
-function extractSelectorBlocks(selector) {
-  return splitSelector(selector, ['+', '~', '>', ' ']);
-}
-
-function joinParts(selectors, joiners) {
-  let selector = '',
-    selectorCount = selectors.length;
-  selectors.forEach(function (part, index) {
-    let suffix = joiners[index];
-    if (!suffix) {
-      if (selectorCount - 1 === index) {
-        suffix = '';
-      } else {
-        throw new Error(`No joiner for index: ${index}`);
-      }
-    } else {
-      if (suffix !== ' ') {
-        suffix = ` ${suffix} `;
-      }
-    }
-    selector += part + suffix;
-  });
-  return selector;
-}
-
-export {extractSelectorBlocks as splitSelectorBlocks};
-
-export {joinParts as joinSelector};
-
-export default extractSelectors;

From f7f316a9e3040d89d658fda73462de3a2dc8f612 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 17 Aug 2022 18:25:18 -0700
Subject: [PATCH 35/76] Fix Closure types.

---
 packages/shadydom/src/patches/selector-parser.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/shadydom/src/patches/selector-parser.js b/packages/shadydom/src/patches/selector-parser.js
index 360138060..6e4e4a8a2 100644
--- a/packages/shadydom/src/patches/selector-parser.js
+++ b/packages/shadydom/src/patches/selector-parser.js
@@ -45,7 +45,7 @@ const findNext = (str, queryChars, withGroupings = true) => {
 const COMBINATORS = [' ', '>', '~', '+'];
 
 /**
- * @param str {string}
+ * @param {string} str
  * @return {!ComplexSelectorParts}
  */
 const parseComplexSelector = (str) => {
@@ -109,7 +109,7 @@ const parseComplexSelector = (str) => {
 };
 
 /**
- * @param str {string}
+ * @param {string} str
  * @return {!Array<!ComplexSelectorParts>}
  */
 export const parseSelectorList = (str) => {

From 682a537a0955219bf631fb932caeb164fccb3a68 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 17 Aug 2022 18:31:39 -0700
Subject: [PATCH 36/76] Remove dead code.

---
 packages/shadydom/src/patches/selector-parser.js | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/shadydom/src/patches/selector-parser.js b/packages/shadydom/src/patches/selector-parser.js
index 6e4e4a8a2..cf6fda0b3 100644
--- a/packages/shadydom/src/patches/selector-parser.js
+++ b/packages/shadydom/src/patches/selector-parser.js
@@ -20,7 +20,6 @@ const STRINGS = {
 };
 
 const findNext = (str, queryChars, withGroupings = true) => {
-  let before = '';
   for (let i = 0; i < str.length; i++) {
     if (str[i] === '\\' && i < str.length - 1 && str[i + 1] !== '\n') {
       // Skip escaped character.

From 2a1c2ba00d674628408f419410d7fcae31006cb0 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 24 Aug 2022 13:44:47 -0700
Subject: [PATCH 37/76] Use a single parens info map.

---
 .../shadydom/src/patches/selector-parser.js   | 41 ++++++++++++-------
 1 file changed, 26 insertions(+), 15 deletions(-)

diff --git a/packages/shadydom/src/patches/selector-parser.js b/packages/shadydom/src/patches/selector-parser.js
index cf6fda0b3..e60521ac8 100644
--- a/packages/shadydom/src/patches/selector-parser.js
+++ b/packages/shadydom/src/patches/selector-parser.js
@@ -9,28 +9,36 @@
  */
 export let ComplexSelectorParts;
 
-const PARENS = {
-  '(': ')',
-  '[': ']',
-};
-
-const STRINGS = {
-  '"': '"',
-  "'": "'",
-};
+/**
+ * @type {!Map<string, {end: string, matchNestedParens: boolean}>}
+ */
+const PARENS = new Map([
+  ['(', {end: ')', matchNestedParens: true}],
+  ['[', {end: ']', matchNestedParens: true}],
+  ['"', {end: '"', matchNestedParens: false}],
+  ["'", {end: "'", matchNestedParens: false}],
+]);
 
-const findNext = (str, queryChars, withGroupings = true) => {
+/**
+ * @param {string} str
+ * @param {!Array<string>} queryChars
+ * @param {boolean} matchNestedParens
+ * @return {number}
+ */
+const findNext = (str, queryChars, matchNestedParens = true) => {
   for (let i = 0; i < str.length; i++) {
     if (str[i] === '\\' && i < str.length - 1 && str[i + 1] !== '\n') {
       // Skip escaped character.
       i++;
     } else if (queryChars.includes(str[i])) {
       return i;
-    } else if (withGroupings && PARENS[str[i]]) {
-      i += findNext(str.substring(i + 1), [PARENS[str[i]]], withGroupings);
-      continue;
-    } else if (withGroupings && STRINGS[str[i]]) {
-      i += findNext(str.substring(i + 1), [STRINGS[str[i]]], false);
+    } else if (matchNestedParens && PARENS.has(str[i])) {
+      const parenInfo = PARENS.get(str[i]);
+      i += findNext(
+        str.substring(i + 1),
+        [parenInfo.end],
+        parenInfo.matchNestedParens
+      );
       continue;
     }
 
@@ -41,6 +49,9 @@ const findNext = (str, queryChars, withGroupings = true) => {
   return str.length;
 };
 
+/**
+ * @type {!Array<string>}
+ */
 const COMBINATORS = [' ', '>', '~', '+'];
 
 /**

From f4a5a7384164a444d5c16cb8db509d04432b0091 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 24 Aug 2022 13:51:44 -0700
Subject: [PATCH 38/76] Remove outer whitespace early with `trim` instead.

---
 packages/shadydom/src/patches/selector-parser.js | 12 ++----------
 1 file changed, 2 insertions(+), 10 deletions(-)

diff --git a/packages/shadydom/src/patches/selector-parser.js b/packages/shadydom/src/patches/selector-parser.js
index e60521ac8..8f0298c20 100644
--- a/packages/shadydom/src/patches/selector-parser.js
+++ b/packages/shadydom/src/patches/selector-parser.js
@@ -59,6 +59,8 @@ const COMBINATORS = [' ', '>', '~', '+'];
  * @return {!ComplexSelectorParts}
  */
 const parseComplexSelector = (str) => {
+  str = str.trim();
+
   /**
    * @type {!Array<string>}
    */
@@ -75,16 +77,6 @@ const parseComplexSelector = (str) => {
     }
   }
 
-  // Remove leading whitespace.
-  while (chunks[0] === ' ') {
-    chunks.shift();
-  }
-
-  // Remove trailing whitespace.
-  while (chunks[chunks.length - 1] === ' ') {
-    chunks.pop();
-  }
-
   // Remove whitespace next to combinators.
   chunks = chunks.filter((x, i) => {
     return !(

From 5123f068ec854126b949e2bf0c9e1d5e43369e31 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 24 Aug 2022 13:58:33 -0700
Subject: [PATCH 39/76] Unzip compound selectors and combinators with `filter`.

---
 .../shadydom/src/patches/selector-parser.js   | 22 ++-----------------
 1 file changed, 2 insertions(+), 20 deletions(-)

diff --git a/packages/shadydom/src/patches/selector-parser.js b/packages/shadydom/src/patches/selector-parser.js
index 8f0298c20..892092531 100644
--- a/packages/shadydom/src/patches/selector-parser.js
+++ b/packages/shadydom/src/patches/selector-parser.js
@@ -86,27 +86,9 @@ const parseComplexSelector = (str) => {
     );
   });
 
-  /**
-   * @type {!Array<string>}
-   */
-  const compoundSelectors = [];
-
-  /**
-   * @type {!Array<string>}
-   */
-  const combinators = [];
-
-  for (let i = 0; i < chunks.length; i++) {
-    if (i % 2 === 0) {
-      compoundSelectors.push(chunks[i]);
-    } else {
-      combinators.push(chunks[i]);
-    }
-  }
-
   return {
-    compoundSelectors,
-    combinators,
+    compoundSelectors: chunks.filter((x, i) => i % 2 === 0),
+    combinators: chunks.filter((x, i) => i % 2 === 1),
   };
 };
 

From bc93800f1d93df1cd000460576cc60da62d41d76 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 24 Aug 2022 14:20:32 -0700
Subject: [PATCH 40/76] `findIndex` now takes a start index.

---
 .../shadydom/src/patches/selector-parser.js   | 33 +++++++++----------
 1 file changed, 15 insertions(+), 18 deletions(-)

diff --git a/packages/shadydom/src/patches/selector-parser.js b/packages/shadydom/src/patches/selector-parser.js
index 892092531..f6f8a1801 100644
--- a/packages/shadydom/src/patches/selector-parser.js
+++ b/packages/shadydom/src/patches/selector-parser.js
@@ -21,12 +21,13 @@ const PARENS = new Map([
 
 /**
  * @param {string} str
+ * @param {number} start
  * @param {!Array<string>} queryChars
  * @param {boolean} matchNestedParens
  * @return {number}
  */
-const findNext = (str, queryChars, matchNestedParens = true) => {
-  for (let i = 0; i < str.length; i++) {
+const findNext = (str, start, queryChars, matchNestedParens = true) => {
+  for (let i = start; i < str.length; i++) {
     if (str[i] === '\\' && i < str.length - 1 && str[i + 1] !== '\n') {
       // Skip escaped character.
       i++;
@@ -34,11 +35,7 @@ const findNext = (str, queryChars, matchNestedParens = true) => {
       return i;
     } else if (matchNestedParens && PARENS.has(str[i])) {
       const parenInfo = PARENS.get(str[i]);
-      i += findNext(
-        str.substring(i + 1),
-        [parenInfo.end],
-        parenInfo.matchNestedParens
-      );
+      i += findNext(str, i + 1, [parenInfo.end], parenInfo.matchNestedParens);
       continue;
     }
 
@@ -66,14 +63,14 @@ const parseComplexSelector = (str) => {
    */
   let chunks = [];
 
-  while (str.length) {
-    const index = findNext(str, COMBINATORS);
-    if (index === 0) {
-      chunks.push(str[0]);
-      str = str.substring(1);
+  for (let i = 0; i < str.length;) {
+    const next = findNext(str, i, COMBINATORS);
+    if (next === i) {
+      chunks.push(str[i]);
+      i++;
     } else {
-      chunks.push(str.substring(0, index));
-      str = str.substring(index);
+      chunks.push(str.substring(i, next));
+      i = next;
     }
   }
 
@@ -99,10 +96,10 @@ const parseComplexSelector = (str) => {
 export const parseSelectorList = (str) => {
   const results = [];
 
-  while (str.length) {
-    const index = findNext(str, [',']);
-    results.push(parseComplexSelector(str.substring(0, index)));
-    str = str.substring(index + 1);
+  for (let i = 0; i < str.length;) {
+    const next = findNext(str, i, [',']);
+    results.push(parseComplexSelector(str.substring(i, next)));
+    i = next + 1;
   }
 
   return results;

From 3e47496cd8e5be0a69334498f9bcecdc7c7cccf1 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 24 Aug 2022 15:01:53 -0700
Subject: [PATCH 41/76] Remove `COMBINATORS` constant.

---
 packages/shadydom/src/patches/selector-parser.js | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/packages/shadydom/src/patches/selector-parser.js b/packages/shadydom/src/patches/selector-parser.js
index f6f8a1801..49abb5b56 100644
--- a/packages/shadydom/src/patches/selector-parser.js
+++ b/packages/shadydom/src/patches/selector-parser.js
@@ -46,11 +46,6 @@ const findNext = (str, start, queryChars, matchNestedParens = true) => {
   return str.length;
 };
 
-/**
- * @type {!Array<string>}
- */
-const COMBINATORS = [' ', '>', '~', '+'];
-
 /**
  * @param {string} str
  * @return {!ComplexSelectorParts}
@@ -64,7 +59,7 @@ const parseComplexSelector = (str) => {
   let chunks = [];
 
   for (let i = 0; i < str.length;) {
-    const next = findNext(str, i, COMBINATORS);
+    const next = findNext(str, i, [' ', '>', '~', '+']);
     if (next === i) {
       chunks.push(str[i]);
       i++;

From 94fe63eec34fda2f031569d761222af998816ada Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 24 Aug 2022 15:32:45 -0700
Subject: [PATCH 42/76] format

---
 packages/shadydom/src/patches/selector-parser.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/shadydom/src/patches/selector-parser.js b/packages/shadydom/src/patches/selector-parser.js
index 49abb5b56..2febdc839 100644
--- a/packages/shadydom/src/patches/selector-parser.js
+++ b/packages/shadydom/src/patches/selector-parser.js
@@ -58,7 +58,7 @@ const parseComplexSelector = (str) => {
    */
   let chunks = [];
 
-  for (let i = 0; i < str.length;) {
+  for (let i = 0; i < str.length; ) {
     const next = findNext(str, i, [' ', '>', '~', '+']);
     if (next === i) {
       chunks.push(str[i]);
@@ -91,7 +91,7 @@ const parseComplexSelector = (str) => {
 export const parseSelectorList = (str) => {
   const results = [];
 
-  for (let i = 0; i < str.length;) {
+  for (let i = 0; i < str.length; ) {
     const next = findNext(str, i, [',']);
     results.push(parseComplexSelector(str.substring(i, next)));
     i = next + 1;

From 3b7bac039b19b2b11ee9cd4b2a6416385469a0b8 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 24 Aug 2022 15:33:06 -0700
Subject: [PATCH 43/76] Remove all whitespace chunks next to other combinators.

---
 .../shadydom/src/patches/selector-parser.js   | 23 ++++++++++++-------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/packages/shadydom/src/patches/selector-parser.js b/packages/shadydom/src/patches/selector-parser.js
index 2febdc839..78d6ba35c 100644
--- a/packages/shadydom/src/patches/selector-parser.js
+++ b/packages/shadydom/src/patches/selector-parser.js
@@ -69,14 +69,21 @@ const parseComplexSelector = (str) => {
     }
   }
 
-  // Remove whitespace next to combinators.
-  chunks = chunks.filter((x, i) => {
-    return !(
-      x === ' ' &&
-      (COMBINATORS.includes(chunks[i - 1]) ||
-        COMBINATORS.includes(chunks[i + 1]))
-    );
-  });
+  // Remove whitespace chunks next to other combinators.
+  chunks = chunks.reduce((out, next) => {
+    const prev = out[out.length - 1];
+    if (['>', '+', '~'].includes(prev) && next === ' ') {
+      return out;
+    }
+
+    if (prev === ' ' && ['>', '+', '~'].includes(next)) {
+      out[out.length - 1] = next;
+      return out;
+    }
+
+    out.push(next);
+    return out;
+  }, []);
 
   return {
     compoundSelectors: chunks.filter((x, i) => i % 2 === 0),

From f3d21bc09b031c81951f21afe265632cf5595ed9 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 24 Aug 2022 15:50:49 -0700
Subject: [PATCH 44/76] Perform splitting and whitespace/combinator collapsing
 simultaneously.

---
 .../shadydom/src/patches/selector-parser.js   | 33 +++++++------------
 1 file changed, 11 insertions(+), 22 deletions(-)

diff --git a/packages/shadydom/src/patches/selector-parser.js b/packages/shadydom/src/patches/selector-parser.js
index 78d6ba35c..87f658fc6 100644
--- a/packages/shadydom/src/patches/selector-parser.js
+++ b/packages/shadydom/src/patches/selector-parser.js
@@ -56,34 +56,23 @@ const parseComplexSelector = (str) => {
   /**
    * @type {!Array<string>}
    */
-  let chunks = [];
+  const chunks = [];
 
   for (let i = 0; i < str.length; ) {
-    const next = findNext(str, i, [' ', '>', '~', '+']);
-    if (next === i) {
-      chunks.push(str[i]);
-      i++;
-    } else {
-      chunks.push(str.substring(i, next));
-      i = next;
-    }
-  }
+    const prev = chunks[chunks.length - 1];
+    const nextIndex = findNext(str, i, [' ', '>', '~', '+']);
+    const next = nextIndex === i ? str[i] : str.substring(i, nextIndex);
 
-  // Remove whitespace chunks next to other combinators.
-  chunks = chunks.reduce((out, next) => {
-    const prev = out[out.length - 1];
     if (['>', '+', '~'].includes(prev) && next === ' ') {
-      return out;
-    }
-
-    if (prev === ' ' && ['>', '+', '~'].includes(next)) {
-      out[out.length - 1] = next;
-      return out;
+      // Do nothing.
+    } else if (prev === ' ' && ['>', '+', '~'].includes(next)) {
+      chunks[chunks.length - 1] = next;
+    } else {
+      chunks.push(next);
     }
 
-    out.push(next);
-    return out;
-  }, []);
+    i = nextIndex + (nextIndex === i ? 1 : 0);
+  }
 
   return {
     compoundSelectors: chunks.filter((x, i) => i % 2 === 0),

From b0577adc04b63eaa19fa075cfc5a43b02678d5ec Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 24 Aug 2022 16:22:57 -0700
Subject: [PATCH 45/76] Fix a bug where `findNext`'s return value was being
 used as a length.

---
 packages/shadydom/src/patches/selector-parser.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/shadydom/src/patches/selector-parser.js b/packages/shadydom/src/patches/selector-parser.js
index 87f658fc6..bc714ec42 100644
--- a/packages/shadydom/src/patches/selector-parser.js
+++ b/packages/shadydom/src/patches/selector-parser.js
@@ -35,7 +35,7 @@ const findNext = (str, start, queryChars, matchNestedParens = true) => {
       return i;
     } else if (matchNestedParens && PARENS.has(str[i])) {
       const parenInfo = PARENS.get(str[i]);
-      i += findNext(str, i + 1, [parenInfo.end], parenInfo.matchNestedParens);
+      i = findNext(str, i + 1, [parenInfo.end], parenInfo.matchNestedParens);
       continue;
     }
 

From e68c62fd41e70e45f06a5bdff1e2118c514026e2 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 24 Aug 2022 16:33:34 -0700
Subject: [PATCH 46/76] Fix a bug where consecutive whitespace was not being
 collapsed.

---
 packages/shadydom/src/patches/selector-parser.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/shadydom/src/patches/selector-parser.js b/packages/shadydom/src/patches/selector-parser.js
index bc714ec42..47e23d8f1 100644
--- a/packages/shadydom/src/patches/selector-parser.js
+++ b/packages/shadydom/src/patches/selector-parser.js
@@ -63,7 +63,7 @@ const parseComplexSelector = (str) => {
     const nextIndex = findNext(str, i, [' ', '>', '~', '+']);
     const next = nextIndex === i ? str[i] : str.substring(i, nextIndex);
 
-    if (['>', '+', '~'].includes(prev) && next === ' ') {
+    if ([' ', '>', '+', '~'].includes(prev) && next === ' ') {
       // Do nothing.
     } else if (prev === ' ' && ['>', '+', '~'].includes(next)) {
       chunks[chunks.length - 1] = next;

From e1cfed97ab1782e2c5a8601858b52869f852f050 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 24 Aug 2022 16:42:48 -0700
Subject: [PATCH 47/76] Flatten `parseComplexSelector` into `parseSelectorList`
 to prevent duplicate searches.

---
 .../shadydom/src/patches/selector-parser.js   | 47 ++++++++++---------
 1 file changed, 24 insertions(+), 23 deletions(-)

diff --git a/packages/shadydom/src/patches/selector-parser.js b/packages/shadydom/src/patches/selector-parser.js
index 47e23d8f1..2ac8e7573 100644
--- a/packages/shadydom/src/patches/selector-parser.js
+++ b/packages/shadydom/src/patches/selector-parser.js
@@ -48,22 +48,40 @@ const findNext = (str, start, queryChars, matchNestedParens = true) => {
 
 /**
  * @param {string} str
- * @return {!ComplexSelectorParts}
+ * @return {!Array<!ComplexSelectorParts>}
  */
-const parseComplexSelector = (str) => {
-  str = str.trim();
+export const parseSelectorList = (str) => {
+  /**
+   * @type {!Array<!ComplexSelectorParts>}
+   */
+  const results = [];
 
   /**
    * @type {!Array<string>}
    */
   const chunks = [];
 
+  const complexSelectorBoundary = () => {
+    if (chunks.length > 0) {
+      while (chunks[chunks.length - 1] === ' ') {
+        chunks.pop();
+      }
+      results.push({
+        compoundSelectors: chunks.filter((x, i) => i % 2 === 0),
+        combinators: chunks.filter((x, i) => i % 2 === 1),
+      });
+      chunks.length = 0;
+    }
+  };
+
   for (let i = 0; i < str.length; ) {
     const prev = chunks[chunks.length - 1];
-    const nextIndex = findNext(str, i, [' ', '>', '~', '+']);
+    const nextIndex = findNext(str, i, [',', ' ', '>', '+', '~']);
     const next = nextIndex === i ? str[i] : str.substring(i, nextIndex);
 
-    if ([' ', '>', '+', '~'].includes(prev) && next === ' ') {
+    if (next === ',') {
+      complexSelectorBoundary();
+    } else if ([undefined, ' ', '>', '+', '~'].includes(prev) && next === ' ') {
       // Do nothing.
     } else if (prev === ' ' && ['>', '+', '~'].includes(next)) {
       chunks[chunks.length - 1] = next;
@@ -74,24 +92,7 @@ const parseComplexSelector = (str) => {
     i = nextIndex + (nextIndex === i ? 1 : 0);
   }
 
-  return {
-    compoundSelectors: chunks.filter((x, i) => i % 2 === 0),
-    combinators: chunks.filter((x, i) => i % 2 === 1),
-  };
-};
-
-/**
- * @param {string} str
- * @return {!Array<!ComplexSelectorParts>}
- */
-export const parseSelectorList = (str) => {
-  const results = [];
-
-  for (let i = 0; i < str.length; ) {
-    const next = findNext(str, i, [',']);
-    results.push(parseComplexSelector(str.substring(i, next)));
-    i = next + 1;
-  }
+  complexSelectorBoundary();
 
   return results;
 };

From a2b116a70e1c9f4e3c4a829cac11b32364068c4b Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 24 Aug 2022 17:40:10 -0700
Subject: [PATCH 48/76] `includes(...)` -> `indexOf(...) !== -1`

---
 packages/shadydom/src/patches/selector-parser.js | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/packages/shadydom/src/patches/selector-parser.js b/packages/shadydom/src/patches/selector-parser.js
index 2ac8e7573..22a581f0b 100644
--- a/packages/shadydom/src/patches/selector-parser.js
+++ b/packages/shadydom/src/patches/selector-parser.js
@@ -31,7 +31,7 @@ const findNext = (str, start, queryChars, matchNestedParens = true) => {
     if (str[i] === '\\' && i < str.length - 1 && str[i + 1] !== '\n') {
       // Skip escaped character.
       i++;
-    } else if (queryChars.includes(str[i])) {
+    } else if (queryChars.indexOf(str[i]) !== -1) {
       return i;
     } else if (matchNestedParens && PARENS.has(str[i])) {
       const parenInfo = PARENS.get(str[i]);
@@ -81,9 +81,12 @@ export const parseSelectorList = (str) => {
 
     if (next === ',') {
       complexSelectorBoundary();
-    } else if ([undefined, ' ', '>', '+', '~'].includes(prev) && next === ' ') {
+    } else if (
+      [undefined, ' ', '>', '+', '~'].indexOf(prev) !== -1 &&
+      next === ' '
+    ) {
       // Do nothing.
-    } else if (prev === ' ' && ['>', '+', '~'].includes(next)) {
+    } else if (prev === ' ' && ['>', '+', '~'].indexOf(next) !== -1) {
       chunks[chunks.length - 1] = next;
     } else {
       chunks.push(next);

From fc375f0d7dd38178f7c8102ec2255ec5e28f814a Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Mon, 29 Aug 2022 12:12:56 -0700
Subject: [PATCH 49/76] Add comments for the selector parser.

---
 .../shadydom/src/patches/selector-parser.js   | 77 +++++++++++++------
 1 file changed, 54 insertions(+), 23 deletions(-)

diff --git a/packages/shadydom/src/patches/selector-parser.js b/packages/shadydom/src/patches/selector-parser.js
index 22a581f0b..2fa51a2eb 100644
--- a/packages/shadydom/src/patches/selector-parser.js
+++ b/packages/shadydom/src/patches/selector-parser.js
@@ -1,15 +1,10 @@
 /**
- * Arrays of compound selectors and combinators that form a complex selector
- * when interleaved.
+ * A map describing parentheses-like grouping characters and their behavior. The
+ * keys are the group's start character and the value's `end` property contains
+ * the end character. The `matchNestedParens` property indicates whether or not
+ * other grouping characters nested in the group retain their grouping behavior
+ * within that group - i.e. if nested grouping characters need to be matched.
  *
- * @typedef {{
- *   compoundSelectors: !Array<string>,
- *   combinators: !Array<string>,
- * }}
- */
-export let ComplexSelectorParts;
-
-/**
  * @type {!Map<string, {end: string, matchNestedParens: boolean}>}
  */
 const PARENS = new Map([
@@ -20,6 +15,13 @@ const PARENS = new Map([
 ]);
 
 /**
+ * Finds the first character of `queryChars` within `str` from index `start`
+ * onwards that is _not_ nested within any parentheses, brackets, or
+ * single/double-quoted strings or part of an escape sequence.
+ *
+ * If the end of the string is reached without finding a character in
+ * `queryChars`, the length of the string is returned.
+ *
  * @param {string} str
  * @param {number} start
  * @param {!Array<string>} queryChars
@@ -29,11 +31,13 @@ const PARENS = new Map([
 const findNext = (str, start, queryChars, matchNestedParens = true) => {
   for (let i = start; i < str.length; i++) {
     if (str[i] === '\\' && i < str.length - 1 && str[i + 1] !== '\n') {
-      // Skip escaped character.
+      // Skip escape sequences.
       i++;
     } else if (queryChars.indexOf(str[i]) !== -1) {
+      // One of `queryChars` was found.
       return i;
     } else if (matchNestedParens && PARENS.has(str[i])) {
+      // Handle any grouping characters by skipping over the group.
       const parenInfo = PARENS.get(str[i]);
       i = findNext(str, i + 1, [parenInfo.end], parenInfo.matchNestedParens);
       continue;
@@ -47,6 +51,20 @@ const findNext = (str, start, queryChars, matchNestedParens = true) => {
 };
 
 /**
+ * Arrays of compound selectors and combinators that form a complex selector
+ * when interleaved.
+ *
+ * @typedef {{
+ *   compoundSelectors: !Array<string>,
+ *   combinators: !Array<string>,
+ * }}
+ */
+export let ComplexSelectorParts;
+
+/**
+ * Splits a selector list into individual complex selectors and creates a
+ * `ComplexSelectorParts` for each.
+ *
  * @param {string} str
  * @return {!Array<!ComplexSelectorParts>}
  */
@@ -57,11 +75,18 @@ export const parseSelectorList = (str) => {
   const results = [];
 
   /**
+   * Compound selectors and combinators parsed from the current complex
+   * selector.
+   *
    * @type {!Array<string>}
    */
   const chunks = [];
 
-  const complexSelectorBoundary = () => {
+  /**
+   * Creates a new `ComplexSelectorParts` from the current `chunks`, pushes it
+   * into `results` and resets `chunks`.
+   */
+  const endComplexSelector = () => {
     if (chunks.length > 0) {
       while (chunks[chunks.length - 1] === ' ') {
         chunks.pop();
@@ -75,27 +100,33 @@ export const parseSelectorList = (str) => {
   };
 
   for (let i = 0; i < str.length; ) {
-    const prev = chunks[chunks.length - 1];
+    const prevChunk = chunks[chunks.length - 1];
+    // `nextIndex` is the next complex selector boundary, combinator, or
+    // whitespace that isn't inside other grouping characters.
     const nextIndex = findNext(str, i, [',', ' ', '>', '+', '~']);
-    const next = nextIndex === i ? str[i] : str.substring(i, nextIndex);
+    // If `nextIndex` is `i`, then the chunk we're considering is only the next
+    // single character.
+    const nextChunk = nextIndex === i ? str[i] : str.substring(i, nextIndex);
 
-    if (next === ',') {
-      complexSelectorBoundary();
+    if (nextChunk === ',') {
+      endComplexSelector();
     } else if (
-      [undefined, ' ', '>', '+', '~'].indexOf(prev) !== -1 &&
-      next === ' '
+      [undefined, ' ', '>', '+', '~'].indexOf(prevChunk) !== -1 &&
+      nextChunk === ' '
     ) {
-      // Do nothing.
-    } else if (prev === ' ' && ['>', '+', '~'].indexOf(next) !== -1) {
-      chunks[chunks.length - 1] = next;
+      // Ignore leading whitespace and whitespace directly after combinators.
+    } else if (prevChunk === ' ' && ['>', '+', '~'].indexOf(nextChunk) !== -1) {
+      // If the last chunk was whitespace and this chunk is a non-whitespace
+      // combinator, replace the whitespace with this combinator.
+      chunks[chunks.length - 1] = nextChunk;
     } else {
-      chunks.push(next);
+      chunks.push(nextChunk);
     }
 
     i = nextIndex + (nextIndex === i ? 1 : 0);
   }
 
-  complexSelectorBoundary();
+  endComplexSelector();
 
   return results;
 };

From 9a745de117ee6ae30740832e1cfc1320f339c793 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Mon, 29 Aug 2022 13:47:52 -0700
Subject: [PATCH 50/76] Move the selector parser out of `patches/`.

---
 packages/shadydom/src/patches/ParentNode.js            | 2 +-
 packages/shadydom/src/{patches => }/selector-parser.js | 0
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename packages/shadydom/src/{patches => }/selector-parser.js (100%)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index f75fec197..e5eb1eede 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -10,7 +10,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 
 import * as utils from '../utils.js';
 import {shadyDataForNode} from '../shady-data.js';
-import {ComplexSelectorParts, parseSelectorList} from './selector-parser.js';
+import {ComplexSelectorParts, parseSelectorList} from '../selector-parser.js';
 
 /**
  * @param {Node} node
diff --git a/packages/shadydom/src/patches/selector-parser.js b/packages/shadydom/src/selector-parser.js
similarity index 100%
rename from packages/shadydom/src/patches/selector-parser.js
rename to packages/shadydom/src/selector-parser.js

From 648c217a600dea41c2b7f02601da0de177895aab Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Mon, 29 Aug 2022 13:50:00 -0700
Subject: [PATCH 51/76] Update a comment.

---
 packages/shadydom/src/patches/ParentNode.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index e5eb1eede..e46e1f398 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -151,8 +151,8 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
 
   /**
    * Determines if a single compound selector matches an element. If the
-   * selector contains `:scope` (as a substring), then `element` must be
-   * `contextElement`.
+   * selector contains `:scope` (as a substring), then the selector only is only
+   * considered matching if `element` is `contextElement`.
    *
    * @param {!Element} element
    * @param {string} compoundSelector

From afc74064db947d049ab033d6783f25570b84e6fa Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Mon, 29 Aug 2022 16:32:35 -0700
Subject: [PATCH 52/76] Add known limitations to the docs for the
 `querySelectorImplementation` setting.

---
 packages/shadydom/src/shadydom.js | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/packages/shadydom/src/shadydom.js b/packages/shadydom/src/shadydom.js
index abffbef1c..a6e1f4b9c 100644
--- a/packages/shadydom/src/shadydom.js
+++ b/packages/shadydom/src/shadydom.js
@@ -164,8 +164,33 @@ if (utils.settings.inUse) {
     //   this option preserves the semantics of `:scope` by only considering
     //   compound selectors containing `:scope` to be matching if the context
     //   element of the `matches` call is also the context element of the
-    //   wrapper call. (Note that this implementation detects `:scope` by simple
-    //   substring inclusion.)
+    //   wrapper call.
+    //
+    //   However, the parser used for this option is not strictly correct.
+    //   Notable caveats include:
+    //
+    //     - The parser assumes the selector list it's given is syntactically
+    //     correct. When given a selector that would not parse under a full
+    //     implementation, this implementation may fail silently.
+    //
+    //     - Only top-level combinators and compound selectors are taken into
+    //     consideration while walking the tree. Each top-level compound
+    //     selector is tested against candidate elements as a whole, without
+    //     modification. This means that selectors nested in arguments of
+    //     functional pseudo-classes (e.g. `a > b` in `:is(a > b)`) are still
+    //     matched by the browser against the real tree, not Shady DOM's logical
+    //     tree.
+    //
+    //     - `:scope` is only supported at the top-level. Particularly, if the
+    //     text `:scope` appears anywhere within a compound selector, then the
+    //     selector engine will only allow that compound selector to match the
+    //     context element. Having the text `:scope` inside a string
+    //     (`x[y=":scope"]`) or an argument to a functional pseudo-selector
+    //     (`:not(:scope > x)`) will likely break your selector.
+    //
+    //     - Comments are not supported. (e.g. `a /* b */ c`)
+    //
+    //     - The (draft) column combinator is not supported. (e.g. `a || b`)
     'querySelectorImplementation':
       utils.settings['querySelectorImplementation'],
   };

From 91ec51d5f8949481e0ce24d740dc7f7296901e6a Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Tue, 30 Aug 2022 10:55:29 -0700
Subject: [PATCH 53/76] Add a change log entry.

---
 packages/shadydom/CHANGELOG.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/packages/shadydom/CHANGELOG.md b/packages/shadydom/CHANGELOG.md
index 0ab856e95..0a53feedb 100644
--- a/packages/shadydom/CHANGELOG.md
+++ b/packages/shadydom/CHANGELOG.md
@@ -28,6 +28,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   original event as its prototype so that it can update `currentTarget` without
   modifying the built-in property descriptor.
   ([#519](https://github.com/webcomponents/polyfills/pull/519))
+- Fix `:scope` in `querySelector{,All}` by traversing the logical tree manually
+  to match selectors.
+  ([#517](https://github.com/webcomponents/polyfills/pull/517))
 
 ## [1.9.0] - 2021-08-02
 

From aed3dcdeb12b983c0d54d5213dc32c12eac621a3 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Tue, 30 Aug 2022 15:49:50 -0700
Subject: [PATCH 54/76] Add tests for escape sequences and nested commas.

---
 packages/tests/shadydom/shady-dynamic.html | 183 +++++++++++++++++++++
 1 file changed, 183 insertions(+)

diff --git a/packages/tests/shadydom/shady-dynamic.html b/packages/tests/shadydom/shady-dynamic.html
index 394ad350f..54b435395 100644
--- a/packages/tests/shadydom/shady-dynamic.html
+++ b/packages/tests/shadydom/shady-dynamic.html
@@ -453,6 +453,72 @@
       defineTestElement('x-query-selector-scope');
     </script>
 
+    <template id="x-query-selector-parser-escape-single-quotes">
+      <div with-single-quote="a'b" decoy></div>
+      <div another-attr decoy></div>
+      <div with-single-quote="a'b" another-attr></div>
+    </template>
+    <script>
+      defineTestElement('x-query-selector-parser-escape-single-quotes');
+    </script>
+
+    <template id="x-query-selector-parser-escape-double-quotes">
+      <div with-double-quote='a"b' decoy></div>
+      <div another-attr decoy></div>
+      <div with-double-quote='a"b' another-attr></div>
+    </template>
+    <script>
+      defineTestElement('x-query-selector-parser-escape-double-quotes');
+    </script>
+
+    <template id="x-query-selector-parser-escape-brackets">
+      <div with-bracket] decoy></div>
+      <div another-attr decoy></div>
+      <div with-bracket] another-attr></div>
+    </template>
+    <script>
+      defineTestElement('x-query-selector-parser-escape-brackets');
+    </script>
+
+    <template id="x-query-selector-parser-escape-parens">
+      <div with-paren) decoy></div>
+      <div without-paren></div>
+    </template>
+    <script>
+      defineTestElement('x-query-selector-parser-escape-parens');
+    </script>
+
+    <template id="x-query-selector-parser-comma-in-attr-name">
+      <div comma-in-name-, decoy></div>
+      <div another-attr decoy></div>
+      <div comma-in-name-, another-attr></div>
+    </template>
+    <script>
+      defineTestElement('x-query-selector-parser-comma-in-attr-name');
+    </script>
+
+    <template id="x-query-selector-parser-comma-in-attr-value">
+      <div comma-in-value="," decoy></div>
+      <div another-attr decoy></div>
+      <some-name another-attr decoy></some-name>
+      <another-name another-attr decoy></another-name>
+      <div comma-in-value="," another-attr></div>
+    </template>
+    <script>
+      defineTestElement('x-query-selector-parser-comma-in-attr-value');
+    </script>
+
+    <template id="x-query-selector-parser-plain-attrs">
+      <div some-attr decoy></div>
+      <div another-attr decoy></div>
+      <some-name another-attr decoy></some-name>
+      <another-name another-attr decoy></another-name>
+      <div some-attr another-attr></div>
+    </template>
+    <script>
+      defineTestElement('x-query-selector-parser-plain-attrs');
+    </script>
+
     <script>
       'use strict';
 
@@ -3136,6 +3202,123 @@
             assert.equal(results[0].id, 'target');
           }
         });
+
+        suite('parseSelectorList', function () {
+          test('Escape sequences are handled in single-quoted strings.', function () {
+            const host = createEnabledElement(
+              'x-query-selector-parser-escape-single-quotes'
+            );
+            const result = host.shadowRoot.querySelector(
+              "div[with-single-quote='a\\'b'][another-attr]"
+            );
+            assert(result);
+            assert(!result.hasAttribute('decoy'));
+            assert.equal(result.getAttribute('with-single-quote'), "a'b");
+            assert(result.hasAttribute('another-attr'));
+          });
+
+          test('Escape sequences are handled in double-quoted strings.', function () {
+            const host = createEnabledElement(
+              'x-query-selector-parser-escape-double-quotes'
+            );
+            const result = host.shadowRoot.querySelector(
+              'div[with-double-quote="a\\"b"][another-attr]'
+            );
+            assert(result);
+            assert(!result.hasAttribute('decoy'));
+            assert.equal(result.getAttribute('with-double-quote'), 'a"b');
+            assert(result.hasAttribute('another-attr'));
+          });
+
+          test('Escape sequences are handled in brackets.', function () {
+            const host = createEnabledElement(
+              'x-query-selector-parser-escape-brackets'
+            );
+            const result = host.shadowRoot.querySelector(
+              'div[with-bracket\\]][another-attr]'
+            );
+            assert(result);
+            assert(!result.hasAttribute('decoy'));
+            assert(result.hasAttribute('with-bracket]'));
+            assert(result.hasAttribute('another-attr'));
+          });
+
+          test('Escape sequences are handled in parentheses.', function () {
+            const host = createEnabledElement(
+              'x-query-selector-parser-escape-parens'
+            );
+            const result = host.shadowRoot.querySelector(
+              ':not([with-paren\\)])[without-paren]'
+            );
+            assert(result);
+            assert(!result.hasAttribute('decoy'));
+            assert(!result.hasAttribute('with-paren)'));
+            assert(result.hasAttribute('without-paren'));
+          });
+
+          test('Commas nested in single-quoted strings do not split top-level complex selectors.', function () {
+            const host = createEnabledElement(
+              'x-query-selector-parser-comma-in-attr-value'
+            );
+            const result = host.shadowRoot.querySelector(
+              "div[comma-in-value=','][another-attr]"
+            );
+            assert(result);
+            assert(!result.hasAttribute('decoy'));
+            assert.equal(result.getAttribute('comma-in-value'), ',');
+            assert(result.hasAttribute('another-attr'));
+          });
+
+          test('Commas nested in double-quoted strings do not split top-level complex selectors.', function () {
+            const host = createEnabledElement(
+              'x-query-selector-parser-comma-in-attr-value'
+            );
+            const result = host.shadowRoot.querySelector(
+              'div[comma-in-value=","][another-attr]'
+            );
+            assert(result);
+            assert(!result.hasAttribute('decoy'));
+            assert.equal(result.getAttribute('comma-in-value'), ',');
+            assert(result.hasAttribute('another-attr'));
+          });
+
+          test('Commas nested in parentheses do not split top-level complex selectors.', function () {
+            // Only run this test in browsers that support selector lists as
+            // arguments to functional pseudo-classes.
+            try {
+              document.querySelector(':not(abc, def)');
+            } catch (e) {
+              this.skip();
+              return;
+            }
+
+            const host = createEnabledElement(
+              'x-query-selector-parser-plain-attrs'
+            );
+            const result = host.shadowRoot.querySelector(
+              'div[some-attr]:not(some-name, another-name)[another-attr]'
+            );
+            assert(result);
+            assert(!result.hasAttribute('decoy'));
+            assert(result.hasAttribute('some-attr'));
+            assert(result.hasAttribute('another-attr'));
+          });
+
+          test('Commas nested in brackets do not split top-level complex selectors.', function () {
+            const host = createEnabledElement(
+              'x-query-selector-parser-comma-in-attr-name'
+            );
+            // This is really a test for escape sequences, since commas aren't
+            // valid inside brackets without being escaped.
+            const result = host.shadowRoot.querySelector(
+              'div[comma-in-name-\\,][another-attr]'
+            );
+            assert(result);
+            assert(!result.hasAttribute('decoy'));
+            assert(result.hasAttribute('comma-in-name-,'));
+            assert(result.hasAttribute('another-attr'));
+          });
+        });
       });
     </script>
   </body>

From d60bbbbcbfb6967d1df84330e5ab0ba6af5bccdb Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Tue, 30 Aug 2022 16:12:08 -0700
Subject: [PATCH 55/76] Test that whitespace surrounding compound selectors and
 combinators is optional.

---
 packages/tests/shadydom/shady-dynamic.html | 59 ++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/packages/tests/shadydom/shady-dynamic.html b/packages/tests/shadydom/shady-dynamic.html
index 54b435395..c96807cb4 100644
--- a/packages/tests/shadydom/shady-dynamic.html
+++ b/packages/tests/shadydom/shady-dynamic.html
@@ -519,6 +519,18 @@
       defineTestElement('x-query-selector-parser-plain-attrs');
     </script>
 
+    <template id="x-query-selector-parser-optional-whitespace">
+      <div decoy>
+        <div another-attr decoy></div>
+        <some-name another-attr decoy></some-name>
+        <another-name another-attr decoy></another-name>
+        <div some-attr another-attr></div>
+      </div>
+    </template>
+    <script>
+      defineTestElement('x-query-selector-parser-optional-whitespace');
+    </script>
+
     <script>
       'use strict';
 
@@ -3318,6 +3330,53 @@
             assert(result.hasAttribute('comma-in-name-,'));
             assert(result.hasAttribute('another-attr'));
           });
+
+          test('Whitespace surrounding compound selectors and combinators is optional.', function () {
+            const host = createEnabledElement(
+              'x-query-selector-parser-optional-whitespace'
+            );
+
+            [
+              'div>[some-attr][another-attr]',
+              'div>[some-attr][another-attr] ',
+              'div> [some-attr][another-attr]',
+              'div> [some-attr][another-attr] ',
+              'div >[some-attr][another-attr]',
+              'div >[some-attr][another-attr] ',
+              'div > [some-attr][another-attr]',
+              'div > [some-attr][another-attr] ',
+              ' div>[some-attr][another-attr]',
+              ' div>[some-attr][another-attr] ',
+              ' div> [some-attr][another-attr]',
+              ' div> [some-attr][another-attr] ',
+              ' div >[some-attr][another-attr]',
+              ' div >[some-attr][another-attr] ',
+              ' div > [some-attr][another-attr]',
+              ' div > [some-attr][another-attr] ',
+              'div>[some-attr][another-attr]',
+              'div>[some-attr][another-attr]    ',
+              'div>    [some-attr][another-attr]',
+              'div>    [some-attr][another-attr]    ',
+              'div    >[some-attr][another-attr]',
+              'div    >[some-attr][another-attr]    ',
+              'div    >    [some-attr][another-attr]',
+              'div    >    [some-attr][another-attr]    ',
+              '    div>[some-attr][another-attr]',
+              '    div>[some-attr][another-attr]    ',
+              '    div>    [some-attr][another-attr]',
+              '    div>    [some-attr][another-attr]    ',
+              '    div    >[some-attr][another-attr]',
+              '    div    >[some-attr][another-attr]    ',
+              '    div    >    [some-attr][another-attr]',
+              '    div    >    [some-attr][another-attr]    ',
+            ].forEach((selector) => {
+              const result = host.shadowRoot.querySelector(selector);
+              assert(result);
+              assert(!result.hasAttribute('decoy'));
+              assert(result.hasAttribute('some-attr'));
+              assert(result.hasAttribute('another-attr'));
+            });
+          });
         });
       });
     </script>

From 565ce0c6a8af8e2e3d8c9ddeb4c64718879fbdbe Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Tue, 30 Aug 2022 16:51:36 -0700
Subject: [PATCH 56/76] Use `ShadyDOM.wrapIfNeeded(...)` on hosts before
 getting shadow roots.

---
 packages/tests/shadydom/shady-dynamic.html | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/packages/tests/shadydom/shady-dynamic.html b/packages/tests/shadydom/shady-dynamic.html
index c96807cb4..b95ae729a 100644
--- a/packages/tests/shadydom/shady-dynamic.html
+++ b/packages/tests/shadydom/shady-dynamic.html
@@ -3220,7 +3220,7 @@
             const host = createEnabledElement(
               'x-query-selector-parser-escape-single-quotes'
             );
-            const result = host.shadowRoot.querySelector(
+            const result = ShadyDOM.wrapIfNeeded(host).shadowRoot.querySelector(
               "div[with-single-quote='a\\'b'][another-attr]"
             );
             assert(result);
@@ -3233,7 +3233,7 @@
             const host = createEnabledElement(
               'x-query-selector-parser-escape-double-quotes'
             );
-            const result = host.shadowRoot.querySelector(
+            const result = ShadyDOM.wrapIfNeeded(host).shadowRoot.querySelector(
               'div[with-double-quote="a\\"b"][another-attr]'
             );
             assert(result);
@@ -3246,7 +3246,7 @@
             const host = createEnabledElement(
               'x-query-selector-parser-escape-brackets'
             );
-            const result = host.shadowRoot.querySelector(
+            const result = ShadyDOM.wrapIfNeeded(host).shadowRoot.querySelector(
               'div[with-bracket\\]][another-attr]'
             );
             assert(result);
@@ -3259,7 +3259,7 @@
             const host = createEnabledElement(
               'x-query-selector-parser-escape-parens'
             );
-            const result = host.shadowRoot.querySelector(
+            const result = ShadyDOM.wrapIfNeeded(host).shadowRoot.querySelector(
               ':not([with-paren\\)])[without-paren]'
             );
             assert(result);
@@ -3272,7 +3272,7 @@
             const host = createEnabledElement(
               'x-query-selector-parser-comma-in-attr-value'
             );
-            const result = host.shadowRoot.querySelector(
+            const result = ShadyDOM.wrapIfNeeded(host).shadowRoot.querySelector(
               "div[comma-in-value=','][another-attr]"
             );
             assert(result);
@@ -3285,7 +3285,7 @@
             const host = createEnabledElement(
               'x-query-selector-parser-comma-in-attr-value'
             );
-            const result = host.shadowRoot.querySelector(
+            const result = ShadyDOM.wrapIfNeeded(host).shadowRoot.querySelector(
               'div[comma-in-value=","][another-attr]'
             );
             assert(result);
@@ -3307,7 +3307,7 @@
             const host = createEnabledElement(
               'x-query-selector-parser-plain-attrs'
             );
-            const result = host.shadowRoot.querySelector(
+            const result = ShadyDOM.wrapIfNeeded(host).shadowRoot.querySelector(
               'div[some-attr]:not(some-name, another-name)[another-attr]'
             );
             assert(result);
@@ -3322,7 +3322,7 @@
             );
             // This is really a test for escape sequences, since commas aren't
             // valid inside brackets without being escaped.
-            const result = host.shadowRoot.querySelector(
+            const result = ShadyDOM.wrapIfNeeded(host).shadowRoot.querySelector(
               'div[comma-in-name-\\,][another-attr]'
             );
             assert(result);
@@ -3337,6 +3337,7 @@
             );
 
             [
+              // All permutations with 1 space.
               'div>[some-attr][another-attr]',
               'div>[some-attr][another-attr] ',
               'div> [some-attr][another-attr]',
@@ -3353,6 +3354,7 @@
               ' div >[some-attr][another-attr] ',
               ' div > [some-attr][another-attr]',
               ' div > [some-attr][another-attr] ',
+              // All permutations with 4 spaces.
               'div>[some-attr][another-attr]',
               'div>[some-attr][another-attr]    ',
               'div>    [some-attr][another-attr]',
@@ -3370,7 +3372,9 @@
               '    div    >    [some-attr][another-attr]',
               '    div    >    [some-attr][another-attr]    ',
             ].forEach((selector) => {
-              const result = host.shadowRoot.querySelector(selector);
+              const result = ShadyDOM.wrapIfNeeded(
+                host
+              ).shadowRoot.querySelector(selector);
               assert(result);
               assert(!result.hasAttribute('decoy'));
               assert(result.hasAttribute('some-attr'));

From f8c4fafe0eb903302872a0e7a93536dd89c280ee Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Tue, 30 Aug 2022 16:56:25 -0700
Subject: [PATCH 57/76] Only run the `shady-dynamic.html` test suite with the
 selector engine.

---
 packages/tests/shadydom/runner.html | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/packages/tests/shadydom/runner.html b/packages/tests/shadydom/runner.html
index 47f1177e5..1cbfd27ea 100644
--- a/packages/tests/shadydom/runner.html
+++ b/packages/tests/shadydom/runner.html
@@ -26,6 +26,12 @@
     'shady-dynamic.html?forceCustomElements=true',
     'shady-dynamic.html?noPatch=true&forceCustomElements=true',
     'shady-dynamic.html?noPatch=on-demand&forceCustomElements=true',
+    'shady-dynamic.html?querySelectorImplementation=selectorEngine',
+    'shady-dynamic.html?noPatch=true&querySelectorImplementation=selectorEngine',
+    'shady-dynamic.html?noPatch=on-demand&querySelectorImplementation=selectorEngine',
+    'shady-dynamic.html?forceCustomElements=true&querySelectorImplementation=selectorEngine',
+    'shady-dynamic.html?noPatch=true&forceCustomElements=true&querySelectorImplementation=selectorEngine',
+    'shady-dynamic.html?noPatch=on-demand&forceCustomElements=true&querySelectorImplementation=selectorEngine',
 
     'shady-content.html',
     'shady-content.html?noPatch=true',
@@ -74,12 +80,7 @@
     'filter-mutations.html',
     'native-access.html',
     'prefer-performance.html',
-  ].reduce((acc, item) => {
-    acc.push(item);
-    const joiner = item.indexOf('?') !== -1 ? '&' : '?';
-    acc.push(item + joiner + 'querySelectorImplementation=selectorEngine');
-    return acc;
-  }, []);
+  ];
 
   // test only under native custom elements.
   if (window.customElements) {

From 658f53aa7a5bf757c8852de67421ea1da422e45c Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Tue, 30 Aug 2022 17:06:43 -0700
Subject: [PATCH 58/76] Fix lint warnings.

---
 packages/shadydom/src/patches/ParentNode.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index e46e1f398..a713bb9f7 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -10,7 +10,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 
 import * as utils from '../utils.js';
 import {shadyDataForNode} from '../shady-data.js';
-import {ComplexSelectorParts, parseSelectorList} from '../selector-parser.js';
+import {ComplexSelectorParts, parseSelectorList} from '../selector-parser.js'; // eslint-disable-line @typescript-eslint/no-unused-vars
 
 /**
  * @param {Node} node
@@ -187,7 +187,7 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
    *   index: number,
    * }}
    */
-  let SelectorMatchingCursor;
+  let SelectorMatchingCursor; // eslint-disable-line @typescript-eslint/no-unused-vars
 
   /**
    * The list of `SelectorMatchingCursor`s, initialized with cursors pointing at

From a4024501ffa3ca21540d5bfb1c12750a16dcecda Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Tue, 30 Aug 2022 18:00:40 -0700
Subject: [PATCH 59/76] IE 11 doesn't support `Map`'s constructor parameter.

---
 packages/shadydom/src/selector-parser.js | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/packages/shadydom/src/selector-parser.js b/packages/shadydom/src/selector-parser.js
index 2fa51a2eb..0603ed227 100644
--- a/packages/shadydom/src/selector-parser.js
+++ b/packages/shadydom/src/selector-parser.js
@@ -7,12 +7,16 @@
  *
  * @type {!Map<string, {end: string, matchNestedParens: boolean}>}
  */
-const PARENS = new Map([
+const PARENS = new Map();
+// IE 11 doesn't support `Map`'s constructor parameter.
+[
   ['(', {end: ')', matchNestedParens: true}],
   ['[', {end: ']', matchNestedParens: true}],
   ['"', {end: '"', matchNestedParens: false}],
   ["'", {end: "'", matchNestedParens: false}],
-]);
+].forEach(([k, v]) => {
+  PARENS.set(k, v);
+});
 
 /**
  * Finds the first character of `queryChars` within `str` from index `start`

From 32075fb7051d69afb77acd783804126c250c6eb7 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Tue, 30 Aug 2022 18:09:40 -0700
Subject: [PATCH 60/76] Test native selector support using Shady DOM's stored
 copy of `querySelector`.

---
 packages/tests/shadydom/shady-dynamic.html | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/tests/shadydom/shady-dynamic.html b/packages/tests/shadydom/shady-dynamic.html
index b95ae729a..4cf486e14 100644
--- a/packages/tests/shadydom/shady-dynamic.html
+++ b/packages/tests/shadydom/shady-dynamic.html
@@ -3298,7 +3298,10 @@
             // Only run this test in browsers that support selector lists as
             // arguments to functional pseudo-classes.
             try {
-              document.querySelector(':not(abc, def)');
+              ShadyDOM.nativeMethods.querySelector.call(
+                document,
+                ':not(abc, def)'
+              );
             } catch (e) {
               this.skip();
               return;

From 59e6ce98ec54b180eb7ffa4f98b3ebec94bf34fa Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 31 Aug 2022 15:01:12 -0700
Subject: [PATCH 61/76] Test that results from queries with selector lists are
 in document order.

---
 packages/tests/shadydom/shady-dynamic.html | 31 ++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/packages/tests/shadydom/shady-dynamic.html b/packages/tests/shadydom/shady-dynamic.html
index 4cf486e14..396058884 100644
--- a/packages/tests/shadydom/shady-dynamic.html
+++ b/packages/tests/shadydom/shady-dynamic.html
@@ -433,6 +433,19 @@
       defineTestElement('x-query-selector-subsequent-sibling-combinator');
     </script>
 
+    <template id="x-query-selector-results-order">
+      <div id="contextElement">
+        <div id="a"></div>
+        <div id="b"></div>
+        <div id="c"></div>
+        <div id="d"></div>
+        <div id="e"></div>
+      </div>
+    </template>
+    <script>
+      defineTestElement('x-query-selector-results-order');
+    </script>
+
     <template id="x-slot-inside-div">
       <div>
         <slot></slot>
@@ -3184,6 +3197,24 @@
           }
         });
 
+        test('Results from queries with selector lists are in document order.', function () {
+          const host = createEnabledElement('x-query-selector-results-order');
+          const contextElement = ShadyDOM.wrapIfNeeded(
+            host
+          ).shadowRoot.getElementById('contextElement');
+
+          const results = ShadyDOM.wrap(contextElement).querySelectorAll(
+            '#b, #e, #a, #c, #d'
+          );
+
+          assert.equal(results.length, 5);
+          assert.equal(results[0].id, 'a');
+          assert.equal(results[1].id, 'b');
+          assert.equal(results[2].id, 'c');
+          assert.equal(results[3].id, 'd');
+          assert.equal(results[4].id, 'e');
+        });
+
         test('The semantics of `:scope` are preserved.', function () {
           // Skip if `:scope` isn't natively supported.
           try {

From 2f36c0642bca55fb860688cf00e66a2c11a7fcb6 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 31 Aug 2022 15:13:54 -0700
Subject: [PATCH 62/76] Use a template in a test instead of building the tree
 manually.

---
 packages/tests/shadydom/shady-dynamic.html | 32 ++++++++++++++++------
 1 file changed, 23 insertions(+), 9 deletions(-)

diff --git a/packages/tests/shadydom/shady-dynamic.html b/packages/tests/shadydom/shady-dynamic.html
index 396058884..9b8df5094 100644
--- a/packages/tests/shadydom/shady-dynamic.html
+++ b/packages/tests/shadydom/shady-dynamic.html
@@ -433,6 +433,19 @@
       defineTestElement('x-query-selector-subsequent-sibling-combinator');
     </script>
 
+    <template id="x-query-selector-child-selector-through-shadow-hosts">
+      <div id="contextElement">
+        <x-slot-inside-div>
+          <x-slot-inside-div>
+            <div target-element></div>
+          </x-slot-inside-div>
+        </x-slot-inside-div>
+      </div>
+    </template>
+    <script>
+      defineTestElement('x-query-selector-child-selector-through-shadow-hosts');
+    </script>
+
     <template id="x-query-selector-results-order">
       <div id="contextElement">
         <div id="a"></div>
@@ -3176,15 +3189,16 @@
         });
 
         test('The `>` combinator can match shadow root hosts with their children.', function () {
-          const layer1 = createEnabledElement('x-slot-inside-div');
-          const layer2 = createEnabledElement('x-slot-inside-div');
-          ShadyDOM.wrapIfNeeded(layer1).appendChild(layer2);
-          const target = document.createElement('div');
-          ShadyDOM.wrapIfNeeded(layer2).appendChild(target);
-
-          const results = ShadyDOM.wrapIfNeeded(layer1).querySelectorAll(
-            'x-slot-inside-div > x-slot-inside-div > div'
+          const host = createEnabledElement(
+            'x-query-selector-child-selector-through-shadow-hosts'
           );
+          const contextElement = ShadyDOM.wrapIfNeeded(
+            host
+          ).shadowRoot.getElementById('contextElement');
+
+          const results = ShadyDOM.wrapIfNeeded(
+            contextElement
+          ).querySelectorAll('x-slot-inside-div > x-slot-inside-div > div');
 
           if (!querySelectorImplementation) {
             // The default implementation can't find the target because of the
@@ -3193,7 +3207,7 @@
             assert.equal(results.length, 0);
           } else if (querySelectorImplementation === 'selectorEngine') {
             assert.equal(results.length, 1);
-            assert.equal(results[0], target);
+            assert(results[0].hasAttribute('target-element'));
           }
         });
 

From 199a201e0dc7104b11f2fbc4f7b2d53f8bfa8eea Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 31 Aug 2022 15:20:13 -0700
Subject: [PATCH 63/76] Use `ShadyDOM.wrapIfNeeded(...)` where necessary.

---
 packages/tests/shadydom/shady-dynamic.html | 26 +++++++++++++---------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/packages/tests/shadydom/shady-dynamic.html b/packages/tests/shadydom/shady-dynamic.html
index 9b8df5094..1b327a388 100644
--- a/packages/tests/shadydom/shady-dynamic.html
+++ b/packages/tests/shadydom/shady-dynamic.html
@@ -3118,9 +3118,9 @@
             host
           ).shadowRoot.getElementById('contextElement');
 
-          const results = contextElement.querySelectorAll(
-            '#contextElement [match]'
-          );
+          const results = ShadyDOM.wrapIfNeeded(
+            contextElement
+          ).querySelectorAll('#contextElement [match]');
 
           // No shadow root hosts below #contextElement or use of `:scope`, so
           // the results are the same for all implementations.
@@ -3138,9 +3138,9 @@
             host
           ).shadowRoot.getElementById('contextElement');
 
-          const results = contextElement.querySelectorAll(
-            '#contextElement > *'
-          );
+          const results = ShadyDOM.wrapIfNeeded(
+            contextElement
+          ).querySelectorAll('#contextElement > *');
 
           // No shadow root hosts below #contextElement or use of `:scope`, so
           // the results are the same for all implementations.
@@ -3158,7 +3158,9 @@
             host
           ).shadowRoot.getElementById('contextElement');
 
-          const results = contextElement.querySelectorAll('[before] + *');
+          const results = ShadyDOM.wrapIfNeeded(
+            contextElement
+          ).querySelectorAll('[before] + *');
 
           // No shadow root hosts below #contextElement or use of `:scope`, so
           // the results are the same for all implementations.
@@ -3176,7 +3178,9 @@
             host
           ).shadowRoot.getElementById('contextElement');
 
-          const results = contextElement.querySelectorAll('[before] ~ *');
+          const results = ShadyDOM.wrapIfNeeded(
+            contextElement
+          ).querySelectorAll('[before] ~ *');
 
           // No shadow root hosts below #contextElement or use of `:scope`, so
           // the results are the same for all implementations.
@@ -3217,9 +3221,9 @@
             host
           ).shadowRoot.getElementById('contextElement');
 
-          const results = ShadyDOM.wrap(contextElement).querySelectorAll(
-            '#b, #e, #a, #c, #d'
-          );
+          const results = ShadyDOM.wrapIfNeeded(
+            contextElement
+          ).querySelectorAll('#b, #e, #a, #c, #d');
 
           assert.equal(results.length, 5);
           assert.equal(results[0].id, 'a');

From 0fc78a1cff7e87ab50d6c9c1ed1979aa8eebe3f5 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Wed, 31 Aug 2022 15:29:23 -0700
Subject: [PATCH 64/76] Add `ShadyDOM.flush();` before querying in tests.

---
 packages/tests/shadydom/shady-dynamic.html | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/packages/tests/shadydom/shady-dynamic.html b/packages/tests/shadydom/shady-dynamic.html
index 1b327a388..1e7ef05f8 100644
--- a/packages/tests/shadydom/shady-dynamic.html
+++ b/packages/tests/shadydom/shady-dynamic.html
@@ -3118,6 +3118,7 @@
             host
           ).shadowRoot.getElementById('contextElement');
 
+          ShadyDOM.flush();
           const results = ShadyDOM.wrapIfNeeded(
             contextElement
           ).querySelectorAll('#contextElement [match]');
@@ -3138,6 +3139,7 @@
             host
           ).shadowRoot.getElementById('contextElement');
 
+          ShadyDOM.flush();
           const results = ShadyDOM.wrapIfNeeded(
             contextElement
           ).querySelectorAll('#contextElement > *');
@@ -3158,6 +3160,7 @@
             host
           ).shadowRoot.getElementById('contextElement');
 
+          ShadyDOM.flush();
           const results = ShadyDOM.wrapIfNeeded(
             contextElement
           ).querySelectorAll('[before] + *');
@@ -3178,6 +3181,7 @@
             host
           ).shadowRoot.getElementById('contextElement');
 
+          ShadyDOM.flush();
           const results = ShadyDOM.wrapIfNeeded(
             contextElement
           ).querySelectorAll('[before] ~ *');
@@ -3200,6 +3204,7 @@
             host
           ).shadowRoot.getElementById('contextElement');
 
+          ShadyDOM.flush();
           const results = ShadyDOM.wrapIfNeeded(
             contextElement
           ).querySelectorAll('x-slot-inside-div > x-slot-inside-div > div');
@@ -3221,6 +3226,7 @@
             host
           ).shadowRoot.getElementById('contextElement');
 
+          ShadyDOM.flush();
           const results = ShadyDOM.wrapIfNeeded(
             contextElement
           ).querySelectorAll('#b, #e, #a, #c, #d');
@@ -3249,6 +3255,7 @@
             host
           ).shadowRoot.getElementById('contextElement');
 
+          ShadyDOM.flush();
           const results = ShadyDOM.wrap(contextElement).querySelectorAll(
             'div:scope > div'
           );
@@ -3269,6 +3276,7 @@
             const host = createEnabledElement(
               'x-query-selector-parser-escape-single-quotes'
             );
+            ShadyDOM.flush();
             const result = ShadyDOM.wrapIfNeeded(host).shadowRoot.querySelector(
               "div[with-single-quote='a\\'b'][another-attr]"
             );
@@ -3282,6 +3290,7 @@
             const host = createEnabledElement(
               'x-query-selector-parser-escape-double-quotes'
             );
+            ShadyDOM.flush();
             const result = ShadyDOM.wrapIfNeeded(host).shadowRoot.querySelector(
               'div[with-double-quote="a\\"b"][another-attr]'
             );
@@ -3295,6 +3304,7 @@
             const host = createEnabledElement(
               'x-query-selector-parser-escape-brackets'
             );
+            ShadyDOM.flush();
             const result = ShadyDOM.wrapIfNeeded(host).shadowRoot.querySelector(
               'div[with-bracket\\]][another-attr]'
             );
@@ -3308,6 +3318,7 @@
             const host = createEnabledElement(
               'x-query-selector-parser-escape-parens'
             );
+            ShadyDOM.flush();
             const result = ShadyDOM.wrapIfNeeded(host).shadowRoot.querySelector(
               ':not([with-paren\\)])[without-paren]'
             );
@@ -3321,6 +3332,7 @@
             const host = createEnabledElement(
               'x-query-selector-parser-comma-in-attr-value'
             );
+            ShadyDOM.flush();
             const result = ShadyDOM.wrapIfNeeded(host).shadowRoot.querySelector(
               "div[comma-in-value=','][another-attr]"
             );
@@ -3334,6 +3346,7 @@
             const host = createEnabledElement(
               'x-query-selector-parser-comma-in-attr-value'
             );
+            ShadyDOM.flush();
             const result = ShadyDOM.wrapIfNeeded(host).shadowRoot.querySelector(
               'div[comma-in-value=","][another-attr]'
             );
@@ -3359,6 +3372,7 @@
             const host = createEnabledElement(
               'x-query-selector-parser-plain-attrs'
             );
+            ShadyDOM.flush();
             const result = ShadyDOM.wrapIfNeeded(host).shadowRoot.querySelector(
               'div[some-attr]:not(some-name, another-name)[another-attr]'
             );
@@ -3372,6 +3386,7 @@
             const host = createEnabledElement(
               'x-query-selector-parser-comma-in-attr-name'
             );
+            ShadyDOM.flush();
             // This is really a test for escape sequences, since commas aren't
             // valid inside brackets without being escaped.
             const result = ShadyDOM.wrapIfNeeded(host).shadowRoot.querySelector(
@@ -3388,6 +3403,7 @@
               'x-query-selector-parser-optional-whitespace'
             );
 
+            ShadyDOM.flush();
             [
               // All permutations with 1 space.
               'div>[some-attr][another-attr]',

From faa3fc1970fc27480f077615a631096efeb04158 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Thu, 8 Sep 2022 13:44:45 -0700
Subject: [PATCH 65/76] Reorder an expression to take advantage of
 short-circuiting.

---
 packages/shadydom/src/patches/ParentNode.js | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index a713bb9f7..88eb9031a 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -160,8 +160,9 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
    */
   const matchesCompoundSelector = (element, compoundSelector) => {
     return (
-      utils.matchesSelector(element, compoundSelector) &&
-      (compoundSelector.indexOf(':scope') === -1 || element === contextElement)
+      (element === contextElement ||
+        compoundSelector.indexOf(':scope') === -1) &&
+      utils.matchesSelector(element, compoundSelector)
     );
   };
 

From 86eb168a688d6a81c74686c42ffeb29820c791b7 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Thu, 8 Sep 2022 13:53:35 -0700
Subject: [PATCH 66/76] `position` -> `matchedElement`

---
 packages/shadydom/src/patches/ParentNode.js | 50 ++++++++++-----------
 1 file changed, 25 insertions(+), 25 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index 88eb9031a..e470e7f3c 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -175,16 +175,16 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
    * - `complexSelectorParts` is the decomposed version of the selector that
    * this cursor is attempting to match.
    *
-   * - `position` is an element that matches a compound selector in
+   * - `matchedElement` is an element that matches a compound selector in
    * `complexSelectorParts`.
    *
    * - `index` is the index of the compound selector in `complexSelectorParts`
-   * that matched `position`.
+   * that matched `matchedElement`.
    *
    * @typedef {{
    *   target: !Element,
    *   complexSelectorParts: !ComplexSelectorParts,
-   *   position: !Element,
+   *   matchedElement: !Element,
    *   index: number,
    * }}
    */
@@ -207,7 +207,7 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
             return {
               target: element,
               complexSelectorParts,
-              position: element,
+              matchedElement: element,
               index,
             };
           } else {
@@ -232,7 +232,7 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
 
         const {
           target,
-          position,
+          matchedElement,
           complexSelectorParts,
           index: lastIndex,
         } = cursor;
@@ -243,11 +243,11 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
         if (combinator === ' ') {
           const results = [];
 
-          // For `a b`, where existing cursors have `position`s matching `b`,
-          // the candidates to test against `a` are all ancestors each cursor's
-          // `position`.
+          // For `a b`, where existing cursors have `matchedElement`s matching
+          // `b`, the candidates to test against `a` are all ancestors each
+          // cursor's `matchedElement`.
           for (
-            let ancestor = position[utils.SHADY_PREFIX + 'parentNode'];
+            let ancestor = matchedElement[utils.SHADY_PREFIX + 'parentNode'];
             ancestor && ancestor instanceof Element;
             ancestor = ancestor[utils.SHADY_PREFIX + 'parentNode']
           ) {
@@ -255,7 +255,7 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
               results.push({
                 target,
                 complexSelectorParts,
-                position: ancestor,
+                matchedElement: ancestor,
                 index,
               });
             }
@@ -263,11 +263,11 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
 
           return results;
         } else if (combinator === '>') {
-          const parent = position[utils.SHADY_PREFIX + 'parentNode'];
+          const parent = matchedElement[utils.SHADY_PREFIX + 'parentNode'];
 
-          // For `a > b`, where existing cursors have `position`s matching `b`,
-          // the candidates to test against `a` are the parents of each cursor's
-          // `position`.
+          // For `a > b`, where existing cursors have `matchedElement`s matching
+          // `b`, the candidates to test against `a` are the parents of each
+          // cursor's `matchedElement`.
           if (
             parent &&
             parent instanceof Element &&
@@ -276,7 +276,7 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
             return {
               target,
               complexSelectorParts,
-              position: parent,
+              matchedElement: parent,
               index,
             };
           }
@@ -284,16 +284,16 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
           return [];
         } else if (combinator === '+') {
           const sibling =
-            position[utils.SHADY_PREFIX + 'previousElementSibling'];
+            matchedElement[utils.SHADY_PREFIX + 'previousElementSibling'];
 
-          // For `a + b`, where existing cursors have `position`s matching `b`,
-          // the candidates to test against `a` are the immediately preceding
-          // siblings of each cursor's `position`.
+          // For `a + b`, where existing cursors have `matchedElement`s matching
+          // `b`, the candidates to test against `a` are the immediately
+          // preceding siblings of each cursor's `matchedElement`.
           if (sibling && matchesCompoundSelector(sibling, compoundSelector)) {
             return {
               target,
               complexSelectorParts,
-              position: sibling,
+              matchedElement: sibling,
               index,
             };
           }
@@ -302,12 +302,12 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
         } else if (combinator === '~') {
           const results = [];
 
-          // For `a ~ b`, where existing cursors have `position`s matching `b`,
-          // the candidates to test against `a` are all preceding siblings of
-          // each cursor's `position`.
+          // For `a ~ b`, where existing cursors have `matchedElement`s matching
+          // `b`, the candidates to test against `a` are all preceding siblings
+          // of each cursor's `matchedElement`.
           for (
             let sibling =
-              position[utils.SHADY_PREFIX + 'previousElementSibling'];
+              matchedElement[utils.SHADY_PREFIX + 'previousElementSibling'];
             sibling;
             sibling = sibling[utils.SHADY_PREFIX + 'previousElementSibling']
           ) {
@@ -315,7 +315,7 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
               results.push({
                 target,
                 complexSelectorParts,
-                position: sibling,
+                matchedElement: sibling,
                 index,
               });
             }

From 87028ba5fdd780f88d0dbb424f3fafe6042742b6 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Thu, 8 Sep 2022 14:03:14 -0700
Subject: [PATCH 67/76] Add a comment explaining why selectors are iterated
 backwards while matching.

---
 packages/shadydom/src/patches/ParentNode.js | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index e470e7f3c..1ef36486b 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -202,6 +202,12 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
       return utils.flat(
         complexSelectors.map((complexSelectorParts) => {
           const {compoundSelectors} = complexSelectorParts;
+          // Selectors are matched by iterating their compound selectors in
+          // reverse order for efficiency. In particular, when finding
+          // candidates for the descendant combinator, iterating forwards would
+          // imply needing to walk all descendants of the last matched element
+          // for possible candidates, but iterating backwards only requires
+          // walking up the ancestor chain.
           const index = compoundSelectors.length - 1;
           if (matchesCompoundSelector(element, compoundSelectors[index])) {
             return {

From 386c48c9dc5a713ad4535d9a1efecb94bf35b48b Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Thu, 8 Sep 2022 14:20:43 -0700
Subject: [PATCH 68/76] Use `parentElement` instead of `parentNode` while
 searching for candidates.

---
 packages/shadydom/src/patches/ParentNode.js | 16 ++++++----------
 1 file changed, 6 insertions(+), 10 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index 1ef36486b..06f621b69 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -250,12 +250,12 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
           const results = [];
 
           // For `a b`, where existing cursors have `matchedElement`s matching
-          // `b`, the candidates to test against `a` are all ancestors each
+          // `b`, the candidates to test against `a` are all ancestors of each
           // cursor's `matchedElement`.
           for (
-            let ancestor = matchedElement[utils.SHADY_PREFIX + 'parentNode'];
-            ancestor && ancestor instanceof Element;
-            ancestor = ancestor[utils.SHADY_PREFIX + 'parentNode']
+            let ancestor = matchedElement[utils.SHADY_PREFIX + 'parentElement'];
+            ancestor;
+            ancestor = ancestor[utils.SHADY_PREFIX + 'parentElement']
           ) {
             if (matchesCompoundSelector(ancestor, compoundSelector)) {
               results.push({
@@ -269,16 +269,12 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
 
           return results;
         } else if (combinator === '>') {
-          const parent = matchedElement[utils.SHADY_PREFIX + 'parentNode'];
+          const parent = matchedElement[utils.SHADY_PREFIX + 'parentElement'];
 
           // For `a > b`, where existing cursors have `matchedElement`s matching
           // `b`, the candidates to test against `a` are the parents of each
           // cursor's `matchedElement`.
-          if (
-            parent &&
-            parent instanceof Element &&
-            matchesCompoundSelector(parent, compoundSelector)
-          ) {
+          if (matchesCompoundSelector(parent, compoundSelector)) {
             return {
               target,
               complexSelectorParts,

From b5548b2948f74922788e2b1dcb8a74118e9b598c Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Thu, 8 Sep 2022 14:21:38 -0700
Subject: [PATCH 69/76] Note in the docs that `:host` and `:host-context` are
 not supported.

---
 packages/shadydom/src/shadydom.js | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/shadydom/src/shadydom.js b/packages/shadydom/src/shadydom.js
index a6e1f4b9c..69b812b59 100644
--- a/packages/shadydom/src/shadydom.js
+++ b/packages/shadydom/src/shadydom.js
@@ -188,6 +188,8 @@ if (utils.settings.inUse) {
     //     (`x[y=":scope"]`) or an argument to a functional pseudo-selector
     //     (`:not(:scope > x)`) will likely break your selector.
     //
+    //     - The `:host` and `:host-context` pseudo-classes are not supported.
+    //
     //     - Comments are not supported. (e.g. `a /* b */ c`)
     //
     //     - The (draft) column combinator is not supported. (e.g. `a || b`)

From ab9dda1936e13c8d5954c61a8896e708b2712531 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Thu, 8 Sep 2022 14:27:58 -0700
Subject: [PATCH 70/76] Remove an outdated comment.

---
 packages/shadydom/src/patches/ParentNode.js | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index 06f621b69..f21742259 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -341,7 +341,6 @@ const querySelectorImplementation =
   utils.settings['querySelectorImplementation'];
 
 export const QueryPatches = utils.getOwnPropertyDescriptors({
-  // TODO(sorvell): consider doing native QSA and filtering results.
   /**
    * @this {Element}
    * @param  {string} selector

From 52103e574565703c0ba5454aa71a3769f9e648d7 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Thu, 8 Sep 2022 16:32:46 -0700
Subject: [PATCH 71/76] Fix the wrappers using the 'native' option and enable
 and update tests for this case.

---
 packages/shadydom/src/patches/ParentNode.js |  20 ++--
 packages/tests/shadydom/runner.html         |   6 +
 packages/tests/shadydom/shady-dynamic.html  | 119 ++++++++++++++------
 3 files changed, 106 insertions(+), 39 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index f21742259..77701835f 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -347,15 +347,19 @@ export const QueryPatches = utils.getOwnPropertyDescriptors({
    */
   querySelector(selector) {
     if (querySelectorImplementation === 'native') {
+      // Polyfilled `ShadowRoot`s don't have a native `querySelectorAll`.
+      const target = this instanceof ShadowRoot ? this.host : this;
       const candidates = Array.prototype.slice.call(
-        this[utils.NATIVE_PREFIX + 'querySelector'](selector)
+        target[utils.NATIVE_PREFIX + 'querySelectorAll'](selector)
       );
       const root = this[utils.SHADY_PREFIX + 'getRootNode']();
-      return utils.createPolyfilledHTMLCollection(
-        candidates.filter(
-          (e) => e[utils.SHADY_PREFIX + 'getRootNode']() == root
-        )
-      );
+      // This could use `find`, but Closure doesn't polyfill it.
+      for (const candidate of candidates) {
+        if (candidate[utils.SHADY_PREFIX + 'getRootNode']() == root) {
+          return candidate;
+        }
+      }
+      return null;
     } else if (querySelectorImplementation === 'selectorEngine') {
       return logicalQuerySelectorAll(this, selector)[0] || null;
     } else if (querySelectorImplementation === undefined) {
@@ -388,8 +392,10 @@ export const QueryPatches = utils.getOwnPropertyDescriptors({
   // https://github.com/webcomponents/shadydom/pull/210#issuecomment-361435503
   querySelectorAll(selector, useNative) {
     if (useNative || querySelectorImplementation === 'native') {
+      // Polyfilled `ShadowRoot`s don't have a native `querySelectorAll`.
+      const target = this instanceof ShadowRoot ? this.host : this;
       const candidates = Array.prototype.slice.call(
-        this[utils.NATIVE_PREFIX + 'querySelectorAll'](selector)
+        target[utils.NATIVE_PREFIX + 'querySelectorAll'](selector)
       );
       const root = this[utils.SHADY_PREFIX + 'getRootNode']();
       return utils.createPolyfilledHTMLCollection(
diff --git a/packages/tests/shadydom/runner.html b/packages/tests/shadydom/runner.html
index 1cbfd27ea..dc32bafdc 100644
--- a/packages/tests/shadydom/runner.html
+++ b/packages/tests/shadydom/runner.html
@@ -32,6 +32,12 @@
     'shady-dynamic.html?forceCustomElements=true&querySelectorImplementation=selectorEngine',
     'shady-dynamic.html?noPatch=true&forceCustomElements=true&querySelectorImplementation=selectorEngine',
     'shady-dynamic.html?noPatch=on-demand&forceCustomElements=true&querySelectorImplementation=selectorEngine',
+    'shady-dynamic.html?querySelectorImplementation=native',
+    'shady-dynamic.html?noPatch=true&querySelectorImplementation=native',
+    'shady-dynamic.html?noPatch=on-demand&querySelectorImplementation=native',
+    'shady-dynamic.html?forceCustomElements=true&querySelectorImplementation=native',
+    'shady-dynamic.html?noPatch=true&forceCustomElements=true&querySelectorImplementation=native',
+    'shady-dynamic.html?noPatch=on-demand&forceCustomElements=true&querySelectorImplementation=native',
 
     'shady-content.html',
     'shady-content.html?noPatch=true',
diff --git a/packages/tests/shadydom/shady-dynamic.html b/packages/tests/shadydom/shady-dynamic.html
index 1e7ef05f8..2e8bb72ae 100644
--- a/packages/tests/shadydom/shady-dynamic.html
+++ b/packages/tests/shadydom/shady-dynamic.html
@@ -141,13 +141,15 @@
       };
     </script>
 
-    <template id="x-project"> x-project: [<slot></slot>] </template>
+    <template id="x-project">
+      x-project: [<slot id="theSlot"></slot>]
+    </template>
     <script>
       defineTestElement('x-project');
     </script>
 
     <template id="x-reproject">
-      <x-project>x-reproject: [<slot></slot>]</x-project>
+      <x-project>x-reproject: [<slot id="theSlot"></slot>]</x-project>
     </template>
 
     <script>
@@ -155,7 +157,7 @@
     </script>
 
     <template id="x-rereproject">
-      <x-reproject>x-rereproject: [<slot></slot>]</x-reproject>
+      <x-reproject>x-rereproject: [<slot id="theSlot"></slot>]</x-reproject>
     </template>
 
     <script>
@@ -223,7 +225,7 @@
       defineTestElement('x-compose');
     </script>
 
-    <template id="x-echo"><slot></slot></template>
+    <template id="x-echo"><slot id="theSlot"></slot></template>
     <script>
       defineTestElement('x-echo');
     </script>
@@ -248,7 +250,11 @@
     </script>
 
     <template id="x-select-attr">
-      Foo: [<slot name="foo"></slot>] Bar: [<slot name="bar"></slot>]
+      Foo: [<slot id="slotFoo" name="foo"></slot>] Bar: [<slot
+        id="slotBar"
+        name="bar"
+      ></slot
+      >]
     </template>
     <script>
       defineTestElement('x-select-attr');
@@ -647,16 +653,34 @@
             ShadyDOM.wrapIfNeeded(rere).shadowRoot
           ).querySelectorAll('*');
           assert.include(rereList, re);
-          assert.equal(rereList.length, 2);
+          if (ShadyDOM.querySelectorImplementation === 'native') {
+            // The `<slot>` in the shadow root does not exist in the real tree,
+            // so the native `querySelectorAll` will not see it.
+            assert.equal(rereList.length, 1);
+          } else {
+            assert.equal(rereList.length, 2);
+          }
           var reList = ShadyDOM.wrapIfNeeded(
             ShadyDOM.wrapIfNeeded(re).shadowRoot
           ).querySelectorAll('*');
           assert.include(reList, p);
-          assert.equal(reList.length, 2);
+          if (ShadyDOM.querySelectorImplementation === 'native') {
+            // The `<slot>` in the shadow root does not exist in the real tree,
+            // so the native `querySelectorAll` will not see it.
+            assert.equal(reList.length, 1);
+          } else {
+            assert.equal(reList.length, 2);
+          }
           var pList = ShadyDOM.wrapIfNeeded(
             ShadyDOM.wrapIfNeeded(p).shadowRoot
           ).querySelectorAll('*');
-          assert.equal(pList.length, 1);
+          if (ShadyDOM.querySelectorImplementation === 'native') {
+            // The `<slot>` in the shadow root does not exist in the real tree,
+            // so the native `querySelectorAll` will not see it.
+            assert.equal(pList.length, 0);
+          } else {
+            assert.equal(pList.length, 1);
+          }
         });
 
         test('shadowRoot.getElementById', function () {
@@ -696,8 +720,12 @@
             ShadyDOM.wrapIfNeeded(rere).querySelector('#projected'),
             projected
           );
-          assert(ShadyDOM.wrapIfNeeded(re).querySelector('slot'));
-          assert(ShadyDOM.wrapIfNeeded(p).querySelector('slot'));
+          // The `<slot>`s in these shadow roots do not exist in the real tree,
+          // so the native `querySelectorAll` will not see it.
+          if (ShadyDOM.querySelectorImplementation !== 'native') {
+            assert(ShadyDOM.wrapIfNeeded(re).querySelector('slot'));
+            assert(ShadyDOM.wrapIfNeeded(p).querySelector('slot'));
+          }
         });
 
         test('element.querySelectorAll', function () {
@@ -717,8 +745,15 @@
             ShadyDOM.wrapIfNeeded(rere).querySelectorAll('#projected')[0],
             projected
           );
-          assert(ShadyDOM.wrapIfNeeded(re).querySelectorAll('slot').length, 1);
-          assert(ShadyDOM.wrapIfNeeded(p).querySelectorAll('slot').length, 1);
+          // The `<slot>`s in these shadow root do not exist in the real tree,
+          // so the native `querySelectorAll` will not see it.
+          if (ShadyDOM.querySelectorImplementation !== 'native') {
+            assert(
+              ShadyDOM.wrapIfNeeded(re).querySelectorAll('slot').length,
+              1
+            );
+            assert(ShadyDOM.wrapIfNeeded(p).querySelectorAll('slot').length, 1);
+          }
         });
 
         test('ShadyDOM.wrapIfNeeded(document).querySelector', function () {
@@ -758,21 +793,21 @@
           ShadyDOM.flush();
           var c1 = ShadyDOM.wrapIfNeeded(
             ShadyDOM.wrapIfNeeded(rere).shadowRoot
-          ).querySelector('slot');
+          ).getElementById('theSlot');
           assert.include(
             ShadyDOM.wrapIfNeeded(c1).assignedNodes({flatten: true}),
             projected
           );
           var c2 = ShadyDOM.wrapIfNeeded(
             ShadyDOM.wrapIfNeeded(re).shadowRoot
-          ).querySelector('slot');
+          ).getElementById('theSlot');
           assert.include(
             ShadyDOM.wrapIfNeeded(c2).assignedNodes({flatten: true}),
             projected
           );
           var c3 = ShadyDOM.wrapIfNeeded(
             ShadyDOM.wrapIfNeeded(p).shadowRoot
-          ).querySelector('slot');
+          ).getElementById('theSlot');
           assert.include(
             ShadyDOM.wrapIfNeeded(c3).assignedNodes({flatten: true}),
             projected
@@ -791,19 +826,19 @@
           ).querySelector('x-rereproject');
           var c1 = ShadyDOM.wrapIfNeeded(
             ShadyDOM.wrapIfNeeded(rere).shadowRoot
-          ).querySelector('slot');
+          ).getElementById('theSlot');
           var re = ShadyDOM.wrapIfNeeded(
             ShadyDOM.wrapIfNeeded(rere).shadowRoot
           ).querySelector('x-reproject');
           var c2 = ShadyDOM.wrapIfNeeded(
             ShadyDOM.wrapIfNeeded(re).shadowRoot
-          ).querySelector('slot');
+          ).getElementById('theSlot');
           var p = ShadyDOM.wrapIfNeeded(
             ShadyDOM.wrapIfNeeded(re).shadowRoot
           ).querySelector('x-project');
           var c3 = ShadyDOM.wrapIfNeeded(
             ShadyDOM.wrapIfNeeded(p).shadowRoot
-          ).querySelector('slot');
+          ).getElementById('theSlot');
           var ip$ = [c1, c2, c3];
           if (testElement.shadyRoot) {
             testElement.shadyRoot.update();
@@ -838,21 +873,23 @@
           var e = ShadyDOM.wrapIfNeeded(document).querySelector(
             'x-select-attr'
           );
-          var ip$ = ShadyDOM.wrapIfNeeded(
+          var xSelectAttrShadowRoot = ShadyDOM.wrapIfNeeded(
             ShadyDOM.wrapIfNeeded(e).shadowRoot
-          ).querySelectorAll('slot');
+          );
+          var slotFoo = xSelectAttrShadowRoot.getElementById('slotFoo');
+          var slotBar = xSelectAttrShadowRoot.getElementById('slotBar');
           var c = ShadyDOM.wrapIfNeeded(e).firstElementChild;
           ShadyDOM.flush();
           assert.equal(
             allInsertionPoints(c)[0],
-            ip$[1],
+            slotBar,
             'child not distributed based on host attribute'
           );
           ShadyDOM.wrapIfNeeded(c).slot = 'foo';
           ShadyDOM.flush();
           assert.equal(
             allInsertionPoints(c)[0],
-            ip$[0],
+            slotFoo,
             'child not distributed based on reflecting attribute'
           );
           ShadyDOM.wrapIfNeeded(c).slot = '';
@@ -868,34 +905,36 @@
           var e = ShadyDOM.wrapIfNeeded(document).querySelector(
             'x-compose-select-attr'
           );
-          var ip$ = ShadyDOM.wrapIfNeeded(
+          var xSelectAttrShadowRoot = ShadyDOM.wrapIfNeeded(
             ShadyDOM.wrapIfNeeded(
               ShadyDOM.wrapIfNeeded(
                 ShadyDOM.wrapIfNeeded(e).shadowRoot
               ).querySelector('#select')
             ).shadowRoot
-          ).querySelectorAll('slot');
+          );
+          var slotFoo = xSelectAttrShadowRoot.getElementById('slotFoo');
+          var slotBar = xSelectAttrShadowRoot.getElementById('slotBar');
           var c1 = ShadyDOM.wrapIfNeeded(
             ShadyDOM.wrapIfNeeded(e).shadowRoot
           ).querySelector('#attr1');
           ShadyDOM.flush();
           assert.equal(
             allInsertionPoints(c1)[0],
-            ip$[1],
+            slotBar,
             'child not distributed based on host attribute'
           );
           ShadyDOM.wrapIfNeeded(c1).slot = 'foo';
           ShadyDOM.flush();
           assert.equal(
             allInsertionPoints(c1)[0],
-            ip$[0],
+            slotFoo,
             'child not distributed based on reflecting attribute'
           );
           ShadyDOM.wrapIfNeeded(c1).slot = 'bar';
           ShadyDOM.flush();
           assert.equal(
             allInsertionPoints(c1)[0],
-            ip$[1],
+            slotBar,
             'child not distributed based on reflecting attribute'
           );
           var c2 = ShadyDOM.wrapIfNeeded(
@@ -904,7 +943,7 @@
           ShadyDOM.flush();
           assert.equal(
             allInsertionPoints(c2)[0],
-            ip$[0],
+            slotFoo,
             'child not distributed based on default value'
           );
         });
@@ -917,6 +956,10 @@
           s.id = 'added';
           ShadyDOM.wrapIfNeeded(s).textContent = 'Added';
           ShadyDOM.wrapIfNeeded(rere).appendChild(s);
+          // Nodes must be distributed to be seen by the native `querySelector`.
+          if (ShadyDOM.querySelectorImplementation === 'native') {
+            ShadyDOM.flush();
+          }
           assert.equal(
             ShadyDOM.wrapIfNeeded(
               ShadyDOM.wrapIfNeeded(testElement).shadowRoot
@@ -936,6 +979,10 @@
           s.id = 'added2';
           ShadyDOM.wrapIfNeeded(s).textContent = 'Added2';
           ShadyDOM.wrapIfNeeded(rere).insertBefore(s, ref);
+          // Nodes must be distributed to be seen by the native `querySelector`.
+          if (ShadyDOM.querySelectorImplementation === 'native') {
+            ShadyDOM.flush();
+          }
           assert.equal(
             ShadyDOM.wrapIfNeeded(
               ShadyDOM.wrapIfNeeded(testElement).shadowRoot
@@ -1205,6 +1252,10 @@
           s.id = 'light';
           ShadyDOM.wrapIfNeeded(s).textContent = 'Light';
           ShadyDOM.wrapIfNeeded(rere).appendChild(s);
+          // Nodes must be distributed to be seen by the native `querySelector`.
+          if (ShadyDOM.querySelectorImplementation === 'native') {
+            ShadyDOM.flush();
+          }
           assert.equal(ShadyDOM.wrapIfNeeded(rere).querySelector('#light'), s);
           assert.equal(ShadyDOM.wrapIfNeeded(s).parentNode, rere);
           assert.notEqual(ShadyDOM.nativeTree.parentNode(s), rere);
@@ -1633,6 +1684,10 @@
         });
 
         test('shadowRoot.appendChild element with slot child and shadowRoot with slot pending distribution', function () {
+          // Nodes must be distributed to be seen by the native `querySelector`.
+          if (ShadyDOM.querySelectorImplementation === 'native') {
+            this.skip();
+          }
           var outerElement = ShadyDOM.wrapIfNeeded(document).querySelector(
             'outer-element'
           );
@@ -2644,7 +2699,7 @@
               allInsertionPoints(child)[0],
               ShadyDOM.wrapIfNeeded(
                 ShadyDOM.wrapIfNeeded(d).shadowRoot
-              ).querySelector('#notTestContent'),
+              ).getElementById('notTestContent'),
               'child not distributed logically'
             );
           }
@@ -2653,7 +2708,7 @@
               allInsertionPoints(child)[0],
               ShadyDOM.wrapIfNeeded(
                 ShadyDOM.wrapIfNeeded(d).shadowRoot
-              ).querySelector('#testContent'),
+              ).getElementById('testContent'),
               'child not distributed logically'
             );
           }
@@ -3094,8 +3149,8 @@
           ShadyDOM.flush();
           const el = d.firstElementChild;
           assert.equal(el.childNodes.length, 4);
-          const slot = ShadyDOM.wrapIfNeeded(el).shadowRoot.querySelector(
-            'slot'
+          const slot = ShadyDOM.wrapIfNeeded(el).shadowRoot.getElementById(
+            'theSlot'
           );
           for (let i = 0; i < el.childNodes.length; i++) {
             const child = el.childNodes[i];

From f0c953b69f5fa263e8d5477e6591a9aa70a4a8f3 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Thu, 8 Sep 2022 17:03:01 -0700
Subject: [PATCH 72/76] Update a comment for clarity.

---
 packages/shadydom/src/shadydom.js | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/packages/shadydom/src/shadydom.js b/packages/shadydom/src/shadydom.js
index 69b812b59..de9a920c5 100644
--- a/packages/shadydom/src/shadydom.js
+++ b/packages/shadydom/src/shadydom.js
@@ -119,11 +119,12 @@ if (utils.settings.inUse) {
     'nativeTree': nativeTree,
     'patchElementProto': patchElementProto,
     // Use this setting to choose the implementation of `querySelector` and
-    // `querySelectorAll`. The logical tree exposed by Shady DOM via the DOM
-    // APIs it wraps doesn't match the structure of the tree seen by the browser
-    // (the 'real tree'), so the level to which the browser itself is used to
-    // match selectors (which always happens against the real tree) affects the
-    // accuracy and performance of these wrappers.
+    // `querySelectorAll`. The options provide different tradeoffs between
+    // accuracy and performance, as explained below. More specifically, the
+    // logical tree exposed by Shady DOM through the DOM APIs it wraps doesn't
+    // match the structure of the tree seen by the browser (the 'real tree'), so
+    // the degree to which the browser itself is used to match selectors affects
+    // this tradeoff.
     //
     // - `undefined` (default): Shady DOM will walk the logical descendants of
     // the context element and call `matches` with the given selector to find

From 39868fe5848cedcfefca82365d4bd3b1f67c28b3 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Thu, 8 Sep 2022 17:20:19 -0700
Subject: [PATCH 73/76] Update a comment for clarity.

---
 packages/shadydom/src/shadydom.js | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/packages/shadydom/src/shadydom.js b/packages/shadydom/src/shadydom.js
index de9a920c5..cb7304240 100644
--- a/packages/shadydom/src/shadydom.js
+++ b/packages/shadydom/src/shadydom.js
@@ -174,13 +174,12 @@ if (utils.settings.inUse) {
     //     correct. When given a selector that would not parse under a full
     //     implementation, this implementation may fail silently.
     //
-    //     - Only top-level combinators and compound selectors are taken into
-    //     consideration while walking the tree. Each top-level compound
-    //     selector is tested against candidate elements as a whole, without
-    //     modification. This means that selectors nested in arguments of
-    //     functional pseudo-classes (e.g. `a > b` in `:is(a > b)`) are still
-    //     matched by the browser against the real tree, not Shady DOM's logical
-    //     tree.
+    //     - Nested selectors are _not_ taken into consideration while walking
+    //     the tree. Each outer-most compound selector is tested against
+    //     candidate elements as a whole, without modification. This means that
+    //     selectors nested in arguments of functional pseudo-classes, such as
+    //     `a > b` in `:is(a > b)`, are still matched by the browser against the
+    //     real tree, not Shady DOM's logical tree.
     //
     //     - `:scope` is only supported at the top-level. Particularly, if the
     //     text `:scope` appears anywhere within a compound selector, then the

From 67076d539ac772945543305360fdbfb8b0df39d2 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Thu, 8 Sep 2022 17:48:56 -0700
Subject: [PATCH 74/76] Tree-walking tests now check results of both
 `querySelector` and `querySelectorAll`. (...)

The `parseSelectorList` tests are not included since they're specifically for
determining if the certain selectors are parsed as expected, rather than finding
elements.
---
 packages/tests/shadydom/shady-dynamic.html | 164 +++++++++++++++------
 1 file changed, 119 insertions(+), 45 deletions(-)

diff --git a/packages/tests/shadydom/shady-dynamic.html b/packages/tests/shadydom/shady-dynamic.html
index 2e8bb72ae..78c691c89 100644
--- a/packages/tests/shadydom/shady-dynamic.html
+++ b/packages/tests/shadydom/shady-dynamic.html
@@ -3174,16 +3174,25 @@
           ).shadowRoot.getElementById('contextElement');
 
           ShadyDOM.flush();
-          const results = ShadyDOM.wrapIfNeeded(
-            contextElement
-          ).querySelectorAll('#contextElement [match]');
 
           // No shadow root hosts below #contextElement or use of `:scope`, so
           // the results are the same for all implementations.
-          assert.equal(results.length, 3);
-          assert.equal(results[0].id, 'a');
-          assert.equal(results[1].id, 'b');
-          assert.equal(results[2].id, 'c');
+
+          const resultQS = ShadyDOM.wrapIfNeeded(contextElement).querySelector(
+            '#contextElement [match]'
+          );
+
+          assert(resultQS);
+          assert(resultQS.id, 'a');
+
+          const resultsQSA = ShadyDOM.wrapIfNeeded(
+            contextElement
+          ).querySelectorAll('#contextElement [match]');
+
+          assert.equal(resultsQSA.length, 3);
+          assert.equal(resultsQSA[0].id, 'a');
+          assert.equal(resultsQSA[1].id, 'b');
+          assert.equal(resultsQSA[2].id, 'c');
         });
 
         test('The `>` combinator finds children.', function () {
@@ -3195,16 +3204,25 @@
           ).shadowRoot.getElementById('contextElement');
 
           ShadyDOM.flush();
-          const results = ShadyDOM.wrapIfNeeded(
-            contextElement
-          ).querySelectorAll('#contextElement > *');
 
           // No shadow root hosts below #contextElement or use of `:scope`, so
           // the results are the same for all implementations.
-          assert.equal(results.length, 3);
-          assert.equal(results[0].id, 'a');
-          assert.equal(results[1].id, 'b');
-          assert.equal(results[2].id, 'c');
+
+          const resultQS = ShadyDOM.wrapIfNeeded(contextElement).querySelector(
+            '#contextElement > *'
+          );
+
+          assert(resultQS);
+          assert.equal(resultQS.id, 'a');
+
+          const resultsQSA = ShadyDOM.wrapIfNeeded(
+            contextElement
+          ).querySelectorAll('#contextElement > *');
+
+          assert.equal(resultsQSA.length, 3);
+          assert.equal(resultsQSA[0].id, 'a');
+          assert.equal(resultsQSA[1].id, 'b');
+          assert.equal(resultsQSA[2].id, 'c');
         });
 
         test('The `+` combinator finds next siblings.', function () {
@@ -3216,16 +3234,25 @@
           ).shadowRoot.getElementById('contextElement');
 
           ShadyDOM.flush();
-          const results = ShadyDOM.wrapIfNeeded(
-            contextElement
-          ).querySelectorAll('[before] + *');
 
           // No shadow root hosts below #contextElement or use of `:scope`, so
           // the results are the same for all implementations.
-          assert.equal(results.length, 3);
-          assert.equal(results[0].id, 'a');
-          assert.equal(results[1].id, 'b');
-          assert.equal(results[2].id, 'c');
+
+          const resultQS = ShadyDOM.wrapIfNeeded(contextElement).querySelector(
+            '[before] + *'
+          );
+
+          assert(resultQS);
+          assert.equal(resultQS.id, 'a');
+
+          const resultsQSA = ShadyDOM.wrapIfNeeded(
+            contextElement
+          ).querySelectorAll('[before] + *');
+
+          assert.equal(resultsQSA.length, 3);
+          assert.equal(resultsQSA[0].id, 'a');
+          assert.equal(resultsQSA[1].id, 'b');
+          assert.equal(resultsQSA[2].id, 'c');
         });
 
         test('The `~` combinator finds subsequent siblings.', function () {
@@ -3237,18 +3264,27 @@
           ).shadowRoot.getElementById('contextElement');
 
           ShadyDOM.flush();
-          const results = ShadyDOM.wrapIfNeeded(
-            contextElement
-          ).querySelectorAll('[before] ~ *');
 
           // No shadow root hosts below #contextElement or use of `:scope`, so
           // the results are the same for all implementations.
-          assert.equal(results.length, 5);
-          assert.equal(results[0].id, 'a');
-          assert.equal(results[1].id, 'b');
-          assert.equal(results[2].id, 'c');
-          assert.equal(results[3].id, 'd');
-          assert.equal(results[4].id, 'e');
+
+          const resultQS = ShadyDOM.wrapIfNeeded(contextElement).querySelector(
+            '[before] ~ *'
+          );
+
+          assert(resultQS);
+          assert.equal(resultQS.id, 'a');
+
+          const resultsQSA = ShadyDOM.wrapIfNeeded(
+            contextElement
+          ).querySelectorAll('[before] ~ *');
+
+          assert.equal(resultsQSA.length, 5);
+          assert.equal(resultsQSA[0].id, 'a');
+          assert.equal(resultsQSA[1].id, 'b');
+          assert.equal(resultsQSA[2].id, 'c');
+          assert.equal(resultsQSA[3].id, 'd');
+          assert.equal(resultsQSA[4].id, 'e');
         });
 
         test('The `>` combinator can match shadow root hosts with their children.', function () {
@@ -3260,7 +3296,22 @@
           ).shadowRoot.getElementById('contextElement');
 
           ShadyDOM.flush();
-          const results = ShadyDOM.wrapIfNeeded(
+
+          const resultQS = ShadyDOM.wrapIfNeeded(contextElement).querySelector(
+            'x-slot-inside-div > x-slot-inside-div > div'
+          );
+
+          if (!querySelectorImplementation) {
+            // The default implementation can't find the target because of the
+            // `<div>`s from the logical shadow roots are in the same root in
+            // the real tree.
+            assert.equal(resultQS, null);
+          } else if (querySelectorImplementation === 'selectorEngine') {
+            assert(resultQS);
+            assert(resultQS.hasAttribute('target-element'));
+          }
+
+          const resultsQSA = ShadyDOM.wrapIfNeeded(
             contextElement
           ).querySelectorAll('x-slot-inside-div > x-slot-inside-div > div');
 
@@ -3268,10 +3319,10 @@
             // The default implementation can't find the target because of the
             // `<div>`s from the logical shadow roots are in the same root in
             // the real tree.
-            assert.equal(results.length, 0);
+            assert.equal(resultsQSA.length, 0);
           } else if (querySelectorImplementation === 'selectorEngine') {
-            assert.equal(results.length, 1);
-            assert(results[0].hasAttribute('target-element'));
+            assert.equal(resultsQSA.length, 1);
+            assert(resultsQSA[0].hasAttribute('target-element'));
           }
         });
 
@@ -3282,16 +3333,24 @@
           ).shadowRoot.getElementById('contextElement');
 
           ShadyDOM.flush();
-          const results = ShadyDOM.wrapIfNeeded(
+
+          const resultQS = ShadyDOM.wrapIfNeeded(contextElement).querySelector(
+            '#b, #e, #a, #c, #d'
+          );
+
+          assert(resultQS);
+          assert.equal(resultQS.id, 'a');
+
+          const resultsQSA = ShadyDOM.wrapIfNeeded(
             contextElement
           ).querySelectorAll('#b, #e, #a, #c, #d');
 
-          assert.equal(results.length, 5);
-          assert.equal(results[0].id, 'a');
-          assert.equal(results[1].id, 'b');
-          assert.equal(results[2].id, 'c');
-          assert.equal(results[3].id, 'd');
-          assert.equal(results[4].id, 'e');
+          assert.equal(resultsQSA.length, 5);
+          assert.equal(resultsQSA[0].id, 'a');
+          assert.equal(resultsQSA[1].id, 'b');
+          assert.equal(resultsQSA[2].id, 'c');
+          assert.equal(resultsQSA[3].id, 'd');
+          assert.equal(resultsQSA[4].id, 'e');
         });
 
         test('The semantics of `:scope` are preserved.', function () {
@@ -3311,7 +3370,22 @@
           ).shadowRoot.getElementById('contextElement');
 
           ShadyDOM.flush();
-          const results = ShadyDOM.wrap(contextElement).querySelectorAll(
+
+          const resultQS = ShadyDOM.wrap(contextElement).querySelector(
+            'div:scope > div'
+          );
+
+          if (!querySelectorImplementation) {
+            // The default implementation can't find the target because it
+            // attempts to match it by calling `matches` on the element with the
+            // full selector, which breaks the semantics of `:scope`.
+            assert.equal(resultQS, null);
+          } else if (querySelectorImplementation === 'selectorEngine') {
+            assert(resultQS);
+            assert.equal(resultQS.id, 'target');
+          }
+
+          const resultsQSA = ShadyDOM.wrap(contextElement).querySelectorAll(
             'div:scope > div'
           );
 
@@ -3319,10 +3393,10 @@
             // The default implementation can't find the target because it
             // attempts to match it by calling `matches` on the element with the
             // full selector, which breaks the semantics of `:scope`.
-            assert.equal(results.length, 0);
+            assert.equal(resultsQSA.length, 0);
           } else if (querySelectorImplementation === 'selectorEngine') {
-            assert.equal(results.length, 1);
-            assert.equal(results[0].id, 'target');
+            assert.equal(resultsQSA.length, 1);
+            assert.equal(resultsQSA[0].id, 'target');
           }
         });
 

From 78d1f65a676dbc63d7a8580b8f8649e9ddba046e Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Thu, 8 Sep 2022 18:16:00 -0700
Subject: [PATCH 75/76] `position` -> `matchedElement` in the
 `logicalQuerySelectorAll` docs.

---
 packages/shadydom/src/patches/ParentNode.js   | 14 ++--
 .../src/patches/logicalQuerySelectorAll.md    | 72 +++++++++----------
 2 files changed, 43 insertions(+), 43 deletions(-)

diff --git a/packages/shadydom/src/patches/ParentNode.js b/packages/shadydom/src/patches/ParentNode.js
index 77701835f..472b2daba 100644
--- a/packages/shadydom/src/patches/ParentNode.js
+++ b/packages/shadydom/src/patches/ParentNode.js
@@ -169,17 +169,17 @@ const logicalQuerySelectorAll = (contextElement, selectorList) => {
   /**
    * An object used to track the current position of a potential selector match.
    *
-   * - `target` is the element that matches the selector if the cursor
+   * - `target` is the element that would be considered matching if the cursor
    * eventually results in a complete match.
    *
-   * - `complexSelectorParts` is the decomposed version of the selector that
-   * this cursor is attempting to match.
+   * - `complexSelectorParts` is the parsed representation of the complex
+   * selector that this cursor is attempting to match.
    *
-   * - `matchedElement` is an element that matches a compound selector in
-   * `complexSelectorParts`.
+   * - `index` is the index into `.complexSelectorParts.compoundSelectors` of
+   * the last successfully matched compound selector.
    *
-   * - `index` is the index of the compound selector in `complexSelectorParts`
-   * that matched `matchedElement`.
+   * - `matchedElement` is the element that successfully matched the compound
+   * selector in `.complexSelectorParts.compoundSelectors` at `index`.
    *
    * @typedef {{
    *   target: !Element,
diff --git a/packages/shadydom/src/patches/logicalQuerySelectorAll.md b/packages/shadydom/src/patches/logicalQuerySelectorAll.md
index 518649489..56ab05358 100644
--- a/packages/shadydom/src/patches/logicalQuerySelectorAll.md
+++ b/packages/shadydom/src/patches/logicalQuerySelectorAll.md
@@ -39,17 +39,17 @@ final compound selectors in each complex selector - in this example, `c` and
 `e`. Any matches create an initial 'cursor', which tracks the progress of a
 potential match. Cursors consist of a handful of properties:
 
-- `target`: the element that would be considered matching if the cursor
-  eventually results in a complete match
+- `target` is the element that would be considered matching if the cursor
+  eventually results in a complete match.
 
-- `complexSelectorParts`: the split complex selector which the cursor is
-  attempting to match
+- `complexSelectorParts` is the parsed representation of the complex selector
+  that this cursor is attempting to match.
 
-- `index`: the index into `.complexSelectorParts.compoundSelectors` of the last
-  successfully matched compound selector
+- `index` is the index into `.complexSelectorParts.compoundSelectors` of the
+  last successfully matched compound selector.
 
-- `position`: the element which successfully matched the compound selector at
-  `index`
+- `matchedElement` is the element that successfully matched the compound
+  selector in `.complexSelectorParts.compoundSelectors` at `index`.
 
 This initial walk through the descendants of the context element results in an
 initial list of cursors with `target`s which are in _document order_.
@@ -58,10 +58,10 @@ initial list of cursors with `target`s which are in _document order_.
 
 ```
 cursors = [
-  {target: #c_1, selector: 'a > b ~ c', index: 2, position: ...},
-  {target: #e_1, selector: 'd e', index: 1, position: ...},
-  {target: #c_2, selector: 'a > b ~ c', index: 2, position: ...},
-  {target: #e_2, selector: 'd e', index: 1, position: ...},
+  {target: #c_1, selector: 'a > b ~ c', index: 2, matchedElement: ...},
+  {target: #e_1, selector: 'd e', index: 1, matchedElement: ...},
+  {target: #c_2, selector: 'a > b ~ c', index: 2, matchedElement: ...},
+  {target: #e_2, selector: 'd e', index: 1, matchedElement: ...},
 ]
 ```
 
@@ -69,28 +69,28 @@ cursors = [
 <a>
   <b></b>
   <x></x>
-  <c id="c_1"></c> <!-- cursors[0].position -->
+  <c id="c_1"></c> <!-- cursors[0].matchedElement -->
   <d>
     <x>
-      <e id="e_1"></e> <!-- cursors[1].position -->
+      <e id="e_1"></e> <!-- cursors[1].matchedElement -->
     </x>
     <b></b>
-    <c id="c_2"></c> <!-- cursors[2].position -->
+    <c id="c_2"></c> <!-- cursors[2].matchedElement -->
   </d>
-  <e id="e_2"></e> <!-- cursors[3].position -->
+  <e id="e_2"></e> <!-- cursors[3].matchedElement -->
 </a>
 ```
 
-Next, the `position` and next combinator (iterating backwards) of each cursor
-with `.index > 0` ('source' cursors) are used to determine the candidate
+Next, the `matchedElement` and next combinator (iterating backwards) of each
+cursor with `.index > 0` ('source' cursors) are used to determine the candidate
 elements to test against that cursor's next compound selector.
 
 ```
 cursors = [
-  {target: #c_1, selector: 'a > b ~ c', index: 2, position: ...},
-  {target: #e_1, selector: 'd e', index: 1, position: ...},
-  {target: #c_2, selector: 'a > b ~ c', index: 2, position: ...},
-  {target: #e_2, selector: 'd e', index: 1, position: ...},
+  {target: #c_1, selector: 'a > b ~ c', index: 2, matchedElement: ...},
+  {target: #e_1, selector: 'd e', index: 1, matchedElement: ...},
+  {target: #c_2, selector: 'a > b ~ c', index: 2, matchedElement: ...},
+  {target: #e_2, selector: 'd e', index: 1, matchedElement: ...},
 ]
 ```
 
@@ -112,7 +112,7 @@ cursors = [
 
 Candidates that do not match the next compound selector in the source cursor's
 complex selector are filtered out. Those that do match result in a new cursor
-being created with `position` set to the matching element and `index`
+being created with `matchedElement` set to the matching element and `index`
 decremented by one, but with the same `target`, `complexSelectorParts` as the
 source cursor. Then, source cursors are each replaced by any new cursors created
 by their matching candidates. Specifically, all new cursors must maintain the
@@ -122,22 +122,22 @@ position in the list unchanged.
 
 ```
 cursors = [
-  {target: #c_1, selector: 'a > b ~ c', index: 1, position: ...},
-  {target: #e_1, selector: 'd e', index: 0, position: ...},
-  {target: #c_2, selector: 'a > b ~ c', index: 1, position: ...},
+  {target: #c_1, selector: 'a > b ~ c', index: 1, matchedElement: ...},
+  {target: #e_1, selector: 'd e', index: 0, matchedElement: ...},
+  {target: #c_2, selector: 'a > b ~ c', index: 1, matchedElement: ...},
 ]
 ```
 
 ```
 <a>
-  <b></b> <!-- cursors[0].position -->
+  <b></b> <!-- cursors[0].matchedElement -->
   <x></x>
   <c id="c_1"></c>
-  <d> <!-- cursors[1].position -->
+  <d> <!-- cursors[1].matchedElement -->
     <x>
       <e id="e_1"></e>
     </x>
-    <b></b> <!-- cursors[2].position -->
+    <b></b> <!-- cursors[2].matchedElement -->
     <c id="c_2"></c>
   </d>
   <e id="e_2"></e>
@@ -150,9 +150,9 @@ Again, candidates for cursors with `.index > 0` are selected.
 
 ```
 cursors = [
-  {target: #c_1, selector: 'a > b ~ c', index: 1, position: ...},
-  {target: #e_1, selector: 'd e', index: 0, position: ...},
-  {target: #c_2, selector: 'a > b ~ c', index: 1, position: ...},
+  {target: #c_1, selector: 'a > b ~ c', index: 1, matchedElement: ...},
+  {target: #e_1, selector: 'd e', index: 0, matchedElement: ...},
+  {target: #c_2, selector: 'a > b ~ c', index: 1, matchedElement: ...},
 ]
 ```
 
@@ -177,17 +177,17 @@ selector to produce new cursors that replace the source cursors.
 
 ```
 cursors = [
-  {target: #c_1, selector: 'a > b ~ c', index: 0, position: ...},
-  {target: #e_1, selector: 'd e', index: 0, position: ...},
+  {target: #c_1, selector: 'a > b ~ c', index: 0, matchedElement: ...},
+  {target: #e_1, selector: 'd e', index: 0, matchedElement: ...},
 ]
 ```
 
 ```
-<a> <!-- cursors[0].position -->
+<a> <!-- cursors[0].matchedElement -->
   <b></b>
   <x></x>
   <c id="c_1"></c>
-  <d> <!-- cursors[1].position -->
+  <d> <!-- cursors[1].matchedElement -->
     <x>
       <e id="e_1"></e>
     </x>

From 8621eeb484c5288a58be7191086af620a8f00ddb Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Thu, 15 Sep 2022 13:49:09 -0700
Subject: [PATCH 76/76] Update change log.

---
 packages/shadydom/CHANGELOG.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/packages/shadydom/CHANGELOG.md b/packages/shadydom/CHANGELOG.md
index 0a53feedb..9cecc93db 100644
--- a/packages/shadydom/CHANGELOG.md
+++ b/packages/shadydom/CHANGELOG.md
@@ -28,8 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   original event as its prototype so that it can update `currentTarget` without
   modifying the built-in property descriptor.
   ([#519](https://github.com/webcomponents/polyfills/pull/519))
-- Fix `:scope` in `querySelector{,All}` by traversing the logical tree manually
-  to match selectors.
+- Add `ShadyDOM.querySelectorImplementation` setting.
   ([#517](https://github.com/webcomponents/polyfills/pull/517))
 
 ## [1.9.0] - 2021-08-02