webperf-snippets 1.5.0 → 1.7.0

package/README.md

@@ -73,7 +73,7 @@ npx webperf-snippets https://example.com --json
 The JSON output records how the page was measured in `conditions`, so a later run can tell whether it measured the same way: the viewport, the workflow (or the path of the snippet with `--snippet`), the wait and the version of the CLI.
 
 ```json
-"conditions": { "viewport": "mobile", "workflow": "core-web-vitals", "waitMs": 3000, "cliVersion": "1.5.0" }
+"conditions": { "viewport": "mobile", "workflow": "core-web-vitals", "waitMs": 3000, "cliVersion": "1.7.0" }
 ```
 
 Single snippet:
@@ -158,7 +158,7 @@ Without `--report-to` the CLI makes no external calls. With it, the results are
   "timestamp": "2026-05-06T10:00:00.000Z",
   "navMs": 1240,
   "results": [],
-  "meta": { "viewport": "mobile", "waitMs": 3000, "cli_version": "1.5.0" }
+  "meta": { "viewport": "mobile", "waitMs": 3000, "cli_version": "1.7.0" }
 }
 ```
 
@@ -300,6 +300,8 @@ CI gating:
 npx webperf-snippets https://example.com --budget-lcp 2500 --budget-cls 0.1
 ```
 
+Each budget compares the value measured, or the median with `--runs`, and fails when the value is above it. `--budget-lcp` and `--budget-cls` need the `core-web-vitals` workflow, `--budget-fcp` the `loading` workflow, `--budget-ttfb` the `loading` or `audit` workflow, and `--budget-inp` the `interaction` workflow with a click or a key press; `--snippet` with the snippet of the metric works too. A budget of a metric that the run does not measure exits with code `2` before the page loads, and one whose metric was not measured, such as INP without interactions, exits with code `1`: a budget never passes unchecked. The report lists every budget with its value and verdict, `passed`, `exceeded` with by how much, or `not measured` with why: a Budgets section in the human and markdown reports, and `budgets` in the JSON output and in the body of `--report-to`. A matrix lists the failed budgets with their combination under its table. Each failed budget is also written to stderr, with `--json` too.
+
 ### Options
 
 | Option                       | Description                                                            |
@@ -325,8 +327,11 @@ npx webperf-snippets https://example.com --budget-lcp 2500 --budget-cls 0.1
 | `--crux-key <key>`           | Add CrUX field data (p75) next to the measured values. Prefer `CRUX_API_KEY`. |
 | `--report-to <url>`          | POST the results to this `https` URL after the run. No external calls without it. |
 | `--api-key <key>`            | Sent as a Bearer token with `--report-to`. Prefer `PERF_REVIEWS_API_KEY`. |
-| `--budget-lcp <ms>`          | Exit `1` if LCP exceeds this value.                                    |
-| `--budget-cls <score>`       | Exit `1` if CLS exceeds this value.                                    |
+| `--budget-lcp <ms>`          | Exit `1` if LCP exceeds this value or was not measured.                                    |
+| `--budget-fcp <ms>`          | Exit `1` if FCP exceeds this value or was not measured.                                    |
+| `--budget-ttfb <ms>`         | Exit `1` if TTFB exceeds this value or was not measured.                                    |
+| `--budget-cls <score>`       | Exit `1` if CLS exceeds this value or was not measured.                                    |
+| `--budget-inp <ms>`          | Exit `1` if INP exceeds this value or was not measured.                                    |
 | `--verbose`                  | Show all items, including passing checks.                              |
 | `--headed`                   | Show the browser window (debug).                                       |
 | `-h, --help`                 | Show help.                                                             |
@@ -453,8 +458,11 @@ jobs:
 | ---------------- | ------------------- | -------------------------------------------------------------------------------------------- |
 | `url`            | required            | URL to measure.                                                                              |
 | `workflow`       | `core-web-vitals`   | Workflow to run: `core-web-vitals`, `loading`, `audit` or `interaction`.                                    |
