webperf-snippets 1.10.0 → 1.12.0

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/runs.js

@@ -4,6 +4,11 @@ import { DEFAULT_THRESHOLDS } from "./baseline.js";
 // Every result of the report comes from that run, so they agree with each other (the sub-parts of
 // the LCP add up to its LCP), and a summary gives the median, min and max of each metric.
 
+// The most runs of a measurement, the same in the tools of the MCP server as in --runs. Mann-Whitney U
+// needs five a side (baseline.js), so nine leave room for failed runs and for a noisy page, and a page
+// that takes a few seconds to load stays under two minutes.
+export const MAX_RUNS = 9;
+
 // The metrics the snippets report, and navMs, which every run has
 export const MEDIAN_METRICS = ["LCP", "FCP", "TTFB", "CLS", "INP", "navMs"];
 
@@ -50,6 +55,23 @@ export function describeRuns({ count, failed, medianRun, medianBy, medianByReque
   return `${count} run${count === 1 ? "" : "s"}, median by ${by}: run ${medianRun}${failed ? ` (${failed} failed)` : ""}`;
 }
 
+// Measures `count` runs one after the other, never in parallel: they would compete for the CPU and
+// skew the timings. A run that fails is kept as { error } and left out of the median, unless isFatal
+// says the next run would fail the same way. An aborted signal, a caller that left, starts no more runs.
+export async function measureRuns(measure, count, { medianBy, isFatal = () => false, signal } = {}) {
+  const runs = [];
+  for (let i = 1; i <= count; i++) {
+    signal?.throwIfAborted();
+    try {
+      runs.push(await measure(i));
+    } catch (err) {
+      if (isFatal(err)) throw err;
+      runs.push({ error: err.message });
+    }
+  }
+  return summarizeRuns(runs, { medianBy });
+}
+
 // The runs as the CLI made them, in order, a run that failed being { error }. Returns the payload of
 // the median run and the `runs` field of the report, or nulls and the errors when every run failed.
 export function summarizeRuns(runs, { medianBy: requested } = {}) {

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.`);
 }