webperf-snippets 1.11.0 → 1.13.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, the version of the CLI and the machine: its CPU model, cores, architecture and memory, as the operating system reports them, and a benchmark index, a short CPU test in Node before Chromium starts, which only informs, since on the same machine it moves by up to 40 % with the load.
 
 ```json
-"conditions": { "viewport": "mobile", "workflow": "core-web-vitals", "waitMs": 3000, "cliVersion": "1.11.0", "machine": { "cpu": "Apple M4", "cores": 10, "arch": "arm64", "memoryGB": 16, "benchmarkIndex": 2371 } }
+"conditions": { "viewport": "mobile", "workflow": "core-web-vitals", "waitMs": 3000, "cliVersion": "1.13.0", "machine": { "cpu": "Apple M4", "cores": 10, "arch": "arm64", "memoryGB": 16, "benchmarkIndex": 2371 } }
 ```
 
 Single snippet:
@@ -171,7 +171,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.11.0" }
+  "meta": { "viewport": "mobile", "waitMs": 3000, "cli_version": "1.13.0" }
 }
 ```
 
@@ -297,7 +297,7 @@ The report adds the comparison after the usual one, and `--markdown` a table for
 }
 ```
 
-When both runs were measured differently, with another workflow or snippet, viewport, wait, throttling, number of runs or version of the CLI, on another CPU model or with other cores, or on another path or query, the CLI compares anyway and warns on stderr, in the reports and in `warnings`: whoever reads the pull request comment does not see the stderr of the CI. Another host does not warn, since it is the review app of a pull request against production. A baseline of one run warns that only the thresholds apply.
+When both runs were measured differently, with another workflow or snippet, viewport, wait, throttling, number of runs or version of the CLI, on another CPU model or with other cores, or on another path or query, the CLI compares anyway and warns on stderr, in the reports and in `warnings`: whoever reads the pull request comment does not see the stderr of the CI. Another host does not warn, since it is the review app of a pull request against production. A baseline of one run warns that only the thresholds apply, and any other metric compared without statistics gets a line with the values left on each side, as in `no statistics for LCP: the baseline has 5 values, and this run 4 after 1 failed run; they need 5 a side, so measure both with 5 runs or more`.
 
 The comparison only informs, and the exit code is the same as without it, unless `--fail-on-regression`, which exits with `1` when a metric regressed or an error is new, and names them on stderr. A baseline that does not exist or is not an output of the CLI, a baseline of a page for a matrix or of a matrix for a page, or a `--threshold` the CLI does not understand exits with code `2`, before the page loads.
 
@@ -351,6 +351,7 @@ Each budget compares the value measured, or the median with `--runs`, and fails
 | `--verbose`                  | Show all items, including passing checks.                              |
 | `--headed`                   | Show the browser window (debug).                                       |
 | `-h, --help`                 | Show help.                                                             |
+| `-v, --version`              | Show the version.                                                      |
 
 ### Snippet aliases
 
@@ -360,6 +361,11 @@ Each budget compares the value measured, or the median with `--runs`, and fails
 | `CLS`              | CoreWebVitals/CLS                              |
 | `INP`              | CoreWebVitals/INP                              |
 | `LCP-Subparts`     | CoreWebVitals/LCP-Subparts                     |
+| `Largest-Contentful-Paint` | CoreWebVitals/LCP                      |
+| `Cumulative-Layout-Shift`  | CoreWebVitals/CLS                      |
+| `Interaction-to-Next-Paint` | CoreWebVitals/INP                     |
+| `First-Contentful-Paint`   | Loading/FCP                            |
+| `Time-to-First-Byte`       | Loading/TTFB                           |
 | `fonts`            | Loading/Fonts-Preloaded-Loaded-and-used-above-the-fold |
 | `render-blocking`  | Loading/Find-render-blocking-resources         |
 | `resource-hints`   | Loading/Resource-Hints-Validation              |
@@ -411,9 +417,11 @@ It needs the Chromium of Playwright (`npx playwright install chromium`); without
 
 Each run is a page load plus `waitMs`. With the default wait of 3 seconds, five runs of a workflow take about 20 seconds on a local page, and about a minute on a page that takes a few seconds to load. When the client asks for progress, the server reports the three stages of each run, numbered across the runs. A client sets its own limit on a tool call: the MCP SDK stops waiting after 60 seconds unless it is given a longer `timeout` or `resetTimeoutOnProgress`, and in Claude Code `MCP_TOOL_TIMEOUT` sets the limit. When the client gives up, the run in progress ends and no other starts.
 
