webperf-snippets 1.3.0 → 1.5.0

package/README.md

@@ -70,6 +70,12 @@ JSON output (for piping into `jq` or CI):
 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 and the version of the CLI.
+
+```json
+"conditions": { "viewport": "mobile", "workflow": "core-web-vitals", "waitMs": 3000, "cliVersion": "1.5.0" }
+```
+
 Single snippet:
 
 ```bash
@@ -152,7 +158,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.3.0" }
+  "meta": { "viewport": "mobile", "waitMs": 3000, "cli_version": "1.5.0" }
 }
 ```
 
@@ -232,10 +238,62 @@ npx webperf-snippets --matrix matrix.json --budget-lcp 2500
 
 The options of the command line apply to every combination: `--workflow`, `--snippet`, `--wait`, `--interact-script`, `--header`, `--own-domains`, `--storage-state`, `--cpu`, `--network` and the budgets. The file replaces `cpu`, `network` and `storageState` where it sets them, and its `headers` and `ownDomains` add to the ones of the command line, the variant winning on the same header. A matrix file is meant to be versioned, so pass secrets, such as the token of an access proxy, with `--header` and an environment variable; a header of the file whose name looks like a secret raises a warning. A key the CLI does not know is an error, so a typo does not measure without its condition.
 
-The report is a table with one row per combination and the rated median of each metric, followed by the errors that decide the exit code; `--verbose` adds the report of the median run of each combination. `--markdown` gives the same table and folds the report of each combination into a `<details>` block, to keep a pull request comment readable. With `--json`, it is `{ "matrix", "runs", "combinations" }`, each combination being the report of its median run with its `id`, `name`, `device`, `variant` (when the file defines variants) and `runs`. The budgets compare the median of each combination. The command exits with code `1` when a combination exceeds a budget, has an error or fails every run, and with code `2` for an invalid file, before any page load, naming the place of the problem in the JSON. `--viewport` does not apply, since each device sets its own.
+The report is a table with one row per combination and the rated median of each metric, followed by the errors that decide the exit code; `--verbose` adds the report of the median run of each combination. `--markdown` gives the same table and folds the report of each combination into a `<details>` block, to keep a pull request comment readable. With `--json`, it is `{ "matrix", "runs", "combinations" }`, each combination being the report of its median run with its `id`, `name`, `device`, `variant` (when the file defines variants), `runs` and `conditions`, with the viewport of its device. The budgets compare the median of each combination. The command exits with code `1` when a combination exceeds a budget, has an error or fails every run, and with code `2` for an invalid file, before any page load, naming the place of the problem in the JSON. `--viewport` does not apply, since each device sets its own.
 
 With CrUX, the CLI asks once for each URL and form factor, so the variants of a device share their field data. With `--report-to`, it posts one report for each combination, the body of one page with `meta.device`, `meta.variant` and `meta.runs`; the headers of the command line and of the file are conditions of the load, and no report carries their values.
 
