webperf-snippets 1.5.0 → 1.6.0

package/snippets/_view/index.js

@@ -0,0 +1,304 @@
+// The view of a snippet result, shared by the panel of the extension, the reports of the CLI and the
+// visualizer of the site: the title of its table, its details and its columns with labels, formats and
+// order. Each one paints the view its own way, so this module writes no HTML. A field with no entry in
+// fields.js or locales/ still reads well: its format comes from the suffix of its key, and its label
+// from the key in words.
+
+import FIELDS from './fields.js'
+import en from './locales/en.js'
+import { formatOfKey, formatValue, SUFFIXES } from './format.js'
+
+export { formatValue }
+
+const LOCALES = { en }
+
+// Kept in capitals when a key is turned into words
+const ACRONYMS = new Set(
+  'api bfcache cdn cls cors cpu css csr dns dom ect fcp fid fps html http https id inp js json lcp loaf loafs rtt ssr svg sw tbt tcp tls ttfb ui url urls'.split(' ')
+)
+const CAPITALS = { bfcache: 'bfcache', loaf: 'LoAF', loafs: 'LoAFs', urls: 'URLs' }
+
+// A key in words, without the unit its suffix names, since the value shows it: totalBlockingUntilMs is
+// "Total blocking until", isLCP "Is LCP". A count is not a unit, so imageCount is "Image count"
+export function words(key) {
+  const suffix = SUFFIXES.find(([s, format]) => format !== 'count' && key.endsWith(s) && key !== s)?.[0]
+  const stem = suffix ? key.slice(0, -suffix.length) : key
+  const parts = stem
+    // Words in mixed case that the split by capitals would break
+    .replace(/LoAF(s?)/g, ' loaf$1 ')
+    .replace(/[_-]+/g, ' ')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .trim()
+    .split(/\s+/)
+    .map((w) => {
+      const lower = w.toLowerCase()
+      if (ACRONYMS.has(lower)) return CAPITALS[lower] ?? lower.toUpperCase()
+      return w.length > 1 && w === w.toUpperCase() ? w : lower
+    })
+  const text = parts.join(' ')
+  return text.charAt(0).toUpperCase() + text.slice(1)
+}
+
+// A field with nothing to show: no value, an empty string, or an empty list or object
+const isEmpty = (value) =>
+  value === undefined || value === null || value === '' || (typeof value === 'object' && Object.keys(value).length === 0)
+
+// The locale, its language, and English, which has every word
+const chainOf = (locale) => [...new Set([locale, locale.split('-')[0], 'en'])]
+
+function dictionaries(script, { locale = 'en', fields = {}, locales = {} }) {
+  const allFields = { ...FIELDS, ...fields }
+  const allLocales = { ...LOCALES, ...locales }
+  const chain = chainOf(locale).map((l) => allLocales[l]).filter(Boolean)
+  // The entries of the snippet come before the general ones in any language: a key can mean something
+  // else in a snippet, and its own label in English says it better than a general one translated
+  const scopes = [...chain.map((d) => d[script]), ...chain.map((d) => d['*'])].filter(Boolean)
+  // The words of the view itself (Yes, No, none, rows), in the first language that has them
+  const ui = (name) => chain.map((l) => l['*']?.words?.[name]).find((w) => w !== undefined)
+  return {
+    title: scopes.find((s) => s.title)?.title,
+    // Label and phrase come from the same entry, so a sentence never mixes two languages
+    words: (key) => scopes.find((s) => s.fields?.[key])?.fields[key] ?? {},
+    shape: (key) => ({ ...allFields['*']?.[key], ...allFields[script]?.[key] }),
+    ui,
+    locale,
+  }
+}
+
+function describeField(key, d) {
+  const shape = d.shape(key)
+  const { label, phrase } = d.words(key)
+  return { key, label: label ?? words(key), format: shape.format ?? formatOfKey(key), order: shape.order, hidden: shape.hidden, phrase }
+}
+
+// A lower order first; a field without one keeps its place after them
+const byOrder = (a, b) => (a.order ?? Infinity) - (b.order ?? Infinity)
+
+const splitPhrase = (template) => {
+  const [before, after = ''] = template.split('{value}')
+  return { before, after }
+}
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+// The format a value has by its shape, when neither its entry nor the suffix of its key gives one
+function shapeOf(value) {
+  if (typeof value === 'boolean') return 'boolean'
+  if (typeof value === 'string' && /^https?:\/\//.test(value)) return 'url'
+  if (Array.isArray(value)) return value.every(isObject) ? 'table' : 'list'
+  if (!isObject(value)) return undefined
+  const values = Object.values(value)
+  if (values.every((v) => typeof v === 'number')) return 'distribution'
+  if (values.every((v) => isObject(v) && typeof v.value === 'number')) return 'phases'
+  if (values.every(isObject)) return 'table'
+  return 'fields'
+}
+
+// The file of a URL, or its host when the path has none
+function shortUrl(url) {
+  try {
+    const { hostname, pathname } = new URL(url)
+    return pathname.split('/').filter(Boolean).pop() ?? hostname
+  } catch {
+    return url
+  }
+}
+
+// A part of a distribution reads inside a line, so in lower case, unless it starts with an acronym
+const inLine = (label) => (/^[A-Z][a-z]/.test(label) ? label.charAt(0).toLowerCase() + label.slice(1) : label)
+
+const plural = (forms, n, locale) => (forms?.[new Intl.PluralRules(locale).select(n)] ?? forms?.other ?? '{n}').replace('{n}', n)
+
+// The phases of a metric: a part each, with its share of the whole and the slowest marked, and the
+// thresholds of the metric as the scale to draw them on
+function phases(value, d, result) {
+  const entries = Object.entries(value).map(([key, v]) => [key, typeof v === 'number' ? { value: v } : v])
+  const sum = entries.reduce((total, [, v]) => total + v.value, 0)
+  // The snippet knows which one is the slowest, also on a tie; otherwise, the longest
+  const named = result?.details?.slowestPhase
+  const slowest = entries.some(([key]) => key === named)
+    ? named
+    : entries.reduce((max, [key, v]) => (v.value > (max?.value ?? 0) ? { key, value: v.value } : max), null)?.key
+  const parts = entries.map(([key, v]) => ({
+    key,
+    label: describeField(key, d).label,
+    value: v.value,
+    text: formatValue(v.value, 'ms', d.locale),
+    percent: v.percent ?? (sum > 0 ? Math.round((v.value / sum) * 100) : 0),
+    overTarget: v.overTarget === true,
+    slowest: key === slowest,
+  }))
+  const t = result?.thresholds
+  const scale = { total: typeof result?.value === 'number' ? result.value : sum, ...(t ? { good: t.good, poor: t.needsImprovement } : {}) }
+  const text = parts
+    .filter((p) => p.value > 0)
+    .map((p) => `${p.label} ${p.text} (${formatValue(p.percent, 'percent', d.locale)})`)
+    .join(' · ')
+  return { parts, scale, text }
+}
+
+// A width and a height of the same thing, as one value of its size: naturalWidth and naturalHeight are
+// naturalSize, 1,200×900
+function joinSizes(rows, locale) {
+  const keys = new Set(rows.flatMap((row) => Object.keys(row)))
+  const heightOf = (width) => width.replace(/^width/, 'height').replace(/Width(Px)?$/, 'Height$1')
+  const pairs = [...keys]
+    .filter((key) => /^(width|.+Width)(Px)?$/.test(key) && keys.has(heightOf(key)))
+    .map((width) => [width, heightOf(width), width.replace(/^width/, 'size').replace(/Width(Px)?$/, 'Size$1')])
+    .filter(([, , size]) => !keys.has(size))
+  if (pairs.length === 0) return rows
+  const number = (n) => formatValue(n, 'count', locale)
+  return rows.map((row) =>
+    Object.fromEntries(
+      Object.entries(row).flatMap(([key, value]) => {
+        const pair = pairs.find(([width, height]) => key === width || key === height)
+        if (!pair) return [[key, value]]
+        if (key === pair[1]) return []
+        const [width, height, size] = pair
+        const both = typeof row[width] === 'number' && typeof row[height] === 'number'
+        const unit = size.endsWith('Px') ? ' px' : ''
+        return [[size, both ? `${number(row[width])}×${number(row[height])}${unit}` : undefined]]
+      })
+    )
+  )
+}
+
+const sameValue = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null)
+
+// A list of objects as a table: its columns, each with its label, and a row of cells per object. A
+// column with the same value in every row is a constant, a line above the table; a column with the
+// file of a URL column gives that one its place and label; and two or more columns of booleans are
+// one column of marks
+function table(items, d) {
+  const rows = joinSizes(
+    items.map((item) => (isObject(item) ? item : { value: item })),
+    d.locale
+  )
+  // A column empty in every row says nothing
+  let columns = [...new Set(rows.flatMap((row) => Object.keys(row)))]
+    .filter((key) => rows.some((row) => !isEmpty(row[key])))
+    .map((key) => describeField(key, d))
+    .filter((c) => !c.hidden)
+    .sort(byOrder)
+  const cells = rows.map((row) => Object.fromEntries(columns.map(({ key }) => [key, describeValue(key, row[key], d, { inTable: true })])))
+
+  const same = (key) => rows.length > 1 && rows.every((row) => sameValue(row[key], rows[0][key]))
+  // Rows that are all the same keep their columns: a table without any says nothing of how many there are
+  const allSame = columns.every(({ key }) => same(key))
+  const constant = (key) => !allSame && same(key)
+  const constants = columns
+    .filter(({ key }) => constant(key))
+    .map(({ key }) => {
+      const { label, text } = describeValue(key, rows[0][key], d)
+      return { key, label, text }
+    })
+  columns = columns.filter(({ key }) => !constant(key))
+
+  for (const url of columns.filter(({ key }) => cells.every((c) => c[key].format === 'url' || c[key].text === ''))) {
+    const short = columns.find(
+      (c) => c !== url && cells.every((row) => (row[url.key].text === '' ? row[c.key].text === '' : row[c.key].value === row[url.key].text))
+    )
+    if (!short) continue
+    columns = columns.filter((c) => c !== url).map((c) => (c === short ? { ...url, label: short.label } : c))
+  }
+
+  const booleans = columns.filter(({ key }) => rows.every((row) => row[key] === undefined || typeof row[key] === 'boolean'))
+  const flagged = booleans.length > 1
+  if (flagged) columns = [...columns.filter((c) => !booleans.includes(c)), { key: 'flags', label: d.ui('flags'), format: 'flags' }]
+  const flagLabel = (c) => inLine(c.label.replace(/^(Is|Has) /, ''))
+
+  return {
+    columns: columns.map(({ key, label, format }) => ({ key, label, format })),
+    constants,
+    rows: cells.map((row, i) => ({
+      cells: columns.map(({ key }) => {
+        if (key !== 'flags' || !flagged) return row[key]
+        const flags = booleans.filter((c) => rows[i][c.key] === true).map(flagLabel)
+        return { key, format: 'flags', value: booleans.filter((c) => rows[i][c.key] === true).map((c) => c.key), flags, text: flags.join(' · ') }
+      }),
+    })),
+  }
+}
+
+// A value with its label and its text, and the parts, fields or rows of a value made of others
+function describeValue(key, value, d, { inTable = false, result } = {}) {
+  const field = describeField(key, d)
+  const format = field.format ?? shapeOf(value)
+  const base = { key, label: field.label, format, value }
+  if (value === undefined || value === null) return { ...base, text: '' }
+  switch (format) {
+    case 'distribution': {
+      const parts = Object.entries(value)
+        .filter(([, n]) => n !== 0)
+        .map(([k, n]) => ({ key: k, label: inLine(describeField(k, d).label), value: n, text: formatValue(n, 'count', d.locale) }))
+      return { ...base, parts, text: parts.length ? parts.map((p) => `${p.label} ${p.text}`).join(' · ') : d.ui('none') }
+    }
+    case 'phases':
+      return { ...base, ...phases(value, d, result) }
+    case 'key':
+      return { ...base, text: describeField(String(value), d).label }
+    case 'table': {
+      // An object of objects is a table too, with the key of each one in its row
+      const items = Array.isArray(value) ? value : Object.entries(value).map(([name, v]) => ({ name, ...v }))
+      return { ...base, ...table(items, d), text: plural(d.ui('rows'), items.length, d.locale) }
+    }
+    case 'fields': {
+      const fields = Object.entries(value)
+        .filter(([k, v]) => !isEmpty(v) && !describeField(k, d).hidden)
+        .map(([k, v]) => describeValue(k, v, d))
+      return { ...base, fields, text: fields.map((f) => `${f.label} ${f.text}`).join(' · ') }
+    }
+    case 'list':
+      return { ...base, text: value.map((v) => formatValue(v, undefined, d.locale)).join(', ') }
+    case 'boolean':
+      return { ...base, text: inTable ? (value ? '✓' : '') : d.ui(value ? 'yes' : 'no') }
+    case 'url':
+      return { ...base, text: shortUrl(value), href: value }
+    default:
+      return { ...base, text: formatValue(value, format, d.locale) }
+  }
+}
+
+export function describeResult(result, options = {}) {
+  const d = dictionaries(result?.script, options)
+
+  const details = Object.entries(isObject(result?.details) ? result.details : {})
+    .filter(([, value]) => !isEmpty(value))
+    .map(([key, value]) => ({ field: describeField(key, d), value, key }))
+    .filter(({ field }) => !field.hidden)
+    .sort((a, b) => byOrder(a.field, b.field))
+    .map(({ field, key, value }) => ({
+      ...describeValue(key, value, d, { result }),
+      ...(field.phrase ? { phrase: splitPhrase(field.phrase) } : {}),
+    }))
+
+  const items = Array.isArray(result?.items) ? result.items : []
+  const { columns, constants, rows } = table(items, d)
+
+  // An issue with a target belongs to the row that has that URL, selector or name in one of its fields
+  const rowOf = (target) => {
+    const index = target === undefined ? -1 : items.findIndex((item) => isObject(item) && Object.values(item).includes(target))
+    return index < 0 ? undefined : index
+  }
+  const issues = (Array.isArray(result?.issues) ? result.issues : []).map(({ severity, code, message, target }) => ({
+    severity,
+    code,
+    message,
+    target,
+    row: rowOf(target),
+  }))
+
+  return {
+    title: d.title,
+    details,
+    columns,
+    constants,
+    rows: rows.map((row, i) => ({ ...row, issues: issues.filter((issue) => issue.row === i) })),
+    issues,
+    recommendations: Array.isArray(result?.recommendations) ? result.recommendations.filter((r) => typeof r === 'string') : [],
+    // The message of a snippet that records is written for the console (call getINP() again); the view
+    // says what to do in its own words
+    message: result?.status === 'tracking' && result.getDataFn ? d.ui('tracking') : result?.message,
+  }
+}