-| `budget-lcp`     | `2500`              | LCP budget in ms. An empty value disables the check.                                         |
-| `budget-cls`     | `0.1`               | CLS budget. An empty value disables the check.                                               |
+| `budget-lcp`     | `auto`              | LCP budget in ms. `auto` is `2500` with `core-web-vitals` and no budget with the other workflows. An empty value disables the check. |
+| `budget-fcp`     |                     | FCP budget in ms, for `loading`.                                                              |
+| `budget-ttfb`    |                     | TTFB budget in ms, for `loading` or `audit`.                                                  |
+| `budget-cls`     | `auto`              | CLS budget. `auto` is `0.1` with `core-web-vitals` and no budget with the other workflows. An empty value disables the check. |
+| `budget-inp`     |                     | INP budget in ms, for `interaction` with a click or a key press.                             |
 | `fail-on-budget` | `true`              | Fail the step when a budget is exceeded or a snippet errors. Use `"false"` to read `exit-code` and decide yourself. |
 | `cli-version`    | `latest`            | Version of the `webperf-snippets` npm package to run.                                        |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webperf-snippets",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "mcpName": "io.github.nucliweb/webperf-snippets",
   "description": "Run curated WebPerf Snippets headlessly via Playwright. Diagnose Core Web Vitals beyond what Lighthouse exposes.",
   "type": "module",

package/snippets/CoreWebVitals/INP.js

@@ -349,10 +349,11 @@
       };
     }
     if (interactions.length === 0) {
+      // Nothing failed: someone has to use the page first, so it is still tracking
       return {
         script: "INP",
-        status: "error",
-        error: "No interactions recorded yet. Interact with the page and call getINP() again.",
+        status: "tracking",
+        message: "No interactions yet: click, tap or type on the page, then call getINP() again.",
         getDataFn: "getINP",
         details,
       };
@@ -378,8 +379,9 @@
       console.groupEnd();
       return {
         script: "INP",
-        status: "error",
-        error: "No interactions recorded yet. Interact with the page and call getINPDetails() again.",
+        status: "tracking",
+        message: "No interactions yet: click, tap or type on the page, then call getINPDetails() again.",
+        getDataFn: "getINPDetails",
         count: 0,
         items: [],
       };

package/snippets/Interaction/DOM-Size-and-Depth.js

@@ -37,6 +37,44 @@
     return (truncated ? "... > " : "") + parts.join(" > ").replace(/> >>> >/g, ">>>");
   };
 
+  // @shared uniqueSelector
+  // A CSS selector that matches only el in its document (or shadow root): its id when it is unique,
+  // otherwise a path of tag, classes and :nth-of-type() that goes up to the nearest ancestor with a
+  // unique id, or to the root, and stops as soon as it matches one element.
+  function uniqueSelector(el) {
+    const root = el.getRootNode();
+    const matchesOne = (selector) => {
+      try {
+        return root.querySelectorAll(selector).length === 1;
+      } catch {
+        return false;
+      }
+    };
+    const parts = [];
+    let node = el;
+    while (node && node.nodeType === 1) {
+      if (node.id && matchesOne(`#${window.CSS.escape(node.id)}`)) {
+        parts.unshift(`#${window.CSS.escape(node.id)}`);
+        break;
+      }
+      const tag = node.localName;
+      let part = tag + Array.from(node.classList).slice(0, 2).map((c) => `.${window.CSS.escape(c)}`).join("");
+      const siblings = node.parentNode ? Array.from(node.parentNode.children) : [node];
+      if (siblings.filter((s) => s.matches(part)).length > 1) {
+        part += `:nth-of-type(${siblings.filter((s) => s.localName === tag).indexOf(node) + 1})`;
+      }
+      parts.unshift(part);
+      if (matchesOne(parts.join(" > "))) break;
+      node = node.parentElement;
+    }
+    return parts.join(" > ");
+  }
+  // @end-shared uniqueSelector
+
+  // An element of the document by its unique selector, which Inspect can select; one inside a shadow
+  // root by the short path above, which marks the boundary
+  const inspectableSelectorFor = (el) => (el.getRootNode() === document ? uniqueSelector(el) : selectorFor(el));
+
   // Iterative walk (explicit stack) so very deep trees cannot overflow the call stack.
   // Depth counts <html> as level 1 and continues through open shadow roots.
   let totalElements = 0;
