webperf-snippets 0.2.0 → 0.4.0

package/snippets/Loading/TTFB.js

@@ -4,7 +4,8 @@
 (() => {
   new PerformanceObserver((entryList) => {
     const [pageNav] = entryList.getEntriesByType("navigation");
-    const ttfb = pageNav.responseStart;
+    // Prerendered pages: measure from activation, not from the start of the prerender
+    const ttfb = Math.max(0, pageNav.responseStart - (pageNav.activationStart || 0));
 
     let rating, color;
     if (ttfb <= 800) {
@@ -30,7 +31,7 @@
   // Synchronous return for agent
   const [nav] = performance.getEntriesByType("navigation");
   if (!nav) return { script: "TTFB", status: "error", error: "No navigation entry" };
-  const value = Math.round(nav.responseStart);
+  const value = Math.round(Math.max(0, nav.responseStart - (nav.activationStart || 0)));
   const rating = value <= 800 ? "good" : value <= 1800 ? "needs-improvement" : "poor";
   return { script: "TTFB", status: "ok", metric: "TTFB", value, unit: "ms", rating,
     thresholds: { good: 800, needsImprovement: 1800 } };

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

@@ -0,0 +1,244 @@
+// Third-Party Impact by Domain
+// Groups third-party requests by root domain and reports requests, transfer size, render-blocking and main-thread time
+// https://webperf-snippets.nucliweb.net
+
+(() => {
+  const MAX_ITEMS = 50;
+  const LOAF_WARNING_MS = 250; // Script time in long animation frames above which one domain is a problem
+  const MAX_LISTED_DOMAINS = 5;
+
+  // Domains that belong to the site but differ from the page's root domain, such as its own CDN.
+  // They count as first party. Example: const OWN_DOMAINS = ["bbci.co.uk", "bbc.co.uk"];
+  const OWN_DOMAINS = [];
+
+  // @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
+
+  // A size that misses some resources is a lower bound, and one that misses all of them is unknown
+  const sizeLabel = (bytes, unknown, total) => {
+    if (total > 0 && unknown === total) return "unknown";
+    return (unknown > 0 ? "≥ " : "") + formatBytes(bytes);
+  };
+
+  // @shared getRootDomain
+  function getRootDomain(hostname) {
+    const host = hostname.replace(/\.$/, "");
+    // An IP address has no registrable domain, so each address is its own root
+    if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host) || host.includes(":")) return host;
+    const parts = host.split(".");
+    if (parts.length <= 2) return host;
+    // Country-code domains with a second-level suffix: example.co.uk, example.com.au, example.ac.jp
+    const secondLevelSuffixes = ["ac", "co", "com", "edu", "go", "gob", "gouv", "gov", "govt", "mil", "ne", "net", "nom", "or", "org", "sch"];
+    const tld = parts[parts.length - 1];
+    const sld = parts[parts.length - 2];
+    if (tld.length === 2 && secondLevelSuffixes.includes(sld)) return parts.slice(-3).join(".");
+    return parts.slice(-2).join(".");
+  }
+  // @end-shared getRootDomain
+
+  // @shared isFirstParty
+  function isFirstParty(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
+
+  // 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) } : null;
+    } catch {
+      return null;
+    }
+  };
+
+  const domains = new Map();
+  const domainEntry = (root) => {
+    if (!domains.has(root)) {
+      domains.set(root, { domain: root, requests: 0, transferBytes: 0, sizeUnknownCount: 0, renderBlocking: false, loafMs: null, loafScripts: 0 });
+    }
+    return domains.get(root);
+  };
+
+  let firstPartyRequests = 0;
+  let thirdPartyRequests = 0;
+  let thirdPartyBytes = 0;
+  let sizeUnknownCount = 0;
+
+  performance.getEntriesByType("resource").forEach((entry) => {
+    const parsed = rootDomainOf(entry.name);
+    if (!parsed) return;
+    if (parsed.first) {
+      firstPartyRequests++;
+      return;
+    }
+    const d = domainEntry(parsed.root);
+    d.requests++;
+    thirdPartyRequests++;
+
+    // Cross-origin resources without Timing-Allow-Origin report every size as zero
+    const sizeKnown = entry.transferSize > 0 || entry.encodedBodySize > 0 || entry.decodedBodySize > 0;
+    if (sizeKnown) {
+      const bytes = entry.transferSize || entry.encodedBodySize || 0;
+      d.transferBytes += bytes;
+      thirdPartyBytes += bytes;
+    } else {
+      d.sizeUnknownCount++;
+      sizeUnknownCount++;
+    }
+
+    if (entry.renderBlockingStatus === "blocking" && (entry.initiatorType === "script" || entry.initiatorType === "link")) {
+      d.renderBlocking = true;
+    }
+  });
+
+  // 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;
+    });
+    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;
+        const d = domainEntry(parsed.root);
+        d.loafMs = (d.loafMs || 0) + script.duration;
+        d.loafScripts++;
+        thirdPartyLoafMs += script.duration;
+      });
+    });
+    domains.forEach((d) => {
+      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(
+    (a, b) =>
+      Number(b.renderBlocking) - Number(a.renderBlocking) ||
+      (b.loafMs || 0) - (a.loafMs || 0) ||
+      b.transferBytes - a.transferBytes ||
+      a.domain.localeCompare(b.domain)
+  );
+
+  const blocking = all.filter((d) => d.renderBlocking);
+  const heavy = all.filter((d) => (d.loafMs || 0) > LOAF_WARNING_MS);
+  const corsLimitedAnalysis = sizeUnknownCount > 0;
+
+  const listDomains = (list) => {
+    const names = list.slice(0, MAX_LISTED_DOMAINS).map((d) => d.domain);
+    return names.join(", ") + (list.length > MAX_LISTED_DOMAINS ? ` and ${list.length - MAX_LISTED_DOMAINS} more` : "");
+  };
+
+  const issues = [];
+  if (blocking.length > 0) {
+    issues.push({
+      severity: "warning",
+      message: `${blocking.length} third-party domain(s) serve render-blocking resources (${listDomains(blocking)}); load them async or defer, or self-host them`,
+    });
+  }
+  heavy.slice(0, MAX_LISTED_DOMAINS).forEach((d) => {
+    issues.push({
+      severity: "warning",
+      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",
+      message: `${sizeUnknownCount} third-party request(s) without Timing-Allow-Origin report zero sizes, so the transfer size is a lower bound`,
+    });
+  }
+
+  console.group("%c🌐 Third-Party Impact by Domain", "font-weight: bold; font-size: 14px;");
+  console.log(
+    `Third-party domains: ${all.length} | requests: ${thirdPartyRequests} | transfer: ${sizeLabel(thirdPartyBytes, sizeUnknownCount, thirdPartyRequests)} | first-party requests: ${firstPartyRequests}`
+  );
+  if (all.length > 0) {
+    console.table(
+      all.slice(0, MAX_ITEMS).map((d) => ({
+        Domain: d.domain,
+        Requests: d.requests,
+        Size: sizeLabel(d.transferBytes, d.sizeUnknownCount, d.requests),
+        "Render-blocking": d.renderBlocking ? "yes" : "no",
+        "Main thread": d.loafMs === null ? "n/a" : d.loafMs + " ms",
+      }))
+    );
+  } else {
+    console.log("%c✅ No third-party requests found", "color: #22c55e;");
+  }
+  if (!loafSupported) {
+    console.log("%cℹ️ Long Animation Frames are not supported; main-thread time is unavailable (Chrome 123+)", "color: #3b82f6;");
+  }
+  if (loafUnattributed) {
+    console.log(
+      `%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 {
+    script: "Third-Party-Impact-by-Domain",
+    status: "ok",
+    count: all.length,
+    corsLimitedAnalysis,
+    details: {
+      thirdPartyRequests,
+      thirdPartyBytes,
+      thirdPartyLoafMs,
+      longFrames,
+      unattributedLoafMs,
+      firstPartyRequests,
+      blockingDomains: blocking.length,
+      loafSupported,
+      sizeUnknownCount,
+    },
+    items: all.slice(0, MAX_ITEMS),
+    issues,
+  };
+})();

package/snippets/Loading/Validate-Preload-Async-Defer-Scripts.js

@@ -378,6 +378,23 @@
 
   console.groupEnd();
 
+  // One item per script (an issue replaces the valid entry of the same URL), at most 50
+  const itemsByUrl = new Map();
+  validPreloads.forEach((v) => itemsByUrl.set(v.url, {
+    url: v.shortUrl,
+    type: v.type === "dynamic" ? "dynamic" : v.type === "mitigated" ? "mitigated" : "blocking",
+    strategy: v.attributes || "blocking-script",
+    location: v.location || "unknown",
+    reviewNote: v.reviewNote || v.note || "",
+  }));
+  issues.forEach((i) => itemsByUrl.set(i.url, {
+    url: i.shortUrl,
+    type: "issue",
+    strategy: i.attributes || i.type,
+    location: i.location || "unknown",
+    reviewNote: i.fix || "",
+  }));
+
   return {
     script: "Validate-Preload-Async-Defer-Scripts",
     status: "ok",
@@ -386,9 +403,10 @@
       validCount: validPreloads.length,
       issueCount: issues.length,
     },
-    items: preloadedScripts.map(p => ({
-      url: p.href.split("/").pop()?.split("?")[0] || p.href,
+    items: Array.from(itemsByUrl.values()).slice(0, 50),
+    issues: issues.map(i => ({
+      severity: i.severity,
+      message: i.fix ? `${i.message.replace(/\.$/, "")}. Fix: ${i.fix}` : i.message,
     })),
-    issues: issues.map(i => ({ severity: i.severity, message: i.message })),
   };
 })();

package/snippets/Loading/WORKFLOWS.md

@@ -19,6 +19,7 @@ When TTFB is slow or the user asks "why is my server slow":
 2. **TTFB-Sub-Parts.js** - Break down into DNS, connection, server time
 3. **Service-Worker-Analysis.js** - Check for SW overhead impacting TTFB
 4. **TTFB-Resources.js** - Identify slow third-party or API endpoints
+5. **Server-Timing-Early-Hints.js** - Read backend phases from `Server-Timing` and check 103 Early Hints
 
 ### Font Loading Optimization
 
@@ -27,6 +28,15 @@ When the user asks about fonts, FOIT, FOUT, or font performance:
 1. **Fonts-Preloaded-Loaded-and-used-above-the-fold.js** - Full font audit
 2. **Resource-Hints-Validation.js** - Verify font preloads are correct
 3. **Find-render-blocking-resources.js** - Check if fonts block rendering
+4. **Webfont-Usage-Analyzer.js** - Find font faces that are unused, never loaded, or use a blocking `font-display`
+
+### Text Compression Audit
+
+When the user asks about compression, gzip, brotli, or large transfer sizes for text resources:
+
+1. **Compression-Audit.js** - Find text resources served without compression and estimate savings
+2. **Find-render-blocking-resources.js** - Prioritize uncompressed CSS/JS that block rendering
+3. **TTFB-Resources.js** - Check server response of the uncompressed resources
 
 ### Script Performance Deep Dive
 
@@ -34,6 +44,7 @@ When scripts are suspected to slow down the page:
 
 1. **Script-Loading.js** - Identify blocking scripts and loading strategy
 2. **First-And-Third-Party-Script-Info.js** - Separate first vs third-party impact
+   - **Third-Party-Impact-by-Domain.js** - Rank third-party domains by render-blocking, main-thread time and size
 3. **First-And-Third-Party-Script-Timings.js** - Diagnose slow script connections
 4. **JS-Execution-Time-Breakdown.js** - Network vs parse/execution time
 5. **Inline-Script-Info-and-Size.js** - Measure inline script overhead
@@ -48,6 +59,7 @@ When the user wants to optimize resource loading priorities:
 3. **Priority-Hints-Audit.js** - Check fetchpriority usage
 4. **Prefetch-Resource-Validation.js** - Validate prefetch strategy
 5. **Validate-Preload-Async-Defer-Scripts.js** - Find conflicts
+6. **Speculation-Rules-Inspector.js** - Inspect prefetch/prerender rules and prerender activation
 
 ### CSS Optimization Workflow
 
@@ -76,6 +88,13 @@ Use this decision tree to automatically run follow-up snippets based on results:
 - **If TTFB > 600ms** → Run **TTFB-Sub-Parts.js** to diagnose where time is spent
 - **If Service Worker detected** → Run **Service-Worker-Analysis.js** to check for SW overhead
 - **If TTFB varies significantly across resources** → Run **TTFB-Resources.js**
+- **If server time dominates TTFB-Sub-Parts.js** → Run **Server-Timing-Early-Hints.js** to see which backend phase is slow
+
+### After Server-Timing-Early-Hints.js
+
+- **If no `Server-Timing` metrics found** → Recommend adding `Server-Timing` headers for database, cache and render phases
+- **If cross-origin resources look hidden** → Recommend `Timing-Allow-Origin` on those responses
+- **If no 103 Early Hints received and server time is high** → Recommend Early Hints for the main stylesheet and LCP image
 
 ### After FCP.js
 
@@ -109,6 +128,19 @@ Use this decision tree to automatically run follow-up snippets based on results:
   2. **Priority-Hints-Audit.js** (LCP candidate)
 - **If preloads on async/defer scripts** → Run **Validate-Preload-Async-Defer-Scripts.js**
 
+### After Compression-Audit.js
+
+- **If uncompressed CSS/JS found** → Run **Find-render-blocking-resources.js** to see if they block rendering
+- **If estimated savings > 100KB** → Recommend enabling gzip or brotli on the server or CDN
+- **If corsLimitedAnalysis is true** → Report the result as a lower bound and suggest `Timing-Allow-Origin` on resources you control
+
+### After Third-Party-Impact-by-Domain.js
+
+- **If a domain is render-blocking** → Recommend `async`, `defer`, lazy loading or self-hosting; run **Script-Loading.js** for the loading strategy
+- **If a domain's main-thread time > 250ms** → Run **Long-Animation-Frames-Script-Attribution.js** (webperf-interaction) to find the functions responsible, and recommend delaying or removing the script
+- **If many domains with few requests each** → Recommend auditing tags and removing unused ones
+- **If corsLimitedAnalysis is true** → Report sizes as a lower bound; use **First-And-Third-Party-Script-Timings.js** for timings of the hidden resources
+
 ### After Service-Worker-Analysis.js
 
 - **If SW overhead > 100ms** → Recommend Navigation Preload API
@@ -119,7 +151,14 @@ Use this decision tree to automatically run follow-up snippets based on results:
 
 - **If fonts preloaded but not used above-the-fold** → Recommend removing preloads
 - **If fonts used but not preloaded** → Recommend adding preload
-- **If many font variants loaded** → Suggest subsetting or reducing variants
+- **If many font variants loaded** → Suggest subsetting or reducing variants, and run **Webfont-Usage-Analyzer.js** to find the unused ones
+
+### After Webfont-Usage-Analyzer.js
+
+- **If fonts loaded but not used** → Recommend removing the `@font-face` declaration or the preload
+- **If faces use `font-display: auto` or `block`** → Recommend `swap` or `optional`, then check **Find-render-blocking-resources.js**
+- **If font bytes are high** → Suggest subsetting with `unicode-range` and WOFF2
+- **If the LCP element is text** → Run **LCP.js** with the **webperf-core-web-vitals** skill
 
 ### After First-And-Third-Party-Script-Info.js
 
@@ -145,6 +184,13 @@ Use this decision tree to automatically run follow-up snippets based on results:
 - **If >10 prefetch hints** → Recommend reducing to critical resources
 - **If individual prefetch > 500KB** → Question necessity
 - **If total prefetch > 2MB** → Flag as mobile bandwidth concern
+- **If few or no prefetch hints for likely next navigations** → Run **Speculation-Rules-Inspector.js** to check for prefetch/prerender rules
+
+### After Speculation-Rules-Inspector.js
+
+- **If no speculation rules found but the site has predictable navigations** → Recommend adding prefetch or prerender rules
+- **If invalid JSON or wasteful rules (eager prerender of many URLs)** → Recommend fixing or lowering eagerness to `moderate` or `conservative`
+- **If the page was prerendered (`activationStart` > 0)** → Subtract `activationStart` when interpreting **TTFB.js**, **FCP.js** and LCP results
 
 ### After Critical-CSS-Detection.js