package/snippets/_view/locales/en.js

@@ -0,0 +1,39 @@
+// The English words of the view: the title of the table of each snippet, and the label of a field
+// when its key in words does not say it well. `phrase` reads a field as a sentence around its value,
+// at {value}. The entries of a snippet win over the general ones under "*". Another language is a file
+// like this one, which falls back to this one for what it does not translate.
+
+export default {
+  '*': {
+    title: 'Items',
+    fields: {
+      subParts: { label: 'Subparts' },
+      sslTls: { label: 'SSL/TLS' },
+    },
+    // The words of the view itself
+    words: {
+      yes: 'Yes',
+      no: 'No',
+      none: 'none',
+      flags: 'Flags',
+      tracking: 'Nothing recorded yet. Use the page, then read the result.',
+      rows: { one: '{n} row', other: '{n} rows' },
+    },
+  },
+  'TTFB-Sub-Parts': {
+    fields: {
+      redirectWait: { label: 'Redirect' },
+      serviceWorkerCache: { label: 'Service worker' },
+      dnsLookup: { label: 'DNS' },
+      tcpConnection: { label: 'TCP' },
+      serverResponse: { label: 'Request' },
+    },
+  },
+  'Find-render-blocking-resources': {
+    title: 'Render-blocking resources',
+    fields: {
+      totalBlockingUntilMs: { label: 'Blocked until', phrase: 'Rendering blocked until {value}' },
+      shortName: { label: 'File' },
+    },
+  },
+}