@@ -69,10 +107,10 @@
   const ranked = parents
     .sort((a, b) => b.children - a.children || a.depth - b.depth);
   const widest = ranked[0] ?? null;
-  const widestSelector = widest ? selectorFor(widest.el) + (widest.root !== widest.el ? " (shadow root)" : "") : null;
+  const widestSelector = widest ? inspectableSelectorFor(widest.el) + (widest.root !== widest.el ? " (shadow root)" : "") : null;
 
   const items = ranked.slice(0, 10).map((p) => ({
-    selector: selectorFor(p.el) + (p.root !== p.el ? " (shadow root)" : ""),
+    selector: inspectableSelectorFor(p.el) + (p.root !== p.el ? " (shadow root)" : ""),
     children: p.children,
     depth: p.depth,
   }));

package/snippets/Interaction/Input-Latency-Breakdown.js

@@ -132,10 +132,11 @@
       console.log(
         "   Interact with the page (click, type, etc.) and call this again."
       );
+      // Nothing failed: someone has to use the page first, so it is still tracking
       return {
         script: "Input-Latency-Breakdown",
-        status: "error",
-        error: "No interactions recorded yet. Interact with the page (click, type, etc.) and call getInputLatencyBreakdown() again.",
+        status: "tracking",
+        message: "No interactions yet: click, tap or type on the page, then call getInputLatencyBreakdown() again.",
         getDataFn: "getInputLatencyBreakdown",
       };
     }

package/snippets/Interaction/Interactions.js

@@ -184,7 +184,14 @@
     if (allInteractions.length === 0) {
       console.log("%c📊 No interactions recorded yet.", "font-weight: bold;");
       console.log("   Interact with the page (click, type, etc.) and call this again.");
-      return { script: "Interactions", status: "error", error: "No interactions recorded yet", count: 0 };
+      // Nothing failed: someone has to use the page first, so it is still tracking
+      return {
+        script: "Interactions",
+        status: "tracking",
+        message: "No interactions yet: click, tap or type on the page, then call getInteractionSummary() again.",
+        getDataFn: "getInteractionSummary",
+        count: 0,
+      };
     }
 
     console.group("%c📊 Interaction Summary", "font-weight: bold; font-size: 14px;");

package/snippets/Interaction/Layout-Shift-Loading-and-Interaction.js

@@ -42,14 +42,44 @@
         totalImpact: Math.round(data.totalShift * 10000) / 10000,
       }));
 
