webperf-snippets 1.5.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.5.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.5.0" }
+  "meta": { "viewport": "mobile", "waitMs": 3000, "cli_version": "1.6.0" }
 }
 ```
 
@@ -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.                                                             |
@@ -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.5.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/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",
       };
     }

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;");

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

@@ -800,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.`
     );
   }
 
@@ -857,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();
   }
@@ -935,6 +937,6 @@
       })),
       ...(coverageIssue ? [coverageIssue] : []),
     ],
-    recommendations,
+    recommendations: [...recommendations].sort((a, b) => PRIORITY.indexOf(a.icon) - PRIORITY.indexOf(b.icon)).map((r) => r.text),
   };
 })();

package/snippets/Loading/Critical-CSS-Detection.js

@@ -24,9 +24,10 @@
   const criticalBudget = 14 * 1024; // 14 KB (first TCP round-trip)
 
   // --- External stylesheets ---
+  // A link without href or disabled loads nothing and blocks nothing, so it is not a stylesheet of the page
   const linkStylesheets = Array.from(
     document.querySelectorAll('link[rel="stylesheet"]')
-  );
+  ).filter((link) => link.href && !link.disabled);
 
   const perfEntries = performance.getEntriesByType("resource").filter((e) => !isOwnRequest(e));
 

package/snippets/SCHEMA.md

@@ -59,6 +59,9 @@ Every script must return an object matching this shape:
     target?: string;   // The URL, selector or name the issue is about, when there is one issue per thing
   }>;
 
+  // Next steps in plain text, most important first, without emoji (Cache-Strategy-Analysis)
+  recommendations?: string[];
+
   // Tracking scripts (status: "tracking")
   message?: string;      // Human-readable status message
   getDataFn?: string;    // window function to call for data: evaluate_script(`${getDataFn}()`). May be a dotted path such as "loafHelpers.getData"
