webperf-snippets 0.2.0 → 0.3.0

package/README.md

@@ -9,7 +9,7 @@ Run curated [WebPerf Snippets](https://webperf-snippets.nucliweb.net) headlessly
 
 ## 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.
@@ -74,6 +74,65 @@ Synthetic INP measurement with an interaction script:
 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
@@ -91,6 +150,10 @@ npx webperf-snippets https://web.dev --budget-lcp 2500 --budget-cls 0.1
 | `--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.                              |
@@ -103,6 +166,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         |
@@ -136,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
 
@@ -153,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
 
@@ -167,7 +282,7 @@ 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
 
@@ -186,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.2.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;

package/snippets/Interaction/DOM-Size-and-Depth.js

@@ -0,0 +1,134 @@
+// DOM Size and Depth
+// https://webperf-snippets.nucliweb.net
+
+(() => {
+  // Lighthouse "Avoid an excessive DOM size" thresholds
+  const THRESHOLDS = { warnNodes: 800, errorNodes: 1400, maxDepth: 32, maxChildren: 60 };
+  const MAX_ITEMS = 50;
+  const SELECTOR_LEVELS = 4;
+
+  // Short selector for reporting: stops at the nearest id, at most SELECTOR_LEVELS levels
+  // up, and marks open shadow root boundaries with ">>>". Never returns DOM nodes.
+  const selectorFor = (el) => {
+    const parts = [];
+    let node = el;
+    let truncated = false;
+    while (node && node.nodeType === 1) {
+      if (parts.length === SELECTOR_LEVELS) {
+        truncated = true;
+        break;
+      }
+      let part = node.localName;
+      if (node.id) {
+        parts.unshift(`${part}#${window.CSS.escape(node.id)}`);
+        break;
+      }
+      const cls = typeof node.className === "string" ? node.className.trim().split(/\s+/)[0] : "";
+      if (cls) part += `.${window.CSS.escape(cls)}`;
+      parts.unshift(part);
+      const parent = node.parentNode;
+      if (parent && parent.nodeType === 11 && parent.host) {
+        parts.unshift(">>>");
+        node = parent.host;
+        continue;
+      }
+      node = node.parentElement;
+    }
+    return (truncated ? "... > " : "") + parts.join(" > ").replace(/> >>> >/g, ">>>");
+  };
+
+  // Iterative walk (explicit stack) so very deep trees cannot overflow the call stack.
+  // Depth counts <html> as level 1 and continues through open shadow roots.
+  let totalElements = 0;
+  let maxDepth = 0;
+  let deepest = null;
+  let shadowRoots = 0;
+  const parents = [];
+  const stack = [document.documentElement, 1];
+
+  while (stack.length) {
+    const depth = stack.pop();
+    const el = stack.pop();
+    totalElements++;
+    if (depth > maxDepth) {
+      maxDepth = depth;
+      deepest = el;
+    }
+    const roots = [el];
+    if (el.shadowRoot) {
+      shadowRoots++;
+      roots.push(el.shadowRoot);
+    }
+    for (const root of roots) {
+      const kids = root.children;
+      if (kids.length) parents.push({ el, root, children: kids.length, depth });
+      for (let i = kids.length - 1; i >= 0; i--) stack.push(kids[i], depth + 1);
+    }
+  }
+
+  const ranked = parents
+    .sort((a, b) => b.children - a.children || a.depth - b.depth);
+  const widest = ranked[0] ?? null;
+  const widestSelector = widest ? selectorFor(widest.el) + (widest.root !== widest.el ? " (shadow root)" : "") : null;
+
+  const items = ranked.slice(0, 10).map((p) => ({
+    selector: selectorFor(p.el) + (p.root !== p.el ? " (shadow root)" : ""),
+    children: p.children,
+    depth: p.depth,
+  }));
+
+  const issues = [];
+  if (totalElements > THRESHOLDS.errorNodes) {
+    issues.push({
+      severity: "error",
+      message: `${totalElements} nodes exceeds ${THRESHOLDS.errorNodes}; a large DOM slows style recalculation and layout on every interaction`,
+    });
+  } else if (totalElements > THRESHOLDS.warnNodes) {
+    issues.push({
+      severity: "warning",
+      message: `${totalElements} nodes exceeds ${THRESHOLDS.warnNodes}; a large DOM increases style recalculation and layout cost`,
+    });
+  }
+  if (maxDepth > THRESHOLDS.maxDepth) {
+    issues.push({
+      severity: "warning",
+      message: `DOM depth of ${maxDepth} exceeds ${THRESHOLDS.maxDepth}; deep trees make style and layout work costlier (deepest: ${selectorFor(deepest)})`,
+    });
+  }
+  if (widest && widest.children > THRESHOLDS.maxChildren) {
+    issues.push({
+      severity: "warning",
+      message: `${widestSelector} has ${widest.children} children, above ${THRESHOLDS.maxChildren}; consider virtualizing or paginating the list`,
+    });
+  }
+
+  const deepestElement = deepest ? selectorFor(deepest) : null;
+
+  // Human output
+  console.group("%cDOM size and depth", "font-weight: bold; font-size: 14px;");
+  console.log(`Elements: ${totalElements} (warn > ${THRESHOLDS.warnNodes}, error > ${THRESHOLDS.errorNodes})`);
+  console.log(`Max depth: ${maxDepth} (limit ${THRESHOLDS.maxDepth}) at ${deepestElement}`);
+  if (widest) console.log(`Widest parent: ${widestSelector} with ${widest.children} children (limit ${THRESHOLDS.maxChildren})`);
+  console.log(`Open shadow roots traversed: ${shadowRoots}`);
+  issues.forEach((i) => console.warn(`${i.severity}: ${i.message}`));
+  if (items.length) console.table(items);
+  console.groupEnd();
+
+  // Agent output
+  return {
+    script: "DOM-Size-and-Depth",
+    status: "ok",
+    count: items.length,
+    issues,
+    items: items.slice(0, MAX_ITEMS),
+    details: {
+      totalElements,
+      maxDepth,
+      maxChildren: widest ? widest.children : 0,
+      widestParent: widestSelector,
+      deepestElement,
+      shadowRoots,
+      thresholds: THRESHOLDS,
+    },
+  };
+})();