-  const getElementSelector = (element) => {
-    if (!element) return "(unknown)";
-    if (element.id) return `#${element.id}`;
-    if (element.className && typeof element.className === "string") {
-      const classes = element.className.trim().split(/\s+/).slice(0, 2).join(".");
-      if (classes) return `${element.tagName.toLowerCase()}.${classes}`;
+  // @shared uniqueSelector
+  // A CSS selector that matches only el in its document (or shadow root): its id when it is unique,
+  // otherwise a path of tag, classes and :nth-of-type() that goes up to the nearest ancestor with a
+  // unique id, or to the root, and stops as soon as it matches one element.
+  function uniqueSelector(el) {
+    const root = el.getRootNode();
+    const matchesOne = (selector) => {
+      try {
+        return root.querySelectorAll(selector).length === 1;
+      } catch {
+        return false;
+      }
+    };
+    const parts = [];
+    let node = el;
+    while (node && node.nodeType === 1) {
+      if (node.id && matchesOne(`#${window.CSS.escape(node.id)}`)) {
+        parts.unshift(`#${window.CSS.escape(node.id)}`);
+        break;
+      }
+      const tag = node.localName;
+      let part = tag + Array.from(node.classList).slice(0, 2).map((c) => `.${window.CSS.escape(c)}`).join("");
+      const siblings = node.parentNode ? Array.from(node.parentNode.children) : [node];
+      if (siblings.filter((s) => s.matches(part)).length > 1) {
+        part += `:nth-of-type(${siblings.filter((s) => s.localName === tag).indexOf(node) + 1})`;
+      }
+      parts.unshift(part);
+      if (matchesOne(parts.join(" > "))) break;
+      node = node.parentElement;
     }
-    return element.tagName?.toLowerCase() || "(unknown)";
+    return parts.join(" > ");
+  }
+  // @end-shared uniqueSelector
+
+  // The node of a source can be a text node, named by its element
+  const getElementSelector = (node) => {
+    const element = node?.nodeType === 1 ? node : node?.parentElement;
+    return element ? uniqueSelector(element) : "(unknown)";
   };
 
   const observer = new PerformanceObserver((list) => {

package/snippets/Loading/Cache-Strategy-Analysis.js

@@ -800,56 +800,58 @@
 
   console.groupEnd(); // Additional Insights
 
-  // Recommendations
+  // Recommendations: the console marks their priority; the result orders them by it, as plain text
+  const PRIORITY = ["🔴", "🟡", "ℹ️"];
   const recommendations = [];
+  const recommend = (icon, text) => recommendations.push({ icon, text });
 
   if (noCacheEntries.filter((e) => isStaticAsset(e.type)).length > 0) {
-    recommendations.push(
-      "🔴 Add Cache-Control headers to static assets (JS, CSS, fonts, images). Start with max-age=86400 and move to immutable for versioned files."
+    recommend("🔴",
+      "Add Cache-Control headers to static assets (JS, CSS, fonts, images). Start with max-age=86400 and move to immutable for versioned files."
     );
   }
   if (shortCacheEntries.filter((e) => e.hasHash).length > 0) {
-    recommendations.push(
-      "🟡 Versioned files (with content hash) should use long cache or Cache-Control: immutable; they can be cached indefinitely since the URL changes on update."
+    recommend("🟡",
+      "Versioned files (with content hash) should use long cache or Cache-Control: immutable; they can be cached indefinitely since the URL changes on update."
     );
   }
   if (allAntiPatterns.some((p) => p.id === "expires-without-cc")) {
-    recommendations.push(
-      "🟡 Replace Expires headers with Cache-Control: max-age. Expires is an outdated mechanism and less reliable."
+    recommend("🟡",
+      "Replace Expires headers with Cache-Control: max-age. Expires is an outdated mechanism and less reliable."
     );
   }
   if (cacheEfficiencyPercent !== null && cacheEfficiencyPercent < 50) {
-    recommendations.push(
-      `🔴 Cache efficiency is low (${cacheEfficiencyPercent}%, measured on the ${analyzableEntries.length} resources whose cache headers could be read). Review caching strategy for those static assets.`
+    recommend("🔴",
+      `Cache efficiency is low (${cacheEfficiencyPercent}%, measured on the ${analyzableEntries.length} resources whose cache headers could be read). Review caching strategy for those static assets.`
     );
   }
   if (cdnHitRate !== null && cdnHitRate < 70) {
-    recommendations.push(
-      `🟡 CDN hit rate is ${cdnHitRate}%. Check CDN cache rules and ensure static assets have appropriate TTLs.`
+    recommend("🟡",
+      `CDN hit rate is ${cdnHitRate}%. Check CDN cache rules and ensure static assets have appropriate TTLs.`
     );
   }
   if (protocolDistribution["http/1.1"] > 0) {
-    recommendations.push(
-      `🟡 ${protocolDistribution["http/1.1"]} resources still use HTTP/1.1. Consider upgrading to HTTP/2 for better multiplexing.`
+    recommend("🟡",
+      `${protocolDistribution["http/1.1"]} resources still use HTTP/1.1. Consider upgrading to HTTP/2 for better multiplexing.`
     );
   }
   if (uncompressedResources.length > 0) {
-    recommendations.push(
-      `🟡 ${uncompressedResources.length} text resources appear uncompressed. Enable Brotli or gzip compression on your server.`
+    recommend("🟡",
+      `${uncompressedResources.length} text resources appear uncompressed. Enable Brotli or gzip compression on your server.`
     );
   }
   if (costlyDuplicates.length > 0) {
-    recommendations.push(
-      `🟡 ${costlyDuplicates.length} resources are loaded multiple times with uncached network requests. Check for duplicate script, stylesheet, or fetch includes.`
+    recommend("🟡",
+      `${costlyDuplicates.length} resources are loaded multiple times with uncached network requests. Check for duplicate script, stylesheet, or fetch includes.`
     );
   } else if (cachedDuplicates.length > 0) {
-    recommendations.push(
-      `ℹ️ ${cachedDuplicates.length} resources are requested multiple times but served from cache; low performance impact, but worth reviewing for correctness.`
+    recommend("ℹ️",
+      `${cachedDuplicates.length} resources are requested multiple times but served from cache; low performance impact, but worth reviewing for correctness.`
     );
   }
   if (corsRestricted > 0 && headersAnalyzed === 0) {
-    recommendations.push(
-      `ℹ️ All resources are cross-origin CORS-restricted, so header analysis was limited. Add Timing-Allow-Origin for more insights.`
+    recommend("ℹ️",
+      `All resources are cross-origin CORS-restricted, so header analysis was limited. Add Timing-Allow-Origin for more insights.`
     );
   }
 
@@ -857,7 +859,7 @@
     console.log("");
     console.group("%c📌 Recommendations", "font-weight: bold;");
     for (const rec of recommendations) {
-      console.log(`   ${rec}`);
+      console.log(`   ${rec.icon} ${rec.text}`);
     }
     console.groupEnd();
   }
@@ -935,6 +937,6 @@
       })),
       ...(coverageIssue ? [coverageIssue] : []),
     ],
-    recommendations,
+    recommendations: [...recommendations].sort((a, b) => PRIORITY.indexOf(a.icon) - PRIORITY.indexOf(b.icon)).map((r) => r.text),
   };
 })();

package/snippets/Loading/Content-Visibility.js

@@ -1,5 +1,39 @@
 // Detect elements with content-visibility: auto and analyze optimization opportunities
 
+// @shared uniqueSelector
+// A CSS selector that matches only el in its document (or shadow root): its id when it is unique,
+// otherwise a path of tag, classes and :nth-of-type() that goes up to the nearest ancestor with a
+// unique id, or to the root, and stops as soon as it matches one element.
+function uniqueSelector(el) {
+  const root = el.getRootNode();
+  const matchesOne = (selector) => {
+    try {
+      return root.querySelectorAll(selector).length === 1;
+    } catch {
+      return false;
+    }
+  };
+  const parts = [];
+  let node = el;
+  while (node && node.nodeType === 1) {
+    if (node.id && matchesOne(`#${window.CSS.escape(node.id)}`)) {
+      parts.unshift(`#${window.CSS.escape(node.id)}`);
+      break;
+    }
+    const tag = node.localName;
+    let part = tag + Array.from(node.classList).slice(0, 2).map((c) => `.${window.CSS.escape(c)}`).join("");
+    const siblings = node.parentNode ? Array.from(node.parentNode.children) : [node];
+    if (siblings.filter((s) => s.matches(part)).length > 1) {
+      part += `:nth-of-type(${siblings.filter((s) => s.localName === tag).indexOf(node) + 1})`;
+    }
+    parts.unshift(part);
+    if (matchesOne(parts.join(" > "))) break;
+    node = node.parentElement;
+  }
+  return parts.join(" > ");
+}
+// @end-shared uniqueSelector
+
 function detectContentVisibility() {
   // Create an object to store the results
   const results = {
@@ -9,39 +43,6 @@ function detectContentVisibility() {
     nodeArray: [],
   };
 
-  // Get the name of the node
-  function getName(node) {
-    const name = node.nodeName;
-    return node.nodeType === 1 ? name.toLowerCase() : name.toUpperCase().replace(/^#/, "");
-  }
-
-  // Get the selector for an element
-  function getSelector(node) {
-    let sel = "";
-
-    try {
-      while (node && node.nodeType !== 9) {
-        const el = node;
-        const part = el.id
-          ? "#" + el.id
-          : getName(el) +
-            (el.classList &&
-            el.classList.value &&
-            el.classList.value.trim() &&
-            el.classList.value.trim().length
-              ? "." + el.classList.value.trim().replace(/\s+/g, ".")
-              : "");
-        if (sel.length + part.length > 100 - 1) return sel || part;
-        sel = sel ? part + ">" + sel : part;
-        if (el.id) break;
-        node = el.parentNode;
-      }
-    } catch {
-      // Do nothing...
-    }
-    return sel;
-  }
-
   // Check if element is in viewport
   function isInViewport(element) {
     const rect = element.getBoundingClientRect();
@@ -59,7 +60,7 @@ function detectContentVisibility() {
     const cs = window.getComputedStyle(node);
 
     return {
-      selector: getSelector(node),
+      selector: uniqueSelector(node),
       contentVisibility: cs["content-visibility"],
       containIntrinsicSize: cs["contain-intrinsic-size"] || "not set",
       width: Math.round(rect.width),
@@ -171,27 +172,6 @@ function analyzeContentVisibilityOpportunities(options = {}) {
   const opportunities = [];
   const processedElements = new Set();
 
-  function getSelector(node) {
-    let sel = "";
-    try {
-      while (node && node.nodeType !== 9) {
-        const el = node;
-        const name = el.nodeName.toLowerCase();
-        const part = el.id
-          ? "#" + el.id
-          : name +
-            (el.classList && el.classList.value && el.classList.value.trim()
-              ? "." + el.classList.value.trim().split(/\s+/).slice(0, 2).join(".")
-              : "");
-        if (sel.length + part.length > 80) return sel || part;
-        sel = sel ? part + ">" + sel : part;
-        if (el.id) break;
-        node = el.parentNode;
-      }
-    } catch {}
-    return sel;
-  }
-
   function estimateRenderSavings(childCount) {
     const baseMs = childCount * 0.2;
     if (baseMs < 5) return "Low (~" + baseMs.toFixed(1) + "ms)";
@@ -233,7 +213,7 @@ function analyzeContentVisibilityOpportunities(options = {}) {
     processedElements.add(el);
 
     opportunities.push({
-      selector: getSelector(el),
+      selector: uniqueSelector(el),
       height: Math.round(rect.height) + "px",
       distanceFromViewport: Math.round(distanceFromViewport) + "px",
       childElements: childCount,

package/snippets/Loading/Critical-CSS-Detection.js

@@ -24,9 +24,10 @@
   const criticalBudget = 14 * 1024; // 14 KB (first TCP round-trip)
 
   // --- External stylesheets ---
+  // A link without href or disabled loads nothing and blocks nothing, so it is not a stylesheet of the page
   const linkStylesheets = Array.from(
     document.querySelectorAll('link[rel="stylesheet"]')
-  );
+  ).filter((link) => link.href && !link.disabled);
 
   const perfEntries = performance.getEntriesByType("resource").filter((e) => !isOwnRequest(e));
 

package/snippets/Loading/Find-Above-The-Fold-Lazy-Loaded-Images.js

@@ -10,26 +10,40 @@
   }
   // @end-shared isOwnRequest
 
-  function getSelector(node) {
-    let sel = "";
-    try {
-      while (node && node.nodeType !== 9) {
-        const el = node;
-        const name = el.nodeName.toLowerCase();
-        const part = el.id
-          ? "#" + el.id
-          : name +
-            (el.classList && el.classList.value && el.classList.value.trim()
-              ? "." + el.classList.value.trim().split(/\s+/).slice(0, 2).join(".")
-              : "");
-        if (sel.length + part.length > 80) return sel || part;
-        sel = sel ? part + ">" + sel : part;
-        if (el.id) break;
-        node = el.parentNode;
+  // @shared uniqueSelector
+  // A CSS selector that matches only el in its document (or shadow root): its id when it is unique,
+  // otherwise a path of tag, classes and :nth-of-type() that goes up to the nearest ancestor with a
+  // unique id, or to the root, and stops as soon as it matches one element.
+  function uniqueSelector(el) {
+    const root = el.getRootNode();
+    const matchesOne = (selector) => {
+      try {
+        return root.querySelectorAll(selector).length === 1;
+      } catch {
+        return false;
       }
-    } catch {}
-    return sel;
+    };
+    const parts = [];
+    let node = el;
+    while (node && node.nodeType === 1) {
+      if (node.id && matchesOne(`#${window.CSS.escape(node.id)}`)) {
+        parts.unshift(`#${window.CSS.escape(node.id)}`);
+        break;
+      }
+      const tag = node.localName;
+      let part = tag + Array.from(node.classList).slice(0, 2).map((c) => `.${window.CSS.escape(c)}`).join("");
+      const siblings = node.parentNode ? Array.from(node.parentNode.children) : [node];
+      if (siblings.filter((s) => s.matches(part)).length > 1) {
+        part += `:nth-of-type(${siblings.filter((s) => s.localName === tag).indexOf(node) + 1})`;
+      }
+      parts.unshift(part);
+      if (matchesOne(parts.join(" > "))) break;
+      node = node.parentElement;
+    }
+    return parts.join(" > ");
   }
+  // @end-shared uniqueSelector
+
 
   function isInViewport(element) {
     const rect = element.getBoundingClientRect();
@@ -81,7 +95,7 @@
     const area = rect.width * rect.height;
 
     return {
-      selector: getSelector(img),
+      selector: uniqueSelector(img),
       lazyType: getLazyType(img),
       dimensions: `${Math.round(rect.width)}×${Math.round(rect.height)}`,
       position: {

package/snippets/Loading/Find-Images-With-Lazy-and-Fetchpriority.js

@@ -2,26 +2,40 @@
 // https://webperf-snippets.net
 
 (() => {
-  function getSelector(node) {
-    let sel = "";
-    try {
-      while (node && node.nodeType !== 9) {
-        const el = node;
-        const name = el.nodeName.toLowerCase();
-        const part = el.id
-          ? "#" + el.id
-          : name +
-            (el.classList && el.classList.value && el.classList.value.trim()
-              ? "." + el.classList.value.trim().split(/\s+/).slice(0, 2).join(".")
-              : "");
-        if (sel.length + part.length > 80) return sel || part;
-        sel = sel ? part + ">" + sel : part;
-        if (el.id) break;
-        node = el.parentNode;
+  // @shared uniqueSelector
+  // A CSS selector that matches only el in its document (or shadow root): its id when it is unique,
+  // otherwise a path of tag, classes and :nth-of-type() that goes up to the nearest ancestor with a
+  // unique id, or to the root, and stops as soon as it matches one element.
+  function uniqueSelector(el) {
+    const root = el.getRootNode();
+    const matchesOne = (selector) => {
+      try {
+        return root.querySelectorAll(selector).length === 1;
+      } catch {
+        return false;
       }
-    } catch {}
-    return sel;
+    };
+    const parts = [];
+    let node = el;
+    while (node && node.nodeType === 1) {
+      if (node.id && matchesOne(`#${window.CSS.escape(node.id)}`)) {
+        parts.unshift(`#${window.CSS.escape(node.id)}`);
+        break;
+      }
+      const tag = node.localName;
+      let part = tag + Array.from(node.classList).slice(0, 2).map((c) => `.${window.CSS.escape(c)}`).join("");
+      const siblings = node.parentNode ? Array.from(node.parentNode.children) : [node];
+      if (siblings.filter((s) => s.matches(part)).length > 1) {
+        part += `:nth-of-type(${siblings.filter((s) => s.localName === tag).indexOf(node) + 1})`;
+      }
+      parts.unshift(part);
+      if (matchesOne(parts.join(" > "))) break;
+      node = node.parentElement;
+    }
+    return parts.join(" > ");
   }
+  // @end-shared uniqueSelector
+
 
   function isInViewport(element) {
     const rect = element.getBoundingClientRect();
@@ -77,7 +91,7 @@
       const isLcp = el === lcpCandidate;
 
       return {
-        selector: getSelector(el),
+        selector: uniqueSelector(el),
         dimensions: `${Math.round(rect.width)}×${Math.round(rect.height)}`,
         inViewport: inViewport ? "Yes" : "No",
         isLcpCandidate: isLcp ? "⚠️ Yes" : "No",
@@ -140,7 +154,7 @@
     items: Array.from(conflictingElements).map((el) => {
       const rect = el.getBoundingClientRect();
       return {
-        selector: getSelector(el),
+        selector: uniqueSelector(el),
         src: el.currentSrc || el.src || "",
         inViewport: isInViewport(el),
         isLcpCandidate: el === lcpCandidate,