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.ymlindex 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 pytestrun: pytest tests/ -vdiff --git a/scripts/parse_html.py b/scripts/parse_html.pyindex 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),})# Linksdiff --git a/skills/seo-images/SKILL.md b/skills/seo-images/SKILL.mdindex 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 ImagesAdd `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.mdindex 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.pynew file mode 100644index 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"]