webperf-snippets 1.10.0 → 1.12.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.10.0", "machine": { "cpu": "Apple M4", "cores": 10, "arch": "arm64", "memoryGB": 16, "benchmarkIndex": 2371 } }
+"conditions": { "viewport": "mobile", "workflow": "core-web-vitals", "waitMs": 3000, "cliVersion": "1.12.0", "machine": { "cpu": "Apple M4", "cores": 10, "arch": "arm64", "memoryGB": 16, "benchmarkIndex": 2371 } }
 ```
 
 Single snippet:
@@ -138,13 +138,13 @@ Get a key for the [Chrome UX Report API](https://developer.chrome.com/docs/crux/
 
 With a key, the field data also gives what CrUX knows of the LCP when it is an image: the p75 of its sub-parts, TTFB, load delay, load duration and render delay. When the measurement ran LCP-Subparts, with `--snippet LCP-Subparts` or the `core-web-vitals` workflow over 2.5 s, a table puts each one next to its lab value, with a note where one side is at least 1.5 times the other and 100 ms apart: a slower server or network for users, an image the lab finds sooner, slower connections, slower devices, or a lab slower than users. The field sub-parts describe only the loads whose LCP is an image, and the table says which share that is; when the LCP of the lab is not an image, only TTFB and render delay compare. Each p75 is taken on its own, so the sub-parts do not add up to the p75 of LCP. A line gives the navigation types of the users, by share, and points to Back-Forward-Cache when over 5 % of the visits come back without the back/forward cache. The JSON output carries them in `crux.subParts`, `crux.lcpImageShare`, `crux.roundTripTime` and `crux.navigationTypes`.
 
-`--crux-history <weeks>` adds the trend of the field data over the last 1 to 40 weeks, from the [CrUX History API](https://developer.chrome.com/docs/crux/history-api), with the same key. Each week is the p75 of the 28 days before it, so the weeks overlap and the series is smooth. For LCP, CLS and INP the section gives the first and the last week, the change between them and its direction, `stable` within 5 %, and the weeks as a sparkline, where a gap is a week with too little data:
+`--crux-history <weeks>` adds the trend of the field data over the last 1 to 40 weeks, from the [CrUX History API](https://developer.chrome.com/docs/crux/history-api), with the same key. Each week is the p75 of the 28 days before it, so the weeks overlap and the series is smooth. For LCP, CLS and INP the section gives the first and the last week, the change between them and its direction, `stable` within 5 %, and the weeks as a sparkline, where a gap is a week with too little data. The bars span at least the smallest change `--baseline` counts for the metric (100 ms for LCP, 50 ms for INP, 0.05 for CLS), so a series that barely moves draws almost flat:
 
 ```
 Field data trend (CrUX p75, 40 weeks, mobile, origin-level)
   LCP   2.88s → 3.10s       ▲ +7.7%   worsening   ▃▃▄▃▃▃▄▆▇██▇▆▄▂▁▂▃▃▄▅▆▆▆▆▆▆
   CLS   0.2600 → 0.2100     ▼ −19.2%  improving   ▅▆▆▇▇█▇▆▆▅▄▃▃▃▃▃▂▂▁▂▂▂▂▂▂▂
