webperf-snippets 0.2.0 → 0.4.0

package/snippets/_shared/helpers.js

@@ -0,0 +1,61 @@
+/* eslint-disable no-unused-vars */
+// Canonical source of the helpers that several snippets copy.
+//
+// Snippets run pasted into the DevTools console, so they cannot import anything. Each snippet
+// that needs a helper carries a copy of it between the same two markers:
+//
+//   // @shared <name>
+//   ...
+//   // @end-shared <name>
+//
+// `npm run check:consistency` fails when a copy differs from the block below (indentation is
+// ignored). Edit the block here first, then paste it into every snippet that carries the marker.
+
+// @shared getRootDomain
+function getRootDomain(hostname) {
+  const host = hostname.replace(/\.$/, "");
+  // An IP address has no registrable domain, so each address is its own root
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host) || host.includes(":")) return host;
+  const parts = host.split(".");
+  if (parts.length <= 2) return host;
+  // Country-code domains with a second-level suffix: example.co.uk, example.com.au, example.ac.jp
+  const secondLevelSuffixes = ["ac", "co", "com", "edu", "go", "gob", "gouv", "gov", "govt", "mil", "ne", "net", "nom", "or", "org", "sch"];
+  const tld = parts[parts.length - 1];
+  const sld = parts[parts.length - 2];
+  if (tld.length === 2 && secondLevelSuffixes.includes(sld)) return parts.slice(-3).join(".");
+  return parts.slice(-2).join(".");
+}
+// @end-shared getRootDomain
+
+// Declared at the top of each snippet that carries isFirstParty: the domains of the site that
+// differ from the page's root domain, such as its own CDN. They count as first party.
+const OWN_DOMAINS = [];
+
+// @shared isFirstParty
+function isFirstParty(hostname) {
+  const root = getRootDomain(hostname);
+  if (root === getRootDomain(location.hostname)) return true;
+  return OWN_DOMAINS.some((d) => getRootDomain(String(d).trim().toLowerCase().replace(/^[a-z]+:\/\//, "").split("/")[0]) === root);
+}
+// @end-shared isFirstParty
+
+// @shared logOwnDomainsHint
+function logOwnDomainsHint(thirdPartyCount) {
+  if (OWN_DOMAINS.length === 0 && thirdPartyCount > 0) {
+    console.log(
+      '%cℹ️ OWN_DOMAINS is empty. If this site serves its own assets from other domains (for example a CDN), add them at the top of the snippet, such as const OWN_DOMAINS = ["cdn.example.net"];, and run it again so they count as first party.',
+      "color: #3b82f6;"
+    );
+  }
+}
+// @end-shared logOwnDomainsHint
+
+// @shared formatBytes
+function formatBytes(bytes) {
+  if (bytes === null || bytes === undefined || Number.isNaN(bytes)) return "-";
+  if (bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB"];
+  const i = Math.max(0, Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1));
+  return (bytes / Math.pow(1024, i)).toFixed(1) + " " + units[i];
+}
+// @end-shared formatBytes

package/src/bin.js

@@ -1,54 +1,27 @@
 #!/usr/bin/env node
+import { existsSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { loadSnippet } from "./load-snippet.js";
+import { resolveSnippetName } from "./snippet-names.js";
 import { runSnippets, runMeasurement, VIEWPORT_PRESETS } from "./runner.js";
 import { cwvWorkflow } from "./workflows/cwv.js";
 import { auditWorkflow } from "./workflows/audit.js";
 import { loadingWorkflow } from "./workflows/loading.js";
+import { interactionWorkflow } from "./workflows/interaction.js";
 import { RULES } from "./decision-tree.js";
 import { reportHuman } from "./reporters/human.js";
 import { reportJson } from "./reporters/json.js";
 import { reportMarkdown } from "./reporters/markdown.js";
+import { cliVersion, reportTo, validateReportUrl } from "./report-to.js";
+import { fetchCrux, formFactorFor } from "./crux.js";
 
 const WORKFLOWS = {
   "core-web-vitals": cwvWorkflow,
   audit: auditWorkflow,
   loading: loadingWorkflow,
+  interaction: interactionWorkflow,
 };
 
-const SNIPPET_ALIASES = {
-  LCP: "CoreWebVitals/LCP",
-  CLS: "CoreWebVitals/CLS",
-  "LCP-Subparts": "CoreWebVitals/LCP-Subparts",
-  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",
-  // Tier 1 — Loading
-  "render-blocking": "Loading/Find-render-blocking-resources",
-  "Find-render-blocking-resources": "Loading/Find-render-blocking-resources",
-  "resource-hints": "Loading/Resource-Hints-Validation",
-  "Resource-Hints-Validation": "Loading/Resource-Hints-Validation",
-  "preload-scripts": "Loading/Validate-Preload-Async-Defer-Scripts",
-  "Validate-Preload-Async-Defer-Scripts": "Loading/Validate-Preload-Async-Defer-Scripts",
-  "priority-hints": "Loading/Priority-Hints-Audit",
-  "Priority-Hints-Audit": "Loading/Priority-Hints-Audit",
-  "critical-css": "Loading/Critical-CSS-Detection",
-  "Critical-CSS-Detection": "Loading/Critical-CSS-Detection",
-  ttfb: "Loading/TTFB-Sub-Parts",
-  "TTFB-Sub-Parts": "Loading/TTFB-Sub-Parts",
-  "script-parties": "Loading/First-And-Third-Party-Script-Info",
-  "First-And-Third-Party-Script-Info": "Loading/First-And-Third-Party-Script-Info",
-  "script-loading": "Loading/Script-Loading",
-  "Script-Loading": "Loading/Script-Loading",
-  // Tier 2 — Media
-  "lazy-atf": "Loading/Find-Above-The-Fold-Lazy-Loaded-Images",
-  "Find-Above-The-Fold-Lazy-Loaded-Images": "Loading/Find-Above-The-Fold-Lazy-Loaded-Images",
-  "lazy-conflict": "Loading/Find-Images-With-Lazy-and-Fetchpriority",
-  "Find-Images-With-Lazy-and-Fetchpriority": "Loading/Find-Images-With-Lazy-and-Fetchpriority",
-  "eager-below-fold": "Loading/Find-non-Lazy-Loaded-Images-outside-of-the-viewport",
-  "Find-non-Lazy-Loaded-Images-outside-of-the-viewport":
-    "Loading/Find-non-Lazy-Loaded-Images-outside-of-the-viewport",
-};
 
 const USAGE = `webperf-snippets <url> [options]
 
@@ -56,9 +29,10 @@ Run curated WebPerf Snippets headlessly via Playwright.
 
 Options:
   --workflow <name>     Workflow to run (default: core-web-vitals)
-                        Workflows: core-web-vitals, audit, loading
-  --snippet <name>      Run a single snippet by alias or Category/Name path
-                        Aliases: LCP, CLS, LCP-Subparts, fonts,
+                        Workflows: core-web-vitals, audit, loading, interaction
+  --snippet <name>      Run a single snippet by name, alias or Category/Name path
+                        Any of the 56 snippets, such as Compression-Audit
+                        Aliases: LCP, CLS, INP, LCP-Subparts, fonts,
                                  render-blocking, resource-hints, preload-scripts,
                                  priority-hints, critical-css, ttfb,
                                  script-parties, script-loading,
@@ -69,8 +43,17 @@ Options:
   --wait <ms>           Post-load wait before evaluating (default: 3000)
   --budget-lcp <ms>     Exit 1 if LCP exceeds this value
   --budget-cls <score>  Exit 1 if CLS exceeds this value
-  --interact-script <path>  JSON file with interactions to run before evaluation
+  --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
+  --storage-state <path>    Playwright storage state (cookies + localStorage) to
+                            measure pages that require authentication
+  --crux-key <key>          Add CrUX field data (p75) next to the measured values.
+                            Also read from the CRUX_API_KEY environment variable
+  --report-to <url>         POST the results to this https URL after the run
+                            (without it the CLI makes no external calls)
+  --api-key <key>           Sent as "Authorization: Bearer <key>" with --report-to.
+                            Prefer the PERF_REVIEWS_API_KEY environment variable
   --verbose             Show all items, even for passing checks
   --headed              Show the browser window (debug)
   -h, --help            Show this help
@@ -82,8 +65,10 @@ Examples:
   npx webperf-snippets https://web.dev --snippet LCP-Subparts
   npx webperf-snippets https://web.dev --snippet render-blocking
   npx webperf-snippets https://web.dev --snippet fonts
+  npx webperf-snippets https://web.dev --snippet Compression-Audit
   npx webperf-snippets https://web.dev --budget-lcp 2500
   npx webperf-snippets https://web.dev --snippet INP --interact-script interactions.json
+  npx webperf-snippets https://example.com/dashboard --storage-state auth.json
 `;
 
 function fail(message, code = 2) {
@@ -91,12 +76,13 @@ function fail(message, code = 2) {
   process.exit(code);
 }
 
-function resolveSnippetPath(name) {
-  return SNIPPET_ALIASES[name] ?? name;
-}
-
 function buildSnippetItem(values) {
-  const path = resolveSnippetPath(values.snippet);
+  let path;
+  try {
+    path = resolveSnippetName(values.snippet);
+  } catch (err) {
+    fail(err.message);
+  }
   return [{ id: values.snippet, path, source: loadSnippet(path) }];
 }
 
@@ -131,6 +117,10 @@ async function main() {
         "budget-cls": { type: "string" },
         viewport: { type: "string" },
         "interact-script": { type: "string" },
+        "storage-state": { type: "string" },
+        "crux-key": { type: "string" },
+        "report-to": { type: "string" },
+        "api-key": { type: "string" },
         verbose: { type: "boolean" },
         headed: { type: "boolean" },
         help: { type: "boolean", short: "h" },
@@ -161,19 +151,33 @@ async function main() {
     fail(`Unknown viewport preset: "${viewportName}". Choose from: ${Object.keys(VIEWPORT_PRESETS).join(", ")}`);
   }
 
+  const reportUrl = values["report-to"];
+  if (reportUrl) {
+    const problem = validateReportUrl(reportUrl);
+    if (problem) fail(problem);
+  }
+
   const interactScript = values["interact-script"];
+  const storageState = values["storage-state"];
+  if (storageState && !existsSync(storageState)) {
+    fail(`Storage state file not found: ${storageState}`);
+  }
 
   let payload;
   if (values.snippet) {
     const items = buildSnippetItem(values);
-    payload = await runSnippets({ url, items, waitMs, headless: !values.headed, viewport, interactScript });
+    payload = await runSnippets({ url, items, waitMs, headless: !values.headed, viewport, interactScript, storageState });
   } else {
     const workflowName = values.workflow ?? "core-web-vitals";
     const workflow = WORKFLOWS[workflowName];
     if (!workflow) fail(`Unknown workflow: ${workflowName}`);
-    payload = await runMeasurement({ url, workflow, rules: RULES, waitMs, headless: !values.headed, viewport, interactScript });
+    payload = await runMeasurement({ url, workflow, rules: RULES, waitMs, headless: !values.headed, viewport, interactScript, storageState });
   }
 
+  const cruxKey = values["crux-key"] || process.env.CRUX_API_KEY;
+  const crux = cruxKey ? await fetchCrux({ url, apiKey: cruxKey, formFactor: formFactorFor(viewportName) }) : undefined;
+  if (crux) payload.crux = crux;
+
   let output;
   if (values.markdown) {
     output = reportMarkdown(payload);
@@ -184,6 +188,27 @@ async function main() {
   }
   process.stdout.write(output + "\n");
 
+  if (reportUrl) {
+    const outcome = await reportTo({
+      url: reportUrl,
+      apiKey: values["api-key"] || process.env.PERF_REVIEWS_API_KEY,
+      body: {
+        url,
+        workflow: values.snippet ? null : (values.workflow ?? "core-web-vitals"),
+        ...(values.snippet ? { snippet: values.snippet } : {}),
+        timestamp: new Date().toISOString(),
+        navMs: payload.navMs,
+        results: payload.results,
+        meta: { viewport: viewportName, waitMs, cli_version: cliVersion },
+      },
+    });
+    if (!outcome.ok) {
+      process.stderr.write(`Warning: could not report results to ${new URL(reportUrl).origin} (${outcome.warning})\n`);
+    } else if (outcome.regressions.length > 0) {
+      process.stderr.write(`Regressions detected:\n${outcome.regressions.map((r) => `  - ${typeof r === "string" ? r : JSON.stringify(r)}`).join("\n")}\n`);
+    }
+  }
+
   // Exit codes.
   const violations = checkBudgets(payload.results, values);
   if (violations.length > 0) {
@@ -194,8 +219,10 @@ async function main() {
   }
 
   const anyError = payload.results.some((r) => r.status === "error");
+  // A follow-up (a result with a reason) only informs: its error issues show in the report and
+  // leave the exit code to the budgets and to the steps the workflow runs itself.
   const anyAuditViolation = payload.results.some(
-    (r) => Array.isArray(r.issues) && r.issues.some((i) => i.severity === "error"),
+    (r) => !r.reason && Array.isArray(r.issues) && r.issues.some((i) => i.severity === "error"),
   );
   process.exit(anyError || anyAuditViolation ? 1 : 0);
 }

package/src/crux.js

@@ -0,0 +1,84 @@
+const DEFAULT_ENDPOINT = "https://chromeuxreport.googleapis.com/v1/records:queryRecord";
+const CRUX_TIMEOUT_MS = 10000;
+
+// Good / needs-improvement upper bounds from web.dev/articles/vitals.
+const METRICS = [
+  { name: "LCP", key: "largest_contentful_paint", unit: "ms", good: 2500, poor: 4000 },
+  { name: "CLS", key: "cumulative_layout_shift", unit: "score", good: 0.1, poor: 0.25 },
+  { name: "INP", key: "interaction_to_next_paint", unit: "ms", good: 200, poor: 500 },
+];
+
+const FORM_FACTOR_LABEL = { PHONE: "mobile", DESKTOP: "desktop", TABLET: "tablet" };
+
+const rate = (value, { good, poor }) => (value <= good ? "good" : value <= poor ? "needs-improvement" : "poor");
+
+// The viewport preset decides which population the field data describes.
+export function formFactorFor(viewportName) {
+  return viewportName === "desktop" ? "DESKTOP" : "PHONE";
+}
+
+function parseMetrics(record) {
+  const metrics = {};
+  for (const m of METRICS) {
+    // CLS p75 comes as a string ("0.08"); LCP and INP as numbers.
+    const p75 = Number(record?.metrics?.[m.key]?.percentiles?.p75);
+    if (Number.isFinite(p75)) metrics[m.name] = { p75, rating: rate(p75, m), unit: m.unit };
+  }
+  return metrics;
+}
+
+async function query({ endpoint, apiKey, body, timeoutMs }) {
+  const res = await fetch(`${endpoint}?key=${encodeURIComponent(apiKey)}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (res.status === 404) return { notFound: true };
+  if (!res.ok) return { status: res.status };
+  return { record: (await res.json()).record };
+}
+
+// Never throws, and no message it returns contains the key (it travels in the
+// query string, so the request URL is never logged or put in an error).
+export async function fetchCrux({
+  url,
+  apiKey,
+  formFactor = "PHONE",
+  endpoint = process.env.WEBPERF_CRUX_ENDPOINT ?? DEFAULT_ENDPOINT,
+  timeoutMs = CRUX_TIMEOUT_MS,
+}) {
+  try {
+    let scope = "url";
+    let answer = await query({ endpoint, apiKey, body: { url, formFactor }, timeoutMs });
+    if (answer.notFound) {
+      scope = "origin";
+      answer = await query({ endpoint, apiKey, body: { origin: new URL(url).origin, formFactor }, timeoutMs });
+    }
+    if (answer.notFound) return { unavailable: "not in the CrUX dataset" };
+    if (answer.status) return { unavailable: `the CrUX API answered ${answer.status}` };
+    const metrics = parseMetrics(answer.record);
+    if (Object.keys(metrics).length === 0) return { unavailable: "no Core Web Vitals in the CrUX record" };
+    return { scope, formFactor, metrics };
+  } catch (err) {
+    const reason = err.name === "TimeoutError" ? `no answer within ${timeoutMs}ms` : (err.cause?.code ?? "request failed");
+    return { unavailable: reason };
+  }
+}
+
+// Shared by both reporters: what to show and next to which synthetic value.
+export function fieldDataView(crux, results) {
+  const label = FORM_FACTOR_LABEL[crux.formFactor] ?? crux.formFactor.toLowerCase();
+  const title = `Field data (CrUX p75, ${label}${crux.scope === "origin" ? ", origin-level" : ""})`;
+  const rows = METRICS.filter((m) => crux.metrics[m.name]).map((m) => {
+    const synthetic = results.find((r) => r.status === "ok" && r.metric === m.name);
+    return {
+      metric: m.name,
+      unit: m.unit,
+      p75: crux.metrics[m.name].p75,
+      rating: crux.metrics[m.name].rating,
+      synthetic: synthetic ? synthetic.value : null,
+    };
+  });
+  return { title, rows };
+}

package/src/decision-tree.js

@@ -1,28 +1,76 @@
-// Declarative follow-ups: if a result matches the predicate, append the step.
+// Declarative follow-ups: if a result matches the predicate, append the steps.
 // Mirrors the WORKFLOWS.md decision trees from the snippet catalogue.
+//
+// A rule looks at the first results only. The results of a follow-up do not fire rules of their own.
+const ok = (r, id) => r.id === id && r.status === "ok";
+
 export const RULES = [
   {
-    when: (r) => r.id === "LCP" && r.status === "ok" && r.value > 2500,
+    when: (r) => ok(r, "LCP") && r.value > 2500,
     append: { id: "LCP-Subparts", path: "CoreWebVitals/LCP-Subparts" },
     reason: "LCP > 2.5s — drilling into sub-parts",
   },
   {
-    when: (r) => r.id === "TTFB" && r.status === "ok" && r.value > 600,
+    when: (r) => ok(r, "LCP") && r.value > 4000,
+    append: { id: "LCP-Trail", path: "CoreWebVitals/LCP-Trail" },
+    reason: "LCP > 4s — listing the LCP candidates",
+  },
+  {
+    when: (r) => ok(r, "LCP") && r.details?.elementType === "Image",
+    append: [
+      { id: "LCP-Image-Entropy", path: "CoreWebVitals/LCP-Image-Entropy" },
+      { id: "image-audit", path: "Media/Image-Element-Audit" },
+    ],
+    reason: "LCP is an image — checking its entropy and its attributes",
+  },
+  {
+    when: (r) => ok(r, "LCP") && r.details?.elementType === "Video poster",
+    append: [
+      { id: "LCP-Video-Candidate", path: "CoreWebVitals/LCP-Video-Candidate" },
+      { id: "video-audit", path: "Media/Video-Element-Audit" },
+    ],
+    reason: "LCP is a video — checking its candidate and its loading",
+  },
+  {
+    when: (r) => ok(r, "CLS") && r.value > 0.1,
+    append: { id: "layout-shifts", path: "Interaction/Layout-Shift-Loading-and-Interaction" },
+    reason: "CLS > 0.1 — separating the shifts of the load from those of the interactions",
+  },
+  {
+    when: (r) => ok(r, "CLS") && r.value > 0.25,
+    append: [
+      { id: "lazy-atf", path: "Loading/Find-Above-The-Fold-Lazy-Loaded-Images" },
+      { id: "fonts", path: "Loading/Fonts-Preloaded-Loaded-and-used-above-the-fold" },
+      { id: "critical-css", path: "Loading/Critical-CSS-Detection" },
+      { id: "image-audit", path: "Media/Image-Element-Audit" },
+    ],
+    reason: "CLS > 0.25 — looking for the usual causes: lazy images, font swaps, late CSS and images without dimensions",
+  },
+  {
+    when: (r) => ok(r, "TTFB") && r.value > 600,
     append: { id: "ttfb-subparts", path: "Loading/TTFB-Sub-Parts" },
     reason: "TTFB > 600ms — drilling into sub-parts",
   },
   {
-    when: (r) => r.id === "FCP" && r.status === "ok" && r.value > 1800,
+    when: (r) => ok(r, "FCP") && r.value > 1800,
     append: { id: "render-blocking", path: "Loading/Find-render-blocking-resources" },
     reason: "FCP > 1.8s — checking render-blocking resources",
   },
 ];
 
-export function nextSteps(results) {
+// The follow-up steps the results call for, each snippet once: a path two rules ask for is added by
+// the first, and a path in `skipPaths` (a step the workflow already ran) is left out.
+export function nextSteps(results, rules = RULES, skipPaths = []) {
+  const seen = new Set(skipPaths);
   const followUps = [];
   for (const result of results) {
-    for (const rule of RULES) {
-      if (rule.when(result)) followUps.push({ ...rule.append, reason: rule.reason });
+    for (const rule of rules) {
+      if (!rule.when(result)) continue;
+      for (const step of [rule.append].flat()) {
+        if (seen.has(step.path)) continue;
+        seen.add(step.path);
+        followUps.push({ ...step, reason: rule.reason });
+      }
     }
   }
   return followUps;

package/src/interactions.js

@@ -22,9 +22,19 @@ export async function executeStep(page, step) {
   }
 }
 
-export async function runInteractions(page, scriptPath) {
-  const { interactions } = JSON.parse(readFileSync(scriptPath, "utf8"));
-  for (const step of interactions) {
+// `source` is the path of a JSON file ({ "interactions": [...] }) or the list of steps itself.
+export function loadInteractionSteps(source) {
+  return Array.isArray(source) ? source : JSON.parse(readFileSync(source, "utf8")).interactions;
+}
+
+// A click or a key press creates the events that Interactions and Input-Latency-Breakdown measure;
+// a scroll, a hover and a wait do not.
+export function isInputStep(step) {
+  return step.action === "click" || step.action === "type";
+}
+
+export async function runInteractions(page, source) {
+  for (const step of loadInteractionSteps(source)) {
     await executeStep(page, step);
   }
 }

package/src/load-snippet.js

@@ -6,7 +6,7 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(HERE, "..");
 
 // Resolution order: bundled (published package) → workspace root (dev).
-const SNIPPET_DIRS = [
+export const SNIPPET_DIRS = [
   join(PKG_ROOT, "snippets"),
   resolve(PKG_ROOT, "..", "snippets"),
 ];

package/src/report-to.js

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPORT_TIMEOUT_MS = 5000;
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+export const cliVersion = JSON.parse(readFileSync(join(HERE, "..", "package.json"), "utf8")).version;
+
+// Returns an error message when the URL cannot receive a report, or null.
+// https is required so the API key is never sent in clear text; local hosts
+// are allowed over http for development and tests.
+export function validateReportUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return `--report-to must be an https URL, got "${value}"`;
+  }
+  if (parsed.protocol === "https:") return null;
+  if (parsed.protocol === "http:" && LOCAL_HOSTS.has(parsed.hostname)) return null;
+  return `--report-to must be an https URL (http is allowed only for localhost), got "${value}"`;
+}
+
+// POSTs the results to `url`. Never throws and never touches the exit code:
+// the caller decides what to do with the outcome. The key is only sent in the
+// Authorization header and never appears in a returned message.
+export async function reportTo({ url, apiKey, body, timeoutMs = REPORT_TIMEOUT_MS }) {
+  const headers = { "Content-Type": "application/json" };
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) return { ok: false, warning: `the endpoint answered ${res.status}` };
+    const data = await res.json().catch(() => ({}));
+    return { ok: true, regressions: data.ok === false ? (data.regressions ?? []) : [] };
+  } catch (err) {
+    const reason = err.name === "TimeoutError" ? `no answer within ${timeoutMs}ms` : (err.cause?.code ?? err.message);
+    return { ok: false, warning: reason };
+  }
+}

package/src/reporters/human.js

@@ -1,4 +1,5 @@
 import { styleText } from "node:util";
+import { fieldDataView } from "../crux.js";
 
 const RATING_ICON = {
   good: "🟢",
@@ -99,11 +100,11 @@ function renderAuditResult(r, 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 ?? "";
-      const tag = item.type ?? item.tag ?? item.strategy ?? item.media ?? "";
+      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, timing].filter(Boolean).join("  ");
-      lines.push(`     ${styleText("dim", `· ${cols}`)}`);
+      const cols = [tag, name, item.detail, timing].filter(Boolean).join("  ");
+      if (cols) lines.push(`     ${styleText("dim", `· ${cols}`)}`);
     }
     if (items.length > MAX_ITEMS) {
       lines.push(`     ${styleText("dim", `… and ${items.length - MAX_ITEMS} more`)}`);
@@ -117,7 +118,22 @@ function renderAuditResult(r, verbose) {
   return lines.join("\n");
 }
 
+// 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 summary = [r.count !== undefined ? String(r.count) : null, ...numbers].filter(Boolean).join("  ·  ");
+  return `  ${RATING_ICON[r.rating] ?? "·"} ${pad(r.id, 16)} ${styleText("dim", summary)}`;
+}
+
 function renderResult(r, verbose) {
+  if (r.status === "skipped") {
+    return `  ${styleText("dim", "-")} ${pad(r.id, 16)} ${styleText("dim", `skipped: ${r.reason}`)}`;
+  }
+
   if (r.status === "error") {
     return `  ${styleText("red", "✗")} ${pad(r.id, 16)} ${styleText("dim", r.error)}`;
   }
@@ -130,6 +146,10 @@ function renderResult(r, verbose) {
     return renderAuditResult(r, verbose);
   }
 
+  if (r.value === undefined && (r.count !== undefined || r.details)) {
+    return renderSummaryResult(r);
+  }
+
   const icon = RATING_ICON[r.rating] ?? "·";
   const valueText = paint(r.rating, formatValue(r.value, r.unit));
   const ratingText = styleText("dim", r.rating ?? "");
@@ -164,12 +184,30 @@ function renderResult(r, verbose) {
   return out;
 }
 
-export function reportHuman({ url, navMs, results, pageErrors, verbose }) {
+function renderFieldData(crux, results) {
+  if (crux.unavailable) return [styleText("dim", `Field data: not available (${crux.unavailable})`)];
+  const { title, rows } = fieldDataView(crux, results);
+  const lines = [styleText("bold", title)];
+  for (const row of rows) {
+    const icon = RATING_ICON[row.rating] ?? "·";
+    const synthetic = row.synthetic == null ? "n/a" : formatValue(row.synthetic, row.unit);
+    lines.push(
+      `  ${icon} ${pad(row.metric, 6)} ${pad(paint(row.rating, formatValue(row.p75, row.unit)), 10)} ${pad(styleText("dim", row.rating), 20)} ${styleText("dim", `(synthetic: ${synthetic})`)}`
+    );
+  }
+  return lines;
+}
+
+export function reportHuman({ url, navMs, results, pageErrors, verbose, crux }) {
   const lines = [];
   lines.push(styleText(["bold"], `WebPerf Snippets — ${url}`));
   lines.push(styleText("dim", `Navigated in ${navMs}ms`));
   lines.push("");
   for (const r of results) lines.push(renderResult(r, verbose));
+  if (crux) {
+    lines.push("");
+    lines.push(...renderFieldData(crux, results));
+  }
   if (pageErrors?.length) {
     lines.push("");
     lines.push(styleText("yellow", "Page errors during run:"));

package/src/reporters/markdown.js

@@ -1,3 +1,5 @@
+import { fieldDataView } from "../crux.js";
+
 const RATING_ICON = {
   good: "✅",
   "needs-improvement": "⚠️",
@@ -29,7 +31,12 @@ function renderErrorRow(r) {
   return `| ${r.id} | ❌ error | ${r.error} |`;
 }
 
+function renderSkippedRow(r) {
+  return `| ${r.id} | ⏭ skipped | ${r.reason} |`;
+}
+
 function renderRow(r) {
+  if (r.status === "skipped") return renderSkippedRow(r);
   if (r.status === "error") return renderErrorRow(r);
   if (Array.isArray(r.issues)) return renderAuditRow(r);
   return renderMetricRow(r);
@@ -50,7 +57,21 @@ function renderSection(title, results) {
   ].join("\n");
 }
 
-export function reportMarkdown({ url, navMs, results, pageErrors }) {
+function renderFieldData(crux, results) {
+  if (crux.unavailable) return [`> Field data: not available (${crux.unavailable})`];
+  const { title, rows } = fieldDataView(crux, results);
+  return [
+    `### ${title}`,
+    "| Metric | Field p75 | Status | Synthetic |",
+    "|--------|-----------|--------|-----------|",
+    ...rows.map((row) => {
+      const synthetic = row.synthetic == null ? "n/a" : formatValue(row.synthetic, row.unit);
+      return `| ${row.metric} | ${formatValue(row.p75, row.unit)} | ${RATING_ICON[row.rating] ?? "·"} ${row.rating} | ${synthetic} |`;
+    }),
+  ];
+}
+
+export function reportMarkdown({ url, navMs, results, pageErrors, crux }) {
   const lines = [];
   lines.push(`## WebPerf Results — ${url}`);
   lines.push(`> Navigated in ${navMs}ms`);
@@ -72,6 +93,11 @@ export function reportMarkdown({ url, navMs, results, pageErrors }) {
     lines.push(renderSection(`Follow-up *(${reason})*`, group));
   }
 
+  if (crux) {
+    lines.push("");
+    lines.push(...renderFieldData(crux, results));
+  }
+
   if (pageErrors?.length) {
     lines.push("");
     lines.push("### ⚠ Page Errors");