webperf-snippets 0.4.0 → 0.5.0

package/snippets/Media/SVG-Embedded-Bitmap-Analysis.js

@@ -1,7 +1,32 @@
 // SVG Embedded Bitmap Analysis
-// https://webperf-snippets.nucliweb.net
+// https://webperf-snippets.net
 
 (async () => {
+  // @shared ownRequestUrl
+  // The URL a snippet requests when it reads a file of the page itself (fetch, a HEAD request,
+  // new Image()). The fragment never reaches the server or the HTTP cache key, so the file still
+  // comes from the cache, but it stays in the name of the Resource Timing entry of the request,
+  // which is how isOwnRequest leaves these requests out of what the page loaded.
+  function ownRequestUrl(url) {
+    try {
+      const parsed = new URL(url, location.href);
+      if (!/^https?:$/.test(parsed.protocol)) return url;
+      parsed.hash = "webperf-snippets";
+      return parsed.href;
+    } catch {
+      return url;
+    }
+  }
+  // @end-shared ownRequestUrl
+
+  // @shared isOwnRequest
+  // True for the Resource Timing entry of a request a snippet made with ownRequestUrl: the page
+  // did not make it, so no snippet counts it.
+  function isOwnRequest(entry) {
+    return entry.name.endsWith("#webperf-snippets");
+  }
+  // @end-shared isOwnRequest
+
   function formatSize(bytes) {
     if (!bytes || bytes === 0) return "—";
     if (bytes < 1024) return `${bytes} B`;
@@ -55,7 +80,7 @@
 
   // ── External SVG files (Performance API) ──────────────────────────────
   const svgEntries = performance
-    .getEntriesByType("resource")
+    .getEntriesByType("resource").filter((e) => !isOwnRequest(e))
     .filter((e) => e.name.split("?")[0].toLowerCase().endsWith(".svg"));
 
   const externalResults = await Promise.all(
@@ -64,7 +89,7 @@
       let bitmaps = [];
 
       try {
-        const res = await fetch(entry.name, { cache: "force-cache" });
+        const res = await fetch(ownRequestUrl(entry.name), { cache: "force-cache" });
         const ce = res.headers.get("content-encoding");
         if (ce) compression = ce; // gzip | br | zstd | deflate
         bitmaps = findEmbeddedBitmaps(await res.text());
@@ -89,6 +114,8 @@
   const inlineSvgTotal = inlineSvgs.length;
   const svgsWithUse = inlineSvgs.filter((svg) => svg.querySelector("use")).length;
   const standaloneInlineSvgs = inlineSvgTotal - svgsWithUse;
+  // Five or more standalone inline SVGs are worth moving into a <symbol> sprite
+  const spriteOpportunity = standaloneInlineSvgs >= 5;
 
   const inlineResults = Array.from(document.querySelectorAll("svg"))
     .map((svg, i) => {
@@ -189,7 +216,7 @@
     );
   }
 
-  if (standaloneInlineSvgs >= 5) {
+  if (spriteOpportunity) {
     console.log("");
     console.group("%c💡 SVG Sprite Opportunity", "color: #3b82f6; font-weight: bold;");
     console.log("");
@@ -213,6 +240,21 @@
 
   console.groupEnd();
 
+  const issues = [];
+  if (withBitmaps.length > 0) {
+    issues.push({ severity: "warning", message: `${withBitmaps.length} SVG file(s) contain embedded bitmaps` });
+  }
+  if (spriteOpportunity) {
+    const withUse =
+      svgsWithUse > 0
+        ? ` (${svgsWithUse} inline SVG${svgsWithUse === 1 ? " already uses" : "s already use"} <use>)`
+        : "";
+    issues.push({
+      severity: "info",
+      message: `${standaloneInlineSvgs} standalone inline SVGs could share one <symbol> sprite referenced with <use>${withUse}`,
+    });
+  }
+
   return {
     script: "SVG-Embedded-Bitmap-Analysis",
     status: "ok",
@@ -222,8 +264,7 @@
       inlineSvgTotal,
       svgsWithUse,
       standaloneInlineSvgs,
-      // Five or more standalone inline SVGs are worth moving into a <symbol> sprite
-      spriteOpportunity: standaloneInlineSvgs >= 5,
+      spriteOpportunity,
     },
     items: withBitmaps.map((r) => ({
       url: r.url || r.name,
@@ -233,8 +274,6 @@
       bitmapTypes: r.bitmaps.map((b) => b.format).join(", "),
       sizeBytes: r.transferSize,
     })),
-    issues: withBitmaps.length > 0
-      ? [{ severity: "warning", message: `${withBitmaps.length} SVG file(s) contain embedded bitmaps` }]
-      : [],
+    issues,
   };
 })();

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

@@ -1,5 +1,5 @@
 // Video Element Audit
-// https://webperf-snippets.nucliweb.net
+// https://webperf-snippets.net
 
 (() => {
   function isInViewport(el) {
@@ -54,8 +54,14 @@
   const videos = Array.from(document.querySelectorAll("video"));
 
   if (videos.length === 0) {
-    console.log("No <video> elements found on this page.");
-    return { script: "Video-Element-Audit", status: "ok", count: 0, items: [], issues: [] };
+    console.log("No <video> elements on this page, nothing to audit.");
+    return {
+      script: "Video-Element-Audit",
+      status: "ok",
+      count: 0,
+      items: [],
+      issues: [{ severity: "info", message: "No <video> elements on this page, so there was nothing to audit." }],
+    };
   }
 
   const audited = videos.map((video) => {
@@ -79,35 +85,35 @@
     if (preload === "auto" && !autoplay) {
       issues.push({
         s: "error",
-        msg: 'preload="auto" loads the full video eagerly — use preload="none" or preload="metadata"',
+        msg: 'preload="auto" loads the full video eagerly: use preload="none" or preload="metadata"',
       });
     }
 
     if (!autoplay && !inViewport && preload !== "none") {
       issues.push({
         s: "warning",
-        msg: 'Off-viewport video without preload="none" — set preload="none" to avoid unnecessary loading',
+        msg: 'Off-viewport video without preload="none": set preload="none" to avoid unnecessary loading',
       });
     }
 
     if (autoplay && !muted) {
       issues.push({
         s: "error",
-        msg: "autoplay without muted — browsers block unmuted autoplay",
+        msg: "autoplay without muted: browsers block unmuted autoplay",
       });
     }
 
     if (autoplay && !playsinline) {
       issues.push({
         s: "warning",
-        msg: "autoplay without playsinline — iOS Safari forces fullscreen mode",
+        msg: "autoplay without playsinline: iOS Safari forces fullscreen mode",
       });
     }
 
     if (!poster) {
       issues.push({
         s: "warning",
-        msg: "Missing poster — no preview frame shown before playback starts",
+        msg: "Missing poster: no preview frame shown before playback starts",
       });
     }
 
@@ -121,14 +127,14 @@
     if (!isModernCodec(codec) && codec !== "no source") {
       issues.push({
         s: "info",
-        msg: "No modern codec source detected — consider adding a WebM source (VP9 or AV1) for better compression",
+        msg: "No modern codec source detected: consider adding a WebM source (VP9 or AV1) for better compression",
       });
     }
 
     if (!controls && !autoplay) {
       issues.push({
         s: "info",
-        msg: "No controls attribute and no autoplay — users may not be able to play the video",
+        msg: "No controls attribute and no autoplay, so users may not be able to play the video",
       });
     }
 

package/snippets/README.md

@@ -87,7 +87,7 @@ See `snippets/Loading/WORKFLOWS.md` for a complete example with:
 The `generate-skills.js` script:
 
 1. Reads all `.js` files from each category
-2. Extracts metadata from corresponding MDX documentation in `/pages/`
+2. Extracts metadata from corresponding MDX documentation in `/content/`
 3. Injects `WORKFLOWS.md` content (if exists)
 4. Generates complete `SKILL.md` files with:
    - Snippet table

package/snippets/Resources/Network-Bandwidth-Connection-Quality.js

@@ -1,5 +1,5 @@
 // Network Bandwidth & Connection Quality Analysis
-// https://webperf-snippets.nucliweb.net
+// https://webperf-snippets.net
 
 (() => {
   const connection =

package/snippets/SCHEMA.md

@@ -207,6 +207,8 @@ A script wrapped in `void (async () => {...})()` discards its return value. Neve
 }
 ```
 
+`details.element` is a CSS selector that matches only the LCP element, so `document.querySelector(details.element)` returns it: the id when it is unique, otherwise a path of tag, classes and `:nth-of-type()` from the nearest ancestor with a unique id, such as `section.intro:nth-of-type(2) > p.copy:nth-of-type(2)`. LCP-Subparts (`details.element`) and LCP-Trail (`finalElement` and each `selector`) build it the same way.
+
 #### CLS
 
 Returns buffered CLS immediately and keeps tracking. Always call `getCLS()` after interactions to get an updated value.
@@ -421,7 +423,16 @@ If no interactions yet, `getINP()` returns `status: "error"` with `getDataFn: "g
       "serverResponse": { "value": 165, "unit": "ms" }
     },
     "slowestPhase": "serverResponse"
-  }
+  },
+  "issues": []
+}
+```
+
+When the rating is not good, `issues` holds one entry that names the TTFB and the slowest phase, a `warning` for `needs-improvement` and an `error` for `poor`:
+
+```json
+{
+  "issues": [{ "severity": "warning", "message": "TTFB is 996 ms (needs-improvement); server response takes 993 ms of it (100%). Fix: optimize server processing, cache the HTML and check slow queries." }]
 }
 ```
 
@@ -744,7 +755,7 @@ Issues keep `{ severity, message }`. The fix is the last sentence of the message
 
 #### CSS-Media-Queries-Analysis
 
-`details.performanceImpact` estimates the cost of the desktop-only CSS for each device profile, in numbers rounded to one decimal. It is `null` when there is no desktop-only CSS. The detailed console report stays opt-in through `analyzeCSSPerformanceImpact()`.
+One item per distinct media query that targets viewports wider than `details.minWidth`, largest first. `details` gives the totals, `totalUnique` and `uniquenessRatio`, and `bySource` breaks the rules down by stylesheet.
 
 ```json
 {
@@ -752,16 +763,21 @@ Issues keep `{ severity, message }`. The fix is the last sentence of the message
   "status": "ok",
   "count": 2,
   "details": {
-    "corsBlockedCount": 0,
-    "performanceImpact": {
-      "unnecessaryBytes": 1200,
-      "totalClasses": 4,
-      "totalProperties": 9,
-      "deviceImpact": {
-        "Mid-range (Moto G Power, iPhone SE)": { "renderBlockingTimeMs": 3.1, "runtimeOverheadMs": 0.1, "fcpImpactMs": 1.9, "lcpImpactMs": 1.2, "inpOverheadMs": 0.1 }
-      }
-    }
-  }
+    "minWidth": 768,
+    "rules": 3,
+    "totalUnique": 2,
+    "uniquenessRatio": 0.667,
+    "classes": 4,
+    "properties": 5,
+    "bytes": 160,
+    "bySource": [{ "source": "https://example.com/app.css", "inline": false, "rules": 3, "bytes": 160 }],
+    "corsBlockedCount": 0
+  },
+  "items": [
+    { "mediaQuery": "(min-width: 1024px)", "rules": 2, "files": 1, "classes": 3, "properties": 3, "bytes": 110 },
+    { "mediaQuery": "(min-width: 1200px)", "rules": 1, "files": 1, "classes": 1, "properties": 2, "bytes": 50 }
+  ],
+  "issues": [{ "severity": "info", "message": "3 @media rules for viewports wider than 768px add 160.0 B of CSS that narrower screens download and parse without using. ..." }]
 }
 ```
 
@@ -1089,7 +1105,7 @@ Same shape as Image-Element-Audit but for video elements.
 
 #### SVG-Embedded-Bitmap-Analysis
 
-`details` counts the SVGs, also on a page with none. `spriteOpportunity` is `true` when five or more standalone inline SVGs could share one `<symbol>` sprite.
+`details` counts the SVGs, also on a page with none. `spriteOpportunity` is `true` when five or more standalone inline SVGs could share one `<symbol>` sprite, and it is then also an `info` issue with the counts.
 
 ```json
 {
@@ -1098,7 +1114,10 @@ Same shape as Image-Element-Audit but for video elements.
   "count": 2,
   "details": { "externalSvgCount": 3, "inlineSvgTotal": 7, "svgsWithUse": 1, "standaloneInlineSvgs": 6, "spriteOpportunity": true },
   "items": [{ "url": "icon.svg", "hasBitmap": true, "bitmapType": "image/png", "sizeBytes": 4500 }],
-  "issues": [{ "severity": "warning", "message": "2 SVG files contain embedded bitmaps" }]
+  "issues": [
+    { "severity": "warning", "message": "2 SVG file(s) contain embedded bitmaps" },
+    { "severity": "info", "message": "6 standalone inline SVGs could share one <symbol> sprite referenced with <use> (1 inline SVG already uses <use>)" }
+  ]
 }
 ```
 

package/snippets/_shared/helpers.js

@@ -59,3 +59,62 @@ function formatBytes(bytes) {
   return (bytes / Math.pow(1024, i)).toFixed(1) + " " + units[i];
 }
 // @end-shared formatBytes
+
+// @shared ownRequestUrl
+// The URL a snippet requests when it reads a file of the page itself (fetch, a HEAD request,
+// new Image()). The fragment never reaches the server or the HTTP cache key, so the file still
+// comes from the cache, but it stays in the name of the Resource Timing entry of the request,
+// which is how isOwnRequest leaves these requests out of what the page loaded.
+function ownRequestUrl(url) {
+  try {
+    const parsed = new URL(url, location.href);
+    if (!/^https?:$/.test(parsed.protocol)) return url;
+    parsed.hash = "webperf-snippets";
+    return parsed.href;
+  } catch {
+    return url;
+  }
+}
+// @end-shared ownRequestUrl
+
+// @shared isOwnRequest
+// True for the Resource Timing entry of a request a snippet made with ownRequestUrl: the page
+// did not make it, so no snippet counts it.
+function isOwnRequest(entry) {
+  return entry.name.endsWith("#webperf-snippets");
+}
+// @end-shared isOwnRequest
+
+// @shared uniqueSelector
+// A CSS selector that matches only el in its document (or shadow root): its id when it is unique,
+// otherwise a path of tag, classes and :nth-of-type() that goes up to the nearest ancestor with a
+// unique id, or to the root, and stops as soon as it matches one element.
+function uniqueSelector(el) {
+  const root = el.getRootNode();
+  const matchesOne = (selector) => {
+    try {
+      return root.querySelectorAll(selector).length === 1;
+    } catch {
+      return false;
+    }
+  };
+  const parts = [];
+  let node = el;
+  while (node && node.nodeType === 1) {
+    if (node.id && matchesOne(`#${window.CSS.escape(node.id)}`)) {
+      parts.unshift(`#${window.CSS.escape(node.id)}`);
+      break;
+    }
+    const tag = node.localName;
+    let part = tag + Array.from(node.classList).slice(0, 2).map((c) => `.${window.CSS.escape(c)}`).join("");
+    const siblings = node.parentNode ? Array.from(node.parentNode.children) : [node];
+    if (siblings.filter((s) => s.matches(part)).length > 1) {
+      part += `:nth-of-type(${siblings.filter((s) => s.localName === tag).indexOf(node) + 1})`;
+    }
+    parts.unshift(part);
+    if (matchesOne(parts.join(" > "))) break;
+    node = node.parentElement;
+  }
+  return parts.join(" > ");
+}
+// @end-shared uniqueSelector

package/src/interactions.js

@@ -38,3 +38,30 @@ export async function runInteractions(page, source) {
     await executeStep(page, step);
   }
 }
+
+// The browser reports the timing of an event after the frame that follows it, and an observer gets it
+// in a task after that frame. Reading a snippet right after the last step can miss that step, so this
+// waits for two frames and a task, which takes a few milliseconds on a page that renders. A page that
+// never renders a frame stops the wait at `limitMs`, and a page that is gone is not an error here: the
+// evaluation that follows reports it.
+export async function settle(page, limitMs = 1000) {
+  try {
+    await page.evaluate(
+      (limit) =>
+        new Promise((resolve) => {
+          const timer = setTimeout(resolve, limit);
+          requestAnimationFrame(() =>
+            requestAnimationFrame(() =>
+              setTimeout(() => {
+                clearTimeout(timer);
+                resolve();
+              }, 0)
+            )
+          );
+        }),
+      limitMs
+    );
+  } catch {
+    // the page navigated or closed
+  }
+}

package/src/runner.js

@@ -1,6 +1,6 @@
 import { chromium } from "playwright";
 import { loadSnippet } from "./load-snippet.js";
-import { runInteractions, loadInteractionSteps, isInputStep } from "./interactions.js";
+import { runInteractions, loadInteractionSteps, isInputStep, settle } from "./interactions.js";
 import { isTrackingSnippet } from "./tracking.js";
 import { nextSteps } from "./decision-tree.js";
 
@@ -42,14 +42,16 @@ async function evaluateItems(page, items) {
 
 // Runs the items around a set of interactions. A tracking snippet is installed first, so it sees
 // the interactions, and answers through its getDataFn afterwards. The other items run after the
-// interactions, as before. Results keep the order of the items. Without interactions every item
-// runs once, as it always did.
+// interactions, as before. The browser reports the timing of an interaction after the frame that
+// follows it, so the runner lets it settle before it reads anything. Results keep the order of the
+// items. Without interactions every item runs once, as it always did.
 async function evaluateAroundInteractions(page, items, interactions) {
   if (!interactions) return evaluateItems(page, items);
 
   const tracking = items.filter((item) => isTrackingSnippet(item.path ?? "", item.source));
   const installed = await evaluateItems(page, tracking);
   await runInteractions(page, interactions);
+  await settle(page);
   const others = await evaluateItems(
     page,
     items.filter((item) => !tracking.includes(item))

package/src/tracking.js

@@ -1,6 +1,6 @@
-// A tracking snippet installs observers and answers later through a window function named in
-// its result (getDataFn). The Interaction snippets work this way. CLS and INP also name a
-// getDataFn but answer with their value in one go, so only the Interaction category counts.
+// A tracking snippet installs observers and answers later through a window function named in its
+// result (getDataFn). The Interaction snippets work this way, and so does INP, whose value only
+// comes out of getINP(). CLS also names a getDataFn but answers with its value in one go.
 export function isTrackingSnippet(path, source) {
-  return path.startsWith("Interaction/") && source.includes("getDataFn");
+  return (path.startsWith("Interaction/") || path === "CoreWebVitals/INP") && source.includes("getDataFn");
 }