-  INP   253ms → 251ms       ▼ −0.8%   stable      ▇▅▃▂▂▄▆██▇▅▃▂▃▄▆▅▃▂▁▂▃▃▄▅▆
+  INP   253ms → 251ms       ▼ −0.8%   stable      ▅▅▅▄▄▄▅▅▆▆▆▅▅▄▄▄▄▅▅▅▅▄▄▄▃▃▄▄▄▅▅
 ```
 
 The JSON output carries it in `crux.history`, with the periods, the p75 of each week and the trend of each metric. Like the p75, it uses the page when it has data of its own and its origin otherwise, and says which in `scope`.
@@ -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.10.0" }
+  "meta": { "viewport": "mobile", "waitMs": 3000, "cli_version": "1.12.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              |
@@ -398,8 +404,8 @@ It needs the Chromium of Playwright (`npx playwright install chromium`); without
 | Tool            | What it does                                                                 |
 | --------------- | ---------------------------------------------------------------------------- |
 | `list_snippets` | Lists the snippets with their category, title, short aliases and whether they track interactions. Takes an optional `category`. |
-| `run_snippet`   | Opens a URL in a headless Chromium, runs one snippet and returns a summary of its result. Takes `url`, `snippet` (name, alias or `Category/Name`), and optional `viewport` and `waitMs`. The snippets that record interactions run on a page opened with `open_page`. |
-| `run_workflow`  | Runs a workflow of the CLI (`core-web-vitals`, `audit`, `loading`, `interaction`) and the follow-ups of its decision tree. Takes `url`, `workflow`, and optional `viewport` and `waitMs`. |
+| `run_snippet`   | Opens a URL in a headless Chromium, runs one snippet and returns a summary of its result. Takes `url`, `snippet` (name, alias or `Category/Name`), and optional `viewport`, `waitMs`, `runs`, `baseline` and `thresholds`. The snippets that record interactions run on a page opened with `open_page`. |
+| `run_workflow`  | Runs a workflow of the CLI (`core-web-vitals`, `audit`, `loading`, `interaction`) and the follow-ups of its decision tree. Takes `url`, `workflow`, and optional `viewport`, `waitMs`, `runs`, `baseline` and `thresholds`. |
 | `get_crux`      | Returns the CrUX p75 of LCP, CLS and INP for a URL, or its origin. Takes `url` and an optional `formFactor` (`phone`, `desktop`, `tablet`). Needs `CRUX_API_KEY` in the environment of the server. |
 | `open_page`     | Opens a URL in a page that stays open between calls and installs tracking snippets (`track`, such as `INP`). Returns a `sessionId`. |
 | `interact`      | Runs steps on an open page: `click`, `type`, `hover`, `scroll` or `wait`. |
@@ -407,6 +413,16 @@ It needs the Chromium of Playwright (`npx playwright install chromium`); without
 | `get_details`   | Returns the whole object of one snippet of a run, by the `runId` that `run_snippet`, `run_workflow` or `read_results` returned, without measuring again. Takes `runId` and `snippet`. |
 | `close_page`    | Closes an open page. |
 
+`run_snippet` and `run_workflow` take `runs`, from 1 to 9, as `--runs`: the page loads that many times, one after the other, and the answer is the median run plus a `runs` field, the one of the JSON, with the median, min, max, the value of each run and the agreement of each metric. A run that fails counts in `failed` and is left out; when every run fails, the answer is a tool error. The server keeps the results of the median run only, as the JSON does, so `get_details` answers from that run and names it in `medianRun`; a metric other than the one that picked it (`medianBy`) can differ there from its median in `runs`.
+
+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`, 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:
 
 | Resource                         | What it has                                                              |
@@ -414,6 +430,7 @@ The server also offers resources, documents a client can attach to the context:
 | `webperf://schema`               | The contract every snippet result follows: base shape, statuses, how to read a result, the rules of the issue codes. |
 | `webperf://schema/{snippet}`     | The fields one snippet returns, with an example, and the codes of its issues. |
 | `webperf://workflows/{category}` | The workflows and the decision tree of a category.                       |
+| `webperf://runs/{runId}`         | A run of `run_snippet` or `run_workflow` of the connection, in the shape of the JSON of the CLI. The list names each run with its snippet or workflow, its URL, its viewport, how many runs it measured when they are several, and its time. |
 
 And prompts, templates that chain the tools (in Claude Code, `/mcp__webperf__audit_lcp`): `audit_lcp`, `debug_inp` and `audit_page`, each with a `url` argument.
 
@@ -524,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. `tracking` after a click means that the document recorded no interaction, as with a click inside an iframe: the run exits with code `0` unless it has a budget.
 
 ## Roadmap
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webperf-snippets",
-  "version": "1.10.0",
+  "version": "1.12.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

