webperf-snippets 1.11.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.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.12.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.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              |
@@ -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. `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.11.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

@@ -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 |

package/src/baseline.js

@@ -204,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;
@@ -221,7 +245,10 @@ function warningsOf(base, 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)}`);
+  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) {
@@ -235,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),
   };
 }
 

package/src/bin.js

@@ -89,6 +89,7 @@ Options:
   --verbose             Show all items, even for passing checks
   --headed              Show the browser window (debug)
   -h, --help            Show this help
+  -v, --version         Show the version
 
 Examples:
   npx webperf-snippets https://example.com
@@ -182,6 +183,7 @@ async function main() {
         verbose: { type: "boolean" },
         headed: { type: "boolean" },
         help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
       },
       allowPositionals: true,
     });
@@ -196,6 +198,11 @@ async function main() {
     return;
   }
 
+  if (values.version) {
+    process.stdout.write(`${cliVersion}\n`);
+    return;
+  }
+
   const url = positionals[0];
   const matrixPath = values.matrix;
   if (url && matrixPath) fail("Use a URL or --matrix, not both");

package/src/mcp/queue.js

@@ -0,0 +1,72 @@
+// The reason of an abort is whatever the client sent, often a string, or nothing: a caller gets an error
+const gaveUp = () => new Error("The caller gave up while it waited for its turn");
+
+// One task at a time, in the order they arrive. A caller that gives up while it waits leaves the line
+// at once, so it never runs and holds up no one. A task that fails passes the turn like any other, and
+// its failure stays with its caller.
+//
+// A waiting caller hears how many tasks are ahead when it starts to wait, whenever the line moves, and
+// every `reportEveryMs` while it does not: a client can restart its timeout on each report, and a task
+// ahead can take minutes.
+export function createQueue({ reportEveryMs = 5000 } = {}) {
+  const waiting = [];
+  let taken = false;
+
+  // A report is a courtesy: one that fails, as one to a client that left, changes nothing
+  const report = async ({ onWait }, ahead) => {
+    try {
+      await onWait?.(ahead);
+    } catch {
+      // nothing to tell, and no one to tell it to
+    }
+  };
+  const reportAll = () => waiting.forEach((waiter, i) => report(waiter, i + 1));
+
+  function take({ signal, onWait }) {
+    if (signal?.aborted) return Promise.reject(gaveUp());
+    if (!taken) {
+      taken = true;
+      return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+      const waiter = { onWait };
+      const leave = () => {
+        waiting.splice(waiting.indexOf(waiter), 1);
+        clearInterval(timer);
+        signal?.removeEventListener("abort", cancel);
+      };
+      const cancel = () => {
+        leave();
+        reject(gaveUp());
+        reportAll();
+      };
+      waiter.enter = () => {
+        leave();
+        resolve();
+      };
+      const timer = setInterval(() => report(waiter, waiting.indexOf(waiter) + 1), reportEveryMs);
+      // The timer alone must not keep the process alive
+      timer.unref?.();
+      signal?.addEventListener("abort", cancel, { once: true });
+      waiting.push(waiter);
+      report(waiter, waiting.length);
+    });
+  }
+
+  function pass() {
+    taken = waiting.length > 0;
+    waiting[0]?.enter();
+    reportAll();
+  }
+
+  async function run(task, options = {}) {
+    await take(options);
+    try {
+      return await task();
+    } finally {
+      pass();
+    }
+  }
+
+  return { run };
+}

package/src/mcp/server.js

@@ -10,6 +10,7 @@ import { RULES } from "../decision-tree.js";
 import { fetchCrux, fetchCruxHistory } from "../crux.js";
 import { runInteractions, isInputStep, settle } from "../interactions.js";
 import { createSessions, SessionError } from "./sessions.js";
+import { createQueue } from "./queue.js";
 import { launchChromium, isMissingBrowser, MISSING_BROWSER } from "../browser.js";
 import { registerResources } from "./documents.js";
 import { registerPrompts } from "./prompts.js";
@@ -24,6 +25,10 @@ import { MAX_RUNS, measureRuns } from "../runs.js";
 const VIEWPORTS = Object.keys(VIEWPORT_PRESETS);
 const STAGES = 3;
 const NAV_TIMEOUT_MS = 30000;
