perf: Check for non-existing selectors

Stranger6667 · Stranger6667 · commit e8911f5cbad2 · 2026-01-25T18:49:13.000+01:00
Signed-off-by: Dmitry Dygalo &lt;dmitry@dygalo.dev&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 ### Performance
 
+- Skip selectors that reference non-existent classes, IDs, or tags.
 - Faster HTML serialization for styles containing double quotes.
 
 ## [0.19.1] - 2026-01-23
diff --git a/README.md b/README.md
@@ -273,7 +273,7 @@ Benchmarks for `css-inline==0.19.0`:
 - Basic: **4.09 µs**, 230 bytes
 - Realistic-1: **78.94 µs**, 8.58 KB
 - Realistic-2: **48.56 µs**, 4.3 KB
-- GitHub page: **28.47 ms**, 1.81 MB
+- GitHub page: **16.78 ms**, 1.81 MB
 
 These benchmarks, conducted using `rustc 1.91` on Ryzen 9 9950X, can be found in `css-inline/benches/inliner.rs`.
 
diff --git a/bindings/c/CHANGELOG.md b/bindings/c/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 ### Performance
 
+- Skip selectors that reference non-existent classes, IDs, or tags.
 - Faster HTML serialization for styles containing double quotes.
 
 ## [0.19.1] - 2026-01-23
diff --git a/bindings/java/CHANGELOG.md b/bindings/java/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 ### Performance
 
+- Skip selectors that reference non-existent classes, IDs, or tags.
 - Faster HTML serialization for styles containing double quotes.
 
 ## [0.19.1] - 2026-01-23
diff --git a/bindings/java/README.md b/bindings/java/README.md
@@ -267,10 +267,10 @@ Here is the performance comparison:
 
 |             | Size    | `css-inline 0.19.0` | `CSSBox 5.0.0`          |
 |-------------|---------|---------------------|-------------------------|
-| Basic       | 230 B   | 7.46 µs             | 52.15 µs (**6.99x**)    |
-| Realistic-1 | 8.58 KB | 111.38 µs           | 1.64 ms (**14.69x**)    |
-| Realistic-2 | 4.3 KB  | 65.93 µs            | 382.94 µs (**5.81x**)   |
-| GitHub page | 1.81 MB | 42.86 ms            | 315.65 ms (**7.37x**)   |
+| Basic       | 230 B   | 7.22 µs             | 53.33 µs (**7.38x**)    |
+| Realistic-1 | 8.58 KB | 109.77 µs           | 1.60 ms (**14.61x**)    |
+| Realistic-2 | 4.3 KB  | 61.92 µs            | 381.42 µs (**6.16x**)   |
+| GitHub page | 1.81 MB | 23.17 ms            | 312.22 ms (**13.48x**)  |
 
 The benchmarking code is available in the `src/jmh/java/org/cssinline/CSSInlineBench.java` file. The benchmarks were conducted using the stable `rustc 1.91`, `OpenJDK 24.0.1` on Ryzen 9 9950X.
 
diff --git a/bindings/javascript/CHANGELOG.md b/bindings/javascript/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 ### Performance
 
+- Skip selectors that reference non-existent classes, IDs, or tags.
 - Faster HTML serialization for styles containing double quotes.
 
 ## [0.19.2] - 2026-01-23
diff --git a/bindings/javascript/README.md b/bindings/javascript/README.md
@@ -252,7 +252,7 @@ Here is the performance comparison:
 | Basic       | 230 B   | 8.37 µs     | 15.96 µs (**1.91x**) | 42.32 µs (**5.06x**)    | 80.85 µs (**9.66x**)    |
 | Realistic-1 | 8.58 KB | 168.95 µs   | 344.59 µs (**2.04x**)| 524.38 µs (**3.10x**)   | 1.15 ms (**6.78x**)     |
 | Realistic-2 | 4.3 KB  | 90.36 µs    | 180.31 µs (**2.00x**)| 634.52 µs (**7.02x**)   | 898.47 µs (**9.94x**)   |
