webperf-snippets 1.0.0 → 1.2.0

package/README.md

@@ -35,44 +35,52 @@ npx webperf-snippets <url> [options]
 Run the default Core Web Vitals workflow (LCP + CLS, plus LCP-Subparts if LCP > 2.5s):
 
 ```bash
-npx webperf-snippets https://web.dev
+npx webperf-snippets https://example.com
 ```
 
 Loading audit (11 steps: TTFB, FCP, render-blocking, scripts, resource timings, third-party impact, fonts, cache; the list is in the [CLI page](https://webperf-snippets.net/CLI)):
 
 ```bash
-npx webperf-snippets https://web.dev --workflow loading
+npx webperf-snippets https://example.com --workflow loading
 ```
 
+The steps that tell first-party from third-party resources count as first party the root domain of the page and its subdomains (`cdn.example.com` for `example.com`). A site that serves its own assets from another domain, such as its CDN, lists it with `--own-domains`, comma-separated or repeated:
+
+```bash
+npx webperf-snippets https://example.com --workflow loading --own-domains cdn.example.net,static.example.org
+```
+
+Each domain counts with its root domain, so `cdn.example.net` makes every host under `example.net` first party. The CLI writes the list in the `OWN_DOMAINS` constant of each snippet, the same one you edit at the top of the snippet in the console. An empty domain or one with spaces exits with code `2`.
+
 Structural checks for CI (22 checks: render-blocking, compression, fonts, images, hints, DOM size and more; the list is in the [CLI page](https://webperf-snippets.net/CLI)):
 
 ```bash
-npx webperf-snippets https://web.dev --workflow audit
+npx webperf-snippets https://example.com --workflow audit
 ```
 
 Markdown output for PR comments:
 
 ```bash
-npx webperf-snippets https://web.dev --markdown
+npx webperf-snippets https://example.com --markdown
 ```
 
 JSON output (for piping into `jq` or CI):
 
 ```bash
-npx webperf-snippets https://web.dev --json
+npx webperf-snippets https://example.com --json
 ```
 
 Single snippet:
 
 ```bash
-npx webperf-snippets https://web.dev --snippet LCP-Subparts
+npx webperf-snippets https://example.com --snippet LCP-Subparts
 ```
 
 Synthetic INP measurement with an interaction script:
 
 ```bash
-npx webperf-snippets https://web.dev --snippet INP --interact-script interactions.json
-npx webperf-snippets https://web.dev --snippet Interaction/Interactions --interact-script interactions.json
+npx webperf-snippets https://example.com --snippet INP --interact-script interactions.json
+npx webperf-snippets https://example.com --snippet Interaction/Interactions --interact-script interactions.json
 ```
 
 The Interaction snippets (`Interactions`, `Input-Latency-Breakdown`, `LongTask`, `Forced-Synchronous-Layout`...) are installed before the first step and read after the last one, so their result holds what the steps caused.
@@ -82,7 +90,7 @@ The CLI waits for the browser to report the timing of the last interaction befor
 Interaction audit (long tasks, long animation frames, scroll, layout shifts, forced layouts, interaction latency). It scrolls the page, or runs your `--interact-script`; the steps that need a click are skipped when the script has none:
 
 ```bash
-npx webperf-snippets https://web.dev --workflow interaction
+npx webperf-snippets https://example.com --workflow interaction
 ```
 
 Pages behind a login, with a Playwright storage state (cookies and localStorage):
@@ -97,10 +105,20 @@ npx webperf-snippets https://example.com/dashboard --storage-state auth.json
 
 The file holds live session cookies. Keep it out of version control (add it to `.gitignore`) and use a throwaway account when you run it in CI. The CLI exits with code `2` if the path does not exist.
 
+Pages behind an access proxy that reads a token from every request, such as the service tokens of Cloudflare Access, take the token as request headers with `--header`, once per header:
+
+```bash
+npx webperf-snippets https://review.example.com \
+  --header "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
+  --header "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET"
+```
+
+The headers go with every request to the origin of the URL and never to another origin, so third parties do not receive the token and their cross-origin requests need no CORS preflight. Each request to that origin is paused in the browser to add them, which adds a few milliseconds to its timing; when the proxy accepts a session cookie, `--storage-state` measures without that cost. A header without a name or a colon exits with code `2`. Read the values from environment variables, as above, to keep them out of the shell history.
+
 Compare the measured values with CrUX field data (what real users experience at the 75th percentile):
 
 ```bash
-CRUX_API_KEY=your-key npx webperf-snippets https://web.dev
+CRUX_API_KEY=your-key npx webperf-snippets https://example.com
 ```
 
 ```
@@ -134,20 +152,36 @@ 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.0.0" }
+  "meta": { "viewport": "mobile", "waitMs": 3000, "cli_version": "1.2.0" }
 }
 ```
 
-For a `--snippet` run, `workflow` is `null` and a `snippet` field carries the name. `results` is the same list the `--json` output contains, so it can include URLs and details of the measured page; send it only to an endpoint you trust.
+For a `--snippet` run, `workflow` is `null` and a `snippet` field carries the name. With `--cpu` or `--network`, `meta` carries the conditions in `throttling`. `results` is the same list the `--json` output contains, so it can include URLs and details of the measured page; send it only to an endpoint you trust.
 
 - The URL must be `https`. `http` is accepted only for `localhost`, so a key is never sent in clear text.
 - `--api-key` is sent as `Authorization: Bearer <key>`. Prefer the `PERF_REVIEWS_API_KEY` environment variable, because a flag ends up in shell history and CI logs. The key is never printed.
 - The exit code never depends on the report. A failed POST (error status, unreachable endpoint, or no answer within 5 seconds) prints a warning and the exit code stays the one the budgets and snippets decide. If the endpoint answers `{ "ok": false, "regressions": [...] }`, the regressions are printed as a warning, again without changing the exit code.
 
+Measure under the conditions of a slower device and network with `--cpu` and `--network`. Without them the CLI runs at the speed of the machine, which on a laptop or a CI runner is faster than most phones:
+
+```bash
+npx webperf-snippets https://example.com --cpu 4 --network slow-4g
+```
+
+`--cpu <factor>` slows the main thread down by that factor. `--network` takes the presets of DevTools, with the same values:
+
+| Preset    | Download    | Upload      | Latency   |
+| --------- | ----------- | ----------- | --------- |
+| `fast-4g` | 8.1 Mbps    | 1.35 Mbps   | 165 ms    |
+| `slow-4g` | 1.44 Mbps   | 675 kbps    | 562.5 ms  |
+| `3g`      | 400 kbps    | 400 kbps    | 2000 ms   |
+
+Chrome adds the latency to the body of each response, not to its headers. The values read from `responseStart`, such as the TTFB and its sub-parts, do not include it; the download of each resource, FCP, LCP and the load event do. The report names the conditions under its header, and the JSON output carries them in `throttling`, such as `{ "cpu": 4, "network": "slow-4g" }`. A CPU factor below `1` or an unknown preset exits with code `2`.
+
 CI gating:
 
 ```bash
-npx webperf-snippets https://web.dev --budget-lcp 2500 --budget-cls 0.1
+npx webperf-snippets https://example.com --budget-lcp 2500 --budget-cls 0.1
 ```
 
 ### Options
@@ -160,8 +194,12 @@ npx webperf-snippets https://web.dev --budget-lcp 2500 --budget-cls 0.1
 | `--markdown`                 | Output GitHub-renderable markdown (for PR comments).                   |
 | `--viewport <preset>`        | Viewport preset: `mobile` (default), `tablet`, `desktop`.             |
 | `--wait <ms>`                | Post-load wait before evaluating snippets. Default: `3000`.            |
+| `--cpu <factor>`             | Slow the main thread down by this factor, such as `4`. No throttling by default. |
+| `--network <preset>`         | Throttle the network with a preset of DevTools: `fast-4g`, `slow-4g`, `3g`. No throttling by default. |
 | `--interact-script <path>`   | JSON file with interactions to run after the page loads (`scroll`, `click`, `hover`, `type`, `wait`). The Interaction snippets are installed first and read afterwards. |
 | `--storage-state <path>`     | Playwright storage state (cookies and localStorage) for pages that require authentication. |
+| `--header "Name: value"`     | Request header for the origin of the URL only, such as the token of an access proxy. Repeat it for more headers. |
+| `--own-domains <list>`       | Domains of the site to count as first party, such as its own CDN. Comma-separated or repeated. |
 | `--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`. |
@@ -204,6 +242,47 @@ The results of a run can add steps on the same page load: LCP over 2.5 s adds `L
 | `1`  | Budget violation, a snippet errored, or a step of the workflow reported an `error` issue. |
 | `2`  | Usage error (missing URL, unknown workflow).  |
 
+## MCP server
+
+`webperf-snippets mcp` starts a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio, so an AI agent can call the snippets by name instead of reading their source. Add it to a client that launches local servers, for example Claude Code:
+
+```bash
+claude mcp add webperf -- npx -y webperf-snippets mcp
+```
+
+It needs the Chromium of Playwright (`npx playwright install chromium`); without it, the tools answer with that command. The [MCP server documentation](https://webperf-snippets.net/MCP) has the configuration of other clients (Cursor, VS Code, Claude Desktop, Gemini CLI). The server is listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.nucliweb/webperf-snippets`.
+
+| Tool            | What it does                                                                 |
+| --------------- | ---------------------------------------------------------------------------- |
+| `list_snippets` | Lists the snippets with their category, title, short aliases and whether they track interactions. Takes an optional `category`. |
+| `run_snippet`   | Opens a URL in a headless Chromium, runs one snippet and returns the object it returns. Takes `url`, `snippet` (name, alias or `Category/Name`), and optional `viewport` and `waitMs`. The snippets that record interactions run on a page opened with `open_page`. |
+| `run_workflow`  | Runs a workflow of the CLI (`core-web-vitals`, `audit`, `loading`, `interaction`) and the follow-ups of its decision tree. Takes `url`, `workflow`, and optional `viewport` and `waitMs`. |
+| `get_crux`      | Returns the CrUX p75 of LCP, CLS and INP for a URL, or its origin. Takes `url` and an optional `formFactor` (`phone`, `desktop`, `tablet`). Needs `CRUX_API_KEY` in the environment of the server. |
+| `open_page`     | Opens a URL in a page that stays open between calls and installs tracking snippets (`track`, such as `INP`). Returns a `sessionId`. |
+| `interact`      | Runs steps on an open page: `click`, `type`, `hover`, `scroll` or `wait`. |
+| `read_results`  | Returns what the tracking snippets of an open page have recorded. |
+| `close_page`    | Closes an open page. |
+
+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://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.
+
+The CrUX key goes in the configuration of the client, never in a tool argument:
+
+```bash
+claude mcp add webperf -e CRUX_API_KEY=<key> -- npx -y webperf-snippets mcp
+```
+
+At most three pages are open at a time, a page closes after 10 minutes without use, and every page and Chromium close when the client disconnects.
+
+The server answers clients of both eras of the protocol: the 2026-07-28 revision and the earlier ones that open with `initialize`. [ADR 0002](../docs/adr/0002-mcp-server-as-cli-subcommand.md) explains why it is a subcommand and uses stdio.
+
 ## CI example
 
 GitHub Actions, fail the PR if LCP exceeds 2.5s:
@@ -212,7 +291,7 @@ GitHub Actions, fail the PR if LCP exceeds 2.5s:
 - run: |
     npm install --no-save webperf-snippets playwright
     npx playwright install --with-deps chromium
-    npx webperf-snippets https://staging.web.dev --budget-lcp 2500 --budget-cls 0.1
+    npx webperf-snippets https://staging.example.com --budget-lcp 2500 --budget-cls 0.1
 ```
 
 ### GitHub Action
@@ -308,9 +387,9 @@ The `NPM_TOKEN` secret must be set in the repository settings with publish acces
 ## How it works
 
 1. Launches headless chromium via Playwright.
-2. Pre-registers `PerformanceObserver`s for LCP and layout-shift before navigation (Chrome doesn't expose these via `getEntriesByType` without a buffered observer, so the runner shims it).
-3. Navigates, waits for the page to settle.
-4. Evaluates each snippet's IIFE in the page context, capturing the returned object.
+2. Navigates to the URL, waits for the `load` event and then for `--wait` milliseconds (3000 by default), so late entries reach the page.
+3. Evaluates each snippet's IIFE in the page context, capturing the returned object. The snippets read the entries Chrome only exposes to observers (LCP, layout shifts, long tasks, event timing) with a buffered `PerformanceObserver`, so they see the entries recorded before they ran.
+4. With an interaction script, installs the tracking snippets first, runs the interactions, lets the page settle and then reads the tracking data and runs the other snippets.
 5. Applies the workflow's decision tree to enqueue follow-up snippets.
 6. Renders results (human or JSON) and exits with an appropriate code.
 

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "webperf-snippets",
-  "version": "1.0.0",
+  "version": "1.2.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",
   "bin": "./src/bin.js",
@@ -15,8 +16,12 @@
     "test:unit": "vitest run tests/unit",
     "test:e2e": "vitest run tests/e2e"
   },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.3.1"
+  },
   "devDependencies": {
-    "vitest": "^4.1.11"
+    "@modelcontextprotocol/client": "^2.3.1",
+    "vitest": "^5.0.5"
   },
   "engines": {
     "node": ">=20.12.0"

package/snippets/CoreWebVitals/INP.js

@@ -6,7 +6,7 @@
     console.warn("⚠️ event entries are not supported in this browser.");
     return { script: "INP", status: "unsupported", error: "event entries not supported in this browser" };
   }
-  const interactions = [];
+  let interactions = [];
   let inpValue = 0;
   let inpEntry = null;
 
@@ -21,6 +21,104 @@
 
   const formatMs = (ms) => `${Math.round(ms)}ms`;
 
+  // @shared createInteractionTracker
+  // Groups Event Timing entries by interactionId across observer callbacks, since the entries of one
+  // interaction (pointerdown, pointerup, click; keydown, keyup) can arrive in separate batches. Each
+  // interaction is measured over its entries painted in the frame of its longest one: Chrome rounds
+  // durations to 8 ms, and an event painted in an earlier frame, such as the keydown of a key held
+  // down, has its own timing. It is reported under the event whose handler ran longest, or under the
+  // click or keydown when no handler took a millisecond more than theirs.
+  function createInteractionTracker() {
+    const byId = new Map();
+    const processing = (e) => e.processingEnd - e.processingStart;
+    const measure = (id, entries) => {
+      const longest = entries.reduce((a, b) => (b.duration > a.duration ? b : a));
+      const paint = longest.startTime + longest.duration;
+      const frame = entries.filter((e) => Math.abs(e.startTime + e.duration - paint) <= 8);
+      const startTime = Math.min(...frame.map((e) => e.startTime));
+      const processingStart = Math.min(...frame.map((e) => e.processingStart));
+      const processingEnd = Math.max(...frame.map((e) => e.processingEnd));
+      const busiest = frame.reduce((a, b) => (processing(b) > processing(a) ? b : a));
+      const primary = frame.find((e) => e.name === "click" || e.name === "keydown");
+      const reported = primary && processing(busiest) - processing(primary) < 1 ? primary : busiest;
+      return {
+        interactionId: id,
+        name: reported.name,
+        target: reported.target ?? frame.find((e) => e.target)?.target ?? null,
+        startTime,
+        duration: longest.duration,
+        phases: {
+          inputDelay: processingStart - startTime,
+          processingTime: processingEnd - processingStart,
+          presentationDelay: Math.max(0, startTime + longest.duration - processingEnd),
+        },
+      };
+    };
+    return {
+      // Adds the entries of one observer callback and returns the interactions they changed
+      add(entries) {
+        const changed = new Set();
+        for (const e of entries) {
+          if (!e.interactionId) continue;
+          const record = byId.get(e.interactionId) ?? { entries: [] };
+          record.entries.push({
+            name: e.name,
+            target: e.target,
+            startTime: e.startTime,
+            duration: e.duration,
+            processingStart: e.processingStart,
+            processingEnd: e.processingEnd,
+          });
+          byId.set(e.interactionId, record);
+          changed.add(e.interactionId);
+        }
+        return [...changed].map((id) => {
+          const record = byId.get(id);
+          record.summary = measure(id, record.entries);
+          return record.summary;
+        });
+      },
+      list() {
+        return [...byId.values()].map((record) => record.summary);
+      },
+    };
+  }
+  // @end-shared createInteractionTracker
+
+  // @shared uniqueSelector
+  // A CSS selector that matches only el in its document (or shadow root): its id when it is unique,
+  // otherwise a path of tag, classes and :nth-of-type() that goes up to the nearest ancestor with a
+  // unique id, or to the root, and stops as soon as it matches one element.
+  function uniqueSelector(el) {
+    const root = el.getRootNode();
+    const matchesOne = (selector) => {
+      try {
+        return root.querySelectorAll(selector).length === 1;
+      } catch {
+        return false;
+      }
+    };
+    const parts = [];
+    let node = el;
+    while (node && node.nodeType === 1) {
+      if (node.id && matchesOne(`#${window.CSS.escape(node.id)}`)) {
+        parts.unshift(`#${window.CSS.escape(node.id)}`);
+        break;
+      }
+      const tag = node.localName;
+      let part = tag + Array.from(node.classList).slice(0, 2).map((c) => `.${window.CSS.escape(c)}`).join("");
+      const siblings = node.parentNode ? Array.from(node.parentNode.children) : [node];
+      if (siblings.filter((s) => s.matches(part)).length > 1) {
+        part += `:nth-of-type(${siblings.filter((s) => s.localName === tag).indexOf(node) + 1})`;
+      }
+      parts.unshift(part);
+      if (matchesOne(parts.join(" > "))) break;
+      node = node.parentElement;
+    }
+    return parts.join(" > ");
+  }
+  // @end-shared uniqueSelector
+
   // Calculate INP (98th percentile of all interactions)
   const calculateINP = () => {
     if (interactions.length === 0) return { value: 0, entry: null };
@@ -54,64 +152,18 @@
     return `${entry.name} → ${selector}`;
   };
 
-  // Get phase breakdown from the Event Timing entry
-  const getPhaseBreakdown = (entry) => {
-    const phases = {
-      inputDelay: 0,
-      processingTime: 0,
-      presentationDelay: 0,
-    };
-
-    if (entry.processingStart && entry.processingEnd) {
-      phases.inputDelay = entry.processingStart - entry.startTime;
-      phases.processingTime = entry.processingEnd - entry.processingStart;
-      phases.presentationDelay = Math.max(
-        0,
-        entry.duration - phases.inputDelay - phases.processingTime
-      );
-    }
-
-    return phases;
+  // One record per interaction (interactionId), with its phases measured over all its entries
+  const tracker = createInteractionTracker();
+  const addEntries = (entries) => {
+    tracker.add(entries);
+    interactions = tracker.list().map((i) => ({ ...i, formattedName: getInteractionName(i) }));
+    const result = calculateINP();
+    inpValue = result.value;
+    inpEntry = result.entry;
   };
 
   // Observer for interactions
-  const observer = new PerformanceObserver((list) => {
-    for (const entry of list.getEntries()) {
-      // Only track interactions with interactionId (meaningful interactions)
-      if (!entry.interactionId) continue;
-
-      // Avoid duplicate entries for the same interaction
-      const existing = interactions.find(
-        (i) => i.interactionId === entry.interactionId
-      );
-
-      if (!existing || entry.duration > existing.duration) {
-        // Remove old entry if exists
-        if (existing) {
-          const idx = interactions.indexOf(existing);
-          interactions.splice(idx, 1);
-        }
-
-        interactions.push({
-          name: entry.name,
-          duration: entry.duration,
-          startTime: entry.startTime,
-          interactionId: entry.interactionId,
-          target: entry.target,
-          processingStart: entry.processingStart,
-          processingEnd: entry.processingEnd,
-          formattedName: getInteractionName(entry),
-          phases: getPhaseBreakdown(entry),
-          entry,
-        });
-      }
-
-      // Recalculate INP
-      const result = calculateINP();
-      inpValue = result.value;
-      inpEntry = result.entry;
-    }
-  });
+  const observer = new PerformanceObserver((list) => addEntries(list.getEntries()));
 
   // Observe event timing
   observer.observe({
@@ -324,7 +376,13 @@
     if (interactions.length === 0) {
       console.log("   No interactions recorded yet.");
       console.groupEnd();
-      return [];
+      return {
+        script: "INP",
+        status: "error",
+        error: "No interactions recorded yet. Interact with the page and call getINPDetails() again.",
+        count: 0,
+        items: [],
+      };
     }
 
     const sorted = [...interactions].sort((a, b) => b.duration - a.duration);
@@ -401,16 +459,30 @@
     }
 
     console.groupEnd();
-    return sorted;
+    // The 15 slowest, as plain data: the target is a selector, not the element
+    return {
+      script: "INP",
+      status: "ok",
+      count: sorted.length,
+      items: sorted.slice(0, maxToShow).map((i) => ({
+        formattedName: i.formattedName,
+        eventType: i.name,
+        target: i.target ? uniqueSelector(i.target) : null,
+        duration: Math.round(i.duration),
+        startTime: Math.round(i.startTime),
+        phases: {
+          inputDelay: Math.round(i.phases.inputDelay),
+          processingTime: Math.round(i.phases.processingTime),
+          presentationDelay: Math.round(i.phases.presentationDelay),
+        },
+      })),
+    };
   };
 
   // Log on page hide (final INP)
   document.addEventListener("visibilitychange", () => {
     if (document.visibilityState === "hidden") {
-      observer.takeRecords();
-      const result = calculateINP();
-      inpValue = result.value;
-      inpEntry = result.entry;
+      addEntries(observer.takeRecords());
 
       console.log("%c📊 Final INP (on page hide):", "font-weight: bold;");
       logINP();

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

@@ -18,6 +18,26 @@
 
   const LCP_THRESHOLD = 0.05; // Chrome's threshold for low-entropy
 
+  // Chrome divides the encoded size by the area the image is displayed at, in CSS pixels (not
+  // device pixels), and an upscaled image by its natural area instead, so stretching an image never
+  // lowers its bits per pixel. Chrome uses the part inside the viewport; this uses the whole box.
+  // https://w3c.github.io/largest-contentful-paint/ (steps 8.9 to 8.13) and Chromium's
+  // LargestContentfulPaintCalculator::ComputeEffectiveVisualSize
+  function displayedSize(img) {
+    const rect = img.getBoundingClientRect();
+    const style = getComputedStyle(img);
+    const px = (prop) => parseFloat(style[prop]) || 0;
+    return {
+      width: Math.max(0, rect.width - px("borderLeftWidth") - px("borderRightWidth") - px("paddingLeft") - px("paddingRight")),
+      height: Math.max(0, rect.height - px("borderTopWidth") - px("borderBottomWidth") - px("paddingTop") - px("paddingBottom")),
+    };
+  }
+  function bitsPerPixel(img, fileSize) {
+    const displayed = displayedSize(img);
+    const pixels = Math.min(displayed.width * displayed.height, img.naturalWidth * img.naturalHeight);
+    return { displayed, bpp: pixels > 0 ? (fileSize * 8) / pixels : 0 };
+  }
+
   // Get current LCP element
   let lcpElement = null;
   let lcpUrl = null;
@@ -47,8 +67,7 @@
         const src = img.currentSrc || img.src;
         const resource = performance.getEntriesByName(src)[0];
         const fileSize = resource?.encodedBodySize || 0;
-        const pixels = img.naturalWidth * img.naturalHeight;
-        const bpp = pixels > 0 ? (fileSize * 8) / pixels : 0;
+        const { displayed, bpp } = bitsPerPixel(img, fileSize);
 
         const isLowEntropy = bpp > 0 && bpp < LCP_THRESHOLD;
         const isLCP = lcpElement === img || lcpUrl === src;
@@ -59,6 +78,8 @@
           shortSrc: src.split("/").pop()?.split("?")[0] || src,
           width: img.naturalWidth,
           height: img.naturalHeight,
+          displayedWidth: Math.round(displayed.width),
+          displayedHeight: Math.round(displayed.height),
           fileSize,
           bpp,
           isLowEntropy,
@@ -105,6 +126,7 @@
       .map((img) => ({
         Image: img.shortSrc.length > 30 ? "..." + img.shortSrc.slice(-27) : img.shortSrc,
         Dimensions: `${img.width}×${img.height}`,
+        Displayed: `${img.displayedWidth}×${img.displayedHeight}`,
         Size: formatBytes(img.fileSize),
         BPP: img.bpp.toFixed(4),
         Entropy: img.isLowEntropy ? "🔴 Low" : "🟢 Normal",
@@ -166,14 +188,15 @@
       const src = img.currentSrc || img.src;
       const resource = performance.getEntriesByName(src)[0];
       const fileSize = resource?.encodedBodySize || 0;
-      const pixels = img.naturalWidth * img.naturalHeight;
-      const bpp = pixels > 0 ? (fileSize * 8) / pixels : 0;
+      const { displayed, bpp } = bitsPerPixel(img, fileSize);
       const isLowEntropy = bpp > 0 && bpp < LCP_THRESHOLD;
       const isLCP = lcpElementSync === img || lcpUrlSync === src;
       return {
         url: src.split("/").pop()?.split("?")[0] || src,
         width: img.naturalWidth,
         height: img.naturalHeight,
+        displayedWidth: Math.round(displayed.width),
+        displayedHeight: Math.round(displayed.height),
         fileSizeBytes: fileSize,
         bpp: Math.round(bpp * 10000) / 10000,
         isLowEntropy,

package/snippets/CoreWebVitals/LCP-Subparts.js

@@ -67,6 +67,15 @@
   }
   // @end-shared uniqueSelector
 
+  // The Resource Load Time splits into the wait for the server, until the first byte of the response,
+  // and the download of the body: a slow server and a heavy image need different fixes. Another
+  // origin without Timing-Allow-Origin reports responseStart as 0, and then there is no split.
+  const splitLoadTime = (resEntry, requestStart, responseEnd, activationStart) => {
+    if (!resEntry?.responseStart) return null;
+    const firstByte = Math.min(Math.max(requestStart, resEntry.responseStart - activationStart), responseEnd);
+    return { waiting: firstByte - requestStart, download: responseEnd - firstByte };
+  };
+
   const getNavigationEntry = () => {
     const navEntry = performance.getEntriesByType("navigation")[0];
     if (navEntry?.responseStart > 0 && navEntry.responseStart < performance.now()) {
@@ -108,6 +117,8 @@
       lcpEntry.startTime - activationStart
     );
 
+    const loadSplit = splitLoadTime(lcpResEntry, lcpRequestStart, lcpResponseEnd, activationStart);
+
     const subPartValues = {
       ttfb: ttfb,
       resourceLoadDelay: lcpRequestStart - ttfb,
@@ -196,6 +207,9 @@
     console.log("");
     console.log("%c💡 Optimization Focus:", "font-weight: bold; color: #3b82f6;");
     console.log(`   Slowest phase: ${slowest.name} (${formatPercent(slowest.value, lcpRenderTime)})`);
+    if (slowest.key === "resourceLoadTime" && loadSplit) {
+      console.log(`   ${formatMs(loadSplit.waiting)} waiting for the server, ${formatMs(loadSplit.download)} downloading the resource`);
+    }
 
     if (slowest.key === "ttfb") {
       console.log("   → Use a CDN to reduce latency");
@@ -205,6 +219,10 @@
       console.log("   → Preload the LCP image: <link rel=\"preload\" as=\"image\" href=\"...\">");
       console.log("   → Remove render-blocking resources");
       console.log("   → Inline critical CSS");
+    } else if (slowest.key === "resourceLoadTime" && loadSplit && loadSplit.waiting > loadSplit.download) {
+      console.log("   → Reduce the server response time of the LCP resource");
+      console.log("   → Serve it from a CDN, with Cache-Control headers");
+      console.log("   → Check that it is cached, not generated on each request");
     } else if (slowest.key === "resourceLoadTime") {
       console.log("   → Compress and resize the LCP image");
       console.log("   → Use modern formats (WebP, AVIF)");
@@ -233,7 +251,9 @@
 
     console.log("");
     console.log("%c📊 Measures added to Performance timeline", "color: #666;");
-    console.log("   Open DevTools → Performance → reload to see waterfall");
+    console.log(
+      '   Read them with performance.getEntriesByType("measure"), or run the snippet during a DevTools Performance recording to see them in the Timings track'
+    );
 
     console.groupEnd();
   });
@@ -275,6 +295,8 @@
   const loadDelayVal = Math.round(lcpRequestStartSync - ttfbSync);
   const loadTimeVal = Math.round(lcpResponseEndSync - lcpRequestStartSync);
   const renderDelayVal = Math.round(lcpRenderTimeSync - lcpResponseEndSync);
+  const loadSplitSync = splitLoadTime(lcpResEntrySync, lcpRequestStartSync, lcpResponseEndSync, activationStartSync);
+  const waitingVal = loadSplitSync ? Math.min(loadTimeVal, Math.round(loadSplitSync.waiting)) : null;
   const subPartsForRank = [
     { key: "ttfb", value: ttfbVal },
     { key: "resourceLoadDelay", value: loadDelayVal },
@@ -310,7 +332,12 @@
       subParts: {
         ttfb: { value: ttfbVal, percent: Math.round((ttfbVal / totalSync) * 100), overTarget: ttfbVal > 800 },
         resourceLoadDelay: { value: loadDelayVal, percent: Math.round((loadDelayVal / totalSync) * 100), overTarget: (loadDelayVal / totalSync) * 100 > 10 },
-        resourceLoadTime: { value: loadTimeVal, percent: Math.round((loadTimeVal / totalSync) * 100), overTarget: (loadTimeVal / totalSync) * 100 > 40 },
+        resourceLoadTime: {
+          value: loadTimeVal,
+          percent: Math.round((loadTimeVal / totalSync) * 100),
+          overTarget: (loadTimeVal / totalSync) * 100 > 40,
+          ...(loadSplitSync ? { waiting: waitingVal, download: loadTimeVal - waitingVal } : {}),
+        },
         elementRenderDelay: { value: renderDelayVal, percent: Math.round((renderDelayVal / totalSync) * 100), overTarget: (renderDelayVal / totalSync) * 100 > 10 },
       },
       slowestPhase: slowestPhaseSync,

package/snippets/CoreWebVitals/WORKFLOWS.md

@@ -34,7 +34,7 @@ When layout shifts are detected or the user asks "debug CLS" or "layout shift is
 
 When interactions feel slow or the user asks "debug INP" or "slow interactions":
 
-1. **INP.js** - Measure overall INP value; call `getINP()` after interactions, `getINPDetails()` for full list
+1. **INP.js** - Measure overall INP value; call `getINP()` after interactions, `getINPDetails()` for the 15 slowest interactions
 2. **Interactions.js** _(pending — available in webperf-interaction skill)_
 3. **Input-Latency-Breakdown.js** _(pending — available in webperf-interaction skill)_
 4. **Long-Animation-Frames.js** _(pending — available in webperf-interaction skill)_
@@ -134,7 +134,7 @@ Use this decision tree to automatically run follow-up snippets based on results:
   3. **webperf-interaction:Long-Animation-Frames.js** (blocking frames)
   4. **webperf-interaction:Long-Animation-Frames-Script-Attribution.js** (culprit scripts)
 - **If specific interaction type is slow (e.g., keyboard)** → Focus analysis on that interaction type
-- **After INP data is collected** → call `getINPDetails()` for the full sorted interaction list (useful for identifying patterns across multiple slow interactions)
+- **After INP data is collected** → call `getINPDetails()` for the 15 slowest interactions, slowest first (useful for identifying patterns across multiple slow interactions)
 
 ### Error Recovery