webperf-snippets 1.4.0 → 1.6.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 and the version of the CLI.
 
 ```json
-"conditions": { "viewport": "mobile", "workflow": "core-web-vitals", "waitMs": 3000, "cliVersion": "1.4.0" }
+"conditions": { "viewport": "mobile", "workflow": "core-web-vitals", "waitMs": 3000, "cliVersion": "1.6.0" }
 ```
 
 Single snippet:
@@ -158,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.4.0" }
+  "meta": { "viewport": "mobile", "waitMs": 3000, "cli_version": "1.6.0" }
 }
 ```
 
@@ -265,7 +265,7 @@ LCP, FCP, TTFB, CLS and INP compare when both runs measured them, the median of
 
 `--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 a code or, without one, when their messages differ only in their figures, 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 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`:
 
@@ -300,6 +300,8 @@ CI gating:
 npx webperf-snippets https://example.com --budget-lcp 2500 --budget-cls 0.1
 ```
 
+Each budget compares the value measured, or the median with `--runs`, and fails when the value is above it. `--budget-lcp` and `--budget-cls` need the `core-web-vitals` workflow, `--budget-fcp` the `loading` workflow, `--budget-ttfb` the `loading` or `audit` workflow, and `--budget-inp` the `interaction` workflow with a click or a key press; `--snippet` with the snippet of the metric works too. A budget of a metric that the run does not measure exits with code `2` before the page loads, and one whose metric was not measured, such as INP without interactions, exits with code `1`: a budget never passes unchecked. The report lists every budget with its value and verdict, `passed`, `exceeded` with by how much, or `not measured` with why: a Budgets section in the human and markdown reports, and `budgets` in the JSON output and in the body of `--report-to`. A matrix lists the failed budgets with their combination under its table. Each failed budget is also written to stderr, with `--json` too.
+
 ### Options
 
 | Option                       | Description                                                            |
@@ -325,8 +327,11 @@ npx webperf-snippets https://example.com --budget-lcp 2500 --budget-cls 0.1
 | `--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`. |
-| `--budget-lcp <ms>`          | Exit `1` if LCP exceeds this value.                                    |
-| `--budget-cls <score>`       | Exit `1` if CLS exceeds this value.                                    |
+| `--budget-lcp <ms>`          | Exit `1` if LCP exceeds this value or was not measured.                                    |
+| `--budget-fcp <ms>`          | Exit `1` if FCP exceeds this value or was not measured.                                    |
+| `--budget-ttfb <ms>`         | Exit `1` if TTFB exceeds this value or was not measured.                                    |
+| `--budget-cls <score>`       | Exit `1` if CLS exceeds this value or was not measured.                                    |
+| `--budget-inp <ms>`          | Exit `1` if INP exceeds this value or was not measured.                                    |
 | `--verbose`                  | Show all items, including passing checks.                              |
 | `--headed`                   | Show the browser window (debug).                                       |
 | `-h, --help`                 | Show help.                                                             |
@@ -389,8 +394,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.
@@ -453,8 +458,11 @@ jobs:
 | ---------------- | ------------------- | -------------------------------------------------------------------------------------------- |
 | `url`            | required            | URL to measure.                                                                              |
 | `workflow`       | `core-web-vitals`   | Workflow to run: `core-web-vitals`, `loading`, `audit` or `interaction`.                                    |
-| `budget-lcp`     | `2500`              | LCP budget in ms. An empty value disables the check.                                         |
-| `budget-cls`     | `0.1`               | CLS budget. An empty value disables the check.                                               |
+| `budget-lcp`     | `auto`              | LCP budget in ms. `auto` is `2500` with `core-web-vitals` and no budget with the other workflows. An empty value disables the check. |
+| `budget-fcp`     |                     | FCP budget in ms, for `loading`.                                                              |
+| `budget-ttfb`    |                     | TTFB budget in ms, for `loading` or `audit`.                                                  |
+| `budget-cls`     | `auto`              | CLS budget. `auto` is `0.1` with `core-web-vitals` and no budget with the other workflows. An empty value disables the check. |
+| `budget-inp`     |                     | INP budget in ms, for `interaction` with a click or a key press.                             |
 | `fail-on-budget` | `true`              | Fail the step when a budget is exceeded or a snippet errors. Use `"false"` to read `exit-code` and decide yourself. |
 | `cli-version`    | `latest`            | Version of the `webperf-snippets` npm package to run.                                        |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webperf-snippets",