+// How long a page load can keep its turn: far beyond the load and the wait, which have their own limits
+// (30 s and 10 s), because a run that reaches this is not slow. A page whose main thread never yields
+// answers no evaluation, and Playwright has no timeout for one, so it would hold up the queue for ever.
+const CALL_LIMIT_MS = 120000;
 
 const HttpUrl = z
   .string()
@@ -111,6 +116,7 @@ const NextSteps = z
 const DETAIL_NOTE =
   "Large results come as summaries with a runId for get_details; nextSteps, when present, is the call to make next.";
 const BASELINE_NOTE = "With baseline, it also compares the run with an earlier one, as --baseline of the CLI, and says what regressed.";
+const QUEUE_NOTE = "Measurements run one at a time, so several in one turn save no time.";
 
 // A page can put instructions for the agent in what a snippet returns: an alt text, a class in a
 // selector, the URL of a script. The tools that return what a page holds say how to read it, and so
@@ -162,12 +168,44 @@ function progressFor(ctx, runs) {
         });
 }
 
+// The report of a call that waits for its turn, for a client that wants progress: how many calls are
+// ahead. Progress has to grow with each report, and the stages of a run start at 1, so it stays below 1.
+function waitProgressFor(ctx, total) {
+  const progressToken = ctx.mcpReq._meta?.progressToken;
+  if (progressToken === undefined) return undefined;
+  let reports = 0;
+  return (ahead) => {
+    reports++;
+    const message = `Waiting for its turn: ${ahead} ${ahead === 1 ? "call" : "calls"} ahead`;
+    return ctx.mcpReq.notify({ method: "notifications/progress", params: { progressToken, progress: reports / (reports + 1), ...(total ? { total } : {}), message } });
+  };
+}
+
+const stoppedAnswering = (limitMs) => `The page did not answer within ${limitMs / 1000} seconds`;
+
+// A page that stopped answering is closed, and the runs left of the call would only hold up the queue
+class PageStoppedError extends Error {}
+const endsTheCall = (err) => isMissingBrowser(err) || err instanceof PageStoppedError;
+
 // A page load measured once, or `count` times with the median run as the answer, as --runs of the CLI.