+Compare a run with an earlier one with `--baseline <file>`, the `--json` output of that run. The comparison says which metrics got worse or better beyond the noise of the lab, which errors are new or fixed, and what differs in how both runs were measured:
+
+```bash
+# On main, once: the baseline
+npx webperf-snippets https://example.com --runs 5 --json > baseline.json
+
+# On the pull request: compare and report
+npx webperf-snippets https://pr-123.example.com --runs 5 --baseline baseline.json --markdown
+
+# Fail when the page gets worse
+npx webperf-snippets https://pr-123.example.com --runs 5 --baseline baseline.json --fail-on-regression
+```
+
+LCP, FCP, TTFB, CLS and INP compare when both runs measured them, the median of each with `--runs`; a metric that only one side measured is `not measured`. A metric regresses when it gets worse by more than its threshold, the larger of a share of the baseline and a minimum, and, when the baseline has two runs or more, ends above the slowest of them: a median inside the range of the baseline is noise the baseline already had. It improves under the same rules the other way, and otherwise it is unchanged.
+
+| Metric         | Share of the baseline | Minimum |
+| -------------- | --------------------- | ------- |
+| LCP, FCP, TTFB | 10%                   | 100 ms  |
+| INP            | 10%                   | 50 ms   |
+| CLS            | none                  | 0.05    |
+
+`--threshold` changes one part of a threshold and keeps the other: `--threshold LCP=15%` the share, `--threshold LCP=200ms` the minimum, and `--threshold CLS=0.1` the only part of CLS. Repeat it for more metrics.
+
+The errors that compare are the ones that decide the exit code: the issues of severity `error` of the steps of the workflow and the snippets that failed. Two errors are the same when they share their [code](https://github.com/nucliweb/webperf-snippets/blob/main/snippets/SCHEMA.md#issue-codes) and the resource they name, whatever their messages say; a resource of the page itself compares by its path and query, so the review app of a pull request, on another host, matches production. A snippet without codes on one side, as in a baseline of an earlier version, compares by message with the figures left out, so "Render-blocking CSS (69.21 KB)…" and "Render-blocking CSS (71.80 KB)…" are one error. An error that only this run has is new, and one that only the baseline had is fixed. Warnings and information do not compare, since they change too easily.
+
+The report adds the comparison after the usual one, and `--markdown` a table for the pull request comment. The JSON output carries it in `baseline`:
+
+```json
+"baseline": {
+  "file": "baseline.json",
+  "url": "https://example.com/",
+  "runs": { "count": 5, "medianBy": "LCP" },
+  "metrics": {
+    "LCP": { "baseline": 2100, "current": 2480, "delta": 380, "deltaPercent": 18.1, "threshold": 210, "verdict": "regressed" }
+  },
+  "errors": { "new": [{ "id": "render-blocking", "message": "1 render-blocking resource(s) delay rendering until 900ms" }], "fixed": [] },
+  "warnings": []
+}
+```
+
+When both runs were measured differently, with another workflow or snippet, viewport, wait, throttling, number of runs or version of the CLI, or on another path or query, the CLI compares anyway and warns on stderr, in the reports and in `warnings`: whoever reads the pull request comment does not see the stderr of the CI. Another host does not warn, since it is the review app of a pull request against production. A baseline of one run warns that only the thresholds apply.
+
+The comparison only informs, and the exit code is the same as without it, unless `--fail-on-regression`, which exits with `1` when a metric regressed or an error is new, and names them on stderr. A baseline that does not exist or is not an output of the CLI, a baseline of a page for a matrix or of a matrix for a page, or a `--threshold` the CLI does not understand exits with code `2`, before the page loads.
+
+A matrix compares with the `--json` output of an earlier matrix, each combination with the one of the same `id`:
+
+```bash
+npx webperf-snippets --matrix matrix.json --runs 3 --baseline last-week.json
+```
+
+The table adds a change column after each metric: the change when it counts (`▲ +380ms`, `▼ −90ms`), `=` when it is unchanged, and `new` for a combination the baseline did not have. Below the table come the warnings, once when every combination has them, the new and fixed errors of each combination, and the combinations that only one side has. `--markdown` gives the same, and the `<details>` block of each combination carries its own comparison. In the JSON output each combination carries its `baseline`, and the root `baseline` names the file and the `added` and `missing` combinations. `--fail-on-regression` exits with `1` when any combination regressed or has a new error.
+
 CI gating:
 
 ```bash
@@ -261,6 +319,9 @@ npx webperf-snippets https://example.com --budget-lcp 2500 --budget-cls 0.1
 | `--runs <n>`                 | Measure the page n times, from 1 to 9, one after the other, and report the median run. |
 | `--median-by <metric>`       | Metric that picks the median run: `LCP`, `FCP`, `TTFB`, `CLS`, `INP` or `navMs`. Default: the first of LCP, FCP, TTFB and `navMs` measured. |
 | `--matrix <file>`            | Measure every URL of a JSON file on every device and in every variant it lists, and report a table of the medians. |
+| `--baseline <file>`          | Compare the page, or each combination of a matrix, with the `--json` output of an earlier run: which metrics got worse or better beyond the noise, and which errors are new or fixed. |
+| `--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`. |
 | `--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`. |
@@ -300,8 +361,8 @@ The results of a run can add steps on the same page load: LCP over 2.5 s adds `L
 | Code | Meaning                                       |
 | ---- | --------------------------------------------- |
 | `0`  | All checks passed.                            |
-| `1`  | Budget violation, a snippet errored, or a step of the workflow reported an `error` issue. |
-| `2`  | Usage error (missing URL, unknown workflow).  |
+| `1`  | Budget violation, a snippet errored, a step of the workflow reported an `error` issue, or, with `--fail-on-regression`, a regression against the baseline. |
+| `2`  | Usage error (missing URL, unknown workflow, a baseline or threshold that is not valid). |
 
 ## MCP server
 
@@ -328,8 +389,8 @@ The server also offers resources, documents a client can attach to the context:
 
 | Resource                         | What it has                                                              |
 | -------------------------------- | ------------------------------------------------------------------------ |
-| `webperf://schema`               | The contract every snippet result follows: base shape, statuses, how to read a result. |
-| `webperf://schema/{snippet}`     | The fields one snippet returns, with an example.                         |
+| `webperf://schema`               | The contract every snippet result follows: base shape, statuses, how to read a result, the rules of the issue codes. |
+| `webperf://schema/{snippet}`     | The fields one snippet returns, with an example, and the codes of its issues. |
 | `webperf://workflows/{category}` | The workflows and the decision tree of a category.                       |
 
 And prompts, templates that chain the tools (in Claude Code, `/mcp__webperf__audit_lcp`): `audit_lcp`, `debug_inp` and `audit_page`, each with a `url` argument.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webperf-snippets",
-  "version": "1.3.0",
+  "version": "1.5.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",
@@ -21,7 +21,8 @@
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "^2.3.1",
-    "vitest": "^5.0.5"
+    "vitest": "^5.0.5",
+    "web-vitals": "^6.2.3"
   },
   "engines": {
     "node": ">=20.12.0"

package/snippets/CoreWebVitals/CLS.js

@@ -53,10 +53,11 @@
 
   observer.observe({ type: "layout-shift", buffered: true });
 
-  // Update on visibility change (final CLS)
+  // Update on visibility change (final CLS). The shifts that the observer has not delivered yet are
+  // in takeRecords(): without them, the last shift before the page hides is lost.
   document.addEventListener("visibilitychange", () => {
     if (document.visibilityState === "hidden") {
-      observer.takeRecords();
+      for (const entry of observer.takeRecords()) addShift(entry);
       console.log("%c📊 Final CLS (on page hide):", "font-weight: bold;");
       logCLS();
     }

package/snippets/CoreWebVitals/LCP-Image-Entropy.js

@@ -213,23 +213,22 @@
   }
   const issuesSync = [];
   if (lowEntropyCount > 0) {
-    issuesSync.push({ severity: "warning", message: `${lowEntropyCount} image(s) have low entropy and are LCP-ineligible in Chrome 112+` });
+    issuesSync.push({ code: "low-entropy-images", severity: "warning", message: `${lowEntropyCount} image(s) have low entropy and are LCP-ineligible in Chrome 112+` });
   }
   if (lcpImageSync?.isLowEntropy) {
-    issuesSync.push({ severity: "error", message: "Current LCP image has low entropy and may be skipped by Chrome" });
+    issuesSync.push({ code: "lcp-low-entropy", severity: "error", message: "Current LCP image has low entropy and may be skipped by Chrome" });
   }
   // Entropy applies to the LCP only when it is an <img> whose file size can be read; for text, or an
   // image this snippet cannot read, it says so. The images of the page are still listed.
   const lcpTag = lcpElementSync ? lcpElementSync.tagName.toLowerCase() : null;
   if (lcpTag && !lcpImageSync) {
-    issuesSync.push({
-      severity: "info",
-      message: lcpTag === "img"
-        ? "The LCP <img> has no file size to read, as with a data: URL or a cross-origin image without Timing-Allow-Origin, so its entropy cannot be computed."
+    issuesSync.push(
+      lcpTag === "img"
+        ? { code: "lcp-size-unknown", severity: "info", message: "The LCP <img> has no file size to read, as with a data: URL or a cross-origin image without Timing-Allow-Origin, so its entropy cannot be computed." }
         : lcpUrlSync
-        ? `The LCP is the image of a <${lcpTag}>, such as a CSS background or a video poster, and this snippet reads <img> elements only. Run the LCP snippet to measure it.`
-        : `The LCP element is <${lcpTag}>, text and not an image, so its entropy does not apply. Run the LCP snippet to measure it.`,
-    });
+        ? { code: "lcp-not-img", severity: "info", message: `The LCP is the image of a <${lcpTag}>, such as a CSS background or a video poster, and this snippet reads <img> elements only. Run the LCP snippet to measure it.` }
+        : { code: "lcp-is-text", severity: "info", message: `The LCP element is <${lcpTag}>, text and not an image, so its entropy does not apply. Run the LCP snippet to measure it.` }
+    );
   }
   // The list keeps the 50 most relevant images (the LCP image, then low entropy, then lowest bits per pixel); count and details cover all of them
   const MAX_ITEMS = 50;

package/snippets/CoreWebVitals/LCP-Subparts.js

@@ -76,6 +76,23 @@
     return { waiting: firstByte - requestStart, download: responseEnd - firstByte };
   };
 
+  // The times that split the LCP into its subparts, as web-vitals computes them. The resource is the
+  // last request for the LCP URL that started before the render: an earlier download of the same URL
+  // did not paint the element. Its end is capped at the LCP, since a video keeps downloading after
+  // its first frame paints, so the four subparts always add up to the LCP.
+  const lcpSubpartTimes = (lcpEntry, navEntry) => {
+    const activationStart = navEntry.activationStart || 0;
+    const renderTime = Math.max(0, lcpEntry.startTime - activationStart);
+    const resEntry = performance
+      .getEntriesByType("resource")
+      .filter((e) => !isOwnRequest(e))
+      .findLast((e) => e.name === lcpEntry.url && (e.requestStart || e.startTime) <= lcpEntry.startTime);
+    const ttfb = Math.max(0, navEntry.responseStart - activationStart);
+    const requestStart = Math.max(ttfb, resEntry ? (resEntry.requestStart || resEntry.startTime) - activationStart : 0);
+    const responseEnd = Math.min(renderTime, Math.max(requestStart, resEntry ? resEntry.responseEnd - activationStart : 0));
+    return { resEntry, activationStart, ttfb, requestStart, responseEnd, renderTime };
+  };
+
   const getNavigationEntry = () => {
     const navEntry = performance.getEntriesByType("navigation")[0];
     if (navEntry?.responseStart > 0 && navEntry.responseStart < performance.now()) {
@@ -91,31 +108,14 @@
     const navEntry = getNavigationEntry();
     if (!navEntry) return;
 
-    const lcpResEntry = performance
-      .getEntriesByType("resource").filter((e) => !isOwnRequest(e))
-      .find((e) => e.name === lcpEntry.url);
-
-    const activationStart = navEntry.activationStart || 0;
-
-    // Calculate sub-parts
-    const ttfb = Math.max(0, navEntry.responseStart - activationStart);
-
-    const lcpRequestStart = Math.max(
+    const {
+      resEntry: lcpResEntry,
+      activationStart,
       ttfb,
-      lcpResEntry
-        ? (lcpResEntry.requestStart || lcpResEntry.startTime) - activationStart
-        : 0
-    );
-
-    const lcpResponseEnd = Math.max(
-      lcpRequestStart,
-      lcpResEntry ? lcpResEntry.responseEnd - activationStart : 0
-    );
-
-    const lcpRenderTime = Math.max(
-      lcpResponseEnd,
-      lcpEntry.startTime - activationStart
-    );
+      requestStart: lcpRequestStart,
+      responseEnd: lcpResponseEnd,
+      renderTime: lcpRenderTime,
+    } = lcpSubpartTimes(lcpEntry, navEntry);
 
     const loadSplit = splitLoadTime(lcpResEntry, lcpRequestStart, lcpResponseEnd, activationStart);
 
@@ -278,17 +278,14 @@
   if (!navEntrySync) {
     return { script: "LCP-Subparts", status: "error", error: "No navigation entry" };
   }
-  const lcpResEntrySync = performance.getEntriesByType("resource").filter((e) => !isOwnRequest(e))
-    .find((e) => e.name === lcpEntry.url);
-  const activationStartSync = navEntrySync.activationStart || 0;
-  const ttfbSync = Math.max(0, navEntrySync.responseStart - activationStartSync);
-  const lcpRequestStartSync = Math.max(ttfbSync,
-    lcpResEntrySync ? (lcpResEntrySync.requestStart || lcpResEntrySync.startTime) - activationStartSync : 0
-  );
-  const lcpResponseEndSync = Math.max(lcpRequestStartSync,
-    lcpResEntrySync ? lcpResEntrySync.responseEnd - activationStartSync : 0
-  );
-  const lcpRenderTimeSync = Math.max(lcpResponseEndSync, lcpEntry.startTime - activationStartSync);
+  const {
+    resEntry: lcpResEntrySync,
+    activationStart: activationStartSync,
+    ttfb: ttfbSync,
+    requestStart: lcpRequestStartSync,
+    responseEnd: lcpResponseEndSync,
+    renderTime: lcpRenderTimeSync,
+  } = lcpSubpartTimes(lcpEntry, navEntrySync);
   const totalSync = Math.round(lcpRenderTimeSync);
   const ratingSync = valueToRating(totalSync);
   const ttfbVal = Math.round(ttfbSync);

package/snippets/CoreWebVitals/LCP-Video-Candidate.js

@@ -71,22 +71,22 @@
   // The value of a non-video LCP belongs to the LCP snippet; this one only says what the element is
   if (!element || element.tagName !== "VIDEO") {
     const tag = element ? element.tagName.toLowerCase() : null;
-    const message = tag
-      ? `The LCP element is <${tag}>, not a <video>. Run the LCP snippet to measure it, and LCP Subparts to see its phases.`
-      : "The LCP element is no longer in the DOM, so it cannot be checked for a <video>. Run the LCP snippet to measure it.";
+    const issue = tag
+      ? { code: "lcp-not-video", severity: "info", message: `The LCP element is <${tag}>, not a <video>. Run the LCP snippet to measure it, and LCP Subparts to see its phases.` }
+      : { code: "lcp-element-removed", severity: "info", message: "The LCP element is no longer in the DOM, so it cannot be checked for a <video>. Run the LCP snippet to measure it." };
     console.log("%cLCP element is not a <video>", "font-weight: bold;");
     console.log("");
     console.log(`   Tag      : ${tag ? `<${tag}>` : "(element no longer in DOM)"}`);
     if (lcp.url) console.log(`   URL      : ${lcp.url}`);
     if (element) console.log("   Element  :", element);
     console.log("");
-    console.log(`   ${message}`);
+    console.log(`   ${issue.message}`);
     console.groupEnd();
     return {
       script: "LCP-Video-Candidate",
       status: "ok",
       details: { isVideo: false, lcpElement: tag, lcpUrl: lcp.url || null },
-      issues: [{ severity: "info", message }],
+      issues: [issue],
     };
   }
 
@@ -140,34 +140,35 @@
 
   if (secondsAfterLoad > 10) {
     issues.push({
+      code: "late-candidate",
       s: "warning",
       msg: `The LCP candidate rendered ${secondsAfterLoad} s after the page loaded, because the page stayed open without interaction. Reload and run the snippet again to measure the LCP of the load`,
     });
   }
 
   if (lcpSource === "first-frame") {
-    issues.push({ s: "info", msg: "LCP is the first video frame: adding a poster gives explicit control over the LCP image" });
+    issues.push({ code: "first-frame-lcp", s: "info", msg: "LCP is the first video frame: adding a poster gives explicit control over the LCP image" });
   }
   if (lcpSource === "first-frame" && (!autoplay || !muted)) {
-    issues.push({ s: "warning", msg: "First-frame LCP requires autoplay + muted for the browser to render it immediately" });
+    issues.push({ code: "first-frame-not-autoplay-muted", s: "warning", msg: "First-frame LCP requires autoplay + muted for the browser to render it immediately" });
   }
 
   if (posterAttr && !posterPreload) {
-    issues.push({ s: "warning", msg: 'No <link rel="preload" as="image"> for the poster: the browser discovers it late' });
+    issues.push({ code: "poster-not-preloaded", s: "warning", msg: 'No <link rel="preload" as="image"> for the poster: the browser discovers it late' });
   } else if (posterPreload && posterPreload.getAttribute("fetchpriority") !== "high") {
-    issues.push({ s: "info", msg: 'Preload found but missing fetchpriority="high", so it may be deprioritised' });
+    issues.push({ code: "poster-preload-no-fetchpriority", s: "info", msg: 'Preload found but missing fetchpriority="high", so it may be deprioritised' });
   }
 
   if (posterAttr && !isModernFormat && posterFormat !== "unknown") {
-    issues.push({ s: "info", msg: `Poster uses ${posterFormat}; AVIF or WebP would reduce file size and LCP load time` });
+    issues.push({ code: "poster-legacy-format", s: "info", msg: `Poster uses ${posterFormat}; AVIF or WebP would reduce file size and LCP load time` });
   }
 
   if (isCrossOrigin) {
-    issues.push({ s: "info", msg: "renderTime is 0: the resource is cross-origin and the server does not send Timing-Allow-Origin" });
+    issues.push({ code: "render-time-hidden", s: "info", msg: "renderTime is 0: the resource is cross-origin and the server does not send Timing-Allow-Origin" });
   }
 
   if (!autoplay && preload === "none") {
-    issues.push({ s: "warning", msg: 'preload="none" on a non-autoplay video may delay poster image loading in some browsers' });
+    issues.push({ code: "preload-none-delays-poster", s: "warning", msg: 'preload="none" on a non-autoplay video may delay poster image loading in some browsers' });
   }
 
   // Summary
@@ -265,6 +266,6 @@
       isCrossOrigin,
       videoAttributes: { autoplay, muted, playsinline, preload },
     },
-    issues: issues.map((i) => ({ severity: i.s === "warning" ? "warning" : "info", message: i.msg })),
+    issues: issues.map((i) => ({ code: i.code, severity: i.s === "warning" ? "warning" : "info", message: i.msg })),
   };
 })();