+An agent often sends several calls in one turn. The calls of a connection that make a page work (`run_snippet`, `run_workflow`, `open_page`, `interact`) run one at a time, in the order they arrive, so they do not compete for the CPU and the turn saves no time. A call keeps its turn only while it runs, so a page left open holds up nothing, and `read_results`, `close_page` and the tools that load no page answer at once. Waiting counts towards the limit of the client; when it asks for progress, a waiting call reports how many calls are ahead, when the queue moves and every 5 seconds. A call the client gives up on leaves the queue and its page never loads; if it was the one measuring, its Chromium closes and the next call starts. A page that stops answering fails its call after 2 minutes per run, plus the `wait` steps of `interact`, and closes. Two clients at the same time, or a client and the CLI, have no queue in common.
+
 `run_snippet` and `run_workflow` compare a run with an earlier one, with the verdict of `--baseline`. `baseline` takes the `runId` of an earlier run of the connection, which every run of these two tools returns, or the path of a page the CLI wrote with `--json`, absolute or relative to the working directory of the server. The answer adds a `baseline` field: the one of the JSON of the CLI, with the `runId` or the `file` it compared with, plus `regressions`, the same lines `--fail-on-regression` prints. `thresholds` takes the values of `--threshold`, such as `["LCP=15%", "CLS=0.1"]`. A baseline that cannot be read or a threshold the server does not understand is a tool error, before the page loads, and a baseline of a matrix is refused, since a tool measures one page.
 
-With five runs or more a side, a regression needs a Mann-Whitney U p-value under 0.05 on top of its threshold, as in the CLI, and each metric adds `stats` with the p-value, the shift and its 95 % interval. With fewer, a metric compares by its threshold and, against a baseline of several runs, by the range of those runs. A single run can be off by more than a threshold on a page that did not change, so read `warnings`, and measure both sides with `runs: 5`, or `--runs 5` in the CLI, when the verdict matters. An earlier run of the connection works for a change made in the same session, and a file measured with the CLI for a comparison with `main`.
+With five runs or more a side, a regression needs a Mann-Whitney U p-value under 0.05 on top of its threshold, as in the CLI, and each metric adds `stats` with the p-value, the shift and its 95 % interval. With fewer, a metric compares by its threshold and, against a baseline of several runs, by the range of those runs. A single run can be off by more than a threshold on a page that did not change, so read `warnings`, which also names each metric left without statistics and the values on each side after failed runs, and measure both sides with `runs: 5`, or `--runs 5` in the CLI, when the verdict matters. An earlier run of the connection works for a change made in the same session, and a file measured with the CLI for a comparison with `main`.
 
 The server also offers resources, documents a client can attach to the context:
 
@@ -533,6 +541,7 @@ The `NPM_TOKEN` secret must be set in the repository settings with publish acces
 - **CLS in headless is conservative**: layout shifts that only happen on scroll are missed unless you script the scroll.
 - **First navigation only**: each `webperf-snippets` invocation runs one URL. SPAs need the post-route URL passed directly.
 - **Synthetic INP ≠ field INP**: `--interact-script` measures handler latency for a single scripted event. Real INP reflects the worst interaction across all user sessions; use RUM for field data.
+- **A click that paints nothing**: INP is under 16 ms with the `no-paint-measured` issue, as web-vitals reports it, so it rates `good` and passes `--budget-inp`. Check that the selector reaches an element that responds. When the document recorded no interaction at all, as with a click inside an iframe, the snippet is an error that says a click or key press was sent, and the run exits with code `1`.
 
 ## Roadmap
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webperf-snippets",
-  "version": "1.11.0",
+  "version": "1.13.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",
@@ -21,6 +21,7 @@
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "^2.3.1",
+    "@projectwallace/css-analyzer": "9.9.5",
     "vitest": "^5.0.5",
     "web-vitals": "^6.2.3"
   },

package/snippets/CoreWebVitals/INP.js

@@ -169,9 +169,14 @@
   observer.observe({
     type: "event",
     buffered: true,
-    durationThreshold: 16, // Only interactions > 16ms (1 frame)
+    durationThreshold: 16, // The lowest the browser accepts
   });
 
+  // With no frame after it, an interaction that paints nothing is measured to the end of its handlers,
+  // under the 16 ms of `event` entries. `first-input` has no threshold, so the first one is still read;
+  // web-vitals does the same.
+  observer.observe({ type: "first-input", buffered: true });
+
   // Log INP summary
   const logINP = () => {
     const rating = valueToRating(inpValue);
@@ -231,7 +236,7 @@
         console.log(`   Presentation Delay: ${formatMs(phases.presentationDelay)}`);
 
         // Visual bar
-        const total = inpEntry.duration;
+        const total = phases.inputDelay + phases.processingTime + phases.presentationDelay;
         const barWidth = 40;
         const inputBar = "▓".repeat(Math.round((phases.inputDelay / total) * barWidth));
         const processBar = "█".repeat(Math.round((phases.processingTime / total) * barWidth));
@@ -358,15 +363,26 @@
         details,
       };
     }
