webperf-snippets 1.4.0 → 1.6.0

package/src/mcp/documents.js

@@ -19,30 +19,50 @@ function readDocument(relativePath) {
 }
 
 // Splits SCHEMA.md into the general contract and the section of each snippet ("#### LCP" up to the next
-// heading of that level or above). The general contract is everything outside "## Script-Specific Schemas".
+// heading of that level or above). The general contract is everything outside "## Script-Specific Schemas"
+// and outside the tables of "## Issue codes", whose rules it keeps. The table of a snippet ("### LCP"
+// under Issue codes) goes with its section, or makes one when the snippet has none.
 export function splitSchema(markdown) {
   const lines = markdown.split("\n");
-  const start = lines.findIndex((l) => l.startsWith("## Script-Specific Schemas"));
-  const end = lines.findIndex((l, i) => i > start && l.startsWith("## "));
-  const general = [...lines.slice(0, start), ...lines.slice(end)].join("\n");
+  const sectionOf = (heading) => {
+    const start = lines.findIndex((l) => l.startsWith(heading));
+    if (start === -1) return [lines.length, lines.length];
+    const next = lines.findIndex((l, i) => i > start && l.startsWith("## "));
+    return [start, next === -1 ? lines.length : next];
+  };
+  const [schemasStart, schemasEnd] = sectionOf("## Script-Specific Schemas");
+  const [codesStart, codesEnd] = sectionOf("## Issue codes");
+  const firstTable = lines.findIndex((l, i) => i > codesStart && i < codesEnd && l.startsWith("### "));
+  const tablesStart = firstTable === -1 ? codesEnd : firstTable;
+  const general = lines
+    .filter((_, i) => !(i >= schemasStart && i < schemasEnd) && !(i >= tablesStart && i < codesEnd))
+    .join("\n");
 
   const sections = new Map();
-  let name = null;
-  let current = [];
-  const flush = () => name && sections.set(name, current.join("\n").trim());
-  for (const line of lines.slice(start, end)) {
-    if (line.startsWith("#### ")) {
-      flush();
-      name = line.slice(5).split(" ")[0];
-      current = [line];
-    } else if (/^#{1,3} /.test(line)) {
-      flush();
-      name = null;
-    } else if (name) {
-      current.push(line);
+  const collect = (from, to, level, add) => {
+    let name = null;
+    let current = [];
+    const flush = () => name && add(name, current.join("\n").trim());
+    for (const line of lines.slice(from, to)) {
+      if (line.startsWith(`${level} `)) {
+        flush();
+        name = line.slice(level.length + 1).split(" ")[0];
+        current = [line];
+      } else if (/^#{1,4} /.test(line)) {
+        flush();
+        name = null;
+      } else if (name) {
+        current.push(line);
+      }
     }
-  }
-  flush();
+    flush();
+  };
+  collect(schemasStart, schemasEnd, "####", (name, text) => sections.set(name, text));
+  collect(tablesStart, codesEnd, "###", (name, text) => {
+    // The last table runs into the rule that closes the section
+    const table = `Issue codes:\n${text.split("\n").slice(1).join("\n").replace(/\n+---$/, "")}`;
+    sections.set(name, sections.has(name) ? `${sections.get(name)}\n\n${table}` : `#### ${name}\n\n${table}`);
+  });
   return { general, sections };
 }
 
@@ -65,7 +85,7 @@ export function registerResources(server) {
     "webperf://schema",
     {
       title: "Snippet result contract",
-      description: "What every snippet returns: the base shape, the statuses, the execution patterns and how to read a result. The fields of each snippet are in webperf://schema/{snippet}.",
+      description: "What every snippet returns: the base shape, the statuses, the execution patterns, how to read a result and the rules of the issue codes. The fields and the issue codes of each snippet are in webperf://schema/{snippet}.",
       mimeType: MARKDOWN,
     },
     async (uri) => markdown(uri, schemaSection())
@@ -80,7 +100,7 @@ export function registerResources(server) {
     }),
     {
       title: "Result of one snippet",
-      description: "The fields one snippet returns, with an example, from snippets/SCHEMA.md.",
+      description: "The fields one snippet returns, with an example, and the codes of its issues, from snippets/SCHEMA.md.",
       mimeType: MARKDOWN,
     },
     async (uri, { snippet }) => {

package/src/mcp/server.js

@@ -350,7 +350,7 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
     {
       title: "Read the tracking snippets",
       description:
-        "Returns what the tracking snippets installed by open_page have recorded on the page so far, as the objects they return. A snippet with nothing recorded yet answers with status error, which is a result, not a failure.",
+        "Returns what the tracking snippets installed by open_page have recorded on the page so far, as the objects they return. A snippet with nothing recorded yet, such as INP before any interaction, answers with status tracking and a message: interact with the page and read again.",
       inputSchema: z.object({ sessionId: SessionId }),
       outputSchema: z.object({ sessionId: z.string(), pageErrors: z.array(z.string()), results: z.array(SnippetResult) }),
       annotations: { readOnlyHint: true, openWorldHint: false },

package/src/reporters/budgets-view.js

@@ -0,0 +1,38 @@
+// The budgets as the reports show them, each report with its own format of a value: a row per budget,
+// passed or not, with by how much it was exceeded or why its metric was not measured.
+
+const difference = (budget) => {
+  const over = budget.value - budget.budget;
+  return budget.unit === "ms" ? Math.round(over) : Math.round(over * 10000) / 10000;
+};
+
+export function budgetRows(budgets, format) {
+  return budgets.map((b) => ({
+    metric: b.metric,
+    value: b.value == null ? "·" : format(b.value, b.unit),
+    budget: format(b.budget, b.unit),
+    passed: b.verdict === "passed",
+    verdict:
+      b.verdict === "exceeded"
+        ? `exceeded by ${format(difference(b), b.unit)}`
+        : b.verdict === "not measured"
+          ? `not measured${b.note ? `: ${b.note}` : ""}`
+          : "passed",
+  }));
+}
+
+// The failed budgets of a matrix, each named with its combination, or null when no combination had
+// budgets to check
+export function matrixBudgetFailures(combinations, format) {
+  const checked = combinations.filter((c) => Array.isArray(c.budgets) && c.budgets.length > 0);
+  if (checked.length === 0) return null;
+  return checked.flatMap((c) =>
+    c.budgets
+      .filter((b) => b.verdict !== "passed")
+      .map((b) =>
+        b.verdict === "exceeded"
+          ? `${c.id}: ${b.metric} ${format(b.value, b.unit)} exceeds budget ${format(b.budget, b.unit)}`
+          : `${c.id}: ${b.metric} was not measured${b.note ? ` (${b.note})` : ""}`
+      )
+  );
+}

package/src/reporters/human.js

@@ -1,9 +1,12 @@
 import { styleText } from "node:util";
+import { describeResult } from "../view.js";
+import { isSummaryResult, summaryNumbers } from "./summary-view.js";
 import { fieldDataView } from "../crux.js";
 import { describeThrottling } from "../throttling.js";
 import { describeRuns } from "../runs.js";
 import { matrixView } from "./matrix-view.js";
 import { baselineView } from "./baseline-view.js";
+import { budgetRows, matrixBudgetFailures } from "./budgets-view.js";
 
 const RATING_ICON = {
   good: "🟢",
@@ -102,12 +105,12 @@ function renderAuditResult(r, verbose) {
   const items = r.items ?? [];
   if (items.length > 0 && (!isGreen || verbose)) {
     lines.push("");
-    const shown = items.slice(0, MAX_ITEMS);
-    for (const item of shown) {
-      const name = item.shortName ?? item.resource ?? item.url ?? item.src ?? item.selector ?? item.filename ?? item.target ?? "";
-      const tag = item.type ?? item.tag ?? item.strategy ?? item.media ?? item.kind ?? "";
-      const timing = item.responseEndMs != null ? `${item.responseEndMs}ms` : item.durationMs != null ? `${item.durationMs}ms` : "";
-      const cols = [tag, name, item.detail, timing].filter(Boolean).join("  ");
+    // The cells of each row as the view gives them: the file of a URL, the values in their units
+    const { rows, constants } = describeResult(r);
+    // The values that are the same in every row, once above them, as in the extension
+    if (constants.length) lines.push(`     ${styleText("dim", constants.map((c) => `${c.label} ${c.text}`).join(" · "))}`);
+    for (const row of rows.slice(0, MAX_ITEMS)) {
+      const cols = row.cells.map((c) => c.text).filter(Boolean).join("  ");
       if (cols) lines.push(`     ${styleText("dim", `· ${cols}`)}`);
     }
     if (items.length > MAX_ITEMS) {
@@ -125,10 +128,7 @@ function renderAuditResult(r, verbose) {
 // A result with a count and details but no value and no issues, such as the long tasks: the count,
 // then the first numbers of its details.
 function renderSummaryResult(r) {
-  const numbers = Object.entries(r.details ?? {})
-    .filter(([, value]) => typeof value === "number")
-    .slice(0, 3)
-    .map(([key, value]) => `${key} ${value}`);
+  const numbers = summaryNumbers(r);
   const summary = [r.count !== undefined ? String(r.count) : null, ...numbers].filter(Boolean).join("  ·  ");
   return `  ${RATING_ICON[r.rating] ?? "·"} ${pad(r.id, 16)} ${styleText("dim", summary)}`;
 }
@@ -142,6 +142,11 @@ function renderResult(r, verbose) {
     return `  ${styleText("red", "✗")} ${pad(r.id, 16)} ${styleText("dim", r.error)}`;
   }
 
+  // A tracking snippet with nothing recorded, such as INP without interactions, measured nothing
+  if (r.status === "tracking") {
+    return `  ${styleText("dim", "·")} ${pad(r.id, 16)} ${styleText("dim", `not measured: ${r.message ?? "nothing recorded"}`)}`;
+  }
+
   if (r.script === "Fonts-Preloaded-Loaded-and-used-above-the-fold") {
     return renderFontsResult(r);
   }
@@ -150,7 +155,7 @@ function renderResult(r, verbose) {
     return renderAuditResult(r, verbose);
   }
 
-  if (r.value === undefined && (r.count !== undefined || r.details)) {
+  if (isSummaryResult(r)) {
     return renderSummaryResult(r);
   }
 
@@ -163,12 +168,10 @@ function renderResult(r, verbose) {
 
   if (r.metric === "LCP" && r.details?.subParts) {
     const sp = r.details.subParts;
-    const rows = [
-      ["TTFB", sp.ttfb],
-      ["Resource Load Delay", sp.resourceLoadDelay],
-      ["Resource Load Time", sp.resourceLoadTime],
-      ["Element Render Delay", sp.elementRenderDelay],
-    ];
+    const view = describeResult(r);
+    // The phases with the labels of the view, and the slowest one by its label, not its key
+    const phases = view.details.find((d) => d.key === "subParts" && d.format === "phases");
+    const rows = (phases?.parts ?? []).map((p) => [p.label, sp[p.key]]);
     out += "\n";
     out += rows
       .map(([name, info]) => {
@@ -180,8 +183,9 @@ function renderResult(r, verbose) {
           : `${row}\n         ${styleText("dim", `${info.waiting}ms waiting for the server, ${info.download}ms downloading`)}`;
       })
       .join("\n");
-    if (r.details.slowestPhase) {
-      out += `\n       ${styleText("blue", "→ Slowest:")} ${r.details.slowestPhase}`;
+    const slowest = view.details.find((d) => d.key === "slowestPhase");
+    if (slowest) {
+      out += `\n       ${styleText("blue", "→ Slowest:")} ${slowest.text}`;
     }
   }
 
@@ -218,6 +222,16 @@ function renderRuns(runs) {
 
 const VERDICT_STYLE = { regressed: "red", improved: "green", unchanged: "dim", "not measured": "dim", new: "cyan" };
 
+// Every budget the run was given, passed or not, so the report says which one decided the exit code
+function renderBudgets(budgets) {
+  const lines = ["", styleText("bold", "Budgets")];
+  for (const row of budgetRows(budgets, formatValue)) {
+    const mark = row.passed ? styleText("green", "✓") : styleText("red", "✗");
+    lines.push(`  ${mark} ${pad(row.metric, 6)}${pad(row.value, 10)}${pad(`budget ${row.budget}`, 18)}${styleText(row.passed ? "green" : "red", row.verdict)}`);
+  }
+  return lines;
+}
+
 // The comparison with --baseline, after the report: its warnings first, since they say how far to
 // trust the table, then a row per metric and the errors that appeared or went away
 function renderBaseline(comparison) {
@@ -235,7 +249,7 @@ function renderBaseline(comparison) {
   return lines;
 }
 
-export function reportHuman({ url, navMs, results, pageErrors, verbose, crux, throttling, runs, baseline, title = `WebPerf Snippets — ${url}` }) {
+export function reportHuman({ url, navMs, results, pageErrors, verbose, crux, throttling, runs, baseline, budgets, title = `WebPerf Snippets — ${url}` }) {
   const lines = [];
   lines.push(styleText(["bold"], title));
   lines.push(styleText("dim", `Navigated in ${navMs}ms`));
@@ -252,6 +266,7 @@ export function reportHuman({ url, navMs, results, pageErrors, verbose, crux, th
     lines.push(styleText("yellow", "Page errors during run:"));
     for (const err of pageErrors) lines.push(`  ${styleText("dim", err)}`);
   }
+  if (budgets?.length) lines.push(...renderBudgets(budgets));
   if (baseline) lines.push(...renderBaseline(baseline));
   return lines.join("\n");
 }
@@ -289,6 +304,13 @@ export function reportMatrixHuman(report) {
     for (const e of errors) lines.push(`  ${styleText("red", "✗")} ${e}`);
   }
 
+  const budgetFailures = matrixBudgetFailures(report.combinations, formatValue);
+  if (budgetFailures) {
+    lines.push("", styleText("bold", "Budgets"));
+    for (const f of budgetFailures) lines.push(`  ${styleText("red", "✗")} ${f}`);
+    if (!budgetFailures.length) lines.push(`  ${styleText("green", "✓ Every budget passed")}`);
+  }
+
   if (comparison) {
     lines.push("", styleText("bold", `Compared with ${comparison.file}`));
     for (const warning of comparison.warnings) lines.push(`  ${styleText("yellow", `Warning: ${warning}`)}`);

package/src/reporters/markdown.js

@@ -1,8 +1,11 @@
 import { fieldDataView } from "../crux.js";
+import { describeResult } from "../view.js";
+import { isSummaryResult, summaryNumbers } from "./summary-view.js";
 import { describeThrottling } from "../throttling.js";
 import { describeRuns } from "../runs.js";
 import { matrixView } from "./matrix-view.js";
 import { baselineView } from "./baseline-view.js";
+import { budgetRows, matrixBudgetFailures } from "./budgets-view.js";
 
 const RATING_ICON = {
   good: "✅",
@@ -39,10 +42,22 @@ function renderSkippedRow(r) {
   return `| ${r.id} | ⏭ skipped | ${r.reason} |`;
 }
 
+// A tracking snippet with nothing recorded, such as INP without interactions, measured nothing
+function renderNotMeasuredRow(r) {
+  return `| ${r.id} | · not measured | ${r.message ?? "nothing recorded"} |`;
+}
+
+// A result with a count and no value: its count, and its first numbers as the human report gives them
+function renderSummaryRow(r) {
+  return `| ${r.id} | · ${r.count ?? ""} | ${summaryNumbers(r).join(" · ")} |`;
+}
+
 function renderRow(r) {
   if (r.status === "skipped") return renderSkippedRow(r);
   if (r.status === "error") return renderErrorRow(r);
+  if (r.status === "tracking") return renderNotMeasuredRow(r);
   if (Array.isArray(r.issues)) return renderAuditRow(r);
+  if (isSummaryResult(r)) return renderSummaryRow(r);
   return renderMetricRow(r);
 }
 
@@ -53,11 +68,36 @@ function sectionHeader(results) {
   return ["| Metric | Value | Status |", "|--------|-------|--------|"];
 }
 
+// Text from the page in a list item: the characters that markdown reads as emphasis or code, escaped
+const md = (text) => String(text).replace(/[\\`*_[\]]/g, "\\$&");
+
+// A field of the view as a list item, with the labels and formats of the extension: a nested table is
+// a line per row, and the fields of an object are items under it
+function detailLines(field, indent = "") {
+  if (field.format === "table") {
+    return [`${indent}- **${md(field.label)}**:`, ...field.rows.map((row) => `${indent}  - ${row.cells.map((c) => md(c.text)).filter(Boolean).join(" · ")}`)];
+  }
+  if (field.format === "fields") {
+    return [`${indent}- **${md(field.label)}**:`, ...field.fields.flatMap((f) => detailLines(f, `${indent}  `))];
+  }
+  return [`${indent}- **${md(field.label)}**: ${md(field.text)}`];
+}
+
+// The details of each result, folded under its id, so the comment of a pull request stays short
+function renderDetails(results) {
+  return results.flatMap((r) => {
+    const { details } = describeResult(r);
+    if (details.length === 0) return [];
+    return ["", `<details><summary>${r.id}</summary>`, "", ...details.flatMap((f) => detailLines(f)), "", "</details>"];
+  });
+}
+
 function renderSection(title, results) {
   return [
     `### ${title}`,
     ...sectionHeader(results),
     ...results.map(renderRow),
+    ...renderDetails(results),
   ].join("\n");
 }
 
@@ -104,7 +144,13 @@ function renderBaseline(comparison) {
 }
 
 // With a null title, the report has no heading, as inside the details block of a matrix
-export function reportMarkdown({ url, navMs, results, pageErrors, crux, throttling, runs, baseline, title = `WebPerf Results — ${url}` }) {
+// Every budget the run was given, passed or not: the comment of a pull request says which one failed
+function renderBudgets(budgets) {
+  const rows = budgetRows(budgets, formatValue).map((row) => `| ${row.metric} | ${row.value} | ${row.budget} | ${row.passed ? "✅" : "❌"} ${row.verdict} |`);
+  return ["", "### Budgets", "| Metric | Value | Budget | Verdict |", "|--------|-------|--------|---------|", ...rows];
+}
+
+export function reportMarkdown({ url, navMs, results, pageErrors, crux, throttling, runs, baseline, budgets, title = `WebPerf Results — ${url}` }) {
   const lines = [];
   if (title) lines.push(`## ${title}`);
   lines.push(`> Navigated in ${navMs}ms`);
@@ -140,6 +186,7 @@ export function reportMarkdown({ url, navMs, results, pageErrors, crux, throttli
     for (const err of pageErrors) lines.push(`- ${err}`);
   }
 
+  if (budgets?.length) lines.push(...renderBudgets(budgets));
   if (baseline) lines.push(...renderBaseline(baseline));
 
   return lines.join("\n");
@@ -172,6 +219,11 @@ export function reportMatrixMarkdown(report) {
     lines.push("", "### Errors", ...errors.map((e) => `- ${e}`));
   }
 
+  const budgetFailures = matrixBudgetFailures(report.combinations, formatValue);
+  if (budgetFailures) {
+    lines.push("", "### Budgets", ...(budgetFailures.length ? budgetFailures.map((f) => `- ❌ ${f}`) : ["✅ Every budget passed"]));
+  }
+
   if (comparison) {
     lines.push("", `### Compared with \`${comparison.file}\``);
     if (comparison.warnings.length) lines.push(...comparison.warnings.flatMap((w, i) => [...(i ? [">"] : []), `> ⚠️ ${w}`]), "");

package/src/reporters/summary-view.js

@@ -0,0 +1,12 @@
+import { describeResult } from "../view.js";
+
+// A result with a count and details but no value and no issues, such as the long tasks: whether it is
+// one, and its first numbers with the labels and formats of the view, which both reports show
+export const isSummaryResult = (r) => r.value === undefined && !Array.isArray(r.issues) && (r.count !== undefined || r.details !== undefined);
+
+export function summaryNumbers(r) {
+  return describeResult(r)
+    .details.filter((d) => typeof d.value === "number")
+    .slice(0, 3)
+    .map((d) => `${d.label} ${d.text}`);
+}

package/src/runner.js

@@ -16,8 +16,8 @@ export const VIEWPORT_PRESETS = {
 const DEFAULT_NAV_TIMEOUT = 30000;
 
 // On a loaded machine the browser can deliver the timing of a click later than the frames `settle`
-// waits for. After a click or a key press, a tracking snippet that has no data yet is read again,
-// every POLL_MS, until it has some or LATE_ENTRIES_MS have passed.
+// waits for. After a click or a key press, a tracking snippet that has no data yet, and so is still
+// tracking, is read again every POLL_MS until it has some or LATE_ENTRIES_MS have passed.
 const LATE_ENTRIES_MS = 2000;
 const POLL_MS = 100;
 
@@ -79,7 +79,7 @@ export async function collectTrackingData(page, result, hasInput) {
     const read = () => page.evaluate(`(async () => await ${result.getDataFn}())()`);
     let data = await read();
     const deadline = Date.now() + LATE_ENTRIES_MS;
-    while (hasInput && data?.status === "error" && Date.now() < deadline) {
+    while (hasInput && data?.status === "tracking" && Date.now() < deadline) {
       await page.waitForTimeout(POLL_MS);
       data = await read();
     }

package/src/view.js

@@ -0,0 +1,11 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { SNIPPET_DIRS } from "./load-snippet.js";
+
+// The view of a result (snippets/_view/): the labels, formats and order the extension shows, so the
+// reports say the same. It comes with the snippets, in the package or at the root of the repository.
+const dir = SNIPPET_DIRS.find((d) => existsSync(join(d, "_view", "index.js")));
+if (!dir) throw new Error("The view of the results is missing: snippets/_view/index.js");
+
+export const { describeResult } = await import(pathToFileURL(join(dir, "_view", "index.js")).href);

package/src/workflows/interaction.js

@@ -24,6 +24,7 @@ export const interactionWorkflow = {
     { id: "scroll", path: "Interaction/Scroll-Performance" },
     { id: "layout-shifts", path: "Interaction/Layout-Shift-Loading-and-Interaction" },
     { id: "forced-layout", path: "Interaction/Forced-Synchronous-Layout" },
+    { id: "INP", path: "CoreWebVitals/INP", needsInput: true },
     { id: "interactions", path: "Interaction/Interactions", needsInput: true },
     { id: "input-latency", path: "Interaction/Input-Latency-Breakdown", needsInput: true },
   ],