package/snippets/_view/package.json

@@ -0,0 +1 @@
+{ "type": "module", "private": true }

package/src/bin.js

@@ -18,6 +18,7 @@ import { parseOwnDomains } from "./own-domains.js";
 import { MEDIAN_METRICS, summarizeRuns } from "./runs.js";
 import { loadMatrix } from "./matrix.js";
 import { blockingErrors } from "./blocking.js";
+import { MEASURED_BY, checkBudgets, parseBudgets, unmeasuredMetrics, violationsOf } from "./budgets.js";
 import { measurementConditions } from "./conditions.js";
 import { loadBaseline, parseThreshold, thresholdsWith, compareRun, compareMatrix } from "./baseline.js";
 import { describeRegressions, describeMatrixRegressions, matrixComparisonView } from "./reporters/baseline-view.js";
@@ -49,8 +50,11 @@ Options:
   --wait <ms>           Post-load wait before evaluating (default: 3000)
   --cpu <factor>        Slow the CPU down by this factor, such as 4 (no throttling by default)
   --network <preset>    Throttle the network as DevTools does: fast-4g, slow-4g, 3g
-  --budget-lcp <ms>     Exit 1 if LCP exceeds this value
-  --budget-cls <score>  Exit 1 if CLS exceeds this value
+  --budget-lcp <ms>     Exit 1 if LCP exceeds this value, or was not measured
+  --budget-fcp <ms>     Exit 1 if FCP exceeds this value, or was not measured
+  --budget-ttfb <ms>    Exit 1 if TTFB exceeds this value, or was not measured
+  --budget-cls <score>  Exit 1 if CLS exceeds this value, or was not measured
+  --budget-inp <ms>     Exit 1 if INP exceeds this value, or was not measured (interaction workflow)
   --interact-script <path>  JSON file with interactions to run after the load; the
                             Interaction snippets are installed first and read last
                             Actions: scroll, click, hover, type, wait