-// When the client gives up (a cancel, its timeout, or leaving), the runs left never start.
-async function measurePage(measure, count, ctx) {
+// `measure` gets the signal of its run, which closes its Chromium. When the client gives up (a cancel,
+// its timeout, or leaving), the run in progress ends and the runs left never start.
+async function measurePage(measure, count, ctx, limitMs) {
   const progress = progressFor(ctx, count);
-  if (count === 1) return measure(progress(1));
-  const { payload, runs, errors } = await measureRuns((i) => measure(progress(i)), count, { isFatal: isMissingBrowser, signal: ctx.mcpReq.signal });
+  const measureRun = async (run) => {
+    const limit = AbortSignal.timeout(limitMs);
+    let measured;
+    try {
+      measured = await measure(progress(run), AbortSignal.any([ctx.mcpReq.signal, limit]));
+    } catch (err) {
+      if (!limit.aborted) throw err;
+    }
+    // The runner keeps a failed evaluation as a result, and closing Chromium fails every one
+    if (limit.aborted) throw new PageStoppedError(stoppedAnswering(limitMs));
+    return measured;
+  };
+  if (count === 1) return measureRun(1);
+  const { payload, runs, errors } = await measureRuns(measureRun, count, { isFatal: endsTheCall, signal: ctx.mcpReq.signal });
   if (!payload) throw new Error(`Every run failed: ${[...new Set(errors.map(firstLine))].join("; ")}`);
   return { ...payload, runs };
 }
@@ -224,10 +262,18 @@ function registerRuns(server, runs) {
 
 // The MCP server of the CLI: the same snippets and runner, offered as tools an agent calls by name.
 // serveStdio creates one instance per connection, so the pages it keeps open belong to that client.
-export function createServer({ launchBrowser = () => launchChromium(), maxPages, idleMs, env = process.env, machine = machineOf } = {}) {
+export function createServer({ launchBrowser = () => launchChromium(), maxPages, idleMs, env = process.env, machine = machineOf, callLimitMs = CALL_LIMIT_MS, reportEveryMs } = {}) {
   const server = new McpServer({ name: "webperf-snippets", version: cliVersion }, { instructions: INSTRUCTIONS });
   const sessions = createSessions({ launchBrowser, maxPages, idleMs });
   const runs = createRuns();
+  // An agent sends several calls in one turn and the client runs them at once. The calls that make a page
+  // work take turns (run_snippet, run_workflow, open_page, interact): a load or a click competes for the
+  // CPU with any other, which inflates what each page reports. A call keeps its turn only while it runs,
+  // so it can wait only for something that ends on its own: never for a later call of the agent, and
+  // never for a page left open, which keeps no turn. read_results and close_page take no turn: they ask
+  // little of Chromium, and they are how an agent gets out of a page.
+  const queue = createQueue({ reportEveryMs });
+  const inTurn = (ctx, total, task) => queue.run(task, { signal: ctx.mcpReq.signal, onWait: waitProgressFor(ctx, total) });
   // The client left (end of stdin, or a closed transport): close the pages and Chromium
   server.server.onclose = () => sessions.closeAll();
   registerResources(server);
@@ -235,10 +281,13 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
   registerRuns(server, runs);
 
   // The machine goes in the conditions of every run, as in the JSON of the CLI, so a baseline measured
-  // on another one warns. It is measured once, with the first run, before its Chromium starts.
+  // on another one warns. It is measured once, in the turn of the first run, before its Chromium starts.
   let machineOfServer;
   const conditionsOf = (conditions) => measurementConditions({ ...conditions, machine: (machineOfServer ??= machine()) });
 
+  const measureInTurn = (conditions, measure, count, ctx) =>
+    inTurn(ctx, STAGES * count, async () => ({ conditions: conditionsOf(conditions), run: await measurePage(measure, count, ctx, callLimitMs) }));
+
   // A run of a page load, kept with its page in the shape of the JSON of the CLI: its runId is the
   // baseline of a later run, and the resources list it
   const keepPage = (run, results, conditions) => {
@@ -292,7 +341,7 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
     {
       title: "Run a snippet",
       description:
-        `Opens the URL in a headless Chromium, runs one web performance snippet on the loaded page and returns the object the snippet returns, as defined in snippets/SCHEMA.md. Use list_snippets for the names. The snippets that record interactions (INP, Interactions, Input-Latency-Breakdown) run on a page opened with open_page instead. ${BASELINE_NOTE} ${DETAIL_NOTE} ${PAGE_DATA}`,
+        `Opens the URL in a headless Chromium, runs one web performance snippet on the loaded page and returns the object the snippet returns, as defined in snippets/SCHEMA.md. Use list_snippets for the names. The snippets that record interactions (INP, Interactions, Input-Latency-Breakdown) run on a page opened with open_page instead. ${QUEUE_NOTE} ${BASELINE_NOTE} ${DETAIL_NOTE} ${PAGE_DATA}`,
       inputSchema: z.object({
         url: HttpUrl,
         snippet: z.string().describe("The snippet: its name (LCP-Subparts), an alias (render-blocking) or Category/Name"),
@@ -337,8 +386,12 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
       }
 
       try {
-        const conditions = conditionsOf({ viewport, snippet: path, waitMs });
-        const run = await measurePage((onProgress) => runSnippets({ url, items: [{ id: path, path, source }], waitMs, viewport: VIEWPORT_PRESETS[viewport], onProgress }), count, ctx);
+        const { conditions, run } = await measureInTurn(
+          { viewport, snippet: path, waitMs },
+          (onProgress, signal) => runSnippets({ url, items: [{ id: path, path, source }], waitMs, viewport: VIEWPORT_PRESETS[viewport], onProgress, signal }),
+          count,
+          ctx
+        );
         const shaped = shapeResults(run.results.map(({ id, ...result }) => result), detail);
         const { runId, current } = keepPage(run, run.results, conditions);
         const id = run.results[0].id;
@@ -369,7 +422,7 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
     {
       title: "Run a workflow",
       description:
-        `Opens the URL in a headless Chromium and runs a workflow: a sequence of snippets plus the follow-ups its decision tree adds from the results (for example LCP-Subparts when LCP is over 2.5 s, with the reason). core-web-vitals: LCP and CLS. audit: render-blocking resources, resource hints, critical CSS, TTFB, scripts, images and more. loading: TTFB, FCP, render-blocking, scripts and fonts. interaction: long tasks, animation frames, scroll and layout shifts while it scrolls the page. ${BASELINE_NOTE} ${DETAIL_NOTE} ${PAGE_DATA}`,
+        `Opens the URL in a headless Chromium and runs a workflow: a sequence of snippets plus the follow-ups its decision tree adds from the results (for example LCP-Subparts when LCP is over 2.5 s, with the reason). core-web-vitals: LCP and CLS. audit: render-blocking resources, resource hints, critical CSS, TTFB, scripts, images and more. loading: TTFB, FCP, render-blocking, scripts and fonts. interaction: long tasks, animation frames, scroll and layout shifts while it scrolls the page. ${QUEUE_NOTE} ${BASELINE_NOTE} ${DETAIL_NOTE} ${PAGE_DATA}`,
       inputSchema: z.object({
         url: HttpUrl,
         workflow: z.enum(Object.keys(WORKFLOWS)).default("core-web-vitals"),
@@ -405,9 +458,9 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
         return toolError(err.message);
       }
       try {
-        const conditions = conditionsOf({ viewport, workflow, waitMs });
-        const run = await measurePage(
-          (onProgress) => runMeasurement({ url, workflow: WORKFLOWS[workflow], rules: RULES, waitMs, viewport: VIEWPORT_PRESETS[viewport], onProgress }),
+        const { conditions, run } = await measureInTurn(
+          { viewport, workflow, waitMs },
+          (onProgress, signal) => runMeasurement({ url, workflow: WORKFLOWS[workflow], rules: RULES, waitMs, viewport: VIEWPORT_PRESETS[viewport], onProgress, signal }),
           count,
           ctx
         );
@@ -537,27 +590,33 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
         items.push({ id: path, path, source });
       }
 
-      let session;
-      try {
-        session = await sessions.create({ viewport: VIEWPORT_PRESETS[viewport], signal: ctx.mcpReq.signal });
-      } catch (err) {
-        if (isMissingBrowser(err)) return toolError(MISSING_BROWSER);
-        throw err;
-      }
-      try {
-        const navStart = Date.now();
-        await session.page.goto(url, { waitUntil: "load", timeout: NAV_TIMEOUT_MS });
-        if (waitMs > 0) await session.page.waitForTimeout(waitMs);
-        const navMs = Date.now() - navStart;
-        session.tracking = await evaluateItems(session.page, items);
-        session.stopListening();
-        const tracking = session.tracking.map(({ id, status }) => ({ snippet: id, status }));
-        return toolResult({ sessionId: session.id, url, viewport, navMs, tracking });
-      } catch (err) {
-        await sessions.close(session.id);
-        if (/page\.goto/.test(err.message)) return toolError(`Could not load ${url}: ${firstLine(err.message)}`);
-        return toolError(`Opening the page failed: ${firstLine(err.message)}`);
-      }
+      return inTurn(ctx, undefined, async () => {
+        const limit = AbortSignal.timeout(callLimitMs);
+        let session;
+        try {
+          session = await sessions.create({ viewport: VIEWPORT_PRESETS[viewport], signal: AbortSignal.any([ctx.mcpReq.signal, limit]) });
+        } catch (err) {
+          if (isMissingBrowser(err)) return toolError(MISSING_BROWSER);
+          throw err;
+        }
+        try {
+          const navStart = Date.now();
+          await session.page.goto(url, { waitUntil: "load", timeout: NAV_TIMEOUT_MS });
+          if (waitMs > 0) await session.page.waitForTimeout(waitMs);
+          const navMs = Date.now() - navStart;
+          session.tracking = await evaluateItems(session.page, items);
+          // evaluateItems keeps a failed evaluation as a result, and closing the page fails every one
+          if (limit.aborted) return toolError(`Opening the page failed: ${stoppedAnswering(callLimitMs)}`);
+          session.stopListening();
+          const tracking = session.tracking.map(({ id, status }) => ({ snippet: id, status }));
+          return toolResult({ sessionId: session.id, url, viewport, navMs, tracking });
+        } catch (err) {
+          await sessions.close(session.id);
+          if (limit.aborted) return toolError(`Opening the page failed: ${stoppedAnswering(callLimitMs)}`);
+          if (/page\.goto/.test(err.message)) return toolError(`Could not load ${url}: ${firstLine(err.message)}`);
+          return toolError(`Opening the page failed: ${firstLine(err.message)}`);
+        }
+      });
     })
   );
 
@@ -575,16 +634,28 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
       // A click can submit a form or change data on the site, so this tool is not read-only
       annotations: { readOnlyHint: false, openWorldHint: true },
     },
-    withSession(async ({ sessionId, steps }) => {
-      const session = sessions.get(sessionId);
-      try {
-        await runInteractions(session.page, steps);
-      } catch (err) {
-        return toolError(`A step failed: ${firstLine(err.message)}`);
-      }
-      session.hadInput ||= steps.some(isInputStep);
-      await settle(session.page);
-      return toolResult({ sessionId, steps: steps.length, url: session.page.url() });
+    withSession(async ({ sessionId, steps }, ctx) => {
+      // A page that is not open answers now, not after a turn it does not need
+      sessions.get(sessionId);
+      return inTurn(ctx, undefined, async () => {
+        const session = sessions.get(sessionId);
+        // A wait step is time the agent asked for. Closing the page fails whatever it stopped answering.
+        const limitMs = callLimitMs + steps.reduce((sum, step) => sum + (step.ms ?? 0), 0);
+        const limit = AbortSignal.timeout(limitMs);
+        const closePage = () => sessions.close(sessionId);
+        limit.addEventListener("abort", closePage, { once: true });
+        try {
+          await runInteractions(session.page, steps);
+          session.hadInput ||= steps.some(isInputStep);
+          await settle(session.page);
+          if (!limit.aborted) return toolResult({ sessionId, steps: steps.length, url: session.page.url() });
+        } catch (err) {
+          if (!limit.aborted) return toolError(`A step failed: ${firstLine(err.message)}`);
+        } finally {
+          limit.removeEventListener("abort", closePage);
+        }
+        return toolError(`${stoppedAnswering(limitMs)}, and it was closed. Open it again with open_page.`);
+      });
     })
   );
 

package/src/runner.js

@@ -21,6 +21,12 @@ const DEFAULT_NAV_TIMEOUT = 30000;
 const LATE_ENTRIES_MS = 2000;
 const POLL_MS = 100;
 
+// A snippet still tracking after that wait has seen no interaction at all, and the browser agrees: a
+// click that paints nothing is recorded too. The message of the snippet (click on the page, then call
+// the function again) would ask for what the run has just done.
+const NOTHING_RECORDED =
+  "A click or key press was sent, and this document recorded no interaction. Check that it reaches an element of this document: an interaction inside an iframe is recorded by the iframe.";
+
 // Snippets are IIFEs. Playwright evaluates a string as an expression, so we
 // trim trailing semicolons to keep the IIFE call as a single expression and
 // recover its return value in Node.
@@ -83,13 +89,26 @@ export async function collectTrackingData(page, result, hasInput) {
       await page.waitForTimeout(POLL_MS);
       data = await read();
     }
-    if (data && typeof data === "object") return { id: result.id, ...data };
+    if (data && typeof data === "object") {
+      const sentAndMissed = hasInput && data.status === "tracking";
+      return { id: result.id, ...data, ...(sentAndMissed && { message: NOTHING_RECORDED }) };
+    }
     return { id: result.id, status: "error", error: `${result.getDataFn}() did not return an object` };
   } catch (err) {
     return { id: result.id, status: "error", error: `${result.getDataFn}() failed: ${err.message}` };
   }
 }
 
+// An aborted signal closes Chromium, which fails whatever the run is waiting for, a page that stopped
+// answering included: Playwright has no timeout for an evaluation. Returns what stops listening.
+function closeOnAbort(browser, signal) {
+  if (!signal) return () => {};
+  const close = () => browser.close().catch(() => {});
+  if (signal.aborted) close();
+  signal.addEventListener("abort", close, { once: true });
+  return () => signal.removeEventListener("abort", close);
+}
+
 export async function runSnippets({
   url,
   items,
@@ -106,9 +125,11 @@ export async function runSnippets({
   ownDomains,
   // Called at each of the three stages of a run, for callers that report progress (the MCP server)
   onProgress = () => {},
+  signal,
 }) {
   await onProgress(1, "Opening Chromium");
   const browser = await launchChromium({ headless });
+  const stopListening = closeOnAbort(browser, signal);
   try {
     const context = await browser.newContext({ viewport, storageState });
     const page = await context.newPage();
@@ -126,6 +147,7 @@ export async function runSnippets({
     await onProgress(3, "Snippets evaluated");
     return { url, navMs, results, pageErrors, throttling: throttlingOf({ cpu, network }) };
   } finally {
+    stopListening();
     await browser.close();
   }
 }
@@ -146,9 +168,11 @@ export async function runMeasurement({
   network,
   ownDomains,
   onProgress = () => {},
+  signal,
 }) {
   await onProgress(1, "Opening Chromium");
   const browser = await launchChromium({ headless });
+  const stopListening = closeOnAbort(browser, signal);
   try {
     const context = await browser.newContext({ viewport, storageState });
     const page = await context.newPage();
@@ -212,6 +236,7 @@ export async function runMeasurement({
     await onProgress(3, "Workflow and follow-ups evaluated");
     return { url, navMs, results: [...initialResults, ...followUpResults], pageErrors, throttling: throttlingOf({ cpu, network }) };
   } finally {
+    stopListening();
     await browser.close();
   }
 }

package/src/snippet-names.js

@@ -11,6 +11,12 @@ const SNIPPET_ALIASES = {
   CLS: "CoreWebVitals/CLS",
   INP: "CoreWebVitals/INP",
   "LCP-Subparts": "CoreWebVitals/LCP-Subparts",
+  // The full names of the metrics, in any case: the words someone types who does not know the acronym
+  "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",
   "Fonts-Preloaded-Loaded-and-used-above-the-fold":
     "Loading/Fonts-Preloaded-Loaded-and-used-above-the-fold",
@@ -65,34 +71,99 @@ export function listSnippets() {
   return cache;
 }
 
+// The edits between two strings. Swapping two neighbours counts as one: LPC is one edit from LCP.
 function distance(a, b) {
-  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  let twoBack = [];
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
   for (let i = 1; i <= a.length; i++) {
-    let previous = row[0];
-    row[0] = i;
+    const row = [i];
     for (let j = 1; j <= b.length; j++) {
-      const current = row[j];
-      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
-      previous = current;
+      row[j] = Math.min(previous[j] + 1, row[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) row[j] = Math.min(row[j], twoBack[j - 2] + 1);
     }
+    twoBack = previous;
+    previous = row;
   }
-  return row[b.length];
+  return previous[b.length];
 }
 
-// Turns an alias, a bare snippet name or a Category/Name path into a Category/Name path.
-// Only a listed snippet resolves, so a name can never point at a file outside the snippets.
-export function resolveSnippetName(name) {
+// The words of a name, without their endings: LongTask and long-tasks give the same two.
+function wordsOf(name) {
+  return name
+    .replace(/([a-z])([A-Z])|([A-Z])([A-Z][a-z])/g, "$1$3-$2$4")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean)
+    .map((word) => (word.length > 4 ? word.replace(/(ing|ed)?s?$/, "") : word));
+}
+
+// The words of a guess that say nothing of what a snippet looks at. They rank, but do not make a match.
+const GENERIC_WORDS = new Set(wordsOf("and the of with by find audit analysis analyzer info detection validation performance"));
+
+// Equal, inside a longer word of the name (font in webfont), or a typo apart. Words of three letters only
+// count when equal, and a typo needs five letters: size and side are one edit apart.
+function isSameWord(guessed, word) {
+  if (guessed === word) return true;
+  if (Math.min(guessed.length, word.length) < 4) return false;
+  return word.includes(guessed) || (Math.max(guessed.length, word.length) > 4 && distance(guessed, word) === 1);
+}
+
+// How close a guess is to a name or an alias of a snippet, from 0 to 1: the share of its words the name
+// has, or how alike they are spelled, which catches what splits into other words, such as LCP-Sub-Parts.
+// Under MIN_SPELLING the likeness is chance: any two short names share letters.
+const MIN_SPELLING = 0.65;
+const MIN_SCORE = 0.5;
+const NEAR_THE_FIRST = 0.75;
+const MAX_SUGGESTIONS = 5;
+
+function closeness(guess, name) {
+  const [a, b] = [guess.toLowerCase(), name.toLowerCase()];
+  const spelling = 1 - distance(a, b) / Math.max(a.length, b.length);
+  const words = wordsOf(name);
+  const guessed = wordsOf(guess);
+  const found = guessed.filter((word) => words.some((other) => isSameWord(word, other)));
+  const shared = found.some((word) => !GENERIC_WORDS.has(word)) ? found.length / guessed.length : 0;
+  return Math.max(spelling >= MIN_SPELLING ? spelling : 0, shared);
+}
+
+// The snippets a guess may have meant, the closest first, and on a tie the shortest name, which says the
+// least else: Script-Loading before Inline-Script-Info-and-Size.
+function suggestionsFor(guess) {
+  const ranked = listSnippets()
+    .map((path) => {
+      const name = path.split("/")[1];
+      const score = Math.max(...[name, ...aliasesOf(path)].map((n) => closeness(guess, n)));
+      return { path, score, length: wordsOf(name).length };
+    })
+    .filter((snippet) => snippet.score >= MIN_SCORE)
+    .sort((a, b) => b.score - a.score || a.length - b.length);
+  return ranked
+    .filter((snippet) => snippet.score >= ranked[0].score * NEAR_THE_FIRST)
+    .slice(0, MAX_SUGGESTIONS)
+    .map((snippet) => snippet.path);
+}
+
+// An alias as written, then a snippet name in any case, then an alias in any case: TTFB is the snippet,
+// and ttfb the alias of its sub-parts.
+function findSnippet(name) {
   if (Object.hasOwn(SNIPPET_ALIASES, name)) return SNIPPET_ALIASES[name];
-  const all = listSnippets();
   const wanted = name.toLowerCase();
-  const found = all.find((path) => path.toLowerCase() === wanted || path.split("/")[1].toLowerCase() === wanted);
+  const snippet = listSnippets().find((path) => path.toLowerCase() === wanted || path.split("/")[1].toLowerCase() === wanted);
+  if (snippet) return snippet;
+  const alias = Object.keys(SNIPPET_ALIASES).find((key) => key.toLowerCase() === wanted);
+  return alias && SNIPPET_ALIASES[alias];
+}
+
+// Turns an alias, a bare snippet name or a Category/Name path into a Category/Name path. The name decides
+// and not the category: no two snippets share a name, so a wrong category can only mean that snippet.
+// Only a listed snippet resolves, so a name can never point at a file outside the snippets.
+export function resolveSnippetName(name) {
+  const [category, bare, ...rest] = name.split("/");
+  const inCategory = bare && rest.length === 0 && CATEGORIES.some((c) => c.toLowerCase() === category.toLowerCase());
+  const found = findSnippet(name) ?? (inCategory ? findSnippet(bare) : undefined);
   if (found) return found;
 
-  const bare = wanted.split("/").pop();
-  const closest = all
-    .map((path) => ({ path, score: distance(bare, path.split("/")[1].toLowerCase()) }))
-    .sort((a, b) => a.score - b.score)
-    .slice(0, 3)
-    .map((c) => c.path);
-  throw new Error(`Unknown snippet "${name}". Closest: ${closest.join(", ")}. Run with a snippet name such as Compression-Audit, or a Category/Name path.`);
+  const suggestions = suggestionsFor(name.split("/").pop());
+  const answer = suggestions.length > 0 ? `Closest: ${suggestions.join(", ")}.` : "No snippet has a close name.";
+  throw new Error(`Unknown snippet "${name}". ${answer} Every name is in the list_snippets tool of the MCP server and in https://webperf-snippets.net/llms.txt.`);
 }