+    const value = Math.round(inpValue);
     return {
       script: "INP",
       status: "ok",
       metric: "INP",
-      value: Math.round(inpValue),
+      value,
       unit: "ms",
       rating,
       thresholds: { good: 200, needsImprovement: 500 },
       details,
+      // Under one frame there is no paint to measure to: the value is real, and says little about the page
+      ...(inpValue < 16 && {
+        issues: [
+          {
+            code: "no-paint-measured",
+            severity: "info",
+            message: `Worst interaction: ${value} ms, under the 16 ms of a frame, so the page most likely painted nothing after it. If it should respond, check that the click or key press reaches an element that does.`,
+          },
+        ],
+      }),
     };
   };
 
@@ -492,7 +508,7 @@
   });
 
   console.log("%c⚡ INP Tracking Active", "font-weight: bold; font-size: 14px;");
-  console.log("   Interactions with duration > 16ms will be tracked.");
+  console.log("   Interactions of 16ms or more are tracked, and the first one whatever it takes.");
   console.log(
     "   Call %cgetINP()%c to see current INP value.",
     "font-family: monospace; background: #f3f4f6; padding: 2px 4px;",

package/snippets/CoreWebVitals/LCP-Trail.js

@@ -64,7 +64,12 @@
   }
   // @end-shared uniqueSelector
 
+  // The element of an entry is null once its node has left the DOM, as with a loading spinner that
+  // an app removes when it renders. The entry keeps its time, size and URL.
+  const REMOVED = "(removed from DOM)";
+
   const getElementInfo = (element, entry) => {
+    if (!element) return entry.url ? { type: "Image", url: entry.url } : { type: "Removed element" };
     const tag = element.tagName.toLowerCase();
     if (tag === "img") return { type: "Image", url: entry.url || element.src };
     if (tag === "video") return { type: "Video poster", url: entry.url || element.poster };
@@ -72,6 +77,19 @@
     return { type: tag === "h1" || tag === "p" ? "Text block" : tag };
   };
 
