[css-pseudo-4] [css-highlight-api-1] Integrate custom highlights into css-pseudo-4 #6755

Co-authored-by: fantasai <fantasai.bugs@inkedblade.net>

Author: dandclark

css-highlight-api-1/Overview.bs

@@ -141,7 +141,7 @@ Setting up Custom Highlights</h2>
 <h3 id=creation>
 Creating Custom Highlights</h3>
 
-	A <dfn>custom highlight</dfn> is a collection of [=ranges=]
+	A <dfn export>custom highlight</dfn> is a collection of [=ranges=]
 	representing portions of a document.
 	They do not necessarily fit into the element tree,
 	and can arbitrarily cross element boundaries without honoring its nesting structure.

css-pseudo-4/Overview.bs

@@ -640,7 +640,7 @@ Styling the First-Letter Pseudo-elements</h4>
 Highlight Pseudo-elements</h2>
 
 <h3 id="highlight-selectors">
-Selecting Highlighted Content: the ''::selection'',  ''::target-text'', ''::spelling-error'', and ''::grammar-error'' pseudo-elements</h3>
+Selecting Highlighted Content: the ''::selection'',  ''::target-text'', ''::spelling-error'', ''::grammar-error'', and ''::highlight'' pseudo-elements</h3>
 
   <wpt>
     grammar-spelling-errors-001.html
@@ -792,15 +792,57 @@ Selecting Highlighted Content: the ''::selection'',  ''::target-text'', ''::spel
       grammar-error-002-manual.html
       grammar-error-003-manual.html
       </wpt>
+
+    <dt><dfn>::highlight()</dfn>
+    <dd>
+      The ''::highlight()'' [=functional pseudo-element=] represents content associated with [=custom highlights=].
+      Each [=custom highlight name=] represents a different type of highlight.
+      See [[CSS-HIGHLIGHT-API-1]] for details.
+      <wpt>
+      css/css-highlight-api/painting/custom-highlight-painting-001.html
+      css/css-highlight-api/painting/custom-highlight-painting-002.html
+      css/css-highlight-api/painting/custom-highlight-painting-003.html
+      css/css-highlight-api/painting/custom-highlight-painting-004.html
+      css/css-highlight-api/painting/custom-highlight-painting-005.html
+      css/css-highlight-api/painting/custom-highlight-painting-006.html
+      css/css-highlight-api/painting/custom-highlight-painting-007.html
+      css/css-highlight-api/painting/custom-highlight-painting-008.html
+      css/css-highlight-api/painting/custom-highlight-painting-009.html
+      css/css-highlight-api/painting/custom-highlight-painting-010.html
+      css/css-highlight-api/painting/custom-highlight-painting-011.html
+      css/css-highlight-api/painting/custom-highlight-painting-012.html
+      css/css-highlight-api/painting/custom-highlight-painting-013.html
+      css/css-highlight-api/painting/custom-highlight-painting-014.html
+      css/css-highlight-api/painting/custom-highlight-painting-015.html
+      css/css-highlight-api/painting/custom-highlight-painting-iframe-001.html
+      css/css-highlight-api/painting/custom-highlight-painting-iframe-002.html
+      css/css-highlight-api/painting/custom-highlight-painting-iframe-003.html
+      css/css-highlight-api/painting/custom-highlight-painting-iframe-004.html
+      css/css-highlight-api/painting/custom-highlight-painting-iframe-005.html
+      css/css-highlight-api/painting/custom-highlight-painting-iframe-006.html
+      css/css-highlight-api/painting/custom-highlight-painting-invalidation-001.html
+      css/css-highlight-api/painting/custom-highlight-painting-invalidation-002.html
+      css/css-highlight-api/painting/custom-highlight-painting-invalidation-003.html
+      css/css-highlight-api/painting/custom-highlight-painting-invalidation-004.html
+      css/css-highlight-api/painting/custom-highlight-painting-invalidation-005.html
+      css/css-highlight-api/painting/custom-highlight-painting-invalidation-006.html
+      css/css-highlight-api/painting/custom-highlight-painting-invalidation-007.html
+      css/css-highlight-api/painting/custom-highlight-painting-prioritization-001.html
+      css/css-highlight-api/painting/custom-highlight-painting-prioritization-002.html
+      css/css-highlight-api/painting/custom-highlight-painting-staticrange-001.html
+      css/css-highlight-api/painting/custom-highlight-painting-staticrange-002.html
+      css/css-highlight-api/painting/custom-highlight-painting-staticrange-003.html
+      css/css-highlight-api/painting/custom-highlight-painting-staticrange-004.html
+      css/css-highlight-api/painting/custom-highlight-painting-staticrange-005.html
+      css/css-highlight-api/painting/custom-highlight-painting-staticrange-006.html
+      css/css-highlight-api/painting/custom-highlight-painting-staticrange-007.html
+      </wpt>
   </dl>
 
   The <a>highlight pseudo-elements</a>
   do not necessarily fit into the element tree,
   and can arbitrarily cross element boundaries without honoring its nesting structure.
 
-  Note: A future level of CSS may introduce ways to create
-  custom highlight pseudo-elements.
-
 <h3 id="highlight-styling">
 Styling Highlights</h3>
 
@@ -1154,7 +1196,8 @@ Backgrounds</h4>
   The ''::selection'' overlay is drawn
   over the ''::target-text'' overlay which is drawn
   over the ''::spelling-error'' overlay
-  which is drawn over the ''::grammar-error'' overlay.
+  which is drawn over the ''::grammar-error'' overlay
+  which is drawn over the ''::highlight'' overlays.
 
   <wpt>
   selection-overlay-and-grammar-001.html