@@ -170,7 +173,7 @@ return {
 **The window function must also return a structured object** matching the same schema, including when nothing has been recorded yet:
 
 - `status: "ok"` with `count: 0` when zero is a valid result (no long tasks, no long animation frames).
-- `status: "error"` with an `error` message when there is nothing to report yet and the agent needs to act first (no interactions recorded).
+- `status: "tracking"` with a `message` and its `getDataFn` when there is nothing to report yet and someone has to act first (no interactions recorded): nothing failed, the snippet is still recording. `status: "error"` is for a snippet that failed.
 
 **Scripts using this pattern:** INP, Interactions, Input-Latency-Breakdown, Layout-Shift-Loading-and-Interaction, Scroll-Performance, Long-Animation-Frames (ongoing tracking), LongTask (ongoing tracking), Long-Animation-Frames-Script-Attribution.
 
@@ -262,11 +265,11 @@ Returns buffered CLS immediately and keeps tracking. Always call `getCLS()` afte
 }
 ```
 
-If no interactions yet, `getINP()` returns `status: "error"` with `getDataFn: "getINP"` — retry after user interaction.
+If no interactions yet, `getINP()` returns `status: "tracking"` with a `message` and `getDataFn: "getINP"`: interact with the page and call it again.
 
 The phases describe the whole interaction, not one of its events. A tap fires `pointerdown`, `pointerup` and `click`, and a key press `keydown` and `keyup`, with one `interactionId`. INP, Interactions and Input-Latency-Breakdown group the entries by `interactionId`, also when they arrive in separate observer callbacks, and measure the interaction over its entries painted in the frame of the longest one: `inputDelay` runs from the first `startTime` to the first `processingStart`, `processingTime` to the last `processingEnd`, and `presentationDelay` from there to the paint (`startTime + duration`, never below zero). The interaction is reported under the event whose handler ran longest, or under the `click` or `keydown` when no handler took a millisecond more than theirs; `worstEvent`, the Interactions `type` and the Input-Latency-Breakdown event type follow that rule.
 
-`getINPDetails()` returns the 15 slowest interactions, slowest first, with the total in `count`. `target` is a CSS selector built like `details.element` of LCP, or `null` when the browser reports no target. Use it when `getINP()` shows poor INP and you need to identify patterns across multiple slow interactions. With no interactions yet it returns `status: "error"`, `count: 0` and no items.
+`getINPDetails()` returns the 15 slowest interactions, slowest first, with the total in `count`. `target` is a CSS selector built like `details.element` of LCP, or `null` when the browser reports no target. Use it when `getINP()` shows poor INP and you need to identify patterns across multiple slow interactions. With no interactions yet it returns `status: "tracking"`, a `message`, `count: 0` and no items.
 
 ```json
 {
@@ -1398,7 +1401,7 @@ Each issue names the preloaded script in `target`.
 
 ### Cache-Strategy-Analysis
 
-Each issue names its resource in `target`, except `header-coverage`. `id` repeats the code, as before the codes.
+Each issue names its resource in `target`, except `header-coverage`. `id` repeats the code, as before the codes. `recommendations` lists the next steps in plain text, the most important first; the console marks their priority with 🔴, 🟡 and ℹ️.
 
 | Code | Severity | When |
 |------|----------|------|

package/snippets/_view/fields.js

@@ -0,0 +1,37 @@
+// How each field of a result is shown, the same in every language: its format, its place among the
+// others (a lower order comes first; a field without one keeps its place after them) and whether it is
+// hidden. The entries of a snippet win over the general ones under "*". A field without an entry takes
+// its format from the suffix of its key (format.js). The words are in locales/.
+
+export default {
+  '*': {
+    // A CSS selector of an element of the page, which a consumer can make inspectable
+    selector: { format: 'selector' },
+    element: { format: 'selector' },
+    lcpElement: { format: 'selector' },
+    finalElement: { format: 'selector' },
+    // The name of a phase, read as its label
+    slowestPhase: { format: 'key' },
+    // The issues of a row: the issues section of the result lists them already
+    issues: { hidden: true },
+  },
+  'Find-Above-The-Fold-Lazy-Loaded-Images': {
+    // Its top and left in px: the distance from the edge of the viewport says what matters
+    position: { hidden: true },
+  },
+  'Input-Latency-Breakdown': {
+    // The same as its rows, one per event type
+    eventTypes: { hidden: true },
+  },
+  INP: {
+    phases: { format: 'phases' },
+  },
+  'Find-render-blocking-resources': {
+    shortName: { order: 1 },
+    type: { order: 2 },
+    responseEndMs: { order: 3 },
+    durationMs: { order: 4 },
+    sizeBytes: { order: 5 },
+    url: { order: 6 },
+  },
+}

package/snippets/_view/format.js

@@ -0,0 +1,39 @@
+// The formats of the values of a result, with the numbers written as the locale writes them. A field
+// without a format in fields.js takes it from the suffix of its key.
+
+const KB = 1024
+const MB = 1024 * 1024
+
+const number = (value, locale, digits = 0, minimum = 0) =>
+  new Intl.NumberFormat(locale, { maximumFractionDigits: digits, minimumFractionDigits: minimum }).format(value)
+
+const FORMATS = {
+  ms: (value, locale) => `${number(Math.round(value), locale)} ms`,
+  bytes: (value, locale) =>
+    value >= MB ? `${number(value / MB, locale, 1, 1)} MB` : value >= KB ? `${number(value / KB, locale, 1, 1)} KB` : `${number(value, locale)} B`,
+  percent: (value, locale) => new Intl.NumberFormat(locale, { style: 'unit', unit: 'percent', maximumFractionDigits: 1 }).format(value),
+  count: (value, locale) => number(value, locale),
+  score: (value, locale) => number(value, locale, 3, 3),
+  bpp: (value, locale) => `${number(value, locale, 3, 3)} bpp`,
+  fps: (value, locale) => `${number(Math.round(value), locale)} fps`,
+  px: (value, locale) => `${number(Math.round(value), locale)} px`,
+}
+
+// The suffixes that name a unit, and the format each one gives
+export const SUFFIXES = [
+  ['Ms', 'ms'],
+  ['Bytes', 'bytes'],
+  ['Percent', 'percent'],
+  ['Count', 'count'],
+  ['Px', 'px'],
+]
+
+export const formatOfKey = (key) => SUFFIXES.find(([suffix]) => key.endsWith(suffix) && key !== suffix)?.[1]
+
+// Text as it is, a number in its format, and an object or a list as compact JSON
+export function formatValue(value, format, locale = 'en') {
+  if (value === undefined || value === null) return ''
+  if (typeof value === 'number') return (FORMATS[format] ?? ((v, l) => number(v, l, 3)))(value, locale)
+  if (typeof value === 'object') return JSON.stringify(value)
+  return String(value)
+}