Skip to content

Universal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.

fix(images): detect JS lazy-loaders (Perfmatters, EWWW, generic) - closes #41 (#95)

Agrici.Danielef850b097674
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ccceda9..e5b476e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -71,8 +71,10 @@ jobs:
with:
python-version: "3.10"
- - name: Install pytest
- run: pip install pytest
+ - name: Install pytest + test deps
+ # beautifulsoup4 is required by tests/test_lazy_detection.py which
+ # exercises parse_html.py via real BeautifulSoup parsing.
+ run: pip install pytest beautifulsoup4
- name: Run pytest
run: pytest tests/ -v
diff --git a/scripts/parse_html.py b/scripts/parse_html.py
index 6233c5f..d7a58b9 100755
--- a/scripts/parse_html.py
+++ b/scripts/parse_html.py
@@ -28,6 +28,46 @@ except ImportError:
_HTML_PARSER = "html.parser"
+# Lazy-loader detection — covers native + the major JS lazy-loaders found on
+# WordPress/WooCommerce sites (Perfmatters, EWWW Image Optimizer, generic
+# `data-src` patterns). Sites optimized by these plugins strip native
+# `loading="lazy"` and replace `src` with a placeholder, so a check on `loading`
+# alone reports "not lazy-loaded" when the page is in fact heavily lazy-loaded.
+_PERFMATTERS_ATTRS = ("data-perfmatters-src", "data-perfmatters-srcset")
+_EWWW_ATTRS = ("data-ewww-src", "data-eio")
+_GENERIC_LAZY_ATTRS = ("data-src", "data-lazy-src", "data-original", "data-srcset")
+_PERFMATTERS_CLASSES = {"perfmatters-lazy", "perfmatters-lazy-loaded"}
+_EWWW_CLASSES = {"lazyload-eio", "lazyloaded-eio"}
+_GENERIC_LAZY_CLASSES = {"lazyload", "lazyloaded", "lazy", "lazy-loaded"}
+
+
+def _detect_lazy_method(img) -> str:
+ """Return a coarse classification of the image's lazy-loading mechanism.
+
+ Order of detection: native -> perfmatters -> ewww -> js-generic -> none.
+ Specific JS lazy-loaders are checked before the generic bucket so reports
+ can attribute the optimization to the right plugin (which informs whether
+ a site is using a specific WP optimization stack).
+
+ Returns one of: 'native', 'perfmatters', 'ewww', 'js-generic', 'none'.
+ """
+ if img.get("loading", "").lower() == "lazy":
+ return "native"
+
+ class_list = set(img.get("class", []) or [])
+
+ if any(img.get(a) for a in _PERFMATTERS_ATTRS) or class_list & _PERFMATTERS_CLASSES:
+ return "perfmatters"
+
+ if any(img.get(a) for a in _EWWW_ATTRS) or class_list & _EWWW_CLASSES:
+ return "ewww"
+
+ if any(img.get(a) for a in _GENERIC_LAZY_ATTRS) or class_list & _GENERIC_LAZY_CLASSES:
+ return "js-generic"
+
+ return "none"
+
+
def parse_html(html: str, base_url: Optional[str] = None) -> dict:
"""
Parse HTML and extract SEO-relevant elements.
@@ -129,6 +169,7 @@ def parse_html(html: str, base_url: Optional[str] = None) -> dict:
"width": img.get("width"),
"height": img.get("height"),
"loading": img.get("loading"),
+ "lazy_method": _detect_lazy_method(img),
})
# Links
diff --git a/skills/seo-images/SKILL.md b/skills/seo-images/SKILL.md
index c130ecd..4f558c0 100644
--- a/skills/seo-images/SKILL.md
+++ b/skills/seo-images/SKILL.md
@@ -104,6 +104,23 @@ In November 2025, Google's Chromium team reversed its 2022 decision and announce
<img src="hero.jpg" alt="Hero image">
```
+#### Detected lazy-loader methods (`lazy_method` field)
+
+`scripts/parse_html.py` classifies each image's lazy-loading mechanism via the
+`lazy_method` field on every image entry. Five values:
+
+| `lazy_method` | Signal detected | Common stack |
+|---|---|---|
+| `native` | `loading="lazy"` HTML attribute | Modern browsers, plain HTML |
+| `perfmatters` | `data-perfmatters-src`/`-srcset` OR class `perfmatters-lazy` | WordPress + Perfmatters plugin |
+| `ewww` | `data-ewww-src` / `data-eio` OR class `lazyload-eio` | WordPress + EWWW Image Optimizer |
+| `js-generic` | `data-src` / `data-lazy-src` / `data-original` / `data-srcset` OR class `lazyload`/`lazyloaded`/`lazy` | Lazysizes, vanilla-lazyload, jQuery plugins |
+| `none` | Neither attribute nor class signal | Page is not lazy-loading this image |
+
+When auditing image SEO, report `lazy_method` alongside `loading` so users know
+whether their site is using a JS-driven lazy-loader (in which case the native
+`loading="lazy"` attribute is intentionally absent — that is not a regression).
+
### `fetchpriority="high"` for LCP Images
Add `fetchpriority="high"` to your hero/LCP image to prioritize its download in the browser's network queue:
diff --git a/skills/seo-page/SKILL.md b/skills/seo-page/SKILL.md
index 6073ceb..6e0dd80 100644
--- a/skills/seo-page/SKILL.md
+++ b/skills/seo-page/SKILL.md
@@ -52,7 +52,7 @@ metadata:
- File size: flag >200KB (warning), >500KB (critical)
- Format: recommend WebP/AVIF over JPEG/PNG
- Dimensions: width/height set for CLS prevention
-- Lazy loading: loading="lazy" on below-fold images
+- Lazy loading: report `lazy_method` per image (native | perfmatters | ewww | js-generic | none). Do not flag "not lazy-loaded" when JS lazy-loaders (Perfmatters, EWWW, lazysizes) are detected — they intentionally strip the native `loading="lazy"` attribute and use `data-src` placeholders
### Core Web Vitals (reference only, not measurable from HTML alone)
- Flag potential LCP issues (huge hero images, render-blocking resources)
diff --git a/tests/test_lazy_detection.py b/tests/test_lazy_detection.py
new file mode 100644
index 0000000..46c7689
--- /dev/null
+++ b/tests/test_lazy_detection.py
@@ -0,0 +1,88 @@
+"""
+Tests for `_detect_lazy_method` in scripts/parse_html.py.
+
+Background: closes issue #41. Sites optimized by Perfmatters, EWWW Image
+Optimizer, or other JS lazy-loaders strip the native `loading="lazy"` attribute
+and replace `src` with a placeholder + a data attribute. A check on `loading`
+alone reports "not lazy-loaded" when the page is heavily lazy-loaded.
+"""
+import sys
+from pathlib import Path
+
+# Make scripts/ importable without requiring it to be a package
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+from bs4 import BeautifulSoup # noqa: E402
+from parse_html import _detect_lazy_method, parse_html # noqa: E402
+
+
+def _img(html: str):
+ """Return the first <img> tag from a snippet."""
+ return BeautifulSoup(html, "html.parser").find("img")
+
+
+def test_native_lazy_loading():
+ img = _img('<img src="hero.jpg" loading="lazy">')
+ assert _detect_lazy_method(img) == "native"
+
+
+def test_native_eager_loading_is_none():
+ img = _img('<img src="hero.jpg" loading="eager">')
+ assert _detect_lazy_method(img) == "none"
+
+
+def test_no_loading_attr_no_data_src_is_none():
+ img = _img('<img src="hero.jpg">')
+ assert _detect_lazy_method(img) == "none"
+
+
+def test_perfmatters_via_data_attr():
+ img = _img('<img src="placeholder.png" data-perfmatters-src="hero.jpg">')
+ assert _detect_lazy_method(img) == "perfmatters"
+
+
+def test_perfmatters_via_class():
+ img = _img('<img class="perfmatters-lazy" data-src="hero.jpg">')
+ # Class detection beats generic data-src detection
+ assert _detect_lazy_method(img) == "perfmatters"
+
+
+def test_ewww_via_data_attr():
+ img = _img('<img src="placeholder.png" data-ewww-src="hero.jpg">')
+ assert _detect_lazy_method(img) == "ewww"
+
+
+def test_js_generic_via_data_src():
+ img = _img('<img src="placeholder.png" data-src="hero.jpg">')
+ assert _detect_lazy_method(img) == "js-generic"
+
+
+def test_js_generic_via_data_lazy_src():
+ img = _img('<img src="placeholder.png" data-lazy-src="hero.jpg">')
+ assert _detect_lazy_method(img) == "js-generic"
+
+
+def test_js_generic_via_lazyloaded_class():
+ img = _img('<img class="lazyloaded" data-src="hero.jpg">')
+ assert _detect_lazy_method(img) == "js-generic"
+
+
+def test_native_wins_over_data_src():
+ """If both native loading=lazy AND data-src present, native wins (most explicit signal)."""
+ img = _img('<img src="hero.jpg" loading="lazy" data-src="hero.jpg">')
+ assert _detect_lazy_method(img) == "native"
+
+
+def test_parse_html_surfaces_lazy_method_per_image():
+ """Integration check: parse_html() emits `lazy_method` on every image entry."""
+ html = """
+ <html><body>
+ <img src="a.jpg" loading="lazy" alt="native">
+ <img src="b-placeholder.png" data-perfmatters-src="b.jpg" alt="pm">
+ <img src="c.jpg" alt="plain">
+ </body></html>
+ """
+ result = parse_html(html)
+ methods = [im["lazy_method"] for im in result["images"]]
+ assert methods == ["native", "perfmatters", "none"]