-| GitHub page | 1.81 MB | 62.31 ms    | 117.81 ms (**1.89x**)| 1.55 s (**24.82x**)     | 312.54 ms (**5.02x**)   |
+| GitHub page | 1.81 MB | 32.73 ms    | 119.60 ms (**3.65x**)| 1.60 s (**48.90x**)     | 326.41 ms (**9.97x**)   |
 
 The "Basic" case was obtained from benchmarking the example from the Usage section.
 
diff --git a/bindings/javascript/js-binding.js b/bindings/javascript/js-binding.js
diff --git a/bindings/php/CHANGELOG.md b/bindings/php/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 ### Performance
 
+- Skip selectors that reference non-existent classes, IDs, or tags.
 - Faster HTML serialization for styles containing double quotes.
 
 ## [0.19.1] - 2026-01-23
diff --git a/bindings/php/README.md b/bindings/php/README.md
@@ -281,7 +281,7 @@ Here is the performance comparison:
 | Simple            | 230 B   | 5.69 µs             | 26.22 µs (**4.61x**)         | 134.37 µs (**23.61x**) |
 | Realistic email 1 | 8.58 KB | 94.07 µs            | 288.20 µs (**3.06x**)        | 588.00 µs (**6.25x**)  |
 | Realistic email 2 | 4.3 KB  | 58.15 µs            | 585.24 µs (**10.07x**)       | 2.24 ms (**38.58x**)   |
-| GitHub Page†      | 1.81 MB | 37.72 ms            | ERROR                        | ERROR                  |
+| GitHub Page†      | 1.81 MB | 24.78 ms            | ERROR                        | ERROR                  |
 
 † The GitHub page benchmark contains complex modern CSS that neither `css-to-inline-styles` nor `emogrifier` can process.
 
diff --git a/bindings/python/CHANGELOG.md b/bindings/python/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 ### Performance
 
+- Skip selectors that reference non-existent classes, IDs, or tags.
 - Faster HTML serialization for styles containing double quotes.
 
 ## [0.19.1] - 2026-01-23
diff --git a/bindings/python/README.md b/bindings/python/README.md
@@ -267,15 +267,15 @@ Most of the time it achieves over a **10x** speed advantage compared to the next
 
 Here is the performance comparison:
 
-|             | Size    | `css_inline 0.19.0` | `premailer 3.10.0`     | `toronado 0.1.0`        | `inlinestyler 0.2.5`   | `pynliner 0.8.0`        |
-|-------------|---------|---------------------|------------------------|-------------------------|------------------------|-------------------------|
-| Basic       | 230 B   | 4.11 µs             | 94.34 µs (**22.96x**)  | 509.48 µs (**124.02x**) | 1.02 ms (**248.30x**)  | 852.17 µs (**207.44x**) |
-| Realistic-1 | 8.58 KB | 78.87 µs            | 1.03 ms (**13.10x**)   | 11.68 ms (**148.04x**)  | 26.37 ms (**334.38x**) | 11.61 ms (**147.19x**)  |
-| Realistic-2 | 4.3 KB  | 48.27 µs            | 1.49 ms (**30.81x**)   | ERROR                   | 17.71 ms (**366.87x**) | ERROR                   |
-| GitHub page | 1.81 MB | 29.54 ms            | 10.91 s (**369.13x**)  | ERROR                   | ERROR                  | ERROR                   |
+|             | Size    | `css_inline 0.19.0` | `premailer 3.10.0`     | `toronado 0.1.0`        | `pynliner 0.8.0`        |
+|-------------|---------|---------------------|------------------------|-------------------------|-------------------------|
+| Basic       | 230 B   | 4.27 µs             | 85.05 µs (**19.93x**)  | 495.30 µs (**116.05x**) | 867.79 µs (**203.32x**) |
+| Realistic-1 | 8.58 KB | 80.59 µs            | 1.03 ms (**12.76x**)   | 11.55 ms (**143.29x**)  | 11.71 ms (**145.36x**)  |
+| Realistic-2 | 4.3 KB  | 46.88 µs            | 1.44 ms (**30.73x**)   | ERROR                   | ERROR                   |
+| GitHub page | 1.81 MB | 17.57 ms            | 10.78 s (**613.48x**)  | ERROR                   | ERROR                   |
 
 The "Basic" case was obtained by benchmarking the example from the Usage section.
