webperf-snippets 1.3.0 → 1.5.0

package/snippets/SCHEMA.md

@@ -53,8 +53,10 @@ Every script must return an object matching this shape:
 
   // Issues detected (for audit scripts)
   issues?: Array<{
+    code: string;      // What the issue is, kebab-case, stable across runs and versions (see Issue codes)
     severity: "error" | "warning" | "info";
     message: string;
+    target?: string;   // The URL, selector or name the issue is about, when there is one issue per thing
   }>;
 
   // Tracking scripts (status: "tracking")
@@ -505,8 +507,8 @@ When the rating is not good, `issues` holds one entry that names the TTFB and th
     }
   ],
   "issues": [
-    { "severity": "error", "message": "2 blocking scripts in <head>" },
-    { "severity": "error", "message": "1 third-party blocking script" }
+    { "code": "blocking-in-head", "severity": "error", "message": "2 blocking script(s) in <head>" },
+    { "code": "third-party-blocking", "severity": "error", "message": "1 third-party blocking script(s)" }
   ]
 }
 ```
@@ -1189,6 +1191,424 @@ Same shape as Image-Element-Audit but for video elements.
 
 ---
 
+## Issue codes
+
+Every issue has a `code` that says what it is, so a comparison pairs the issues of two runs without reading their text: the message carries figures, and its wording can change from a version to the next. The code is kebab-case and unique within its snippet, so `script` and `code` together name an issue across the collection. A code never changes once published, and is never reused for another situation. The same situation keeps its code when its severity depends on a threshold.
+
+An issue about one thing among several, one issue per thing, also names it in `target`: the URL of a resource, a CSS selector, or a name such as an event type or a CSS property. Two issues with the same code and different targets are two issues.
+
+### LCP-Image-Entropy
+
+| Code | Severity | When |
+|------|----------|------|
+| `low-entropy-images` | warning | Images under 0.05 bits per pixel, which Chrome does not take as the LCP |
+| `lcp-low-entropy` | error | The LCP image itself has low entropy |
+| `lcp-size-unknown` | info | The LCP `<img>` has no file size to read (a `data:` URL, or cross-origin without `Timing-Allow-Origin`) |
+| `lcp-not-img` | info | The LCP is the image of another element, such as a CSS background or a video poster |
+| `lcp-is-text` | info | The LCP element is text |
+
+### LCP-Video-Candidate
+
+| Code | Severity | When |
+|------|----------|------|
+| `lcp-not-video` | info | The LCP element is not a `<video>` |
+| `lcp-element-removed` | info | The LCP element is no longer in the DOM |
+| `late-candidate` | warning | The LCP candidate rendered more than 10 s after the load |
+| `first-frame-lcp` | info | The LCP is the first frame of the video, without a poster |
+| `first-frame-not-autoplay-muted` | warning | A first-frame LCP on a video without `autoplay` and `muted` |
+| `poster-not-preloaded` | warning | The poster has no `<link rel="preload" as="image">` |
+| `poster-preload-no-fetchpriority` | info | The preload of the poster has no `fetchpriority="high"` |
+| `poster-legacy-format` | info | The poster is not AVIF or WebP |
+| `render-time-hidden` | info | `renderTime` is 0: the video is cross-origin without `Timing-Allow-Origin` |
+| `preload-none-delays-poster` | warning | `preload="none"` on a video without `autoplay` |
+
+### Script-Loading
+
+| Code | Severity | When |
+|------|----------|------|
+| `blocking-in-head` | error | Classic scripts without `async`, `defer` or `type="module"` in `<head>` |
+| `third-party-blocking` | error | Blocking scripts from a third party |
+| `large-blocking` | warning | Blocking scripts larger than 50 KB |
+| `could-defer` | info | Blocking scripts other than the last three of `<body>`, which could try `defer` |
+| `unknown-size` | info | Scripts whose size is hidden by a missing `Timing-Allow-Origin`, so the total is a lower bound |
+
+### CSS-Media-Queries-Analysis
+
+| Code | Severity | When |
+|------|----------|------|
+| `no-wide-rules` | info | No `@media` rules for viewports wider than the breakpoint (768 px by default) |
+| `wide-rules` | info or warning | `@media` rules for wider viewports that narrower screens download without using, a warning above 50 KB |
+| `repeated-queries` | info | Few distinct queries repeated across many `@media` blocks |
+| `unreadable-stylesheets` | info | Cross-origin stylesheets whose rules cannot be read |
+
+### Content-Visibility
+
+| Code | Severity | When |
+|------|----------|------|
+| `missing-intrinsic-size` | warning | An element with `content-visibility: auto` and no `contain-intrinsic-size`; `target` is its selector |
+| `not-used` | info | No `content-visibility` on the page |
+
+### Critical-CSS-Detection
+
+| Code | Severity | When |
+|------|----------|------|
+| `no-inline-critical-css` | error | Render-blocking stylesheets and no inline critical CSS |
+| `render-blocking-over-budget` | error | Render-blocking CSS above the 14 KB critical budget |
+| `large-not-preloaded` | warning | Render-blocking stylesheets above 10 KB without preload |
+| `inline-over-budget` | error | Inline CSS above the 14 KB critical budget |
+| `styles-in-body` | warning | Inline style blocks in `<body>` |
+
+### Find-Above-The-Fold-Lazy-Loaded-Images
+
+| Code | Severity | When |
+|------|----------|------|
+| `lcp-lazy` | error | The LCP candidate image has `loading="lazy"` |
+| `lazy-above-fold` | warning | Other images above the fold with `loading="lazy"` |
+
+### Find-Images-With-Lazy-and-Fetchpriority
+
+| Code | Severity | When |
+|------|----------|------|
+| `lazy-and-high-priority` | error | Elements with both `loading="lazy"` and `fetchpriority="high"` |
+
+### Find-non-Lazy-Loaded-Images-outside-of-the-viewport
+
+| Code | Severity | When |
+|------|----------|------|
+| `eager-off-viewport` | warning | Images outside the viewport without `loading="lazy"` |
+
+### Find-render-blocking-resources
+
+| Code | Severity | When |
+|------|----------|------|
+| `render-blocking` | error | Resources that block rendering |
+
+### Fonts-Preloaded-Loaded-and-used-above-the-fold
+
+Each issue names its font in `target`.
+
+| Code | Severity | When |
+|------|----------|------|
+| `preloaded-unused` | warning | A preloaded font that the content above the fold does not use |
+| `used-not-preloaded` | warning | A font used above the fold without preload |
+| `preload-no-crossorigin` | error | A font preload without `crossorigin`, which fetches the font twice |
+
+### Inline-CSS-Info-and-Size
+
+| Code | Severity | When |
+|------|----------|------|
+| `over-budget` | warning | Inline CSS above the 14 KB critical budget |
+| `duplicate-blocks` | warning | Style blocks with identical content |
+| `large-blocks` | warning | Style blocks above 5 KB |
+| `styles-in-body` | warning | Style blocks in `<body>` |
+
+### Webfont-Usage-Analyzer
+
+`load-failed`, `loaded-unused` and `redeclared` name the font file by its URL in `target`, or the face when it has none.
+
+| Code | Severity | When |
+|------|----------|------|
+| `load-failed` | error | A font that failed to load |
+| `loaded-unused` | warning | A loaded font that no rendered element uses |
+| `redeclared` | warning | A loaded font declared again later with the same descriptors, so the page uses the other file |
+| `blocking-font-display` | warning | Faces with `font-display` `auto` or `block`, which can keep text invisible |
+| `heavy-fonts` | warning | Web fonts above 300 KB in total |
+| `never-loaded` | info | Faces declared and never loaded |
+| `shadowed` | info | Faces declared more than once, whose earlier declarations never loaded |
+| `unused-subsets` | info | `unicode-range` subsets the page did not need |
+| `size-unknown` | info | Cross-origin font files without `Timing-Allow-Origin`, so the byte totals are a lower bound |
+| `unreadable-stylesheets` | info | Cross-origin stylesheets whose font files cannot be matched to faces |
+| `elements-capped` | info | Only the first 20,000 elements were scanned for text |
+
+### First-And-Third-Party-Script-Info
+
+| Code | Severity | When |
+|------|----------|------|
+| `unknown-size` | info | Scripts whose size is hidden by a missing `Timing-Allow-Origin`, so the totals are a lower bound |
+| `render-blocking-unsupported` | info | The browser has no `renderBlockingStatus` (only Chromium has it) |
+| `third-party-blocking` | error | Third-party scripts that block rendering |
+| `many-third-party-hosts` | warning | Scripts from more than 3 third-party hosts |
+| `large-third-party` | warning | Third-party scripts above 100 KB in total |
+
+### First-And-Third-Party-Script-Timings
+
+| Code | Severity | When |
+|------|----------|------|
+| `slow-scripts` | warning | Scripts that take more than 500 ms to load |
+| `slow-dns` | warning | A DNS lookup above 100 ms |
+| `slow-connection` | warning | A TCP connection above 100 ms |
+| `slow-server` | warning | A server response above 200 ms |
+
+### Inline-Script-Info-and-Size
+
+| Code | Severity | When |
+|------|----------|------|
+| `parser-blocking-in-head` | error | Inline scripts in `<head>` that block the parser |
+| `large-inline` | warning | Inline scripts above 2 KB |
+| `duplicate-scripts` | warning | Inline scripts with identical content |
+| `analytics-in-head` | warning | Analytics scripts that block in `<head>` |
+
+### JS-Execution-Time-Breakdown
+
+| Code | Severity | When |
+|------|----------|------|
+| `render-blocking` | error | Scripts that block HTML parsing |
+| `high-parse-cost` | warning | An estimated parse cost above 500 ms on mobile |
+| `split-candidates` | warning | Scripts above 50 KB decoded, candidates for code splitting |
+| `low-compression` | warning | A compression ratio below 2x on more than 10 KB of scripts |
+
+### SSR-Hydration-Data-Analysis
+
+| Code | Severity | When |
+|------|----------|------|
+| `large-hydration-data` | warning | The hydration data of a framework above its threshold; `target` is the framework |
+| `large-arrays` | warning | `pageProps` arrays with more than 50 entries |
+| `deep-nesting` | warning | `pageProps` nested more than 5 levels |
+| `sensitive-keys` | warning | `pageProps` keys that look sensitive |
+
+### Third-Party-Impact-by-Domain
+
+| Code | Severity | When |
+|------|----------|------|
+| `render-blocking-domains` | warning | Third-party domains that serve render-blocking resources |
+| `heavy-domain` | warning | A domain whose scripts take more than 250 ms in long animation frames; `target` is the domain |
+| `render-blocking-unsupported` | info | The browser has no `renderBlockingStatus` (only Chromium has it) |
+| `loaf-unattributed` | info | Long animation frames with no third-party script attributed |
+| `unknown-size` | info | Third-party requests without `Timing-Allow-Origin`, so the transfer size is a lower bound |
+
+### Validate-Preload-Async-Defer-Scripts
+
+Each issue names the preloaded script in `target`.
+
+| Code | Severity | When |
+|------|----------|------|
+| `orphan-preload` | warning | A preloaded script that the page neither has nor loaded |
+| `async-defer-preload` | error | A script with `async` or `defer` that is also preloaded, which raises its priority |
+| `module-preload` | warning | An ES module preloaded with `rel="preload"` instead of `rel="modulepreload"` |
+
+### Back-Forward-Cache
+
+| Code | Severity | When |
+|------|----------|------|
+| `not-restored` | error | A reason the browser gave for not restoring the page from bfcache, after a back or forward navigation; `target` is the reason and its frame |
+| `unload-handler` | error | A `window.onunload` handler |
+| `cache-control-no-store` | warning | `Cache-Control: no-store` on the page response |
+| `iframes` | info | Iframes on the page, whose blockers block the whole page |
+| `service-worker` | info | A Service Worker controls the page, which bfcache allows |
+
+### Cache-Strategy-Analysis
+
+Each issue names its resource in `target`, except `header-coverage`. `id` repeats the code, as before the codes.
+
+| Code | Severity | When |
+|------|----------|------|
+| `static-no-store` | error | A static asset with `no-store` |
+| `versioned-short-cache` | warning | A URL with a hash and a short `max-age` |
+| `versioned-not-immutable` | info | A URL with a hash and no `immutable` |
+| `large-no-cache` | error | A large resource with no effective cache |
+| `expires-without-cc` | warning | An `Expires` header without `Cache-Control` |
+| `maxage-zero-static` | warning | A static asset with `max-age=0` |
+| `short-cache-static` | warning | A static asset with a `max-age` under an hour |
+| `uncompressed` | warning | A text resource sent uncompressed |
+| `duplicate-uncached` | warning | A resource loaded several times from the network |
+| `header-coverage` | info | The share of resources whose cache headers could be read |
+
+### Client-Side-Redirect-Detection
+
+| Code | Severity | When |
+|------|----------|------|
+| `server-redirects` | warning | Server-side redirects before the document |
+| `document-navigation` | error | Same-origin document navigations, likely a client-side redirect |
+| `same-origin-navigation` | warning | A same-origin referrer with another path |
+| `fast-minimal-navigation` | warning | A small same-origin page that loads fast, possibly a redirect page |
+
+### Compression-Audit
+
+| Code | Severity | When |
+|------|----------|------|
+| `uncompressed` | warning | Text resources served without compression |
+| `unknown-size` | info | Cross-origin text resources without `Timing-Allow-Origin`, whose compression is unknown |
+| `content-encoding-unavailable` | info | No `contentEncoding` in Resource Timing, so compression is inferred from the sizes |
+
+### Prefetch-Resource-Validation
+
+Each issue about one prefetch names its URL in `target`.
+
+| Code | Severity | When |
+|------|----------|------|
+| `no-prefetch` | info | No `rel="prefetch"` hints on the page |
+| `missing-as` | warning | A prefetch without `as` |
+| `invalid-as` | warning | A prefetch with an `as` value that does not exist |
+| `duplicate-prefetch` | warning | A URL prefetched more than once |
+| `used-on-current-page` | error | A prefetched resource that the current page uses, which needs `preload` |
+| `large-file` | warning | A prefetched file above 500 KB |
+| `inappropriate-type` | warning | A prefetched type that may not suit prefetch |
+| `too-many-prefetches` | warning | More than 10 prefetch hints |
+| `large-total-size` | warning or error | Prefetches above 2 MB in total, an error above 5 MB |
+
+### Priority-Hints-Audit
+
+Each issue names its resource in `target`.
+
+| Code | Severity | When |
+|------|----------|------|
+| `preload-low-priority` | error | A preload with `fetchpriority="low"` |
+| `low-priority-loaded-early` | warning | A `fetchpriority="low"` resource that still loaded early |
+| `high-priority-loaded-late` | warning | A `fetchpriority="high"` resource that still loaded late |
+| `lcp-no-fetchpriority` | warning | The LCP candidate image without `fetchpriority="high"` |
+
+### Resource-Hints
+
+Each issue about one hint names its URL in `target`.
+
+| Code | Severity | When |
+|------|----------|------|
+| `preload-missing-as` | error | A preload without `as` |
+| `font-preload-no-crossorigin` | error | A font preload without `crossorigin`, which fetches the font twice |
+| `preconnect-no-crossorigin` | warning | A preconnect without `crossorigin` to an origin that serves CORS resources |
+| `unused-preload` | warning | A preload that the page did not use during the load |
+| `unused-preconnect` | warning | A preconnect to an origin the page loaded nothing from |
+| `too-many-preloads` | warning | More than 6 preloads |
+
+### Resource-Hints-Validation
+
+| Code | Severity | When |
+|------|----------|------|
+| `unused-hints` | warning | Hints the page did not use |
+| `missing-connection-hints` | info | Domains that could use a connection hint |
+| `redundant-hints` | warning | Domains with both `preconnect` and `dns-prefetch` |
+
+### Server-Timing-Early-Hints
+
+| Code | Severity | When |
+|------|----------|------|
+| `no-server-timing` | info | The document response has no `Server-Timing` header |
+| `timing-hidden` | info | Cross-origin resources without `Timing-Allow-Origin`, whose Server-Timing cannot be read |
+| `no-early-hints` | info | No 103 Early Hints response for the document |
+
+### Service-Worker-Analysis
+
+| Code | Severity | When |
+|------|----------|------|
+| `unsupported` | error | The browser has no Service Workers |
+| `no-service-worker` | info | No Service Worker registered |
+| `not-controlled` | warning | The page is not controlled by its Service Worker, after a hard reload or on a first visit |
+| `update-pending` | warning | A waiting update; `target` is the scope |
+| `navigation-preload-disabled` | info | Navigation Preload is off; `target` is the scope |
+| `slow-startup` | warning or error | A Service Worker startup above 50 ms, an error above 100 ms |
+| `low-cache-hit-rate` | warning or error | A cache hit rate under 80%, an error under 50% |
+| `unknown-source` | info | Intercepted cross-origin resources without `Timing-Allow-Origin`, left out of the hit rate |
+
+### Speculation-Rules-Inspector
+
+| Code | Severity | When |
+|------|----------|------|
+| `invalid-json` | error | A speculation rules script that is not valid JSON |
+| `eager-list-capped` | warning | An eager prerender list with more than 10 URLs, above what Chrome prerenders |
+| `eager-document-rule` | warning | A document prerender rule with eager eagerness |
+| `no-rules` | info | No speculation rules in the DOM |
+| `no-prefetch-or-prerender` | info | Speculation rules scripts without prefetch or prerender rules |
+| `unsupported` | info | The browser does not support speculation rules |
+| `prerendered` | info | The page was prerendered, so its timings start at `activationStart` |
+
+### TTFB-Resources
+
+| Code | Severity | When |
+|------|----------|------|
+| `no-resources` | info | No resources with TTFB data |
+
+### TTFB-Sub-Parts
+
+| Code | Severity | When |
+|------|----------|------|
+| `slow-ttfb` | warning or error | A TTFB that is not good, an error when poor, naming its slowest phase |
+
+### DOM-Size-and-Depth
+
+| Code | Severity | When |
+|------|----------|------|
+| `too-many-nodes` | warning or error | More than 800 nodes, an error above 1,400 |
+| `too-deep` | warning | A DOM deeper than 32 levels |
+| `too-many-children` | warning | An element with more than 60 children |
+
+### Forced-Synchronous-Layout
+
+| Code | Severity | When |
+|------|----------|------|
+| `forced-layout` | warning or error | A layout property read after a write forced a layout, an error above 5 times; `target` is the property |
+
+### Input-Latency-Breakdown
+
+| Code | Severity | When |
+|------|----------|------|
+| `slow-event-type` | warning or error | An event type whose P75 is not good, an error when poor; `target` is the event type |
+
+### Interactions
+
+| Code | Severity | When |
+|------|----------|------|
+| `slow-interaction` | warning or error | An interaction above 200 ms, an error above 500 ms; `target` is its type |
+
+### Scroll-Performance
+
+| Code | Severity | When |
+|------|----------|------|
+| `non-passive-listeners` | warning | Scroll or touch listeners without `{ passive: true }` |
+| `will-change` | info | Elements with `will-change` set |
+
+### Image-Element-Audit
+
+Each issue names its image in `target`, except `lcp-not-img`.
+
+| Code | Severity | When |
+|------|----------|------|
+| `lcp-not-img` | info | The LCP element is not an `<img>` |
+| `lcp-no-fetchpriority` | error | The LCP image has no `fetchpriority="high"` |
+| `lcp-lazy` | error | The LCP image has `loading="lazy"` |
+| `lcp-not-decoding-sync` | warning | The LCP image has no `decoding="sync"` |
+| `lcp-not-preloaded` | warning | The LCP image has no `<link rel="preload" as="image">` |
+| `lcp-preload-no-fetchpriority` | info | The preload of the LCP image has no `fetchpriority="high"` |
+| `lazy-in-viewport` | warning | An image in the viewport with `loading="lazy"` |
+| `eager-off-viewport` | warning | An image outside the viewport without `loading="lazy"` |
+| `high-priority-off-viewport` | error | An image outside the viewport with `fetchpriority="high"` |
+| `lazy-and-high-priority` | error | An image with both `loading="lazy"` and `fetchpriority="high"` |
+| `missing-dimensions` | warning | An image without `width` and `height` |
+| `no-modern-format` | info | An image that is not WebP, AVIF, JPEG XL or SVG, outside a `<picture>` |
+
+### Oversized-Images
+
+Each issue names its image in `target`.
+
+| Code | Severity | When |
+|------|----------|------|
+| `oversized` | info or warning | A file larger than its slot needs, a warning when it is far larger |
+| `undersized` | info or warning | A file smaller than its slot needs, so it looks blurry, a warning when it is far smaller |
+
+### SVG-Embedded-Bitmap-Analysis
+
+| Code | Severity | When |
+|------|----------|------|
+| `embedded-bitmaps` | warning | SVG files that contain bitmaps |
+| `sprite-opportunity` | info | Standalone inline SVGs that could share one `<symbol>` sprite |
+
+### Video-Element-Audit
+
+Each issue names its video in `target`, except `no-videos`.
+
+| Code | Severity | When |
+|------|----------|------|
+| `no-videos` | info | No `<video>` elements on the page |
+| `preload-auto` | error | `preload="auto"` on a video without `autoplay` |
+| `off-viewport-preload` | warning | A video outside the viewport without `preload="none"` |
+| `autoplay-not-muted` | error | `autoplay` without `muted` |
+| `autoplay-no-playsinline` | warning | `autoplay` without `playsinline` |
+| `missing-poster` | warning | A video without a poster |
+| `missing-dimensions` | warning | A video without `width` and `height` |
+| `no-modern-codec` | info | No WebM source (VP9 or AV1) |
+| `no-controls` | info | A video without `controls` and without `autoplay` |
+
+---
+
 ## Guidelines for Agents
 
 ### Reading results
@@ -1223,6 +1643,7 @@ data = evaluate_script("getINP()")
 - `rating === "poor"` → high priority fix, check `issues` for specific problems
 - `count > 0` and `issues.length > 0` → audit found actionable problems
 - `count === 0` → nothing to audit (no render-blocking resources, no images, etc.)
+- To tell whether an issue is new, fixed or the same as in an earlier run, compare `script`, `code` and `target`, not `message`
 
 ---
 
@@ -1240,5 +1661,6 @@ data = evaluate_script("getINP()")
 10. **Valid statuses only** — `ok`, `tracking`, `error` or `unsupported`, with an `error` message when the status is `error` or `unsupported`.
 11. **Hidden cross-origin data is reported, not guessed** — a resource whose timing or size is hidden (no `Timing-Allow-Origin`) reports zeros for every size and timing. Count it (`sizeKnown: false`, `corsRestrictedCount`) instead of treating the zero as a measurement.
 12. **Partial analysis is flagged** — when hidden cross-origin data leaves part of the set unanalyzed, set the top-level `corsLimitedAnalysis: true` and report how many resources were skipped in `details` (`sizeUnknownCount`, `corsRestrictedCount`). Set it to `false` when every resource was analyzed.
+13. **Issues carry a stable code**: every issue has a kebab-case `code`, written as a literal in the source (`code: "blocking-in-head"`) and listed under Issue codes, and a `target` string when it is about one resource.
 
-The rules are checked by `cli/tests/e2e/snippet-contract.test.js`, which runs every script, its `getDataFn` and every other getter it exposes on `window` (such as `getINPDetails()` and `checkBfcache()`), on an empty page, a seeded page and a heavy page.
+The rules are checked by `cli/tests/e2e/snippet-contract.test.js`, which runs every script, its `getDataFn` and every other getter it exposes on `window` (such as `getINPDetails()` and `checkBfcache()`), on an empty page, a seeded page and a heavy page. `cli/tests/unit/issue-codes.test.js` checks that the codes in the source of each snippet match its table under Issue codes.