@@ -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) => ({

package/snippets/SCHEMA.md

@@ -64,7 +64,7 @@ Every script must return an object matching this shape:
 
   // Tracking scripts (status: "tracking")
   message?: string;      // Human-readable status message
-  getDataFn?: string;    // window function to call for data: evaluate_script(`${getDataFn}()`). May be a dotted path such as "loafHelpers.getData"
+  getDataFn?: string;    // window function to call for data: evaluate_script(`() => ${getDataFn}()`). May be a dotted path such as "loafHelpers.getData"
 
   // Error info (status: "error" or "unsupported")
   error?: string;
@@ -169,7 +169,7 @@ return {
 ```
 1. evaluate_script(INP.js)          → { status: "tracking", getDataFn: "getINP" }
 2. (user interacts with the page)
-3. evaluate_script("getINP()")      → { script: "INP", status: "ok", value: 350, rating: "needs-improvement", ... }
+3. evaluate_script("() => getINP()") → { script: "INP", status: "ok", value: 350, rating: "needs-improvement", ... }
 ```
 
 **The window function must also return a structured object** matching the same schema, including when nothing has been recorded yet:
@@ -181,7 +181,7 @@ return {
 
 ### Pattern 4: Async scripts
 
-Scripts that use `async/await` or `setTimeout`. The IIFE returns a Promise, which `evaluate_script` can await (Chrome DevTools `awaitPromise`).
+Scripts that use `async/await` or `setTimeout`. The IIFE returns a Promise, which `evaluate_script` awaits with `format: "script"` (Chrome DevTools `awaitPromise`).
 
 Keep the existing `async () => {}` wrapper. Add a `return` statement with structured data at the end. The agent receives the resolved value.
 
@@ -217,6 +217,8 @@ A script wrapped in `void (async () => {...})()` discards its return value. Neve
 
 `details.element` is a CSS selector that matches only the LCP element, so `document.querySelector(details.element)` returns it: the id when it is unique, otherwise a path of tag, classes and `:nth-of-type()` from the nearest ancestor with a unique id, such as `section.intro:nth-of-type(2) > p.copy:nth-of-type(2)`. LCP-Subparts (`details.element`) and LCP-Trail (`finalElement` and each `selector`) build it the same way.
 
+In LCP-Trail, a candidate whose element has left the DOM has `selector: null` and `removed: true`, with its `time`, `sizePixels`, `url` for an image and `id` when the element had one, and `finalElement` is `null` when the LCP element itself was removed. `value` is the time of the last entry either way.
+
 #### CLS
 
 Returns buffered CLS immediately and keeps tracking. Always call `getCLS()` after interactions to get an updated value.
@@ -269,6 +271,24 @@ Returns buffered CLS immediately and keeps tracking. Always call `getCLS()` afte
 
 If no interactions yet, `getINP()` returns `status: "tracking"` with a `message` and `getDataFn: "getINP"`: interact with the page and call it again.
 
+An interaction that paints nothing has no frame to be measured to, so the browser measures it to the end of its handlers, often 0 ms, and gives no `event` entry under 16 ms at any `durationThreshold`. The first interaction of a page always has a `first-input` entry, which is how web-vitals reads it too, so `getINP()` returns it as `status: "ok"` with its value, and an `info` issue when the worst value is under 16 ms:
+
+```json
+{
+  "script": "INP",
+  "status": "ok",
+  "metric": "INP",
+  "value": 0,
+  "unit": "ms",
+  "rating": "good",
+  "thresholds": { "good": 200, "needsImprovement": 500 },
+  "details": { "totalInteractions": 1, "worstEvent": "pointerdown → h1", "phases": { "inputDelay": 0, "processingTime": 0, "presentationDelay": 0 } },
+  "issues": [{ "code": "no-paint-measured", "severity": "info", "message": "Worst interaction: 0 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." }]
+}
+```
+
+Later interactions that short have no entry of any kind: they only count in `performance.interactionCount`, and INP does not depend on them. `tracking` after a click means that the document recorded no interaction at all, as with a click inside an iframe, which records its own; the CLI and the MCP server replace the `message` to say that a click or key press was sent.
+
 The phases describe the whole interaction, not one of its events. A tap fires `pointerdown`, `pointerup` and `click`, and a key press `keydown` and `keyup`, with one `interactionId`. INP, Interactions and Input-Latency-Breakdown group the entries by `interactionId`, also when they arrive in separate observer callbacks, and measure the interaction over its entries painted in the frame of the longest one: `inputDelay` runs from the first `startTime` to the first `processingStart`, `processingTime` to the last `processingEnd`, and `presentationDelay` from there to the paint (`startTime + duration`, never below zero). The interaction is reported under the event whose handler ran longest, or under the `click` or `keydown` when no handler took a millisecond more than theirs; `worstEvent`, the Interactions `type` and the Input-Latency-Breakdown event type follow that rule.
 
 `getINPDetails()` returns the 15 slowest interactions, slowest first, with the total in `count`. `target` is a CSS selector built like `details.element` of LCP, or `null` when the browser reports no target. Use it when `getINP()` shows poor INP and you need to identify patterns across multiple slow interactions. With no interactions yet it returns `status: "tracking"`, a `message`, `count: 0` and no items.
@@ -853,6 +873,8 @@ With no usage the script returns `count: 0`, no items and an `info` issue.
 
 Tracking scripts return `status: "tracking"` first. The function named by `getDataFn` returns the full result. Items are capped at 50 (20 for frames) and sorted by relevance; `count` holds the total.
 
+Interactions and Input-Latency-Breakdown read `first-input` as INP does, so an interaction that paints nothing counts when it is the first one, and the later ones under 16 ms have no entry.
+
 #### Interactions (tracking)
 
 ```json
@@ -1202,6 +1224,12 @@ Every issue has a `code` that says what it is, so a comparison pairs the issues
 
 An issue about one thing among several, one issue per thing, also names it in `target`: the URL of a resource, a CSS selector, or a name such as an event type or a CSS property. Two issues with the same code and different targets are two issues.
 
+### INP
+
+| Code | Severity | When |
+|------|----------|------|
+| `no-paint-measured` | info | The worst interaction took under 16 ms, too short for a frame, so the page most likely painted nothing after it |
+
 ### LCP-Image-Entropy
 
 | Code | Severity | When |
@@ -1622,7 +1650,7 @@ Each issue names its video in `target`, except `no-videos`.
 // Read the return value: the skill scripts have no console output
 result = evaluate_script(scriptCode)
 if result.status == "ok" → use result.value, result.rating, result.details, result.items
-if result.status == "tracking" → call evaluate_script(`${result.getDataFn}()`) after user interaction
+if result.status == "tracking" → call evaluate_script(`() => ${result.getDataFn}()`) after user interaction
 if result.status == "error" → check result.error, the browser may not have loaded the page yet
 if result.status == "unsupported" → browser does not support the required API (check: Chrome 107+?)
 ```
@@ -1637,7 +1665,7 @@ result = evaluate_script(INP_js)
 // 2. Wait for/trigger user interactions
 
 // 3. Collect data
-data = evaluate_script("getINP()")
+data = evaluate_script("() => getINP()")
 // data = { status: "ok", value: 350, rating: "needs-improvement", ... }
 ```
 

package/src/baseline.js

@@ -23,7 +23,8 @@ export const DEFAULT_THRESHOLDS = {
 // The baseline in a file, as { kind: "page" | "matrix", file, data }. Throws with what to do when
 // the file is not an output of the CLI.
 export function readBaseline(text, file) {
-  const howTo = `save one with webperf-snippets <url> --json > ${file}`;
+  // Never this path as the place to save it: the file is something else, and an agent may follow the message
+  const howTo = "give a file saved with webperf-snippets <url> --json";
   let data;
   try {
     data = JSON.parse(text);
@@ -49,18 +50,18 @@ export function loadBaseline(path) {
 // (absolute), CLS=0.1 (CLS has only an absolute part, with no unit)
 export function parseThreshold(raw) {
   const match = /^([A-Za-z]+)=(\d+(?:\.\d+)?)(%|ms)?$/.exec(raw.trim());
-  if (!match) throw new Error(`Invalid --threshold "${raw}": give METRIC=VALUE with its unit, such as LCP=15%, LCP=200ms or CLS=0.1`);
+  if (!match) throw new Error(`Invalid threshold "${raw}": give METRIC=VALUE with its unit, such as LCP=15%, LCP=200ms or CLS=0.1`);
   const [, name, number, unit] = match;
   const metric = name.toUpperCase();
-  if (!METRICS.includes(metric)) throw new Error(`Unknown metric "${name}" in --threshold "${raw}". Choose from: ${METRICS.join(", ")}`);
+  if (!METRICS.includes(metric)) throw new Error(`Unknown metric "${name}" in threshold "${raw}". Choose from: ${METRICS.join(", ")}`);
   const value = Number(number);
   if (metric === "CLS") {
-    if (unit) throw new Error(`Invalid --threshold "${raw}": CLS is a score, with no unit and no relative part, such as CLS=0.1`);
+    if (unit) throw new Error(`Invalid threshold "${raw}": CLS is a score, with no unit and no relative part, such as CLS=0.1`);
     return { metric, absolute: value };
   }
   if (unit === "%") return { metric, relative: value / 100 };
   if (unit === "ms") return { metric, absolute: value };
-  throw new Error(`Invalid --threshold "${raw}": give the unit, such as ${metric}=15% or ${metric}=200ms`);
+  throw new Error(`Invalid threshold "${raw}": give the unit, such as ${metric}=15% or ${metric}=200ms`);
 }
 
 // The default thresholds with the parts that --threshold changes
@@ -153,8 +154,17 @@ function targetOf(target, pageUrl) {
 // (69.21 KB)…" and "Render-blocking CSS (71.80 KB)…"
 const byMessage = (error) => `${error.id}\u0000${error.message.replace(/\d+(?:[.,]\d+)*/g, "#")}`;
 
+// One snippet measured on both sides is the same result, whatever name it was asked by: the CLI names
+// the result of --snippet as it was typed (an alias, its name or Category/Name), and the MCP server by
+// its path. Its conditions name it by its path on both.
+function baseResultsOf(base, current) {
+  const path = base.conditions?.snippet;
+  if (!path || path !== current.conditions?.snippet || current.results?.length !== 1) return base.results ?? [];
+  return base.results.map((r) => ({ ...r, id: current.results[0].id }));
+}
+
 function compareErrors(base, current) {
-  const baseErrors = blockingErrors(base.results ?? []);
+  const baseErrors = blockingErrors(baseResultsOf(base, current));
   const currentErrors = blockingErrors(current.results ?? []);
   // The snippets whose errors on one side all lack a code pair by message on both
   const uncoded = (errors) => {
@@ -194,8 +204,32 @@ function machineWarning(base, current) {
   return `the baseline was measured on another machine (${base.cpu}, ${base.cores} cores) than this run (${current.cpu}, ${current.cores} cores); timings can differ for that alone`;
 }
 
-// What differs in how both were measured. The comparison goes on: the warnings say how far to trust it.
-function warningsOf(base, current) {
+const valueCount = (payload, metric) => measured(payload, metric).values?.length ?? 1;
+
+// Why five runs can leave four values, when a run failed; a run that missed a metric alone does not count
+function afterFailedRuns(payload) {
+  const failed = payload.runs?.failed ?? 0;
+  return failed ? ` after ${failed} failed run${failed === 1 ? "" : "s"}` : "";
+}
+
+// The metrics compared on both sides that have no statistics, one line for each set of numbers. A
+// metric that one side lacks has no comparison to back, and its verdict already says "not measured".
+function statisticsWarnings(base, current, metrics) {
+  const metricsByNumbers = new Map();
+  for (const [metric, { stats, verdict }] of Object.entries(metrics)) {
+    if (stats || verdict === "not measured") continue;
+    const inBase = valueCount(base, metric);
+    const numbers = `the baseline has ${inBase} value${inBase === 1 ? "" : "s"}${afterFailedRuns(base)}, and this run ${valueCount(current, metric)}${afterFailedRuns(current)}`;
+    metricsByNumbers.set(numbers, [...(metricsByNumbers.get(numbers) ?? []), metric]);
+  }
+  return [...metricsByNumbers].map(
+    ([numbers, names]) => `no statistics for ${names.join(", ")}: ${numbers}; they need ${RUNS_FOR_STATISTICS} a side, so measure both with ${RUNS_FOR_STATISTICS} runs or more`
+  );
+}
+
+// What differs in how both were measured, and what it cost. The comparison goes on: the warnings say
+// how far to trust it.
+function warningsOf(base, current, metrics) {
   const warnings = [];
   const b = base.conditions;
   const c = current.conditions;
@@ -209,8 +243,12 @@ function warningsOf(base, current) {
   if (describeLoad(base.throttling) !== describeLoad(current.throttling)) {
     warnings.push(`the baseline was measured ${describeLoad(base.throttling)}, and this run ${describeLoad(current.throttling)}`);
   }
-  if (runCount(base) < 2) warnings.push("the baseline has 1 run, so only the thresholds apply; measure both with --runs");
-  else if (runCount(base) !== runCount(current)) warnings.push(`the baseline has ${runCount(base)} runs, and this run ${runCount(current)}`);
+  // In words for both: the CLI asks for runs with --runs, and the tools of the MCP server with runs
+  if (runCount(base) < 2) warnings.push(`the baseline has 1 run, so only the thresholds apply; measure both with ${RUNS_FOR_STATISTICS} runs or more`);
+  else {
+    if (runCount(base) !== runCount(current)) warnings.push(`the baseline has ${runCount(base)} runs, and this run ${runCount(current)}`);
+    warnings.push(...statisticsWarnings(base, current, metrics));
+  }
   const machine = machineWarning(b?.machine, c?.machine);
   if (machine) warnings.push(machine);
   if (b && c && b.cliVersion !== c.cliVersion) {
@@ -224,13 +262,14 @@ function warningsOf(base, current) {
 // A page against its baseline, as the `baseline` field of its JSON. The runs of the baseline say how
 // much to trust its values, in the header of the reports.
 export function compareRun(base, current, { file, thresholds = DEFAULT_THRESHOLDS }) {
+  const metrics = compareMetrics(base, current, thresholds);
   return {
     file,
     url: base.url,
     runs: base.runs ? { count: base.runs.count, medianBy: base.runs.medianBy } : { count: 1 },
-    metrics: compareMetrics(base, current, thresholds),
+    metrics,
     errors: compareErrors(base, current),
-    warnings: warningsOf(base, current),
+    warnings: warningsOf(base, current, metrics),
   };
 }