-  "version": "1.4.0",
+  "version": "1.6.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/snippets/CoreWebVitals/INP.js

@@ -349,10 +349,11 @@
       };
     }
     if (interactions.length === 0) {
+      // Nothing failed: someone has to use the page first, so it is still tracking
       return {
         script: "INP",
-        status: "error",
-        error: "No interactions recorded yet. Interact with the page and call getINP() again.",
+        status: "tracking",
+        message: "No interactions yet: click, tap or type on the page, then call getINP() again.",
         getDataFn: "getINP",
         details,
       };
@@ -378,8 +379,9 @@
       console.groupEnd();
       return {
         script: "INP",
-        status: "error",
-        error: "No interactions recorded yet. Interact with the page and call getINPDetails() again.",
+        status: "tracking",
+        message: "No interactions yet: click, tap or type on the page, then call getINPDetails() again.",
+        getDataFn: "getINPDetails",
         count: 0,
         items: [],
       };

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-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

@@ -132,10 +132,11 @@
       console.log(
         "   Interact with the page (click, type, etc.) and call this again."
       );
+      // Nothing failed: someone has to use the page first, so it is still tracking
       return {
         script: "Input-Latency-Breakdown",
-        status: "error",
-        error: "No interactions recorded yet. Interact with the page (click, type, etc.) and call getInputLatencyBreakdown() again.",
+        status: "tracking",
+        message: "No interactions yet: click, tap or type on the page, then call getInputLatencyBreakdown() again.",
         getDataFn: "getInputLatencyBreakdown",
       };
     }
@@ -259,8 +260,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

@@ -184,7 +184,14 @@
     if (allInteractions.length === 0) {
       console.log("%c📊 No interactions recorded yet.", "font-weight: bold;");
       console.log("   Interact with the page (click, type, etc.) and call this again.");
-      return { script: "Interactions", status: "error", error: "No interactions recorded yet", count: 0 };
+      // Nothing failed: someone has to use the page first, so it is still tracking
+      return {
+        script: "Interactions",
+        status: "tracking",
+        message: "No interactions yet: click, tap or type on the page, then call getInteractionSummary() again.",
+        getDataFn: "getInteractionSummary",
+        count: 0,
+      };
     }
 
     console.group("%c📊 Interaction Summary", "font-weight: bold; font-size: 14px;");
