webperf-snippets 0.2.0 → 0.4.0

package/README.md

@@ -5,11 +5,11 @@ Run curated [WebPerf Snippets](https://webperf-snippets.nucliweb.net) headlessly
 <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.
+> **Status:** v0.4. Core Web Vitals, loading, interaction and structural audit workflows, and every snippet of the collection by name. See the [Roadmap](#roadmap).
 
 ## 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.
@@ -38,13 +38,13 @@ 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):
+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.nucliweb.net/CLI)):
 
 ```bash
 npx webperf-snippets https://web.dev --workflow loading
 ```
 
-Structural checks for CI (render-blocking, fonts, priority hints, resource hints):
+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.nucliweb.net/CLI)):
 
 ```bash
 npx webperf-snippets https://web.dev --workflow audit
@@ -72,8 +72,76 @@ 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
 ```
 
+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.
+
+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
+```
+
+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.4.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
@@ -84,13 +152,17 @@ npx webperf-snippets https://web.dev --budget-lcp 2500 --budget-cls 0.1
 
 | 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.                 |
+| `--workflow <name>`          | Workflow to run. Default: `core-web-vitals`. Options: `core-web-vitals`, `loading`, `audit`, `interaction`. |
+| `--snippet <name>`           | Run a single snippet by name, 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).        |
+| `--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. |
+| `--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.                              |
@@ -103,6 +175,7 @@ npx webperf-snippets https://web.dev --budget-lcp 2500 --budget-cls 0.1
 | ------------------ | ---------------------------------------------- |
 | `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         |
@@ -117,12 +190,16 @@ npx webperf-snippets https://web.dev --budget-lcp 2500 --budget-cls 0.1
 | `lazy-conflict`    | Loading/Find-Images-With-Lazy-and-Fetchpriority |
 | `eager-below-fold` | Loading/Find-non-Lazy-Loaded-Images-outside-of-the-viewport |
 
+### Follow-up steps
+
+The results of a run can add steps on the same page load: LCP over 2.5 s adds `LCP-Subparts`, over 4 s `LCP-Trail`; an image or video LCP adds its entropy, image or video audit; CLS over 0.1 adds `Layout-Shift-Loading-and-Interaction`, over 0.25 also the lazy images, fonts, critical CSS and images without dimensions; TTFB over 600 ms adds `TTFB-Sub-Parts`; FCP over 1.8 s adds the render-blocking check. The full table is in the [CLI page](https://webperf-snippets.nucliweb.net/CLI). Each snippet runs once, and a follow-up informs: its `error` issues do not change the exit code.
+
 ### Exit codes
 
 | Code | Meaning                                       |
 | ---- | --------------------------------------------- |
 | `0`  | All checks passed.                            |
-| `1`  | Budget violation, or a snippet errored.       |
+| `1`  | Budget violation, a snippet errored, or a step of the workflow reported an `error` issue. |
 | `2`  | Usage error (missing URL, unknown workflow).  |
 
 ## CI example
@@ -136,9 +213,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`, `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.                                               |
+| `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
 
@@ -153,7 +281,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
 
@@ -167,13 +295,13 @@ The `NPM_TOKEN` secret must be set in the repository settings with publish acces
 
 - **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.
-- **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.
+- **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, markdown reporter for PR comments.~~ ✓ Released
-- v0.3: GitHub Action wrapper.
-- v0.4: Auth flows (login + measure logged-in pages), CrUX field-data enrichment.
+- ~~v0.3: GitHub Action wrapper, auth flows (login + measure logged-in pages), CrUX field-data enrichment, `--report-to`.~~ ✓ Released
+- ~~v0.4: Every snippet by name, a 22-step audit, an 11-step loading workflow, the interaction workflow and decision-tree follow-ups for Core Web Vitals.~~ ✓ Released
 
 ## How it works
 
@@ -186,4 +314,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.2.0",
+  "version": "0.4.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;