+  // One candidate per element, or per entry when its element was removed
+  const candidateKey = (entry) => entry.element ?? `${entry.startTime}|${entry.size}`;
+
+  // A data: URL keeps its media type, and another URL its file name
+  const shortUrl = (url) => {
+    if (url.startsWith("data:")) return `${url.split(",")[0]},…`;
+    try {
+      const u = new URL(url);
+      const file = u.pathname.split("/").pop()?.split("?")[0];
+      return u.hostname !== location.hostname ? `${u.hostname}/…/${file}` : file || url;
+    } catch { return url; }
+  };
+
   const candidates = [];
 
   const logTrail = () => {
@@ -89,12 +107,13 @@
     // Current LCP element attribution
     console.log("");
     console.log("%cLCP Element:", "font-weight: bold;");
-    console.log(`   Element: ${current.selector}`, current.element);
+    if (current.element) console.log(`   Element: ${current.selector}`, current.element);
+    else console.log(`   Element: ${REMOVED}${current.entry.id ? ` #${current.entry.id}` : ""}`);
 
     const { type, url } = getElementInfo(current.element, current.entry);
     console.log(`   Type: ${type}`);
-    if (url) console.log(`   URL: ${url}`);
-    if (current.element.naturalWidth) {
+    if (url) console.log(`   URL: ${shortUrl(url)}`);
+    if (current.element?.naturalWidth) {
       console.log(
         `   Dimensions: ${current.element.naturalWidth}×${current.element.naturalHeight}`
       );
@@ -111,14 +130,14 @@
       console.log(
         `%c  ● ${index}. ${selector}`,
         `color: ${color}; font-weight: ${isCurrent ? "bold" : "normal"};`,
-        `| ${(time / 1000).toFixed(2)}s — ${name}${isCurrent ? " ← LCP" : ""}`,
-        element
+        `| ${(time / 1000).toFixed(2)}s${element ? ` — ${name}` : ""}${isCurrent ? " ← LCP" : ""}`,
+        ...(element ? [element] : [])
       );
     });
 
     console.log("");
     console.log(
-      "%c✓ Each candidate highlighted with a colored dashed outline",
+      "%c✓ Each candidate in the DOM highlighted with a colored dashed outline",
       "color: #22c55e;"
     );
     console.groupEnd();
@@ -126,28 +145,30 @@
 
   const observer = new PerformanceObserver((list) => {
     const activationStart = getActivationStart();
-    const seen = new Set(candidates.map((c) => c.element));
+    const seen = new Set(candidates.map((c) => candidateKey(c.entry)));
 
     for (const entry of list.getEntries()) {
-      const { element } = entry;
-      if (!element || seen.has(element)) continue;
+      const key = candidateKey(entry);
+      if (seen.has(key)) continue;
+      seen.add(key);
 
+      const { element } = entry;
       const { color, name } = PALETTE[candidates.length % PALETTE.length];
 
-      element.style.outline = `3px dashed ${color}`;
-      element.style.outlineOffset = "2px";
+      if (element) {
+        element.style.outline = `3px dashed ${color}`;
+        element.style.outlineOffset = "2px";
+      }
 
       candidates.push({
         index: candidates.length + 1,
         element,
-        selector: uniqueSelector(element),
-        color,
+        selector: element ? uniqueSelector(element) : REMOVED,
+        color: element ? color : "#9CA3AF",
         name,
         time: Math.max(0, entry.startTime - activationStart),
         entry,
       });
-
-      seen.add(element);
     }
 
     logTrail();
@@ -171,37 +192,28 @@
     return { script: "LCP-Trail", status: "error", error: "No LCP entries yet" };
   }
   const trailActivationStart = getActivationStart();
-  const seenEls = new Set();
-  const syncCandidates = [];
+  const byKey = new Map();
   for (const entry of trailEntries) {
+    const key = candidateKey(entry);
+    if (byKey.has(key)) continue;
     const el = entry.element;
-    if (!el || seenEls.has(el)) continue;
-    seenEls.add(el);
-    const selector = uniqueSelector(el);
-    const time = Math.round(Math.max(0, entry.startTime - trailActivationStart));
     const { type, url } = getElementInfo(el, entry);
-    syncCandidates.push({
-      index: syncCandidates.length + 1,
-      selector,
-      time,
+    byKey.set(key, {
+      index: byKey.size + 1,
+      selector: el ? uniqueSelector(el) : null,
+      ...(el ? {} : { removed: true }),
+      ...(!el && entry.id ? { id: entry.id } : {}),
+      time: Math.round(Math.max(0, entry.startTime - trailActivationStart)),
       elementType: type,
-      ...(url ? {
-        url: (() => {
-          try {
-            const u = new URL(url);
-            return u.hostname !== location.hostname
-              ? `${u.hostname}/…/${u.pathname.split("/").pop()?.split("?")[0]}`
-              : u.pathname.split("/").pop()?.split("?")[0] || url;
-          } catch { return url; }
-        })(),
-      } : {}),
+      sizePixels: entry.size,
+      ...(url ? { url: shortUrl(url) } : {}),
     });
   }
-  if (syncCandidates.length === 0) {
-    return { script: "LCP-Trail", status: "error", error: "No LCP elements in DOM" };
-  }
-  const lastCandidate = syncCandidates.at(-1);
-  const trailValue = lastCandidate.time;
+  const syncCandidates = [...byKey.values()];
+  // The LCP is the last entry, whether or not its element is still in the DOM
+  const lastEntry = trailEntries.at(-1);
+  const lastCandidate = byKey.get(candidateKey(lastEntry));
+  const trailValue = Math.round(Math.max(0, lastEntry.startTime - trailActivationStart));
   const trailRating = valueToRating(trailValue);
   return {
     script: "LCP-Trail",

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

@@ -92,6 +92,9 @@
   const tracker = createInteractionTracker();
   const observer = new PerformanceObserver((list) => tracker.add(list.getEntries()));
   observer.observe({ type: "event", durationThreshold: 0, buffered: true });
+  // The browser gives no `event` entries under 16 ms, whatever the threshold, and an interaction that
+  // paints nothing can take less. `first-input` has no threshold, so the first one is still read.
+  observer.observe({ type: "first-input", buffered: true });
 
   // Interactions grouped by event type: "click", "keydown", "pointerdown", etc.
   const groupByEventType = () => {

package/snippets/Interaction/Interactions.js

@@ -173,6 +173,10 @@
     buffered: true,
   });
 
+  // The browser gives no `event` entries under 16 ms, whatever the threshold, and an interaction that
+  // paints nothing can take less. `first-input` has no threshold, so the first one is still read.
+  observer.observe({ type: "first-input", buffered: true });
+
   // Summary function
   window.getInteractionSummary = () => {
     const allInteractions = tracker.list().map((i) => ({