webperf-snippets 0.3.0 → 0.4.0

package/snippets/Loading/Third-Party-Impact-by-Domain.js

@@ -45,19 +45,28 @@
 
   // @shared isFirstParty
   function isFirstParty(hostname) {
-    return getRootDomain(hostname) === getRootDomain(location.hostname);
+    const root = getRootDomain(hostname);
+    if (root === getRootDomain(location.hostname)) return true;
+    return OWN_DOMAINS.some((d) => getRootDomain(String(d).trim().toLowerCase().replace(/^[a-z]+:\/\//, "").split("/")[0]) === root);
   }
   // @end-shared isFirstParty
 
-  const ownRoots = new Set(
-    OWN_DOMAINS.map((d) => getRootDomain(String(d).trim().toLowerCase().replace(/^[a-z]+:\/\//, "").split("/")[0]))
-  );
+  // @shared logOwnDomainsHint
+  function logOwnDomainsHint(thirdPartyCount) {
+    if (OWN_DOMAINS.length === 0 && thirdPartyCount > 0) {
+      console.log(
+        '%cℹ️ OWN_DOMAINS is empty. If this site serves its own assets from other domains (for example a CDN), add them at the top of the snippet, such as const OWN_DOMAINS = ["cdn.example.net"];, and run it again so they count as first party.',
+        "color: #3b82f6;"
+      );
+    }
+  }
+  // @end-shared logOwnDomainsHint
 
   // Root domain of an http(s) URL, or null for anything else (data:, blob:, empty)
   const rootDomainOf = (url) => {
     try {
       const u = new URL(url);
-      return /^https?:$/.test(u.protocol) ? { root: getRootDomain(u.hostname), first: isFirstParty(u.hostname) || ownRoots.has(getRootDomain(u.hostname)) } : null;
+      return /^https?:$/.test(u.protocol) ? { root: getRootDomain(u.hostname), first: isFirstParty(u.hostname) } : null;
     } catch {
       return null;
     }
@@ -106,12 +115,17 @@
   // Main-thread time: script time inside long animation frames, attributed by the script's source URL
   const loafSupported = !!PerformanceObserver.supportedEntryTypes?.includes("long-animation-frame");
   let thirdPartyLoafMs = null;
+  let longFrames = null;
+  let longFramesMs = null;
   if (loafSupported) {
     thirdPartyLoafMs = 0;
     domains.forEach((d) => {
       d.loafMs = 0;
     });
-    performance.getEntriesByType("long-animation-frame").forEach((frame) => {
+    const frames = performance.getEntriesByType("long-animation-frame");
+    longFrames = frames.length;
+    longFramesMs = frames.reduce((total, frame) => total + frame.duration, 0);
+    frames.forEach((frame) => {
       (frame.scripts || []).forEach((script) => {
         const parsed = rootDomainOf(script.sourceURL);
         if (!parsed || parsed.first) return;
@@ -125,7 +139,12 @@
       d.loafMs = Math.round(d.loafMs || 0);
     });
     thirdPartyLoafMs = Math.round(thirdPartyLoafMs);
+    longFramesMs = Math.round(longFramesMs);
   }
+  // Time in long frames that no third-party script accounts for: first-party scripts, scripts under
+  // the 5 ms that Long Animation Frames list, and style, layout and rendering work
+  const unattributedLoafMs = loafSupported ? Math.max(0, longFramesMs - thirdPartyLoafMs) : null;
+  const loafUnattributed = loafSupported && domains.size > 0 && thirdPartyLoafMs === 0 && longFrames > 0;
 
   // Render-blocking first, then main-thread time, then transfer size
   const all = [...domains.values()].sort(
@@ -158,6 +177,12 @@
       message: `${d.domain} scripts take ${d.loafMs} ms of main-thread time in long animation frames (over ${LOAF_WARNING_MS} ms); defer, delay or remove them`,
     });
   });
+  if (loafUnattributed) {
+    issues.push({
+      severity: "info",
+      message: `${longFrames} long animation frame(s) took ${longFramesMs} ms, but no third-party script was attributed in them (Long Animation Frames only list scripts over 5 ms), so 0 ms per domain does not rule out third-party cost`,
+    });
+  }
   if (corsLimitedAnalysis) {
     issues.push({
       severity: "info",
@@ -185,15 +210,16 @@
   if (!loafSupported) {
     console.log("%cℹ️ Long Animation Frames are not supported; main-thread time is unavailable (Chrome 123+)", "color: #3b82f6;");
   }
-  if (corsLimitedAnalysis) {
-    console.log("%cℹ️ Some third-party sizes are hidden (no Timing-Allow-Origin); sizes are a lower bound", "color: #3b82f6;");
-  }
-  if (OWN_DOMAINS.length === 0 && all.length > 0) {
+  if (loafUnattributed) {
     console.log(
-      '%cℹ️ OWN_DOMAINS is empty. If this site serves its own assets from other domains (for example a CDN), add them at the top of the snippet, such as const OWN_DOMAINS = ["cdn.example.net"];, and run it again so they count as first party.',
+      `%cℹ️ ${longFrames} long animation frame(s) took ${longFramesMs} ms, but no third-party script was attributed in them (Long Animation Frames only list scripts over 5 ms), so 0 ms per domain does not rule out third-party cost`,
       "color: #3b82f6;"
     );
   }
+  if (corsLimitedAnalysis) {
+    console.log("%cℹ️ Some third-party sizes are hidden (no Timing-Allow-Origin); sizes are a lower bound", "color: #3b82f6;");
+  }
+  logOwnDomainsHint(all.length);
   console.groupEnd();
 
   return {
@@ -205,6 +231,8 @@
       thirdPartyRequests,
       thirdPartyBytes,
       thirdPartyLoafMs,
+      longFrames,
+      unattributedLoafMs,
       firstPartyRequests,
       blockingDomains: blocking.length,
       loafSupported,

package/snippets/Media/Image-Element-Audit.js

@@ -14,7 +14,8 @@
     );
   }
 
-  function findLcpCandidate(imgs) {
+  // Fallback when the browser cannot report the LCP element: the largest image in the viewport
+  function estimateLcpCandidate(imgs) {
     let candidate = null;
     let maxArea = 0;
     imgs.filter(isInViewport).forEach((img) => {
@@ -28,6 +29,40 @@
     return candidate;
   }
 
+  // Chrome only exposes largest-contentful-paint entries through a PerformanceObserver
+  function getLastLcpEntry() {
+    return new Promise((resolve) => {
+      const entries = [];
+      const observer = new PerformanceObserver((list) => entries.push(...list.getEntries()));
+      observer.observe({ type: "largest-contentful-paint", buffered: true });
+      setTimeout(() => {
+        observer.disconnect();
+        resolve(entries.at(-1) ?? null);
+      }, 100);
+    });
+  }
+
+  // The <img> the browser reports as the Largest Contentful Paint, or null when the LCP element is
+  // not one of the page's images (text, a CSS background, a video). Estimates by area when the
+  // browser reports no LCP.
+  async function findLcpCandidate(imgs) {
+    if (!PerformanceObserver.supportedEntryTypes?.includes("largest-contentful-paint")) {
+      return { candidate: estimateLcpCandidate(imgs), nonImageTag: null };
+    }
+    const entry = await getLastLcpEntry();
+    if (!entry) return { candidate: estimateLcpCandidate(imgs), nonImageTag: null };
+    const el = entry.element;
+    if (el?.tagName === "IMG") {
+      return imgs.includes(el) ? { candidate: el, nonImageTag: null } : { candidate: null, nonImageTag: "IMG" };
+    }
+    // The element left the DOM after painting: find its image by URL
+    if (!el && entry.url) {
+      const byUrl = imgs.find((img) => (img.currentSrc || img.src) === entry.url) ?? null;
+      return { candidate: byUrl, nonImageTag: byUrl ? null : "unknown" };
+    }
+    return { candidate: null, nonImageTag: el ? el.tagName : "unknown" };
+  }
+
   function detectFormat(url) {
     if (!url) return "unknown";
     const lower = url.toLowerCase();
@@ -120,7 +155,7 @@
     return { script: "Image-Element-Audit", status: "ok", count: 0, corsLimitedAnalysis: false, items: [], issues: [] };
   }
 
-  const lcpCandidate = findLcpCandidate(images);
+  const { candidate: lcpCandidate, nonImageTag } = await findLcpCandidate(images);
   const imagePreloads = Array.from(document.querySelectorAll('link[rel="preload"][as="image"]'));
 
   // Fetch actual formats from Content-Type headers in parallel.
@@ -213,6 +248,10 @@
   );
 
   // LCP candidate
+  if (nonImageTag) {
+    console.log("");
+    console.log(`%cℹ️ The LCP element is not an <img> (${nonImageTag === "unknown" ? "not in the page's images" : nonImageTag}), so no image is audited as the LCP.`, "color: #3b82f6;");
+  }
   if (lcpCandidate) {
     const lcp = audited.find((r) => r.isLcp);
     const fpOk = lcp.fetchpriority === "high";
@@ -359,11 +398,16 @@
       inPicture: r.inPicture,
       issues: r.issues.map((i) => ({ severity: i.s, message: i.msg })),
     })),
-    issues: audited.flatMap((r) =>
-      r.issues.map((i) => ({
-        severity: i.s,
-        message: `${shortSrc(r.src) || "(no src)"}: ${i.msg}`,
-      }))
-    ),
+    issues: [
+      ...(nonImageTag
+        ? [{ severity: "info", message: `The LCP element is not an <img> (${nonImageTag === "unknown" ? "not in the page's images" : nonImageTag}), so no image is audited as the LCP` }]
+        : []),
+      ...audited.flatMap((r) =>
+        r.issues.map((i) => ({
+          severity: i.s,
+          message: `${shortSrc(r.src) || "(no src)"}: ${i.msg}`,
+        }))
+      ),
+    ],
   };
 })();

package/snippets/SCHEMA.md

@@ -527,7 +527,7 @@ Synchronous. `count` is the number of uncompressed text resources; `items` holds
 
 #### Third-Party-Impact-by-Domain
 
-Synchronous. `count` is the number of third-party root domains; `items` holds the 50 to look at first (render-blocking, then the most main-thread time, then the largest transfer), while `details` totals every domain. `loafMs` is the script time attributed to the domain in `long-animation-frame` entries (sum of `scripts[].duration` by `sourceURL`), or `null` for every item when `details.loafSupported` is `false`. A cross-origin request without `Timing-Allow-Origin` reports zero for every size, so it is counted in `sizeUnknownCount` (per domain and in `details`), left out of the byte totals, and `corsLimitedAnalysis` is `true`.
+Synchronous. `count` is the number of third-party root domains; `items` holds the 50 to look at first (render-blocking, then the most main-thread time, then the largest transfer), while `details` totals every domain. `loafMs` is the script time attributed to the domain in `long-animation-frame` entries (sum of `scripts[].duration` by `sourceURL`), or `null` for every item when `details.loafSupported` is `false`. `details.longFrames` counts the long animation frames on the page and `details.unattributedLoafMs` is the time in them that no third-party script accounts for (first-party scripts, scripts under the 5 ms that the API lists, and style, layout and rendering work); both are `null` when `loafSupported` is `false`. A cross-origin request without `Timing-Allow-Origin` reports zero for every size, so it is counted in `sizeUnknownCount` (per domain and in `details`), left out of the byte totals, and `corsLimitedAnalysis` is `true`.
 
 ```json
 {
@@ -539,6 +539,8 @@ Synchronous. `count` is the number of third-party root domains; `items` holds th
     "thirdPartyRequests": 3,
     "thirdPartyBytes": 5120,
     "thirdPartyLoafMs": 128,
+    "longFrames": 2,
+    "unattributedLoafMs": 74,
     "firstPartyRequests": 1,
     "blockingDomains": 1,
     "loafSupported": true,
@@ -667,15 +669,16 @@ Async. Returns one item per registration. `cacheHitRate` is computed over the re
 
 #### Resource-Hints-Validation
 
-`items` lists the origins that need a hint and the origins that have both `preconnect` and `dns-prefetch` (at most 50).
+`items` lists the hints to remove because nothing uses them (`remove-unused-preload`, `remove-unused-preconnect`, `remove-unused-dns-prefetch`, with the `href` of the hint), the origins that need a hint and the origins that have both `preconnect` and `dns-prefetch` (at most 50). `href` is `null` for the last two kinds.
 
 ```json
 {
   "script": "Resource-Hints-Validation",
   "status": "ok",
   "items": [
-    { "domain": "https://cdn.example", "requestCount": 6, "action": "add-preconnect", "recommendedHint": "preconnect" },
-    { "domain": "https://fonts.example", "requestCount": 2, "action": "remove-dns-prefetch", "recommendedHint": "preconnect" }
+    { "domain": "https://old.example", "href": "https://old.example/", "requestCount": 0, "action": "remove-unused-preconnect", "recommendedHint": null },
+    { "domain": "https://cdn.example", "href": null, "requestCount": 6, "action": "add-preconnect", "recommendedHint": "preconnect" },
+    { "domain": "https://fonts.example", "href": null, "requestCount": 2, "action": "remove-dns-prefetch", "recommendedHint": "preconnect" }
   ]
 }
 ```

package/snippets/_shared/helpers.js

@@ -27,12 +27,29 @@ function getRootDomain(hostname) {
 }
 // @end-shared getRootDomain
 
+// Declared at the top of each snippet that carries isFirstParty: the domains of the site that
+// differ from the page's root domain, such as its own CDN. They count as first party.
+const OWN_DOMAINS = [];
+
 // @shared isFirstParty
 function isFirstParty(hostname) {
-  return getRootDomain(hostname) === getRootDomain(location.hostname);
+  const root = getRootDomain(hostname);
+  if (root === getRootDomain(location.hostname)) return true;
+  return OWN_DOMAINS.some((d) => getRootDomain(String(d).trim().toLowerCase().replace(/^[a-z]+:\/\//, "").split("/")[0]) === root);
 }
 // @end-shared isFirstParty
 
+// @shared logOwnDomainsHint
+function logOwnDomainsHint(thirdPartyCount) {
+  if (OWN_DOMAINS.length === 0 && thirdPartyCount > 0) {
+    console.log(
+      '%cℹ️ OWN_DOMAINS is empty. If this site serves its own assets from other domains (for example a CDN), add them at the top of the snippet, such as const OWN_DOMAINS = ["cdn.example.net"];, and run it again so they count as first party.',
+      "color: #3b82f6;"
+    );
+  }
+}
+// @end-shared logOwnDomainsHint
+
 // @shared formatBytes
 function formatBytes(bytes) {
   if (bytes === null || bytes === undefined || Number.isNaN(bytes)) return "-";

package/src/bin.js

@@ -2,10 +2,12 @@
 import { existsSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { loadSnippet } from "./load-snippet.js";
+import { resolveSnippetName } from "./snippet-names.js";
 import { runSnippets, runMeasurement, VIEWPORT_PRESETS } from "./runner.js";
 import { cwvWorkflow } from "./workflows/cwv.js";
 import { auditWorkflow } from "./workflows/audit.js";
 import { loadingWorkflow } from "./workflows/loading.js";
+import { interactionWorkflow } from "./workflows/interaction.js";
 import { RULES } from "./decision-tree.js";
 import { reportHuman } from "./reporters/human.js";
 import { reportJson } from "./reporters/json.js";
@@ -17,42 +19,9 @@ const WORKFLOWS = {
   "core-web-vitals": cwvWorkflow,
   audit: auditWorkflow,
   loading: loadingWorkflow,
+  interaction: interactionWorkflow,
 };
 
-const SNIPPET_ALIASES = {
-  LCP: "CoreWebVitals/LCP",
-  CLS: "CoreWebVitals/CLS",
-  INP: "CoreWebVitals/INP",
-  "LCP-Subparts": "CoreWebVitals/LCP-Subparts",
-  fonts: "Loading/Fonts-Preloaded-Loaded-and-used-above-the-fold",
-  "Fonts-Preloaded-Loaded-and-used-above-the-fold":
-    "Loading/Fonts-Preloaded-Loaded-and-used-above-the-fold",
-  // Tier 1 — Loading
-  "render-blocking": "Loading/Find-render-blocking-resources",
-  "Find-render-blocking-resources": "Loading/Find-render-blocking-resources",
-  "resource-hints": "Loading/Resource-Hints-Validation",
-  "Resource-Hints-Validation": "Loading/Resource-Hints-Validation",
-  "preload-scripts": "Loading/Validate-Preload-Async-Defer-Scripts",
-  "Validate-Preload-Async-Defer-Scripts": "Loading/Validate-Preload-Async-Defer-Scripts",
-  "priority-hints": "Loading/Priority-Hints-Audit",
-  "Priority-Hints-Audit": "Loading/Priority-Hints-Audit",
-  "critical-css": "Loading/Critical-CSS-Detection",
-  "Critical-CSS-Detection": "Loading/Critical-CSS-Detection",
-  ttfb: "Loading/TTFB-Sub-Parts",
-  "TTFB-Sub-Parts": "Loading/TTFB-Sub-Parts",
-  "script-parties": "Loading/First-And-Third-Party-Script-Info",
-  "First-And-Third-Party-Script-Info": "Loading/First-And-Third-Party-Script-Info",
-  "script-loading": "Loading/Script-Loading",
-  "Script-Loading": "Loading/Script-Loading",
-  // Tier 2 — Media
-  "lazy-atf": "Loading/Find-Above-The-Fold-Lazy-Loaded-Images",
-  "Find-Above-The-Fold-Lazy-Loaded-Images": "Loading/Find-Above-The-Fold-Lazy-Loaded-Images",
-  "lazy-conflict": "Loading/Find-Images-With-Lazy-and-Fetchpriority",
-  "Find-Images-With-Lazy-and-Fetchpriority": "Loading/Find-Images-With-Lazy-and-Fetchpriority",
-  "eager-below-fold": "Loading/Find-non-Lazy-Loaded-Images-outside-of-the-viewport",
-  "Find-non-Lazy-Loaded-Images-outside-of-the-viewport":
-    "Loading/Find-non-Lazy-Loaded-Images-outside-of-the-viewport",
-};
 
 const USAGE = `webperf-snippets <url> [options]
 
@@ -60,8 +29,9 @@ Run curated WebPerf Snippets headlessly via Playwright.
 
 Options:
   --workflow <name>     Workflow to run (default: core-web-vitals)
-                        Workflows: core-web-vitals, audit, loading
-  --snippet <name>      Run a single snippet by alias or Category/Name path
+                        Workflows: core-web-vitals, audit, loading, interaction
+  --snippet <name>      Run a single snippet by name, alias or Category/Name path
+                        Any of the 56 snippets, such as Compression-Audit
                         Aliases: LCP, CLS, INP, LCP-Subparts, fonts,
                                  render-blocking, resource-hints, preload-scripts,
                                  priority-hints, critical-css, ttfb,
@@ -73,7 +43,8 @@ Options:
   --wait <ms>           Post-load wait before evaluating (default: 3000)
   --budget-lcp <ms>     Exit 1 if LCP exceeds this value
   --budget-cls <score>  Exit 1 if CLS exceeds this value
-  --interact-script <path>  JSON file with interactions to run before evaluation
+  --interact-script <path>  JSON file with interactions to run after the load; the
+                            Interaction snippets are installed first and read last
                             Actions: scroll, click, hover, type, wait
   --storage-state <path>    Playwright storage state (cookies + localStorage) to
                             measure pages that require authentication
@@ -94,6 +65,7 @@ Examples:
   npx webperf-snippets https://web.dev --snippet LCP-Subparts
   npx webperf-snippets https://web.dev --snippet render-blocking
   npx webperf-snippets https://web.dev --snippet fonts
+  npx webperf-snippets https://web.dev --snippet Compression-Audit
   npx webperf-snippets https://web.dev --budget-lcp 2500
   npx webperf-snippets https://web.dev --snippet INP --interact-script interactions.json
   npx webperf-snippets https://example.com/dashboard --storage-state auth.json
@@ -104,12 +76,13 @@ function fail(message, code = 2) {
   process.exit(code);
 }
 
-function resolveSnippetPath(name) {
-  return SNIPPET_ALIASES[name] ?? name;
-}
-
 function buildSnippetItem(values) {
-  const path = resolveSnippetPath(values.snippet);
+  let path;
+  try {
+    path = resolveSnippetName(values.snippet);
+  } catch (err) {
+    fail(err.message);
+  }
   return [{ id: values.snippet, path, source: loadSnippet(path) }];
 }
 
@@ -246,8 +219,10 @@ async function main() {
   }
 
   const anyError = payload.results.some((r) => r.status === "error");
+  // A follow-up (a result with a reason) only informs: its error issues show in the report and
+  // leave the exit code to the budgets and to the steps the workflow runs itself.
   const anyAuditViolation = payload.results.some(
-    (r) => Array.isArray(r.issues) && r.issues.some((i) => i.severity === "error"),
+    (r) => !r.reason && Array.isArray(r.issues) && r.issues.some((i) => i.severity === "error"),
   );
   process.exit(anyError || anyAuditViolation ? 1 : 0);
 }

package/src/decision-tree.js

@@ -1,28 +1,76 @@
-// Declarative follow-ups: if a result matches the predicate, append the step.
+// Declarative follow-ups: if a result matches the predicate, append the steps.
 // Mirrors the WORKFLOWS.md decision trees from the snippet catalogue.
+//
+// A rule looks at the first results only. The results of a follow-up do not fire rules of their own.
+const ok = (r, id) => r.id === id && r.status === "ok";
+
 export const RULES = [
   {
-    when: (r) => r.id === "LCP" && r.status === "ok" && r.value > 2500,
+    when: (r) => ok(r, "LCP") && r.value > 2500,
     append: { id: "LCP-Subparts", path: "CoreWebVitals/LCP-Subparts" },
     reason: "LCP > 2.5s — drilling into sub-parts",
   },
   {
-    when: (r) => r.id === "TTFB" && r.status === "ok" && r.value > 600,
+    when: (r) => ok(r, "LCP") && r.value > 4000,
+    append: { id: "LCP-Trail", path: "CoreWebVitals/LCP-Trail" },
+    reason: "LCP > 4s — listing the LCP candidates",
+  },
+  {
+    when: (r) => ok(r, "LCP") && r.details?.elementType === "Image",
+    append: [
+      { id: "LCP-Image-Entropy", path: "CoreWebVitals/LCP-Image-Entropy" },
+      { id: "image-audit", path: "Media/Image-Element-Audit" },
+    ],
+    reason: "LCP is an image — checking its entropy and its attributes",
+  },
+  {
+    when: (r) => ok(r, "LCP") && r.details?.elementType === "Video poster",
+    append: [
+      { id: "LCP-Video-Candidate", path: "CoreWebVitals/LCP-Video-Candidate" },
+      { id: "video-audit", path: "Media/Video-Element-Audit" },
+    ],
+    reason: "LCP is a video — checking its candidate and its loading",
+  },
+  {
+    when: (r) => ok(r, "CLS") && r.value > 0.1,
+    append: { id: "layout-shifts", path: "Interaction/Layout-Shift-Loading-and-Interaction" },
+    reason: "CLS > 0.1 — separating the shifts of the load from those of the interactions",
+  },
+  {
+    when: (r) => ok(r, "CLS") && r.value > 0.25,
+    append: [
+      { id: "lazy-atf", path: "Loading/Find-Above-The-Fold-Lazy-Loaded-Images" },
+      { id: "fonts", path: "Loading/Fonts-Preloaded-Loaded-and-used-above-the-fold" },
+      { id: "critical-css", path: "Loading/Critical-CSS-Detection" },
+      { id: "image-audit", path: "Media/Image-Element-Audit" },
+    ],
+    reason: "CLS > 0.25 — looking for the usual causes: lazy images, font swaps, late CSS and images without dimensions",
+  },
+  {
+    when: (r) => ok(r, "TTFB") && r.value > 600,
     append: { id: "ttfb-subparts", path: "Loading/TTFB-Sub-Parts" },
     reason: "TTFB > 600ms — drilling into sub-parts",
   },
   {
-    when: (r) => r.id === "FCP" && r.status === "ok" && r.value > 1800,
+    when: (r) => ok(r, "FCP") && r.value > 1800,
     append: { id: "render-blocking", path: "Loading/Find-render-blocking-resources" },
     reason: "FCP > 1.8s — checking render-blocking resources",
   },
 ];
 
-export function nextSteps(results) {
+// The follow-up steps the results call for, each snippet once: a path two rules ask for is added by
+// the first, and a path in `skipPaths` (a step the workflow already ran) is left out.
+export function nextSteps(results, rules = RULES, skipPaths = []) {
+  const seen = new Set(skipPaths);
   const followUps = [];
   for (const result of results) {
-    for (const rule of RULES) {
-      if (rule.when(result)) followUps.push({ ...rule.append, reason: rule.reason });
+    for (const rule of rules) {
+      if (!rule.when(result)) continue;
+      for (const step of [rule.append].flat()) {
+        if (seen.has(step.path)) continue;
+        seen.add(step.path);
+        followUps.push({ ...step, reason: rule.reason });
+      }
     }
   }
   return followUps;

package/src/interactions.js

@@ -22,9 +22,19 @@ export async function executeStep(page, step) {
   }
 }
 
-export async function runInteractions(page, scriptPath) {
-  const { interactions } = JSON.parse(readFileSync(scriptPath, "utf8"));
-  for (const step of interactions) {
+// `source` is the path of a JSON file ({ "interactions": [...] }) or the list of steps itself.
+export function loadInteractionSteps(source) {
+  return Array.isArray(source) ? source : JSON.parse(readFileSync(source, "utf8")).interactions;
+}
+
+// A click or a key press creates the events that Interactions and Input-Latency-Breakdown measure;
+// a scroll, a hover and a wait do not.
+export function isInputStep(step) {
+  return step.action === "click" || step.action === "type";
+}
+
+export async function runInteractions(page, source) {
+  for (const step of loadInteractionSteps(source)) {
     await executeStep(page, step);
   }
 }

package/src/load-snippet.js

@@ -6,7 +6,7 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(HERE, "..");
 
 // Resolution order: bundled (published package) → workspace root (dev).
-const SNIPPET_DIRS = [
+export const SNIPPET_DIRS = [
   join(PKG_ROOT, "snippets"),
   resolve(PKG_ROOT, "..", "snippets"),
 ];

package/src/reporters/human.js

@@ -100,11 +100,11 @@ function renderAuditResult(r, verbose) {
     lines.push("");
     const shown = items.slice(0, MAX_ITEMS);
     for (const item of shown) {
-      const name = item.shortName ?? item.resource ?? item.url ?? item.src ?? item.selector ?? item.filename ?? "";
-      const tag = item.type ?? item.tag ?? item.strategy ?? item.media ?? "";
+      const name = item.shortName ?? item.resource ?? item.url ?? item.src ?? item.selector ?? item.filename ?? item.target ?? "";
+      const tag = item.type ?? item.tag ?? item.strategy ?? item.media ?? item.kind ?? "";
       const timing = item.responseEndMs != null ? `${item.responseEndMs}ms` : item.durationMs != null ? `${item.durationMs}ms` : "";
-      const cols = [tag, name, timing].filter(Boolean).join("  ");
-      lines.push(`     ${styleText("dim", `· ${cols}`)}`);
+      const cols = [tag, name, item.detail, timing].filter(Boolean).join("  ");
+      if (cols) lines.push(`     ${styleText("dim", `· ${cols}`)}`);
     }
     if (items.length > MAX_ITEMS) {
       lines.push(`     ${styleText("dim", `… and ${items.length - MAX_ITEMS} more`)}`);
@@ -118,7 +118,22 @@ function renderAuditResult(r, verbose) {
   return lines.join("\n");
 }
 
+// A result with a count and details but no value and no issues, such as the long tasks: the count,
+// then the first numbers of its details.
+function renderSummaryResult(r) {
+  const numbers = Object.entries(r.details ?? {})
+    .filter(([, value]) => typeof value === "number")
+    .slice(0, 3)
+    .map(([key, value]) => `${key} ${value}`);
+  const summary = [r.count !== undefined ? String(r.count) : null, ...numbers].filter(Boolean).join("  ·  ");
+  return `  ${RATING_ICON[r.rating] ?? "·"} ${pad(r.id, 16)} ${styleText("dim", summary)}`;
+}
+
 function renderResult(r, verbose) {
+  if (r.status === "skipped") {
+    return `  ${styleText("dim", "-")} ${pad(r.id, 16)} ${styleText("dim", `skipped: ${r.reason}`)}`;
+  }
+
   if (r.status === "error") {
     return `  ${styleText("red", "✗")} ${pad(r.id, 16)} ${styleText("dim", r.error)}`;
   }
@@ -131,6 +146,10 @@ function renderResult(r, verbose) {
     return renderAuditResult(r, verbose);
   }
 
+  if (r.value === undefined && (r.count !== undefined || r.details)) {
+    return renderSummaryResult(r);
+  }
+
   const icon = RATING_ICON[r.rating] ?? "·";
   const valueText = paint(r.rating, formatValue(r.value, r.unit));
   const ratingText = styleText("dim", r.rating ?? "");

package/src/reporters/markdown.js

@@ -31,7 +31,12 @@ function renderErrorRow(r) {
   return `| ${r.id} | ❌ error | ${r.error} |`;
 }
 
+function renderSkippedRow(r) {
+  return `| ${r.id} | ⏭ skipped | ${r.reason} |`;
+}
+
 function renderRow(r) {
+  if (r.status === "skipped") return renderSkippedRow(r);
   if (r.status === "error") return renderErrorRow(r);
   if (Array.isArray(r.issues)) return renderAuditRow(r);
   return renderMetricRow(r);