package/snippets/Interaction/DOM-Size-and-Depth.js

@@ -80,23 +80,27 @@
   const issues = [];
   if (totalElements > THRESHOLDS.errorNodes) {
     issues.push({
+      code: "too-many-nodes",
       severity: "error",
       message: `${totalElements} nodes exceeds ${THRESHOLDS.errorNodes}; a large DOM slows style recalculation and layout on every interaction`,
     });
   } else if (totalElements > THRESHOLDS.warnNodes) {
     issues.push({
+      code: "too-many-nodes",
       severity: "warning",
       message: `${totalElements} nodes exceeds ${THRESHOLDS.warnNodes}; a large DOM increases style recalculation and layout cost`,
     });
   }
   if (maxDepth > THRESHOLDS.maxDepth) {
     issues.push({
+      code: "too-deep",
       severity: "warning",
       message: `DOM depth of ${maxDepth} exceeds ${THRESHOLDS.maxDepth}; deep trees make style and layout work costlier (deepest: ${selectorFor(deepest)})`,
     });
   }
   if (widest && widest.children > THRESHOLDS.maxChildren) {
     issues.push({
+      code: "too-many-children",
       severity: "warning",
       message: `${widestSelector} has ${widest.children} children, above ${THRESHOLDS.maxChildren}; consider virtualizing or paginating the list`,
     });

package/snippets/Interaction/Forced-Synchronous-Layout.js

@@ -265,8 +265,10 @@
         .sort((a, b) => b[1] - a[1])
         .slice(0, 10)
         .map(([property, count]) => ({
+          code: "forced-layout",
           severity: count > 5 ? "error" : "warning",
           message: `${property} triggered ${count} forced synchronous layout${count > 1 ? "s" : ""}. Read layout properties before writing to the DOM.`,
+          target: property,
         })),
     };
   };

