webperf-snippets 0.1.0 → 0.3.0

package/README.md

@@ -2,11 +2,14 @@
 
 Run curated [WebPerf Snippets](https://webperf-snippets.nucliweb.net) headlessly via Playwright. Diagnose Core Web Vitals beyond what Lighthouse exposes and gate CI on real performance budgets.
 
-> **Status:** v0.1 (MVP). Core Web Vitals workflow only. See [Roadmap](#roadmap) for what's next.
+<img width="1820" height="1442" alt="webperf-snippets-CLI" src="https://github.com/user-attachments/assets/af7e6b02-8877-407e-87a4-db063468b5fb" />
+
+
+> **Status:** v0.2. Core Web Vitals, loading audit, and structural checks. See [Roadmap](#roadmap) for what's next.
 
 ## Why
 
-Lighthouse gives you a score. The DevTools snippets give you the *diagnosis* — TTFB / Resource Load Delay / Element Render Delay sub-parts, LoAF script attribution, render-blocking resources, etc. This CLI runs the same curated snippets in a headless browser so you can:
+Lighthouse gives you a score. The DevTools snippets give you the *diagnosis*, such as TTFB / Resource Load Delay / Element Render Delay sub-parts, LoAF script attribution, and render-blocking resources. This CLI runs the same curated snippets in a headless browser so you can:
 
 - Diagnose LCP regressions in CI without copy-pasting into DevTools.
 - Gate pull requests on real performance budgets.
@@ -35,6 +38,24 @@ Run the default Core Web Vitals workflow (LCP + CLS, plus LCP-Subparts if LCP >
 npx webperf-snippets https://web.dev
 ```
 
+Loading audit (TTFB, FCP, render-blocking, scripts, fonts):
+
+```bash
+npx webperf-snippets https://web.dev --workflow loading
+```
+
+Structural checks for CI (render-blocking, fonts, priority hints, resource hints):
+
+```bash
+npx webperf-snippets https://web.dev --workflow audit
+```
+
+Markdown output for PR comments:
+
+```bash
+npx webperf-snippets https://web.dev --markdown
+```
+
 JSON output (for piping into `jq` or CI):
 
 ```bash
@@ -47,6 +68,71 @@ Single snippet:
 npx webperf-snippets https://web.dev --snippet LCP-Subparts
 ```
 
+Synthetic INP measurement with an interaction script:
+
+```bash
+npx webperf-snippets https://web.dev --snippet INP --interact-script interactions.json
+```
+
+Pages behind a login, with a Playwright storage state (cookies and localStorage):
+
+```bash
+# Step 1: sign in once and save the session
+npx playwright codegen --save-storage=auth.json https://example.com/login
+
+# Step 2: measure an authenticated page
+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.
+
+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
+```
+
+```
+Field data (CrUX p75, mobile)
+  🟡 LCP    2.80s      needs-improvement    (synthetic: 2.10s)
+  🟢 CLS    0.0800     good                 (synthetic: 0.0500)
+  🟡 INP    220ms      needs-improvement    (synthetic: n/a)
+```
+
+Get a key for the [Chrome UX Report API](https://developer.chrome.com/docs/crux/api) and pass it with `--crux-key` or the `CRUX_API_KEY` environment variable; prefer the variable, because a flag ends up in shell history and CI logs. The section appears in the human and markdown output and under `crux` in the `--json` output.
+
+- The population follows `--viewport`: `desktop` uses desktop data, `mobile` and `tablet` use phone data. The heading says which one.
+- When the page itself has no data, the CLI looks the origin up instead and labels the section `origin-level`, so it is not mistaken for page-level data. If the origin has none either, the output says `Field data: not available`.
+- A CrUX error (quota, network, no answer within 10 seconds) only skips the section. It never changes the exit code, and the key is never printed.
+- INP shows `n/a` as the synthetic value unless you run an interaction script.
+
+Send the results to an endpoint after the run with `--report-to`:
+
+```bash
+npx webperf-snippets https://example.com --workflow audit \
+  --report-to https://reports.example.com/api/report \
+  --api-key $REPORT_API_KEY
+```
+
+Without `--report-to` the CLI makes no external calls. With it, the results are POSTed as JSON once the snippets have finished:
+
+```json
+{
+  "url": "https://example.com",
+  "workflow": "audit",
+  "timestamp": "2026-05-06T10:00:00.000Z",
+  "navMs": 1240,
+  "results": [],
+  "meta": { "viewport": "mobile", "waitMs": 3000, "cli_version": "0.3.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.
+
+- 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.
+
 CI gating:
 
 ```bash
@@ -55,16 +141,45 @@ npx webperf-snippets https://web.dev --budget-lcp 2500 --budget-cls 0.1
 
 ### Options
 
-| Option                | Description                                                |
-| --------------------- | ---------------------------------------------------------- |
-| `--workflow <name>`   | Workflow to run. Default: `core-web-vitals`.               |
-| `--snippet <name>`    | Run a single snippet (`LCP`, `CLS`, or `Category/Name`).   |
-| `--json`              | Output JSON instead of formatted text.                     |
-| `--wait <ms>`         | Post-load wait before evaluating snippets. Default: `3000`.|
-| `--budget-lcp <ms>`   | Exit `1` if LCP exceeds this value.                        |
-| `--budget-cls <score>`| Exit `1` if CLS exceeds this value.                        |
-| `--headed`            | Show the browser window (debug).                           |
-| `-h, --help`          | Show help.                                                 |
+| Option                       | Description                                                            |
+| ---------------------------- | ---------------------------------------------------------------------- |
+| `--workflow <name>`          | Workflow to run. Default: `core-web-vitals`. Options: `core-web-vitals`, `loading`, `audit`. |
+| `--snippet <name>`           | Run a single snippet by alias or `Category/Name` path.                 |
+| `--json`                     | Output JSON instead of formatted text.                                 |
+| `--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`.            |
+| `--interact-script <path>`   | JSON file with interactions to run before evaluation (for INP).        |
+| `--storage-state <path>`     | Playwright storage state (cookies and localStorage) for pages that require authentication. |
+| `--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.                                    |
+| `--verbose`                  | Show all items, including passing checks.                              |
+| `--headed`                   | Show the browser window (debug).                                       |
+| `-h, --help`                 | Show help.                                                             |
+
+### Snippet aliases
+
+| Alias              | Snippet                                        |
+| ------------------ | ---------------------------------------------- |
+| `LCP`              | CoreWebVitals/LCP                              |
+| `CLS`              | CoreWebVitals/CLS                              |
+| `INP`              | CoreWebVitals/INP                              |
+| `LCP-Subparts`     | CoreWebVitals/LCP-Subparts                     |
+| `fonts`            | Loading/Fonts-Preloaded-Loaded-and-used-above-the-fold |
+| `render-blocking`  | Loading/Find-render-blocking-resources         |
+| `resource-hints`   | Loading/Resource-Hints-Validation              |
+| `preload-scripts`  | Loading/Validate-Preload-Async-Defer-Scripts   |
+| `priority-hints`   | Loading/Priority-Hints-Audit                   |
+| `critical-css`     | Loading/Critical-CSS-Detection                 |
+| `ttfb`             | Loading/TTFB-Sub-Parts                         |
+| `script-parties`   | Loading/First-And-Third-Party-Script-Info      |
+| `script-loading`   | Loading/Script-Loading                         |
+| `lazy-atf`         | Loading/Find-Above-The-Fold-Lazy-Loaded-Images |
+| `lazy-conflict`    | Loading/Find-Images-With-Lazy-and-Fetchpriority |
+| `eager-below-fold` | Loading/Find-non-Lazy-Loaded-Images-outside-of-the-viewport |
 
 ### Exit codes
 
@@ -85,9 +200,60 @@ GitHub Actions, fail the PR if LCP exceeds 2.5s:
     npx webperf-snippets https://staging.web.dev --budget-lcp 2500 --budget-cls 0.1
 ```
 
+### GitHub Action
+
+The repository ships a composite action that installs the CLI and Chromium, runs a workflow and exposes the result as markdown, so any repository can gate on performance budgets without extra setup:
+
+```yaml
+jobs:
+  webperf:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: nucliweb/webperf-snippets/.github/actions/webperf-snippets@main
+        id: webperf
+        with:
+          url: https://staging.example.com
+          budget-lcp: 2500
+          fail-on-budget: "false"
+
+      - uses: actions/github-script@v7
+        env:
+          BODY: ${{ steps.webperf.outputs.markdown }}
+        with:
+          script: |
+            await github.rest.issues.createComment({
+              ...context.repo,
+              issue_number: context.issue.number,
+              body: process.env.BODY,
+            });
+
+      - if: steps.webperf.outputs.exit-code != '0'
+        run: exit 1
+```
+
+| Input            | Default             | Description                                                                                  |
+| ---------------- | ------------------- | -------------------------------------------------------------------------------------------- |
+| `url`            | required            | URL to measure.                                                                              |
+| `workflow`       | `core-web-vitals`   | Workflow to run: `core-web-vitals`, `loading` or `audit`.                                    |
+| `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.                                               |
+| `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.                                        |
+
+| Output      | Description                                                                          |
+| ----------- | ------------------------------------------------------------------------------------ |
+| `markdown`  | The results as markdown. Also written to the job summary.                            |
+| `exit-code` | Exit code of the CLI: `0` passed, `1` budget exceeded or a snippet errored, `2` usage error. |
+
+The markdown includes text taken from the measured page, so pass it to other steps through an environment variable (`env:` and `process.env`) as above, never by interpolating `${{ steps.webperf.outputs.markdown }}` inside a script. With `fail-on-budget: "false"` the action step always succeeds, which lets later steps post the comment before the job fails. Without `permissions: pull-requests: write` the comment step cannot post on a pull request.
+
+LCP, CLS and INP vary by 15 to 30% on shared runners; prefer the deterministic `audit` workflow for a gate, or generous budgets.
+
 ## Publishing
 
-The CLI package is published to npm via a tag-based workflow. Publishing is explicit and intentional — it only happens when a `cli-v*` tag is pushed.
+The CLI package is published to npm via a tag-based workflow. Publishing is explicit and intentional; it only happens when a `cli-v*` tag is pushed.
 
 ### Release steps
 
@@ -102,7 +268,7 @@ The CLI package is published to npm via a tag-based workflow. Publishing is expl
 
 ### Why tag-based and not path-based
 
-An alternative is to publish automatically on every push to `main` that touches `cli/`, using a version check to skip republishes. Tag-based publishing was chosen instead because it keeps releases deliberate — a passing CI on `main` does not mean the package is ready to ship, and a tag communicates that intent explicitly.
+An alternative is to publish automatically on every push to `main` that touches `cli/`, using a version check to skip republishes. Tag-based publishing was chosen instead because it keeps releases deliberate; a passing CI on `main` does not mean the package is ready to ship, and a tag communicates that intent explicitly.
 
 ### Access control
 
@@ -112,17 +278,16 @@ Tag protection rules restrict who can push `cli-v*` tags. Configure them under *
 
 The `NPM_TOKEN` secret must be set in the repository settings with publish access to the `webperf-snippets` npm package.
 
-## Known limitations (v0.1)
+## Known limitations
 
-- **No INP**: INP requires real user interactions. v0.2 will support synthetic interaction scripts.
 - **CLS in headless is conservative**: layout shifts that only happen on scroll are missed unless you script the scroll.
 - **First navigation only**: each `webperf-snippets` invocation runs one URL. SPAs need the post-route URL passed directly.
-- **Decision-tree follow-ups re-navigate**: when a follow-up snippet fires (e.g. LCP-Subparts), the page is loaded again. v0.2 will share a single page session.
+- **Synthetic INP ≠ field INP**: `--interact-script` measures handler latency for a single scripted event. Real INP reflects the worst interaction across all user sessions; use RUM for field data.
 
 ## Roadmap
 
-- v0.2: Loading workflow (TTFB, FCP, render-blocking, scripts, fonts), shared page session, synthetic interactions for INP.
-- v0.3: Markdown reporter for PR comments, GitHub Action wrapper.
+- ~~v0.2: Loading workflow (TTFB, FCP, render-blocking, scripts, fonts), shared page session, synthetic interactions for INP, markdown reporter for PR comments.~~ ✓ Released
+- v0.3: GitHub Action wrapper.
 - v0.4: Auth flows (login + measure logged-in pages), CrUX field-data enrichment.
 
 ## How it works
@@ -136,4 +301,4 @@ The `NPM_TOKEN` secret must be set in the repository settings with publish acces
 
 ## License
 
-MIT — see [LICENSE](../LICENSE).
+MIT, see [LICENSE](../LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webperf-snippets",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Run curated WebPerf Snippets headlessly via Playwright. Diagnose Core Web Vitals beyond what Lighthouse exposes.",
   "type": "module",
   "bin": "./src/bin.js",

package/snippets/CoreWebVitals/CLS.js

@@ -2,7 +2,31 @@
 // https://webperf-snippets.nucliweb.net
 
 (async () => {
+  if (!PerformanceObserver.supportedEntryTypes?.includes("layout-shift")) {
+    console.warn("⚠️ layout-shift entries are not supported in this browser.");
+    return { script: "CLS", status: "unsupported", error: "layout-shift entries not supported in this browser" };
+  }
+  // CLS is the largest session window: shifts less than 1s apart, in a window of at most 5s.
   let cls = 0;
+  let sessionValue = 0;
+  let sessionFirst = null;
+  let sessionLast = null;
+
+  const addShift = (entry) => {
+    if (entry.hadRecentInput) return;
+    if (
+      sessionLast &&
+      entry.startTime - sessionLast.startTime < 1000 &&
+      entry.startTime - sessionFirst.startTime < 5000
+    ) {
+      sessionValue += entry.value;
+    } else {
+      sessionValue = entry.value;
+      sessionFirst = entry;
+    }
+    sessionLast = entry;
+    cls = Math.max(cls, sessionValue);
+  };
 
   const valueToRating = (score) =>
     score <= 0.1 ? "good" : score <= 0.25 ? "needs-improvement" : "poor";
@@ -23,11 +47,7 @@
   };
 
   const observer = new PerformanceObserver((list) => {
-    for (const entry of list.getEntries()) {
-      if (!entry.hadRecentInput) {
-        cls += entry.value;
-      }
-    }
+    for (const entry of list.getEntries()) addShift(entry);
     logCLS();
   });
 
@@ -63,16 +83,10 @@
     ""
   );
 
-  // Return for agent — collect via buffered observer (getEntriesByType does not
-  // expose layout-shift entries in Chrome without an active observer).
-  const clsSync = await new Promise((resolve) => {
-    let sum = 0;
-    const obs = new PerformanceObserver((list) => {
-      for (const e of list.getEntries()) if (!e.hadRecentInput) sum += e.value;
-    });
-    obs.observe({ type: "layout-shift", buffered: true });
-    setTimeout(() => { obs.disconnect(); resolve(sum); }, 100);
-  });
+  // Return for agent. Chrome only exposes layout-shift entries through a PerformanceObserver,
+  // so wait for the buffered observer above to deliver them.
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  const clsSync = cls;
   const clsRating = valueToRating(clsSync);
   return {
     script: "CLS",

package/snippets/CoreWebVitals/INP.js

@@ -2,6 +2,10 @@
 // https://webperf-snippets.nucliweb.net
 
 (() => {
+  if (!PerformanceObserver.supportedEntryTypes?.includes("event")) {
+    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 inpValue = 0;
   let inpEntry = null;
@@ -24,10 +28,10 @@
     // Sort by duration
     const sorted = [...interactions].sort((a, b) => b.duration - a.duration);
 
-    // Get 98th percentile (or worst if < 50 interactions)
-    const index = interactions.length < 50
-      ? 0
-      : Math.floor(interactions.length * 0.02);
+    // Skip one interaction for every 50. Use the browser's total interaction count when
+    // available: `interactions` only holds those above the duration threshold.
+    const totalInteractions = performance.interactionCount || interactions.length;
+    const index = Math.min(sorted.length - 1, Math.floor(totalInteractions / 50));
 
     return {
       value: sorted[index].duration,
@@ -50,7 +54,7 @@
     return `${entry.name} → ${selector}`;
   };
 
-  // Get phase breakdown (requires LoAF support)
+  // Get phase breakdown from the Event Timing entry
   const getPhaseBreakdown = (entry) => {
     const phases = {
       inputDelay: 0,
@@ -61,7 +65,10 @@
     if (entry.processingStart && entry.processingEnd) {
       phases.inputDelay = entry.processingStart - entry.startTime;
       phases.processingTime = entry.processingEnd - entry.processingStart;
-      phases.presentationDelay = entry.duration - phases.inputDelay - phases.processingTime;
+      phases.presentationDelay = Math.max(
+        0,
+        entry.duration - phases.inputDelay - phases.processingTime
+      );
     }
 
     return phases;
@@ -130,7 +137,7 @@
 
     if (inpEntry) {
       console.log("");
-      console.log(`%c🎯 Worst Interaction (INP):`, "font-weight: bold; color: ${color};");
+      console.log(`%c🎯 Worst Interaction (INP):`, `font-weight: bold; color: ${color};`);
       console.log(`   Event: ${inpEntry.formattedName}`);
       console.log(`   Duration: ${formatMs(inpEntry.duration)}`);
 

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

@@ -1,14 +1,20 @@
 // LCP Image Entropy Check
 // https://webperf-snippets.nucliweb.net
 
-(() => {
-  const formatBytes = (bytes) => {
-    if (!bytes) return "-";
-    const k = 1024;
-    const sizes = ["B", "KB", "MB"];
-    const i = Math.floor(Math.log(bytes) / Math.log(k));
-    return (bytes / Math.pow(k, i)).toFixed(1) + " " + sizes[i];
-  };
+(async () => {
+  if (!PerformanceObserver.supportedEntryTypes?.includes("largest-contentful-paint")) {
+    console.warn("⚠️ largest-contentful-paint entries are not supported in this browser.");
+    return { script: "LCP-Image-Entropy", status: "unsupported", error: "largest-contentful-paint entries not supported in this browser" };
+  }
+  // @shared formatBytes
+  function formatBytes(bytes) {
+    if (bytes === null || bytes === undefined || Number.isNaN(bytes)) return "-";
+    if (bytes === 0) return "0 B";
+    const units = ["B", "KB", "MB", "GB"];
+    const i = Math.max(0, Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1));
+    return (bytes / Math.pow(1024, i)).toFixed(1) + " " + units[i];
+  }
+  // @end-shared formatBytes
 
   const LCP_THRESHOLD = 0.05; // Chrome's threshold for low-entropy
 
@@ -142,8 +148,15 @@
     console.groupEnd();
   }, 100);
 
-  // Synchronous return for agent (buffered entries + DOM)
-  const lcpEntriesSync = performance.getEntriesByType("largest-contentful-paint");
+  // Return for agent (buffered entries + DOM)
+  // Chrome only exposes largest-contentful-paint entries through a PerformanceObserver,
+  // so performance.getEntriesByType() returns [] here. Collect via a buffered observer.
+  const lcpEntriesSync = await new Promise((resolve) => {
+    const entries = [];
+    const obs = new PerformanceObserver((list) => entries.push(...list.getEntries()));
+    obs.observe({ type: "largest-contentful-paint", buffered: true });
+    setTimeout(() => { obs.disconnect(); resolve(entries); }, 100);
+  });
   const lcpEntrySync = lcpEntriesSync.at(-1);
   const lcpElementSync = lcpEntrySync?.element ?? null;
   const lcpUrlSync = lcpEntrySync?.url ?? null;
@@ -182,6 +195,11 @@
   if (lcpImageSync?.isLowEntropy) {
     issuesSync.push({ severity: "error", message: "Current LCP image has low entropy and may be skipped by Chrome" });
   }
+  // 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;
+  const rankedImages = [...imagesSync].sort(
+    (a, b) => Number(b.isLCP) - Number(a.isLCP) || Number(b.isLowEntropy) - Number(a.isLowEntropy) || a.bpp - b.bpp
+  );
   return {
     script: "LCP-Image-Entropy",
     status: "ok",
@@ -192,7 +210,7 @@
       lcpImageEligible: lcpImageSync ? !lcpImageSync.isLowEntropy : null,
       lcpImage: lcpImageSync ? { url: lcpImageSync.url, bpp: lcpImageSync.bpp, isLowEntropy: lcpImageSync.isLowEntropy } : null,
     },
-    items: imagesSync,
+    items: rankedImages.slice(0, MAX_ITEMS),
     issues: issuesSync,
   };
 })();

package/snippets/CoreWebVitals/LCP-Subparts.js

@@ -2,6 +2,10 @@
 // https://webperf-snippets.nucliweb.net
 
 (async () => {
+  if (!PerformanceObserver.supportedEntryTypes?.includes("largest-contentful-paint")) {
+    console.warn("⚠️ largest-contentful-paint entries are not supported in this browser.");
+    return { script: "LCP-Subparts", status: "unsupported", error: "largest-contentful-paint entries not supported in this browser" };
+  }
   const formatMs = (ms) => `${Math.round(ms)}ms`;
   const formatPercent = (value, total) => `${Math.round((value / total) * 100)}%`;
 

package/snippets/CoreWebVitals/LCP-Trail.js

@@ -2,7 +2,11 @@
 // Tracks all LCP candidate elements during page load
 // https://webperf-snippets.nucliweb.net
 
-(() => {
+(async () => {
+  if (!PerformanceObserver.supportedEntryTypes?.includes("largest-contentful-paint")) {
+    console.warn("⚠️ largest-contentful-paint entries are not supported in this browser.");
+    return { script: "LCP-Trail", status: "unsupported", error: "largest-contentful-paint entries not supported in this browser" };
+  }
   const PALETTE = [
     { color: "#EF4444", name: "Red" },
     { color: "#F97316", name: "Orange" },
@@ -129,8 +133,15 @@
   console.log("%c⏱️ LCP Trail Active", "font-weight: bold; font-size: 14px;");
   console.log("   Highlights all LCP candidate elements with distinct colors.");
 
-  // Synchronous return for agent (buffered entries)
-  const trailEntries = performance.getEntriesByType("largest-contentful-paint");
+  // Return for agent (buffered entries)
+  // Chrome only exposes largest-contentful-paint entries through a PerformanceObserver,
+  // so performance.getEntriesByType() returns [] here. Collect via a buffered observer.
+  const trailEntries = await new Promise((resolve) => {
+    const entries = [];
+    const obs = new PerformanceObserver((list) => entries.push(...list.getEntries()));
+    obs.observe({ type: "largest-contentful-paint", buffered: true });
+    setTimeout(() => { obs.disconnect(); resolve(entries); }, 100);
+  });
   if (trailEntries.length === 0) {
     return { script: "LCP-Trail", status: "error", error: "No LCP entries yet" };
   }

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

@@ -1,8 +1,26 @@
 // LCP Video Candidate
 // https://webperf-snippets.nucliweb.net
 
-(() => {
-  const lcpEntries = performance.getEntriesByType("largest-contentful-paint");
+(async () => {
+  if (!PerformanceObserver.supportedEntryTypes?.includes("largest-contentful-paint")) {
+    console.warn("⚠️ largest-contentful-paint entries are not supported in this browser.");
+    return { script: "LCP-Video-Candidate", status: "unsupported", error: "largest-contentful-paint entries not supported in this browser" };
+  }
+  // Chrome only exposes largest-contentful-paint entries through a PerformanceObserver, so
+  // performance.getEntriesByType() returns [] here. Collect via a buffered observer.
+  const collectBuffered = (type, timeoutMs = 100) =>
+    new Promise((resolve) => {
+      const entries = [];
+      try {
+        const obs = new PerformanceObserver((list) => entries.push(...list.getEntries()));
+        obs.observe({ type, buffered: true });
+        setTimeout(() => { obs.disconnect(); resolve(entries); }, timeoutMs);
+      } catch {
+        resolve(entries);
+      }
+    });
+
+  const lcpEntries = await collectBuffered("largest-contentful-paint");
 
   if (lcpEntries.length === 0) {
     console.warn(

package/snippets/CoreWebVitals/LCP.js

@@ -2,6 +2,10 @@
 // https://webperf-snippets.nucliweb.net
 
 (async () => {
+  if (!PerformanceObserver.supportedEntryTypes?.includes("largest-contentful-paint")) {
+    console.warn("⚠️ largest-contentful-paint entries are not supported in this browser.");
+    return { script: "LCP", status: "unsupported", error: "largest-contentful-paint entries not supported in this browser" };
+  }
   const valueToRating = (ms) =>
     ms <= 2500 ? "good" : ms <= 4000 ? "needs-improvement" : "poor";
 
@@ -97,8 +101,6 @@
     return { script: "LCP", status: "error", error: "No LCP entries buffered" };
   }
 
-  printLCP(lastLcpEntry);
-
   const lcpActivationStart = getActivationStart();
   const lcpValue = Math.round(Math.max(0, lastLcpEntry.startTime - lcpActivationStart));
   const lcpRating = valueToRating(lcpValue);

package/snippets/DevTools-Overrides/Fetch-XHR-Timeline-read.js

@@ -1,7 +1,7 @@
 // Fetch & XHR Timeline — Run in console after page load
 // https://webperf-snippets.nucliweb.net
 
-(() => {
+(async () => {
   const calls = window.__perfCalls;
 
   if (!calls) {
@@ -11,7 +11,14 @@
     return;
   }
 
-  const lcpEntries = performance.getEntriesByType("largest-contentful-paint");
+  // Chrome only exposes largest-contentful-paint entries through a PerformanceObserver,
+  // so performance.getEntriesByType() returns [] here. Collect via a buffered observer.
+  const lcpEntries = await new Promise((resolve) => {
+    const entries = [];
+    const obs = new PerformanceObserver((list) => entries.push(...list.getEntries()));
+    obs.observe({ type: "largest-contentful-paint", buffered: true });
+    setTimeout(() => { obs.disconnect(); resolve(entries); }, 100);
+  });
   const lcpTime = lcpEntries.length
     ? Math.round(lcpEntries[lcpEntries.length - 1].startTime)
     : window.__lcpTime ?? null;