-Note that the `toronado`, `inlinestyler`, and `pynliner` libraries both encountered errors when used to inline CSS in the last scenario.
+Note that the `toronado` and `pynliner` libraries encountered errors when used to inline CSS in the last scenarios.
 
 The benchmarking code is available in the `benches/bench.py` file. The benchmarks were conducted using the stable `rustc 1.91`, Python `3.14.2` on Ryzen 9 9950X.
 
diff --git a/bindings/python/benches/bench.py b/bindings/python/benches/bench.py
@@ -2,7 +2,7 @@
 import multiprocessing
 import pathlib
 
-import inlinestyler.utils
+# import inlinestyler.utils  # Disabled: doesn't build on Python 3.14
 import premailer
 import pynliner
 import pytest
@@ -16,15 +16,15 @@
     benchmark_data = json.load(f)
 
 
-def parametrize_functions(*funcs, ids=("css_inline", "premailer", "pynliner", "inlinestyler", "toronado")):
+def parametrize_functions(*funcs, ids=("css_inline", "premailer", "pynliner", "toronado")):
     return pytest.mark.parametrize("func", funcs, ids=ids)
 
 
 all_functions = parametrize_functions(
     css_inline.inline,
     premailer.transform,
     pynliner.fromString,
-    inlinestyler.utils.inline_css,
+    # inlinestyler.utils.inline_css,  # Disabled: doesn't build on Python 3.14
     toronado.from_string,
 )
 
@@ -38,14 +38,14 @@ def parallel(func):
     parallel(css_inline.inline),
     parallel(premailer.transform),
     parallel(pynliner.fromString),
-    parallel(inlinestyler.utils.inline_css),
+    # parallel(inlinestyler.utils.inline_css),  # Disabled: doesn't build on Python 3.14
     parallel(toronado.from_string),
     ids=(
         "css_inline",
         "css_inline_pyprocess",
         "premailer",
         "pynliner",
-        "inlinestyler",
+        # "inlinestyler",
         "toronado",
     ),
 )
diff --git a/bindings/ruby/CHANGELOG.md b/bindings/ruby/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 ### Performance
 
+- Skip selectors that reference non-existent classes, IDs, or tags.
 - Faster HTML serialization for styles containing double quotes.
 
 ## [0.19.1] - 2026-01-23