package/snippets/Interaction/Input-Latency-Breakdown.js

@@ -259,8 +259,10 @@
         const bottleneck = phases.reduce((a, c) => (a.value > c.value ? a : c));
         const rating = valueToRating(p75(b.durations));
         return {
+          code: "slow-event-type",
           severity: rating === "poor" ? "error" : "warning",
           message: `${type} P75 is ${Math.round(p75(b.durations))}ms (${rating}). Bottleneck: ${bottleneck.name}. Fix: ${BOTTLENECK_FIXES[bottleneck.name]}.`,
+          target: type,
         };
       });
 

package/snippets/Interaction/Interactions.js

@@ -264,8 +264,10 @@
         .sort((a, b) => b.duration - a.duration)
         .slice(0, 10)
         .map((i) => ({
+          code: "slow-interaction",
           severity: i.rating === "poor" ? "error" : "warning",
           message: `${i.type} interaction took ${Math.round(i.duration)}ms (${i.rating}), above the ${i.rating === "poor" ? "500ms" : "200ms"} threshold`,
+          target: i.type,
         })),
     };
   };

package/snippets/Interaction/Scroll-Performance.js

@@ -207,12 +207,14 @@
     const issues = [];
     if (nonPassiveListeners.length > 0) {
       issues.push({
+        code: "non-passive-listeners",
         severity: "warning",
         message: `${nonPassiveListeners.length} non-passive scroll or touch listener(s). Add { passive: true } so scrolling does not wait for JavaScript.`,
       });
     }
     if (css.willChangeElements.length > 0) {
       issues.push({
+        code: "will-change",
         severity: "info",
         message: `will-change is set on ${css.willChangeElements.length} element(s). Remove it from elements that do not animate, since each one keeps a compositor layer.`,
       });

package/snippets/Loading/Back-Forward-Cache.js

@@ -82,6 +82,7 @@
       : [];
     confirmed.forEach(({ reason, frame }) => {
       issues.push({
+        code: 'not-restored',
         reason: `${reason} (${frame})`,
         severity: 'high',
         source: 'browser',
@@ -93,6 +94,7 @@
     // cannot be detected from JavaScript.
     if (window.onunload !== null && !confirmed.some(({ reason }) => reason === 'unload-listener')) {
       issues.push({
+        code: 'unload-handler',
         reason: 'window.onunload handler set',
         severity: 'high',
         source: 'detected',
@@ -108,6 +110,7 @@
         const cacheControl = res.headers.get('cache-control') || '';
         if (/no-store/i.test(cacheControl) && !confirmed.some(({ reason }) => reason === 'response-cache-control-no-store')) {
           issues.push({
+            code: 'cache-control-no-store',
             reason: 'Cache-Control: no-store on the page response',
             severity: 'medium',
             source: 'detected',
@@ -123,6 +126,7 @@
     const iframeCount = document.querySelectorAll('iframe').length;
     if (iframeCount > 0) {
       issues.push({
+        code: 'iframes',
         reason: `${iframeCount} iframe(s) on the page`,
         severity: 'info',
         source: 'note',
@@ -132,6 +136,7 @@
 
     if ('serviceWorker' in navigator && navigator.serviceWorker.controller) {
       issues.push({
+        code: 'service-worker',
         reason: 'Service Worker controls the page',
         severity: 'info',
         source: 'note',
@@ -255,8 +260,10 @@
       notRestoredReasons: results.notRestoredReasons,
     },
     issues: results.blockingReasons.map((i) => ({
+      code: i.code,
       severity: i.severity === 'high' ? 'error' : i.severity === 'medium' ? 'warning' : 'info',
       message: i.reason,
+      ...(i.code === 'not-restored' ? { target: i.reason } : {}),
     })),
   });
 

package/snippets/Loading/CSS-Media-Queries-Analysis.js

@@ -151,21 +151,23 @@ async function analyzeCSSMediaQueries(minWidth = 768) {
 
   const issues = [];
   if (rules.length === 0) {
-    issues.push({ severity: "info", message: `No @media rules for viewports wider than ${minWidth}px` });
+    issues.push({ code: "no-wide-rules", severity: "info", message: `No @media rules for viewports wider than ${minWidth}px` });
   } else {
     issues.push({
+      code: "wide-rules",
       severity: totalBytes > WARNING_BYTES ? "warning" : "info",
       message: `${rules.length} @media rules for viewports wider than ${minWidth}px add ${formatBytes(totalBytes)} of CSS that narrower screens download and parse without using. Move them to a stylesheet with a media attribute, such as <link rel="stylesheet" href="wide.css" media="(min-width: ${minWidth + 1}px)">, which narrower screens fetch at low priority without blocking rendering`,
     });
     if (rules.length >= 20 && uniquenessRatio < 0.1) {
       issues.push({
+        code: "repeated-queries",
         severity: "info",
         message: `${queries.length} distinct queries repeat across ${rules.length} @media blocks, the pattern of component-scoped or compiled CSS. Grouping the rules of each query under one block shortens the stylesheets`,
       });
     }
   }
   if (corsBlockedCount > 0) {
-    issues.push({ severity: "info", message: `${corsBlockedCount} cross-origin stylesheet(s) could not be read, so their @media rules are not counted` });
+    issues.push({ code: "unreadable-stylesheets", severity: "info", message: `${corsBlockedCount} cross-origin stylesheet(s) could not be read, so their @media rules are not counted` });
   }
 
   // --- Console output --------------------------------------------------------------------

package/snippets/Loading/Cache-Strategy-Analysis.js

@@ -337,6 +337,7 @@
 
     if (isStaticAsset(type) && cc["no-store"]) {
       entry.antiPatterns.push({
+        code: "static-no-store",
         id: "static-no-store",
         severity: "error",
         message: `${type} asset with no-store; static assets should be cacheable`,
@@ -345,6 +346,7 @@
 
     if (entry.hasHash && maxAge !== null && maxAge < 86400 && !cc["no-store"]) {
       entry.antiPatterns.push({
+        code: "versioned-short-cache",
         id: "versioned-short-cache",
         severity: "warning",
         message: `Versioned URL (hash detected) but max-age=${maxAge}s: consider long cache or immutable`,
@@ -353,6 +355,7 @@
 
     if (entry.hasHash && !cc["immutable"] && !cc["no-store"] && (maxAge === null || maxAge >= 86400)) {
       entry.antiPatterns.push({
+        code: "versioned-not-immutable",
         id: "versioned-not-immutable",
         severity: "info",
         message: `Versioned URL (hash detected) without Cache-Control: immutable`,
@@ -364,6 +367,7 @@
       ["none", "no-store", "no-cache"].includes(strategy)
     ) {
       entry.antiPatterns.push({
+        code: "large-no-cache",
         id: "large-no-cache",
         severity: "error",
         message: `Large resource (${formatBytes(entry.decodedBodySize)}) with no effective cache`,
@@ -372,6 +376,7 @@
 
     if (entry.headers["expires"] && !entry.headers["cache-control"]) {
       entry.antiPatterns.push({
+        code: "expires-without-cc",
         id: "expires-without-cc",
         severity: "warning",
         message: `Uses Expires header without Cache-Control (outdated pattern)`,
@@ -380,6 +385,7 @@
 
     if (isStaticAsset(type) && maxAge === 0) {
       entry.antiPatterns.push({
+        code: "maxage-zero-static",
         id: "maxage-zero-static",
         severity: "warning",
         message: `Static asset with max-age=0, which forces revalidation on every request`,
@@ -394,6 +400,7 @@
       !cc["no-store"]
     ) {
       entry.antiPatterns.push({
+        code: "short-cache-static",
         id: "short-cache-static",
         severity: "warning",
         message: `Static asset with max-age=${maxAge}s (< 1h): consider a longer cache duration`,
@@ -472,6 +479,7 @@
   // are anti-patterns like the header-based ones: they reach `items` and `issues`.
   for (const entry of uncompressedResources) {
     entry.antiPatterns.push({
+      code: "uncompressed",
       id: "uncompressed",
       severity: "warning",
       message: `${entry.type} sent uncompressed (${formatBytes(entry.encodedBodySize)} on the wire for ${formatBytes(entry.decodedBodySize)}): enable Brotli or gzip`,
@@ -480,6 +488,7 @@
   for (const duplicate of costlyDuplicates) {
     // One finding per URL, on the first request, not one per request
     entries.find((e) => e.url === duplicate.url).antiPatterns.push({
+      code: "duplicate-uncached",
       id: "duplicate-uncached",
       severity: "warning",
       message: `Loaded ${duplicate.count} times, ${duplicate.uncachedLoads} from the network: load it once or make it cacheable`,
@@ -551,6 +560,7 @@
       .join(", ");
     coverageIssue = {
       severity: "info",
+      code: "header-coverage",
       id: "header-coverage",
       message: `Cache headers were read for ${headersAnalyzed} of ${entries.length} resources (${headerCoveragePercent}%): the rest are on other origins or are not static assets, so their Cache-Control cannot be read from the page. Most of them are on ${topHosts}; check those hosts in the Network panel or with curl -I`,
     };
@@ -916,10 +926,12 @@
       })),
     issues: [
       ...allAntiPatterns.map((p) => ({
+        code: p.code,
         severity: p.severity,
         id: p.id,
         resource: p.resource,
         message: p.message,
+        target: p.url,
       })),
       ...(coverageIssue ? [coverageIssue] : []),
     ],

package/snippets/Loading/Client-Side-Redirect-Detection.js

@@ -99,6 +99,7 @@
   if (sameOrigin && referrerPath !== currentPath && referrerPath !== '') {
     hasClientRedirect = true;
     indicators.push({
+      code: 'same-origin-navigation',
       type: 'Same-origin navigation',
       from: referrerPath,
       to: currentPath,
@@ -153,6 +154,7 @@
   // Only flag if it's BOTH fast AND small (likely a redirect page)
   if (sameOrigin && domContentLoaded < 500 && responseSize < 10000) {
     indicators.push({
+      code: 'fast-minimal-navigation',
       type: 'Fast minimal-content navigation',
       duration: domContentLoaded.toFixed(1) + 'ms',
       size: (responseSize / 1024).toFixed(1) + ' KB',
@@ -337,9 +339,9 @@
       referrerPath,
     },
     issues: [
-      ...(serverRedirects > 0 ? [{ severity: "warning", message: `${serverRedirects} server-side redirect(s) detected (${Math.round(redirectTime)}ms)` }] : []),
-      ...(documentNavigations.length > 0 ? [{ severity: "error", message: `${documentNavigations.length} same-origin document navigation(s) detected, likely a client-side redirect` }] : []),
-      ...indicators.filter(i => i.severity === "warning").map(i => ({ severity: "warning", message: i.type })),
+      ...(serverRedirects > 0 ? [{ code: "server-redirects", severity: "warning", message: `${serverRedirects} server-side redirect(s) detected (${Math.round(redirectTime)}ms)` }] : []),
+      ...(documentNavigations.length > 0 ? [{ code: "document-navigation", severity: "error", message: `${documentNavigations.length} same-origin document navigation(s) detected, likely a client-side redirect` }] : []),
+      ...indicators.filter(i => i.severity === "warning").map(i => ({ code: i.code, severity: "warning", message: i.type })),
     ],
   };
 })();