webperf-snippets 1.9.0 → 1.10.0

package/README.md

@@ -73,7 +73,7 @@ npx webperf-snippets https://example.com --json
 The JSON output records how the page was measured in `conditions`, so a later run can tell whether it measured the same way: the viewport, the workflow (or the path of the snippet with `--snippet`), the wait, the version of the CLI and the machine: its CPU model, cores, architecture and memory, as the operating system reports them, and a benchmark index, a short CPU test in Node before Chromium starts, which only informs, since on the same machine it moves by up to 40 % with the load.
 
 ```json
-"conditions": { "viewport": "mobile", "workflow": "core-web-vitals", "waitMs": 3000, "cliVersion": "1.9.0", "machine": { "cpu": "Apple M4", "cores": 10, "arch": "arm64", "memoryGB": 16, "benchmarkIndex": 2371 } }
+"conditions": { "viewport": "mobile", "workflow": "core-web-vitals", "waitMs": 3000, "cliVersion": "1.10.0", "machine": { "cpu": "Apple M4", "cores": 10, "arch": "arm64", "memoryGB": 16, "benchmarkIndex": 2371 } }
 ```
 
 Single snippet:
@@ -136,6 +136,19 @@ Field data (CrUX p75, mobile)
 
 Get a key for the [Chrome UX Report API](https://developer.chrome.com/docs/crux/api) and pass it with `--crux-key` or the `CRUX_API_KEY` environment variable; prefer the variable, because a flag ends up in shell history and CI logs. The section appears in the human and markdown output and under `crux` in the `--json` output.
 
+With a key, the field data also gives what CrUX knows of the LCP when it is an image: the p75 of its sub-parts, TTFB, load delay, load duration and render delay. When the measurement ran LCP-Subparts, with `--snippet LCP-Subparts` or the `core-web-vitals` workflow over 2.5 s, a table puts each one next to its lab value, with a note where one side is at least 1.5 times the other and 100 ms apart: a slower server or network for users, an image the lab finds sooner, slower connections, slower devices, or a lab slower than users. The field sub-parts describe only the loads whose LCP is an image, and the table says which share that is; when the LCP of the lab is not an image, only TTFB and render delay compare. Each p75 is taken on its own, so the sub-parts do not add up to the p75 of LCP. A line gives the navigation types of the users, by share, and points to Back-Forward-Cache when over 5 % of the visits come back without the back/forward cache. The JSON output carries them in `crux.subParts`, `crux.lcpImageShare`, `crux.roundTripTime` and `crux.navigationTypes`.
+
+`--crux-history <weeks>` adds the trend of the field data over the last 1 to 40 weeks, from the [CrUX History API](https://developer.chrome.com/docs/crux/history-api), with the same key. Each week is the p75 of the 28 days before it, so the weeks overlap and the series is smooth. For LCP, CLS and INP the section gives the first and the last week, the change between them and its direction, `stable` within 5 %, and the weeks as a sparkline, where a gap is a week with too little data:
+
+```
+Field data trend (CrUX p75, 40 weeks, mobile, origin-level)
+  LCP   2.88s → 3.10s       ▲ +7.7%   worsening   ▃▃▄▃▃▃▄▆▇██▇▆▄▂▁▂▃▃▄▅▆▆▆▆▆▆
+  CLS   0.2600 → 0.2100     ▼ −19.2%  improving   ▅▆▆▇▇█▇▆▆▅▄▃▃▃▃▃▂▂▁▂▂▂▂▂▂▂
+  INP   253ms → 251ms       ▼ −0.8%   stable      ▇▅▃▂▂▄▆██▇▅▃▂▃▄▆▅▃▂▁▂▃▃▄▅▆
+```
+
+The JSON output carries it in `crux.history`, with the periods, the p75 of each week and the trend of each metric. Like the p75, it uses the page when it has data of its own and its origin otherwise, and says which in `scope`.
+
 - The population follows `--viewport`: `desktop` uses desktop data, `mobile` and `tablet` use phone data. The heading says which one.
 - When the page itself has no data, the CLI looks the origin up instead and labels the section `origin-level`, so it is not mistaken for page-level data. If the origin has none either, the output says `Field data: not available`.
 - A CrUX error (quota, network, no answer within 10 seconds) only skips the section. It never changes the exit code, and the key is never printed.
@@ -158,7 +171,7 @@ Without `--report-to` the CLI makes no external calls. With it, the results are
   "timestamp": "2026-05-06T10:00:00.000Z",
   "navMs": 1240,
   "results": [],
-  "meta": { "viewport": "mobile", "waitMs": 3000, "cli_version": "1.9.0" }
+  "meta": { "viewport": "mobile", "waitMs": 3000, "cli_version": "1.10.0" }
 }
 ```
 
@@ -327,6 +340,7 @@ Each budget compares the value measured, or the median with `--runs`, and fails
 | `--threshold <metric>=<v>`   | The threshold of a metric for `--baseline`, such as `LCP=15%`, `LCP=200ms` or `CLS=0.1`. Repeat it for more metrics. |
 | `--fail-on-regression`       | Exit `1` when a metric regressed or an error is new against `--baseline`. |
 | `--crux-key <key>`           | Add CrUX field data (p75) next to the measured values. Prefer `CRUX_API_KEY`. |
+| `--crux-history <weeks>`     | Add the trend of the field data over the last 1 to 40 weeks. Needs a CrUX key. |
 | `--report-to <url>`          | POST the results to this `https` URL after the run. No external calls without it. |
 | `--api-key <key>`            | Sent as a Bearer token with `--report-to`. Prefer `PERF_REVIEWS_API_KEY`. |
 | `--budget-lcp <ms>`          | Exit `1` if LCP exceeds this value or was not measured.                                    |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webperf-snippets",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "mcpName": "io.github.nucliweb/webperf-snippets",
   "description": "Run curated WebPerf Snippets headlessly via Playwright. Diagnose Core Web Vitals beyond what Lighthouse exposes.",
   "type": "module",

package/src/bin.js

@@ -10,7 +10,7 @@ import { reportHuman, reportMatrixHuman } from "./reporters/human.js";
 import { reportJson } from "./reporters/json.js";
 import { reportMarkdown, reportMatrixMarkdown } from "./reporters/markdown.js";
 import { cliVersion, reportTo, validateReportUrl } from "./report-to.js";
-import { fetchCrux, formFactorFor } from "./crux.js";
+import { fetchCrux, fetchCruxHistory, formFactorFor } from "./crux.js";
 import { MissingBrowserError } from "./browser.js";
 import { parseHeader } from "./headers.js";
 import { NETWORK_PRESETS, parseCpuFactor } from "./throttling.js";
@@ -80,6 +80,7 @@ Options:
                             LCP=200ms or CLS=0.1. Repeat it for more metrics
   --fail-on-regression      Exit 1 when a metric regressed or an error is new against --baseline
   --crux-key <key>          Add CrUX field data (p75) next to the measured values.
+  --crux-history <weeks>    Add the trend of the field data over the last 1 to 40 weeks (needs a CrUX key).
                             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)
@@ -175,6 +176,7 @@ async function main() {
         threshold: { type: "string", multiple: true },
         "fail-on-regression": { type: "boolean" },
         "crux-key": { type: "string" },
+        "crux-history": { type: "string" },
         "report-to": { type: "string" },
         "api-key": { type: "string" },
         verbose: { type: "boolean" },
@@ -253,6 +255,19 @@ async function main() {
   }
   if (medianBy != null && runCount == null && !matrixPath) fail("--median-by needs --runs");
 
+  // The field data: the p75 of the last 28 days with a key, and its trend week by week with --crux-history
+  const cruxKey = values["crux-key"] || process.env.CRUX_API_KEY;
+  let cruxWeeks;
+  if (values["crux-history"] !== undefined) {
+    cruxWeeks = /^\d+$/.test(values["crux-history"]) ? Number(values["crux-history"]) : NaN;
+    if (!(cruxWeeks >= 1 && cruxWeeks <= 40)) fail(`--crux-history takes 1 to 40 weeks, not "${values["crux-history"]}"`);
+    if (!cruxKey) fail("--crux-history needs a CrUX key: --crux-key or CRUX_API_KEY");
+  }
+  const fieldDataOf = async (url, formFactor) => {
+    const crux = await fetchCrux({ url, apiKey: cruxKey, formFactor });
+    return cruxWeeks ? { ...crux, history: await fetchCruxHistory({ url, apiKey: cruxKey, formFactor, weeks: cruxWeeks }) } : crux;
+  };
+
   // The baseline is read and checked before the browser opens: a wrong file fails at once
   let baseline;
   let thresholds;
@@ -301,7 +316,7 @@ async function main() {
     } catch (err) {
       fail(err.message);
     }
-    await runMatrix(matrixPath, matrix, measureWith, { values, waitMs, reportUrl, conditionsFor, baseline, thresholds, budgets });
+    await runMatrix(matrixPath, matrix, measureWith, { values, waitMs, reportUrl, conditionsFor, baseline, thresholds, budgets, cruxKey, fieldDataOf });
     return;
   }
 
@@ -316,9 +331,7 @@ async function main() {
   }
   payload.conditions = conditionsFor(viewportName);
 
-  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;
+  if (cruxKey) payload.crux = await fieldDataOf(url, formFactorFor(viewportName));
 
   if (baseline) {
     payload.baseline = compareRun(baseline.data, payload, { file: baseline.file, thresholds });
@@ -394,7 +407,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, budgets }) {
+async function runMatrix(matrixPath, matrix, measureWith, { values, waitMs, reportUrl, conditionsFor, baseline, thresholds, budgets, cruxKey, fieldDataOf }) {
   for (const warning of matrix.warnings) process.stderr.write(`Warning: ${warning}\n`);
   const viewportOf = new Map(matrix.combinations.map((c) => [c.id, c.viewport]));
 
@@ -414,13 +427,12 @@ async function runMatrix(matrixPath, matrix, measureWith, { values, waitMs, repo
   }
 
   // The field data of a URL depends on the form factor, not on the variant: one query for each pair
-  const cruxKey = values["crux-key"] || process.env.CRUX_API_KEY;
   if (cruxKey) {
     const queries = new Map();
     for (const c of combinations.filter((c) => !c.error)) {
       const formFactor = formFactorFor(viewportOf.get(c.id));
       const key = `${c.url} ${formFactor}`;
-      if (!queries.has(key)) queries.set(key, fetchCrux({ url: c.url, apiKey: cruxKey, formFactor }));
+      if (!queries.has(key)) queries.set(key, fieldDataOf(c.url, formFactor));
       const crux = await queries.get(key);
       if (crux) c.crux = crux;
     }

package/src/crux.js

@@ -1,6 +1,8 @@
 import { rate } from "./ratings.js";
 
 const DEFAULT_ENDPOINT = "https://chromeuxreport.googleapis.com/v1/records:queryRecord";
+// The History API lives next to the daily one; an endpoint given for tests or a proxy points at both
+const historyEndpointOf = (endpoint) => endpoint.replace(/records:queryRecord$/, "records:queryHistoryRecord");
 const CRUX_TIMEOUT_MS = 10000;
 
 const METRICS = [
@@ -27,6 +29,42 @@ function parseMetrics(record) {
   return metrics;
 }
 
+// The sub-parts of the LCP as CrUX reports them, for the loads whose LCP is an image, by the names of
+// the lab sub-parts of LCP-Subparts
+const SUB_PARTS = [
+  { part: "ttfb", label: "TTFB", key: "largest_contentful_paint_image_time_to_first_byte" },
+  { part: "resourceLoadDelay", label: "Load delay", key: "largest_contentful_paint_image_resource_load_delay" },
+  { part: "resourceLoadTime", label: "Load duration", key: "largest_contentful_paint_image_resource_load_duration" },
+  { part: "elementRenderDelay", label: "Render delay", key: "largest_contentful_paint_image_element_render_delay" },
+];
+
+const p75Of = (record, key) => {
+  const value = Number(record?.metrics?.[key]?.percentiles?.p75);
+  return Number.isFinite(value) ? value : undefined;
+};
+
+// What else the record of a page says besides LCP, CLS and INP: the sub-parts of an image LCP, the
+// share of loads whose LCP is an image, the round trip time and the navigation types, by share
+export function parseFieldExtras(record) {
+  const extras = {};
+  const subParts = {};
+  for (const { part, key } of SUB_PARTS) {
+    const value = p75Of(record, key);
+    if (value !== undefined) subParts[part] = value;
+  }
+  if (Object.keys(subParts).length) extras.subParts = subParts;
+  const imageShare = record?.metrics?.largest_contentful_paint_resource_type?.fractions?.image;
+  if (typeof imageShare === "number") extras.lcpImageShare = imageShare;
+  const rtt = p75Of(record, "round_trip_time");
+  if (rtt !== undefined) extras.roundTripTime = rtt;
+  const fractions = record?.metrics?.navigation_types?.fractions;
+  if (fractions) {
+    const sorted = Object.entries(fractions).filter(([, share]) => share > 0).sort((a, b) => b[1] - a[1]);
+    if (sorted.length) extras.navigationTypes = Object.fromEntries(sorted);
+  }
+  return extras;
+}
+
 async function query({ endpoint, apiKey, body, timeoutMs }) {
   const res = await fetch(`${endpoint}?key=${encodeURIComponent(apiKey)}`, {
     method: "POST",
@@ -61,7 +99,78 @@ export async function fetchCrux({
     if (answer.status) return { unavailable: `the CrUX API answered ${answer.status}`, failed: true };
     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 };
+    return { scope, formFactor, metrics, ...parseFieldExtras(answer.record) };
+  } catch (err) {
+    const reason = err.name === "TimeoutError" ? `no answer within ${timeoutMs}ms` : (err.cause?.code ?? "request failed");
+    return { unavailable: reason, failed: true };
+  }
+}
+
+// A trend compares the first and the last periods with data: each period already covers 28 days, so the
+// series is smooth enough. Within 5 % it is stable; lower is better for every metric.
+const STABLE_WITHIN = 5;
+
+export function trendOf(p75s) {
+  const values = p75s.filter((v) => v !== null);
+  const first = values[0];
+  const last = values.at(-1);
+  if (values.length < 2) return { first, last, change: null, trend: null };
+  const change = first === 0 ? null : Math.round(((last - first) / first) * 1000) / 10;
+  const trend = change === null || Math.abs(change) <= STABLE_WITHIN ? "stable" : change < 0 ? "improving" : "worsening";
+  return { first, last, change, trend };
+}
+
+const BARS = "▁▂▃▄▅▆▇█";
+
+// The series as bars between its lowest and highest values, a space for a period without data
+export function sparkline(values) {
+  const known = values.filter((v) => v !== null);
+  const min = Math.min(...known);
+  const max = Math.max(...known);
+  return values.map((v) => (v === null ? " " : max === min ? BARS[3] : BARS[Math.round(((v - min) / (max - min)) * 7)])).join("");
+}
+
+const dateOf = ({ year, month, day }) => `${year}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+
+// The record of the History API as periods, oldest first, and the p75s of each Core Web Vital
+export function parseHistory(record) {
+  const periods = (record?.collectionPeriods ?? []).map((p) => ({ start: dateOf(p.firstDate), end: dateOf(p.lastDate) }));
+  const metrics = {};
+  for (const m of METRICS) {
+    const raw = record?.metrics?.[m.key]?.percentilesTimeseries?.p75s;
+    if (!raw) continue;
+    // CLS comes as strings ("0.21"), and a period with too little data as null
+    const p75s = raw.map((v) => (v === null || v === undefined || !Number.isFinite(Number(v)) ? null : Number(v)));
+    if (p75s.every((v) => v === null)) continue;
+    metrics[m.name] = { unit: m.unit, p75s, ...trendOf(p75s) };
+  }
+  return { periods, metrics };
+}
+
+// The p75 of LCP, CLS and INP week by week over the last `weeks` periods (1 to 40), from the History
+// API: the URL, or its origin when the URL has too little traffic. Never throws, and like fetchCrux
+// never puts the key in a message.
+export async function fetchCruxHistory({
+  url,
+  apiKey,
+  weeks,
+  formFactor = "PHONE",
+  endpoint = process.env.WEBPERF_CRUX_ENDPOINT ?? DEFAULT_ENDPOINT,
+  timeoutMs = CRUX_TIMEOUT_MS,
+}) {
+  const history = historyEndpointOf(endpoint);
+  try {
+    let scope = "url";
+    let answer = await query({ endpoint: history, apiKey, body: { url, formFactor, collectionPeriodCount: weeks }, timeoutMs });
+    if (answer.notFound) {
+      scope = "origin";
+      answer = await query({ endpoint: history, apiKey, body: { origin: new URL(url).origin, formFactor, collectionPeriodCount: weeks }, timeoutMs });
+    }
+    if (answer.notFound) return { unavailable: "not in the CrUX dataset" };
+    if (answer.status) return { unavailable: `the CrUX History API answered ${answer.status}`, failed: true };
+    const { periods, metrics } = parseHistory(answer.record);
+    if (Object.keys(metrics).length === 0) return { unavailable: "no Core Web Vitals in the CrUX history" };
+    return { scope, formFactor, weeks: periods.length, periods, metrics };
   } catch (err) {
     const reason = err.name === "TimeoutError" ? `no answer within ${timeoutMs}ms` : (err.cause?.code ?? "request failed");
     return { unavailable: reason, failed: true };
@@ -84,3 +193,79 @@ export function fieldDataView(crux, results) {
   });
   return { title, rows };
 }
+
+// The trend of the field data, shared by both reporters: per metric the first and last p75 of the
+// weeks, the change and its direction, and the series as a sparkline
+export function historyView(history) {
+  const label = FORM_FACTOR_LABEL[history.formFactor] ?? history.formFactor.toLowerCase();
+  const title = `Field data trend (CrUX p75, ${history.weeks} weeks, ${label}${history.scope === "origin" ? ", origin-level" : ""})`;
+  const rows = METRICS.filter((m) => history.metrics[m.name]).map((m) => {
+    const { p75s, first, last, change, trend } = history.metrics[m.name];
+    const changeText = change === null ? "·" : `${change > 0 ? "▲ +" : change < 0 ? "▼ −" : "= "}${Math.abs(change)}%`;
+    return { metric: m.name, unit: m.unit, first, last, change: changeText, trend: trend ?? "·", sparkline: sparkline(p75s) };
+  });
+  return { title, rows };
+}
+
+const share = (fraction) => (fraction < 0.01 ? `${Math.round(fraction * 1000) / 10}%` : `${Math.round(fraction * 100)}%`);
+
+// A sub-part counts as different when one side is at least 1.5 times the other and 100 ms apart: less
+// than that is within the noise of the lab and of a percentile
+const differs = (slow, fast) => slow >= fast * 1.5 && slow - fast >= 100;
+
+const rttNote = (rtt) => (rtt === undefined ? "" : ` (RTT p75 ${rtt} ms)`);
+const FIELD_SLOWER = {
+  ttfb: (rtt) => `real users wait longer for the server: network distance${rttNote(rtt)}, the CDN or cache misses the lab does not see`,
+  resourceLoadDelay: () => 'the lab finds the image sooner: preload it or give it fetchpriority="high", or users run more scripts before it',
+  resourceLoadTime: (rtt) => `slower connections in the field${rttNote(rtt)}: compress or resize the LCP image`,
+  elementRenderDelay: () => "slower devices or more main-thread work in the field",
+};
+const LAB_SLOWER = "the lab is slower than users: check the CPU and network throttling of the lab";
+
+// The sub-parts of the field next to those of LCP-Subparts in the lab, when it ran, with a note where
+// they differ, and what the field sub-parts describe. Null without field sub-parts.
+export function subPartsView(extras, results) {
+  if (!extras.subParts) return null;
+  const labResult = results.find((r) => r.script === "LCP-Subparts" && r.status === "ok");
+  const labParts = labResult?.details?.subParts ?? {};
+  // The field sub-parts are those of image LCPs: a lab LCP without a resource, such as text, has no load
+  // delay or duration to set against them
+  const labImage = !labResult || Boolean(labResult.details?.url);
+  const rows = SUB_PARTS.filter(({ part }) => extras.subParts[part] !== undefined).map(({ part, label }) => {
+    const field = extras.subParts[part];
+    const comparable = labImage || part === "ttfb" || part === "elementRenderDelay";
+    const lab = comparable ? (labParts[part]?.value ?? null) : null;
+    let note = null;
+    if (lab !== null && differs(field, lab)) note = FIELD_SLOWER[part](extras.roundTripTime);
+    else if (lab !== null && differs(lab, field)) note = LAB_SLOWER;
+    return { part, label, field, lab, note };
+  });
+  const caveats = [
+    ...(extras.lcpImageShare !== undefined ? [`The field sub-parts describe the ${share(extras.lcpImageShare)} of loads whose LCP is an image.`] : []),
+    ...(labImage ? [] : ["The LCP of the lab is not an image, so it has no load delay or duration to compare."]),
+    "Each p75 is taken on its own, so the sub-parts do not add up to the p75 of LCP.",
+  ];
+  return { rows, caveats };
+}
+
+const NAVIGATION_LABELS = {
+  navigate: "navigate",
+  navigate_cache: "navigate from cache",
+  reload: "reload",
+  restore: "restore",
+  back_forward: "back/forward",
+  back_forward_cache: "back/forward cache",
+  prerender: "prerender",
+};
+
+// How users arrive at the page, by share, and a pointer to Back-Forward-Cache when over 5 % of the
+// visits come back without the back/forward cache, which would have shown the page at once
+export function navigationView(extras) {
+  if (!extras.navigationTypes) return null;
+  const parts = Object.entries(extras.navigationTypes).map(([type, fraction]) => `${NAVIGATION_LABELS[type] ?? type} ${share(fraction)}`);
+  const missed = extras.navigationTypes.back_forward ?? 0;
+  return {
+    line: `Navigations: ${parts.join(", ")}`,
+    hint: missed > 0.05 ? `${share(missed)} of the visits come back without the back/forward cache: run Back-Forward-Cache to see what blocks it.` : null,
+  };
+}

package/src/mcp/server.js

@@ -7,7 +7,7 @@ import { isTrackingSnippet } from "../tracking.js";
 import { runSnippets, runMeasurement, evaluateItems, collectTrackingData, VIEWPORT_PRESETS } from "../runner.js";
 import { WORKFLOWS } from "../workflows/index.js";
 import { RULES } from "../decision-tree.js";
-import { fetchCrux } from "../crux.js";
+import { fetchCrux, fetchCruxHistory } from "../crux.js";
 import { runInteractions, isInputStep, settle } from "../interactions.js";
 import { createSessions, SessionError } from "./sessions.js";
 import { launchChromium, isMissingBrowser, MISSING_BROWSER } from "../browser.js";
@@ -295,10 +295,11 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
     {
       title: "Get CrUX field data",
       description:
-        "Returns the p75 of LCP, CLS and INP that real Chrome users had on a URL over the last 28 days, from the Chrome UX Report, with their rating. Falls back to the origin when the URL has no data of its own. Compare it with the lab values of run_snippet: field data is what users get.",
+        "Returns the p75 of LCP, CLS and INP that real Chrome users had on a URL over the last 28 days, from the Chrome UX Report, with their rating. Falls back to the origin when the URL has no data of its own. Compare it with the lab values of run_snippet: field data is what users get. With weeks, it adds the trend: the p75 of each week, each the 28 days before it, with the change from the first week to the last.",
       inputSchema: z.object({
         url: HttpUrl,
         formFactor: z.enum(Object.keys(CRUX_FORM_FACTORS)).default("phone").describe("The devices the data describes"),
+        weeks: z.number().int().min(1).max(40).optional().describe("Add the trend of the last 1 to 40 weeks"),
       }),
       outputSchema: z.object({
         url: z.string(),
@@ -309,21 +310,38 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
           .optional()
           .describe("By metric name: LCP, CLS, INP"),
         unavailable: z.string().optional().describe("Why there is no field data, such as a page with too little traffic"),
+        subParts: z
+          .record(z.string(), z.number())
+          .optional()
+          .describe("The p75 of the sub-parts of an image LCP: ttfb, resourceLoadDelay, resourceLoadTime, elementRenderDelay"),
+        lcpImageShare: z.number().optional().describe("The share of loads whose LCP is an image, which the sub-parts describe"),
+        roundTripTime: z.number().optional().describe("The p75 of the round trip time of the users, in ms"),
+        navigationTypes: z.record(z.string(), z.number()).optional().describe("The share of each navigation type, such as navigate, reload or back_forward_cache"),
+        history: z
+          .looseObject({})
+          .meta({ additionalProperties: true })
+          .optional()
+          .describe("With weeks: scope, weeks, periods, and per metric its p75s, first, last, change in percent and trend"),
       }),
       annotations: { readOnlyHint: true, openWorldHint: true },
     },
-    async ({ url, formFactor }) => {
+    async ({ url, formFactor, weeks }) => {
       const apiKey = env.CRUX_API_KEY;
       if (!apiKey) return toolError(CRUX_SETUP);
-      const crux = await fetchCrux({
+      const options = {
         url,
         apiKey,
         formFactor: CRUX_FORM_FACTORS[formFactor],
         ...(env.WEBPERF_CRUX_ENDPOINT ? { endpoint: env.WEBPERF_CRUX_ENDPOINT } : {}),
-      });
+      };
+      const crux = await fetchCrux(options);
       if (crux.failed) return toolError(`Could not read the CrUX data: ${crux.unavailable}.`);
-      if (crux.unavailable) return toolResult({ url, formFactor, unavailable: crux.unavailable });
-      return toolResult({ url, formFactor, scope: crux.scope, metrics: crux.metrics });
+      const history = weeks ? await fetchCruxHistory({ ...options, weeks }) : undefined;
+      // A history that failed says why in its own unavailable, next to the p75 that did come
+      const trend = history ? { history: history.failed ? { unavailable: history.unavailable } : history } : {};
+      if (crux.unavailable) return toolResult({ url, formFactor, unavailable: crux.unavailable, ...trend });
+      const { scope, metrics, subParts, lcpImageShare, roundTripTime, navigationTypes } = crux;
+      return toolResult({ url, formFactor, scope, metrics, subParts, lcpImageShare, roundTripTime, navigationTypes, ...trend });
     }
   );
 

package/src/reporters/human.js

@@ -1,7 +1,7 @@
 import { styleText } from "node:util";
 import { describeResult } from "../view.js";
 import { isSummaryResult, summaryNumbers } from "./summary-view.js";
-import { fieldDataView } from "../crux.js";
+import { fieldDataView, historyView, subPartsView, navigationView } from "../crux.js";
 import { describeThrottling } from "../throttling.js";
 import { describeRuns, describeAgreement } from "../runs.js";
 import { matrixView } from "./matrix-view.js";
@@ -197,7 +197,8 @@ function renderResult(r, verbose) {
 }
 
 function renderFieldData(crux, results) {
-  if (crux.unavailable) return [styleText("dim", `Field data: not available (${crux.unavailable})`)];
+  const trend = crux.history ? ["", ...renderFieldTrend(crux.history)] : [];
+  if (crux.unavailable) return [styleText("dim", `Field data: not available (${crux.unavailable})`), ...trend];
   const { title, rows } = fieldDataView(crux, results);
   const lines = [styleText("bold", title)];
   for (const row of rows) {
@@ -207,7 +208,41 @@ function renderFieldData(crux, results) {
       `  ${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;
+  return [...lines, ...renderFieldSubParts(crux, results), ...renderNavigations(crux), ...trend];
+}
+
+// "TTFB  1.53s  lab 400ms  real users wait longer for the server…"
+function renderFieldSubParts(crux, results) {
+  const view = subPartsView(crux, results);
+  if (!view) return [];
+  return [
+    "",
+    styleText("bold", "LCP sub-parts (CrUX p75 against the lab)"),
+    ...view.rows.map(
+      (row) => `  ${pad(row.label, 14)}${pad(formatValue(row.field, "ms"), 10)}${pad(`lab ${row.lab === null ? "n/a" : formatValue(row.lab, "ms")}`, 12)}${row.note ?? ""}`.trimEnd()
+    ),
+    ...view.caveats.map((caveat) => styleText("dim", `  ${caveat}`)),
+  ];
+}
+
+function renderNavigations(crux) {
+  const view = navigationView(crux);
+  if (!view) return [];
+  return ["", styleText("dim", view.line), ...(view.hint ? [`  ${view.hint}`] : [])];
+}
+
+// "LCP  2.88s → 3.10s  ▲ +7.7%  worsening  ▁▅█"
+function renderFieldTrend(history) {
+  if (history.unavailable) return [styleText("dim", `Field data trend: not available (${history.unavailable})`)];
+  const { title, rows } = historyView(history);
+  const style = { improving: "green", worsening: "red" };
+  return [
+    styleText("bold", title),
+    ...rows.map(
+      (row) =>
+        `  ${pad(row.metric, 6)}${pad(`${formatValue(row.first, row.unit)} → ${formatValue(row.last, row.unit)}`, 20)}${pad(row.change, 10)}${pad(style[row.trend] ? styleText(style[row.trend], row.trend) : row.trend, 12)}${row.sparkline}`
+    ),
+  ];
 }
 
 // The runs line, and the median, min and max of each metric across the runs, with how much they agree

package/src/reporters/markdown.js

@@ -1,4 +1,4 @@
-import { fieldDataView } from "../crux.js";
+import { fieldDataView, historyView, subPartsView, navigationView } from "../crux.js";
 import { describeResult } from "../view.js";
 import { isSummaryResult, summaryNumbers } from "./summary-view.js";
 import { describeThrottling } from "../throttling.js";
@@ -102,7 +102,8 @@ function renderSection(title, results) {
 }
 
 function renderFieldData(crux, results) {
-  if (crux.unavailable) return [`> Field data: not available (${crux.unavailable})`];
+  const trend = crux.history ? ["", ...renderFieldTrend(crux.history)] : [];
+  if (crux.unavailable) return [`> Field data: not available (${crux.unavailable})`, ...trend];
   const { title, rows } = fieldDataView(crux, results);
   return [
     `### ${title}`,
@@ -112,6 +113,40 @@ function renderFieldData(crux, results) {
       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} |`;
     }),
+    ...renderFieldSubParts(crux, results),
+    ...renderNavigations(crux),
+    ...trend,
+  ];
+}
+
+function renderFieldSubParts(crux, results) {
+  const view = subPartsView(crux, results);
+  if (!view) return [];
+  return [
+    "",
+    "### LCP sub-parts (CrUX p75 against the lab)",
+    "| Sub-part | Field p75 | Lab | Note |",
+    "|----------|-----------|-----|------|",
+    ...view.rows.map((row) => `| ${row.label} | ${formatValue(row.field, "ms")} | ${row.lab === null ? "n/a" : formatValue(row.lab, "ms")} | ${row.note ?? ""} |`),
+    "",
+    ...view.caveats.map((caveat) => `> ${caveat}`),
+  ];
+}
+
+function renderNavigations(crux) {
+  const view = navigationView(crux);
+  if (!view) return [];
+  return ["", `> ${view.line}`, ...(view.hint ? [">", `> ${view.hint}`] : [])];
+}
+
+function renderFieldTrend(history) {
+  if (history.unavailable) return [`> Field data trend: not available (${history.unavailable})`];
+  const { title, rows } = historyView(history);
+  return [
+    `### ${title}`,
+    "| Metric | First | Last | Change | Trend | Weeks |",
+    "|--------|-------|------|--------|-------|-------|",
+    ...rows.map((row) => `| ${row.metric} | ${formatValue(row.first, row.unit)} | ${formatValue(row.last, row.unit)} | ${row.change} | ${row.trend} | ${row.sparkline} |`),
   ];
 }