diff --git a/bindings/ruby/Cargo.lock b/bindings/ruby/Cargo.lock
diff --git a/bindings/ruby/README.md b/bindings/ruby/README.md
@@ -245,7 +245,7 @@ The table below shows benchmark results comparing `css_inline`, `roadie`, and `p
 | Basic usage       | 230 B   | 6.07 µs             | 173.50 µs (**28.60x**)  | 345.30 µs (**56.91x**)  |
 | Realistic email 1 | 8.58 KB | 91.23 µs            | 713.40 µs (**7.82x**)   | 6.80 ms (**74.53x**)    |
 | Realistic email 2 | 4.3 KB  | 57.56 µs            | 1.99 ms (**34.56x**)    | ERROR                   |
-| GitHub Page       | 1.81 MB | 39.15 ms            | 8.20 s (**208.62x**)    | 2.40 s (**61.29x**)     |
+| GitHub Page       | 1.81 MB | 21.61 ms            | 8.20 s (**379.45x**)    | 2.40 s (**111.06x**)    |
 
 Please refer to the `test/bench.rb` file to review the benchmark code.
 The results displayed above were measured using stable `rustc 1.91` on Ruby `3.4.7`.
diff --git a/css-inline/src/html/document.rs b/css-inline/src/html/document.rs
@@ -201,6 +201,40 @@ impl Document {
         self.by_tag.get(tag).map_or(&[], Vec::as_slice)
     }
 
+    /// Quick check if a selector's anchor exists in the document.
+    /// Returns `false` if we can determine the selector won't match anything.
+    ///
+    /// This is a fast heuristic, not a full CSS parser. It extracts the leftmost
+    /// identifier from the selector and checks if it exists in our indexes.
+    /// False positives (returning `true` for non-matching selectors) are acceptable;
+    /// the full selector matching will filter those out later.
+    #[inline]
+    pub(crate) fn anchor_exists(&self, selector: &str) -> bool {
+        // Only use this optimization when indexes are enabled.
+        // For small documents, indexes aren't built so we can't do this check.
+        if !self.use_indexes {
+            return true;
+        }
+
+        let bytes = selector.trim_ascii_start().as_bytes();
+
+        match bytes.first() {
+            // Class selector: .classname
+            Some(b'.') => extract_identifier(&bytes[1..]).map_or(true, |name| {
+                self.by_class.contains_key(&LocalName::from(name))
+            }),
+            // ID selector: #id
+            Some(b'#') => extract_identifier(&bytes[1..])
+                .map_or(true, |name| self.by_id.contains_key(&LocalName::from(name))),
+            // Tag selector: starts with ASCII letter
+            Some(b'a'..=b'z' | b'A'..=b'Z') => extract_identifier(bytes).map_or(true, |name| {
+                self.by_tag.contains_key(&LocalName::from(name))
+            }),
+            // Universal (*), attribute ([), pseudo-class (:), empty, or unknown
+            _ => true,
+        }
+    }
+
     pub(crate) fn detach_node(&mut self, node: NodeId) {
         self.detach(node);
     }
@@ -406,6 +440,24 @@ impl std::ops::IndexMut<NodeId> for Document {
     }
 }
 
+/// Extract a CSS identifier (class/id/tag name) from a byte slice.
+/// Returns the identifier as a `&str` if valid, `None` otherwise.
+#[inline]
+fn extract_identifier(bytes: &[u8]) -> Option<&str> {
+    // Find the end of the identifier (ASCII letters, digits, underscore, hyphen)
+    let end = bytes
+        .iter()
+        .position(|&b| !matches!(b, b'a'..=b'z' | b'A'..=b'Z' | b'0'..=b'9' | b'_' | b'-'))
+        .unwrap_or(bytes.len());
+
+    if end == 0 {
+        return None;
+    }
+
+    // SAFETY: All matched bytes are ASCII (0x00-0x7F), which is valid UTF-8
+    Some(unsafe { std::str::from_utf8_unchecked(&bytes[..end]) })
+}
+
 #[cfg(test)]
 mod tests {
     use super::{super::node::ElementData, *};
diff --git a/css-inline/src/lib.rs b/css-inline/src/lib.rs
@@ -738,6 +738,24 @@ impl<'a> CSSInliner<'a> {
             // With `is` or `where` selectors (Level 4) this split should be done on the parser level
             for selector in selectors.split(',') {
                 let mut matched_any = false;
+                // Quick check: skip selectors whose anchor doesn't exist in the document
+                // This avoids parsing selectors that can't possibly match anything
+                if !document.anchor_exists(selector) {
+                    if let Some(state) = selector_cleanup_state.as_mut() {
+                        if let Some(chunk_index) =
+                            rule_chunk_indices.get(rule_id).copied().flatten()
+                        {
+                            state.record_usage(SelectorUsage {
+                                selector,
+                                declarations: (*start, *end),
+                                rule_id,
+                                chunk_index,
+                                matched: false,
+                            });
+                        }
+                    }
+                    continue;
+                }
                 if let Ok(matching_elements) = document.select(selector, &mut caches) {
                     let specificity = matching_elements.specificity();
                     for matching_element in matching_elements {
diff --git a/css-inline/tests/test_inlining.rs b/css-inline/tests/test_inlining.rs
@@ -1611,3 +1611,107 @@ fn remove_inlined_selectors_empty_style_tag() {
         "<html><head><style></style></head><body><h1>Test</h1></body></html>"
     );
 }
+
+// Tests for anchor_exists fast path with remove_inlined_selectors.
+// These require documents >= 1024 bytes to trigger index building.
+
+fn make_large_html(style: &str) -> String {
+    // Create HTML >= 1024 bytes to enable index-based optimizations
+    let padding = "x".repeat(1000);
+    format!(
+        r#"<html><head><style>{style}</style></head><body><h1 class="exists">Test</h1><!-- {padding} --></body></html>"#
+    )
+}
+
+#[test]
+fn remove_inlined_selectors_nonexistent_class_with_indexes() {
+    // Tests the anchor_exists fast path for class selectors
+    let inliner = CSSInliner::options().remove_inlined_selectors(true).build();
+    let html = make_large_html(".nonexistent { color: blue; }");
+    let result = inliner.inline(&html).unwrap();
+    // Class doesn't exist, selector should be kept
+    assert!(result.contains(".nonexistent { color: blue; }"));
+}
+
+#[test]
+fn remove_inlined_selectors_nonexistent_id_with_indexes() {
+    // Tests the anchor_exists fast path for ID selectors
+    let inliner = CSSInliner::options().remove_inlined_selectors(true).build();
+    let html = make_large_html("#nonexistent { color: blue; }");
+    let result = inliner.inline(&html).unwrap();
+    // ID doesn't exist, selector should be kept
+    assert!(result.contains("#nonexistent { color: blue; }"));
+}
+
+#[test]
+fn remove_inlined_selectors_nonexistent_tag_with_indexes() {
+    // Tests the anchor_exists fast path for tag selectors
+    let inliner = CSSInliner::options().remove_inlined_selectors(true).build();
+    let html = make_large_html("article { color: blue; }");
+    let result = inliner.inline(&html).unwrap();
+    // Tag doesn't exist, selector should be kept
+    assert!(result.contains("article { color: blue; }"));
+}
+
+#[test]
+fn remove_inlined_selectors_mixed_existent_nonexistent_with_indexes() {
+    // Tests mixed selectors: one matches via anchor_exists, one doesn't
+    let inliner = CSSInliner::options().remove_inlined_selectors(true).build();
+    let html = make_large_html("h1 { color: blue; } .nonexistent { color: red; }");
+    let result = inliner.inline(&html).unwrap();
+    // h1 exists and matches, so its selector is removed and style is inlined
+    assert!(result.contains(r#"style="color: blue;""#));
+    // .nonexistent doesn't exist, so its selector is kept
+    assert!(result.contains(".nonexistent { color: red; }"));
+}
+
+#[test]
+fn remove_inlined_selectors_comma_list_with_nonexistent_anchor() {
+    // Tests comma-separated selectors where one anchor doesn't exist
+    let inliner = CSSInliner::options().remove_inlined_selectors(true).build();
+    let html = make_large_html("h1, .nonexistent { color: blue; }");
+    let result = inliner.inline(&html).unwrap();
+    // h1 matches and gets inlined
+    assert!(result.contains(r#"style="color: blue;""#));
+    // .nonexistent doesn't exist, so that part of selector is kept
+    assert!(result.contains(".nonexistent { color: blue; }"));
+}
+
+#[test]
+fn remove_inlined_selectors_universal_and_attribute_selectors_with_indexes() {
+    // Tests selectors that hit the `_ => true` branch in anchor_exists:
+    // universal (*), attribute ([), pseudo-class (:)
+    // These all return true from anchor_exists, so they proceed to normal matching
+    let inliner = CSSInliner::options().remove_inlined_selectors(true).build();
+
+    // Universal selector - matches all elements, gets inlined and removed
+    let html = make_large_html("* { margin: 0; }");
+    let result = inliner.inline(&html).unwrap();
+    assert!(result.contains(r#"style="margin: 0;""#));
+    assert!(!result.contains("* { margin: 0; }"));
+
+    // Attribute selector - can't be inlined, stays in style block
+    let html = make_large_html("[class] { font-weight: bold; }");
+    let result = inliner.inline(&html).unwrap();
+    assert!(result.contains("[class]"));
+
+    // Pure pseudo-class selector starting with colon
+    let html = make_large_html(":hover { color: red; }");
+    let result = inliner.inline(&html).unwrap();
+    // :hover can't be inlined, check it doesn't panic
+    assert!(result.contains(":hover"));
+}
+
+#[test]
+fn remove_inlined_selectors_invalid_identifier_with_indexes() {
+    // Tests edge case where selector starts with . or # but has no valid identifier
+    // CSS parser may reject these, but anchor_exists handles them defensively
+    let inliner = CSSInliner::options().remove_inlined_selectors(true).build();
+
+    // Empty class name after dot - extract_identifier returns None, anchor_exists returns true
+    // These are invalid CSS but we handle them gracefully
+    let html = make_large_html(". { color: red; }");
+    let result = inliner.inline(&html).unwrap();
+    // Should not panic, invalid CSS is ignored
+    assert!(!result.contains(r#"style="color: red;""#));
+}