@@ -124,30 +128,13 @@ function parseRunCount(raw) {
   return /^[1-9]$/.test(raw.trim()) ? Number(raw) : null;
 }
 
-function checkBudgets({ results, runs }, values) {
-  const violations = [];
-  const lcpBudget = values["budget-lcp"] ? Number(values["budget-lcp"]) : null;
-  const clsBudget = values["budget-cls"] ? Number(values["budget-cls"]) : null;
-
-  // With several runs the budgets compare the median of each metric, not one sample
-  if (runs) {
-    const lcp = runs.summary.LCP?.median;
-    const cls = runs.summary.CLS?.median;
-    if (lcp != null && lcpBudget != null && lcp > lcpBudget) violations.push(`LCP ${lcp}ms exceeds budget ${lcpBudget}ms`);
-    if (cls != null && clsBudget != null && cls > clsBudget) violations.push(`CLS ${cls} exceeds budget ${clsBudget}`);
-    return violations;
-  }
-
-  for (const r of results) {
-    if (r.status !== "ok") continue;
-    if (r.metric === "LCP" && lcpBudget != null && r.value > lcpBudget) {
-      violations.push(`LCP ${r.value}ms exceeds budget ${lcpBudget}ms`);
-    }
-    if (r.metric === "CLS" && clsBudget != null && r.value > clsBudget) {
-      violations.push(`CLS ${r.value} exceeds budget ${clsBudget}`);
-    }
-  }
-  return violations;
+// What to run instead, when a budget names a metric the run does not measure
+function budgetUsage(metric, run) {
+  const workflows = Object.values(WORKFLOWS)
+    .filter((w) => w.steps.some((step) => MEASURED_BY[metric].includes(step.path)))
+    .map((w) => w.id);
+  const instead = [...workflows.map((id) => `--workflow ${id}`), `--snippet ${MEASURED_BY[metric][0].split("/").pop()}`].join(" or ");
+  return `--budget-${metric.toLowerCase()} needs a run that measures ${metric}, and ${run} does not. Use ${instead}`;
 }
 
 async function main() {
@@ -168,7 +155,10 @@ async function main() {
         markdown: { type: "boolean" },
         wait: { type: "string" },
         "budget-lcp": { type: "string" },
+        "budget-fcp": { type: "string" },
+        "budget-ttfb": { type: "string" },
         "budget-cls": { type: "string" },
+        "budget-inp": { type: "string" },
         viewport: { type: "string" },
         cpu: { type: "string" },
         network: { type: "string" },
@@ -275,10 +265,20 @@ async function main() {
     if (values["fail-on-regression"]) fail("--fail-on-regression needs --baseline");
   }
 
+  let budgets;
+  try {
+    budgets = parseBudgets(values);
+  } catch (err) {
+    fail(err.message);
+  }
+
   // What each page load runs, a snippet or a workflow, under the conditions of the load
   const items = values.snippet ? buildSnippetItem(values) : null;
   const workflow = values.snippet ? null : WORKFLOWS[values.workflow ?? "core-web-vitals"];
   if (!values.snippet && !workflow) fail(`Unknown workflow: ${values.workflow}`);
+  // A budget of a metric that no snippet of the run measures could never pass: a usage error
+  const [unmeasured] = unmeasuredMetrics(budgets, items ? [items[0].path] : workflow.steps.map((step) => step.path));
+  if (unmeasured) fail(budgetUsage(unmeasured, items ? `--snippet ${values.snippet}` : `the ${workflow.id} workflow`));
   const measureWith = (conditions) => {
     const options = { waitMs, headless: !values.headed, interactScript, ...conditions };
     return items ? runSnippets({ ...options, items }) : runMeasurement({ ...options, workflow, rules: RULES });
@@ -294,7 +294,7 @@ async function main() {
     } catch (err) {
       fail(err.message);
     }
-    await runMatrix(matrixPath, matrix, measureWith, { values, waitMs, reportUrl, conditionsFor, baseline, thresholds });
+    await runMatrix(matrixPath, matrix, measureWith, { values, waitMs, reportUrl, conditionsFor, baseline, thresholds, budgets });
     return;
   }
 
@@ -318,6 +318,9 @@ async function main() {
     for (const warning of payload.baseline.warnings) process.stderr.write(`Warning: ${warning}\n`);
   }
 
+  // The verdict of each budget goes in the report, so a pull request comment says which one failed
+  if (Object.keys(budgets).length > 0) payload.budgets = checkBudgets(payload, budgets);
+
   let output;
   if (values.markdown) {
     output = reportMarkdown(payload);
@@ -339,6 +342,7 @@ async function main() {
         timestamp: new Date().toISOString(),
         navMs: payload.navMs,
         results: payload.results,
+        ...(payload.budgets ? { budgets: payload.budgets } : {}),
         meta: { viewport: viewportName, waitMs, ...(payload.throttling ? { throttling: payload.throttling } : {}), ...(payload.runs ? { runs: payload.runs } : {}), cli_version: cliVersion },
       },
     });
@@ -349,12 +353,10 @@ async function main() {
     }
   }
 
-  // Exit codes.
-  const violations = checkBudgets(payload, values);
+  // Exit codes. stderr names the budgets that failed, also with --json, whose report is on stdout
+  const violations = violationsOf(payload.budgets ?? []);
   if (violations.length > 0) {
-    if (!values.json) {
-      for (const v of violations) process.stderr.write(`Budget violation: ${v}\n`);
-    }
+    for (const v of violations) process.stderr.write(`Budget violation: ${v}\n`);
     process.exit(1);
   }
   // Without --fail-on-regression the comparison only informs, and the exit code is the one of today
@@ -385,7 +387,7 @@ async function measureRuns(measure, count, medianBy, progress) {
 
 // Every combination of the matrix, in order, each one `matrix.runs` times. Each combination reports
 // its median run, and the exit code follows the same rules as one page, for every combination.
-async function runMatrix(matrixPath, matrix, measureWith, { values, waitMs, reportUrl, conditionsFor, baseline, thresholds }) {
+async function runMatrix(matrixPath, matrix, measureWith, { values, waitMs, reportUrl, conditionsFor, baseline, thresholds, budgets }) {
   for (const warning of matrix.warnings) process.stderr.write(`Warning: ${warning}\n`);
   const viewportOf = new Map(matrix.combinations.map((c) => [c.id, c.viewport]));
 
@@ -426,6 +428,8 @@ async function runMatrix(matrixPath, matrix, measureWith, { values, waitMs, repo
     for (const warning of matrixComparisonView(root, combinations).warnings) process.stderr.write(`Warning: ${warning}\n`);
   }
 
+  if (Object.keys(budgets).length > 0) for (const c of combinations.filter((c) => !c.error)) c.budgets = checkBudgets(c, budgets);
+
   const withBaseline = comparison ? { baseline: comparison } : {};
   const report = { matrix: matrixPath, runs: matrix.runs, combinations, verbose: values.verbose, ...withBaseline };
   const output = values.markdown ? reportMatrixMarkdown(report) : values.json ? reportJson({ matrix: matrixPath, runs: matrix.runs, ...withBaseline, combinations }) : reportMatrixHuman(report);
@@ -445,6 +449,7 @@ async function runMatrix(matrixPath, matrix, measureWith, { values, waitMs, repo
           timestamp: new Date().toISOString(),
           navMs: c.navMs,
           results: c.results,
+          ...(c.budgets ? { budgets: c.budgets } : {}),
           meta: {
             viewport: viewportOf.get(c.id),
             device: c.device,
@@ -464,10 +469,8 @@ async function runMatrix(matrixPath, matrix, measureWith, { values, waitMs, repo
     }
   }
 
-  const violations = combinations.filter((c) => !c.error).flatMap((c) => checkBudgets(c, values).map((v) => `${v} (${c.id})`));
-  if (!values.json) {
-    for (const v of violations) process.stderr.write(`Budget violation: ${v}\n`);
-  }
+  const violations = combinations.flatMap((c) => violationsOf(c.budgets ?? []).map((v) => `${v} (${c.id})`));
+  for (const v of violations) process.stderr.write(`Budget violation: ${v}\n`);
   const failed = combinations.some((c) => c.error || blockingErrors(c.results).length > 0);
   // Without --fail-on-regression the comparison only informs
   const regressions = values["fail-on-regression"] ? describeMatrixRegressions(combinations) : [];

package/src/budgets.js

@@ -0,0 +1,73 @@
+// The performance budgets of the command line (--budget-lcp, --budget-fcp, --budget-ttfb,
+// --budget-cls and --budget-inp): reading them, telling whether the run can measure their metric,
+// and the verdict of each one against what a page measured.
+
+// The metrics that take a budget, with their unit
+export const BUDGET_METRICS = { LCP: "ms", FCP: "ms", TTFB: "ms", CLS: "score", INP: "ms" };
+
+// The snippets whose result carries each metric, by path
+export const MEASURED_BY = {
+  LCP: ["CoreWebVitals/LCP", "CoreWebVitals/LCP-Subparts"],
+  FCP: ["Loading/FCP"],
+  TTFB: ["Loading/TTFB", "Loading/TTFB-Sub-Parts"],
+  CLS: ["CoreWebVitals/CLS"],
+  INP: ["CoreWebVitals/INP"],
+};
+
+const optionOf = (metric) => `--budget-${metric.toLowerCase()}`;
+
+// The budgets given on the command line, by metric. A value that is not a number of 0 or more throws,
+// so the command can exit with 2 before the browser opens.
+export function parseBudgets(values) {
+  const budgets = {};
+  for (const metric of Object.keys(BUDGET_METRICS)) {
+    const raw = values[optionOf(metric).slice(2)];
+    if (raw === undefined) continue;
+    if (!/^\d+(?:\.\d+)?$/.test(raw.trim())) {
+      throw new Error(`Invalid ${optionOf(metric)} "${raw}". Use a number of 0 or more, such as ${metric === "CLS" ? "0.1" : "2500"}`);
+    }
+    budgets[metric] = Number(raw);
+  }
+  return budgets;
+}
+
+// The metrics with a budget that no snippet of the run measures, such as LCP in the audit workflow
+export const unmeasuredMetrics = (budgets, paths) =>
+  Object.keys(budgets).filter((metric) => !MEASURED_BY[metric].some((path) => paths.includes(path)));
+
+const nameOf = (path) => path.split("/").pop().toLowerCase();
+
+// The result of the snippet that measures a metric, a step of the run before a follow-up
+function resultFor(results, metric) {
+  const names = MEASURED_BY[metric].map(nameOf);
+  const ofMetric = results.filter((r) => r.metric === metric || names.includes(String(r.script ?? r.id).toLowerCase()));
+  return ofMetric.find((r) => !r.reason || r.status === "skipped") ?? ofMetric[0];
+}
+
+// The verdict of each budget: passed when the value is at most the budget, exceeded above it, and not
+// measured when the run has no value, with the reason its snippet gave. With several runs, the median.
+export function checkBudgets({ results = [], runs }, budgets) {
+  return Object.entries(budgets).map(([metric, budget]) => {
+    const unit = BUDGET_METRICS[metric];
+    const result = resultFor(results, metric);
+    const measured = result?.status === "ok" && typeof result.value === "number" ? result.value : null;
+    const value = runs ? (runs.summary?.[metric]?.median ?? null) : measured;
+    if (value === null) {
+      const note = result?.error ?? result?.message ?? (result?.status === "skipped" ? result.reason : undefined);
+      return { metric, budget, value: null, unit, verdict: "not measured", ...(note ? { note } : {}) };
+    }
+    return { metric, budget, value, unit, verdict: value > budget ? "exceeded" : "passed" };
+  });
+}
+
+const amount = (value, unit) => (unit === "ms" ? `${value}ms` : String(value));
+
+// The budgets that failed, in the words of stderr
+export const violationsOf = (checked) =>
+  checked
+    .filter((b) => b.verdict !== "passed")
+    .map((b) =>
+      b.verdict === "exceeded"
+        ? `${b.metric} ${amount(b.value, b.unit)} exceeds budget ${amount(b.budget, b.unit)}`
+        : `${b.metric} was not measured (budget ${amount(b.budget, b.unit)})${b.note ? `: ${b.note}` : ""}`
+    );

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})` : ""}`
+      )
+  );
+}