@@ -264,8 +271,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`,
     };
@@ -790,56 +800,58 @@
 
   console.groupEnd(); // Additional Insights
 
-  // Recommendations
+  // Recommendations: the console marks their priority; the result orders them by it, as plain text
+  const PRIORITY = ["🔴", "🟡", "ℹ️"];
   const recommendations = [];
+  const recommend = (icon, text) => recommendations.push({ icon, text });
 
   if (noCacheEntries.filter((e) => isStaticAsset(e.type)).length > 0) {
-    recommendations.push(
-      "🔴 Add Cache-Control headers to static assets (JS, CSS, fonts, images). Start with max-age=86400 and move to immutable for versioned files."
+    recommend("🔴",
+      "Add Cache-Control headers to static assets (JS, CSS, fonts, images). Start with max-age=86400 and move to immutable for versioned files."
     );
   }
   if (shortCacheEntries.filter((e) => e.hasHash).length > 0) {
-    recommendations.push(
-      "🟡 Versioned files (with content hash) should use long cache or Cache-Control: immutable; they can be cached indefinitely since the URL changes on update."
+    recommend("🟡",
+      "Versioned files (with content hash) should use long cache or Cache-Control: immutable; they can be cached indefinitely since the URL changes on update."
     );
   }
   if (allAntiPatterns.some((p) => p.id === "expires-without-cc")) {
-    recommendations.push(
-      "🟡 Replace Expires headers with Cache-Control: max-age. Expires is an outdated mechanism and less reliable."
+    recommend("🟡",
+      "Replace Expires headers with Cache-Control: max-age. Expires is an outdated mechanism and less reliable."
     );
   }
   if (cacheEfficiencyPercent !== null && cacheEfficiencyPercent < 50) {
-    recommendations.push(
-      `🔴 Cache efficiency is low (${cacheEfficiencyPercent}%, measured on the ${analyzableEntries.length} resources whose cache headers could be read). Review caching strategy for those static assets.`
+    recommend("🔴",
+      `Cache efficiency is low (${cacheEfficiencyPercent}%, measured on the ${analyzableEntries.length} resources whose cache headers could be read). Review caching strategy for those static assets.`
     );
   }
   if (cdnHitRate !== null && cdnHitRate < 70) {
-    recommendations.push(
-      `🟡 CDN hit rate is ${cdnHitRate}%. Check CDN cache rules and ensure static assets have appropriate TTLs.`
+    recommend("🟡",
+      `CDN hit rate is ${cdnHitRate}%. Check CDN cache rules and ensure static assets have appropriate TTLs.`
     );
   }
   if (protocolDistribution["http/1.1"] > 0) {
-    recommendations.push(
-      `🟡 ${protocolDistribution["http/1.1"]} resources still use HTTP/1.1. Consider upgrading to HTTP/2 for better multiplexing.`
+    recommend("🟡",
+      `${protocolDistribution["http/1.1"]} resources still use HTTP/1.1. Consider upgrading to HTTP/2 for better multiplexing.`
     );
   }
   if (uncompressedResources.length > 0) {
-    recommendations.push(
-      `🟡 ${uncompressedResources.length} text resources appear uncompressed. Enable Brotli or gzip compression on your server.`
+    recommend("🟡",
+      `${uncompressedResources.length} text resources appear uncompressed. Enable Brotli or gzip compression on your server.`
     );
   }
   if (costlyDuplicates.length > 0) {
-    recommendations.push(
-      `🟡 ${costlyDuplicates.length} resources are loaded multiple times with uncached network requests. Check for duplicate script, stylesheet, or fetch includes.`
+    recommend("🟡",
+      `${costlyDuplicates.length} resources are loaded multiple times with uncached network requests. Check for duplicate script, stylesheet, or fetch includes.`
     );
   } else if (cachedDuplicates.length > 0) {
-    recommendations.push(
-      `ℹ️ ${cachedDuplicates.length} resources are requested multiple times but served from cache; low performance impact, but worth reviewing for correctness.`
+    recommend("ℹ️",
+      `${cachedDuplicates.length} resources are requested multiple times but served from cache; low performance impact, but worth reviewing for correctness.`
     );
   }
   if (corsRestricted > 0 && headersAnalyzed === 0) {
-    recommendations.push(
-      `ℹ️ All resources are cross-origin CORS-restricted, so header analysis was limited. Add Timing-Allow-Origin for more insights.`
+    recommend("ℹ️",
+      `All resources are cross-origin CORS-restricted, so header analysis was limited. Add Timing-Allow-Origin for more insights.`
     );
   }
 
@@ -847,7 +859,7 @@
     console.log("");
     console.group("%c📌 Recommendations", "font-weight: bold;");
     for (const rec of recommendations) {
-      console.log(`   ${rec}`);
+      console.log(`   ${rec.icon} ${rec.text}`);
     }
     console.groupEnd();
   }
@@ -916,13 +928,15 @@
       })),
     issues: [
       ...allAntiPatterns.map((p) => ({
+        code: p.code,
         severity: p.severity,
         id: p.id,
         resource: p.resource,
         message: p.message,
+        target: p.url,
       })),
       ...(coverageIssue ? [coverageIssue] : []),
     ],
-    recommendations,
+    recommendations: [...recommendations].sort((a, b) => PRIORITY.indexOf(a.icon) - PRIORITY.indexOf(b.icon)).map((r) => r.text),
   };
 })();

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 })),
     ],
   };
 })();