webperf-snippets 0.2.0 → 0.4.0

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,
+    },
+  };
+})();

package/snippets/Interaction/Forced-Synchronous-Layout.js

@@ -179,7 +179,9 @@
         script: "Forced-Synchronous-Layout",
         status: "ok",
         count: 0,
-        details: { fslEvents: [] },
+        details: {},
+        items: [],
+        issues: [],
       };
     }
 
@@ -235,13 +237,37 @@
         fastestSinceLastMutationMs: Math.min(
           ...fslEvents.map((e) => e.sinceLastMutationMs)
         ),
-        fslEvents: fslEvents.map(({ property, accessType, element, sinceLastMutationMs }) => ({
-          property,
-          accessType,
-          element,
-          sinceLastMutationMs,
-        })),
       },
+      // One item per property and element, most frequent first (at most 50)
+      items: Object.values(
+        fslEvents.reduce((acc, e) => {
+          const key = `${e.property}|${e.accessType}|${e.element}`;
+          if (!acc[key]) {
+            acc[key] = {
+              property: e.property,
+              accessType: e.accessType,
+              element: e.element,
+              count: 0,
+              fastestSinceLastMutationMs: e.sinceLastMutationMs,
+            };
+          }
+          acc[key].count++;
+          acc[key].fastestSinceLastMutationMs = Math.min(
+            acc[key].fastestSinceLastMutationMs,
+            e.sinceLastMutationMs
+          );
+          return acc;
+        }, {})
+      )
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 50),
+      issues: Object.entries(byProperty)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10)
+        .map(([property, count]) => ({
+          severity: count > 5 ? "error" : "warning",
+          message: `${property} triggered ${count} forced synchronous layout${count > 1 ? "s" : ""}. Read layout properties before writing to the DOM.`,
+        })),
     };
   };
 

package/snippets/Interaction/Input-Latency-Breakdown.js

@@ -81,7 +81,12 @@
       console.log(
         "   Interact with the page (click, type, etc.) and call this again."
       );
-      return;
+      return {
+        script: "Input-Latency-Breakdown",
+        status: "error",
+        error: "No interactions recorded yet. Interact with the page (click, type, etc.) and call getInputLatencyBreakdown() again.",
+        getDataFn: "getInputLatencyBreakdown",
+      };
     }
 
     console.group(
@@ -171,11 +176,50 @@
       };
     }
     console.groupEnd();
+
+    const BOTTLENECK_FIXES = {
+      "Input Delay": "break up the long tasks that block the main thread (scheduler.yield(), setTimeout)",
+      Processing: "optimize the event handlers or debounce them",
+      Presentation: "reduce the DOM changes after the handler and avoid layout thrashing",
+    };
+
+    const items = types.map((type) => {
+      const b = byEventType[type];
+      return {
+        type,
+        count: b.count,
+        p75Ms: Math.round(p75(b.durations)),
+        inputDelayMs: Math.round(p75(b.inputDelays)),
+        processingMs: Math.round(p75(b.processingTimes)),
+        presentationMs: Math.round(p75(b.presentationDelays)),
+        rating: valueToRating(p75(b.durations)),
+      };
+    });
+
+    const issues = types
+      .filter((type) => valueToRating(p75(byEventType[type].durations)) !== "good")
+      .map((type) => {
+        const b = byEventType[type];
+        const phases = [
+          { name: "Input Delay", value: p75(b.inputDelays) },
+          { name: "Processing", value: p75(b.processingTimes) },
+          { name: "Presentation", value: p75(b.presentationDelays) },
+        ];
+        const bottleneck = phases.reduce((a, c) => (a.value > c.value ? a : c));
+        const rating = valueToRating(p75(b.durations));
+        return {
+          severity: rating === "poor" ? "error" : "warning",
+          message: `${type} P75 is ${Math.round(p75(b.durations))}ms (${rating}). Bottleneck: ${bottleneck.name}. Fix: ${BOTTLENECK_FIXES[bottleneck.name]}.`,
+        };
+      });
+
     return {
       script: "Input-Latency-Breakdown",
       status: "ok",
       count: types.length,
       details: { eventTypes: typeSummary },
+      items,
+      issues,
     };
   };
 

package/snippets/Interaction/Interactions.js

@@ -199,11 +199,22 @@
         p75Ms: Math.round(p75),
         byRating,
       },
-      items: allInteractions.map((i) => ({
-        type: i.type,
-        durationMs: Math.round(i.duration),
-        rating: i.rating,
-      })),
+      // Slowest first, at most 50
+      items: [...allInteractions]
+        .sort((a, b) => b.duration - a.duration)
+        .slice(0, 50)
+        .map((i) => ({
+          type: i.type,
+          durationMs: Math.round(i.duration),
+          rating: i.rating,
+        })),
+      issues: [...slowInteractions]
+        .sort((a, b) => b.duration - a.duration)
+        .slice(0, 10)
+        .map((i) => ({
+          severity: i.rating === "poor" ? "error" : "warning",
+          message: `${i.type} interaction took ${Math.round(i.duration)}ms (${i.rating}), above the ${i.rating === "poor" ? "500ms" : "200ms"} threshold`,
+        })),
     };
   };
 

package/snippets/Interaction/Layout-Shift-Loading-and-Interaction.js

@@ -1,7 +1,11 @@
 // Layout Shift Tracking
 // 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: "Layout-Shift-Loading-and-Interaction", status: "unsupported", error: "layout-shift entries not supported in this browser" };
+  }
   // CLS thresholds
   const valueToRating = (score) =>
     score <= 0.1 ? "good" : score <= 0.25 ? "needs-improvement" : "poor";
@@ -18,11 +22,26 @@
     poor: "🔴",
   };
 
-  // Track all shifts
+  // Track all shifts. CLS is the largest session window: shifts less than 1s apart,
+  // in a window of at most 5s.
   let totalCLS = 0;
+  let sessionValue = 0;
+  let sessionFirst = null;
+  let sessionLast = null;
   const allShifts = [];
   const elementShifts = new Map(); // Track shifts per element
 
+  // The five elements that shifted the most (same value at start and in the summary)
+  const getTopElements = () =>
+    Array.from(elementShifts.entries())
+      .sort((a, b) => b[1].totalShift - a[1].totalShift)
+      .slice(0, 5)
+      .map(([selector, data]) => ({
+        selector,
+        shiftCount: data.count,
+        totalImpact: Math.round(data.totalShift * 10000) / 10000,
+      }));
+
   const getElementSelector = (element) => {
     if (!element) return "(unknown)";
     if (element.id) return `#${element.id}`;
@@ -39,7 +58,18 @@
       const countedForCLS = !entry.hadRecentInput;
 
       if (countedForCLS) {
-        totalCLS += entry.value;
+        if (
+          sessionLast &&
+          entry.startTime - sessionLast.startTime < 1000 &&
+          entry.startTime - sessionFirst.startTime < 5000
+        ) {
+          sessionValue += entry.value;
+        } else {
+          sessionValue = entry.value;
+          sessionFirst = entry;
+        }
+        sessionLast = entry;
+        totalCLS = Math.max(totalCLS, sessionValue);
       }
 
       // Get affected elements
@@ -81,7 +111,7 @@
           `font-weight: bold; color: ${countedForCLS ? clsColor : "#888"};`
         );
 
-        console.log(`%cCumulative CLS: ${totalCLS.toFixed(4)}`, `color: ${clsColor}; font-weight: bold;`);
+        console.log(`%cCurrent CLS: ${totalCLS.toFixed(4)}`, `color: ${clsColor}; font-weight: bold;`);
         console.log(`   Time: ${Math.round(entry.startTime)}ms`);
         console.log(`   Had recent input: ${entry.hadRecentInput ? "Yes (excluded from CLS)" : "No"}`);
 
@@ -205,10 +235,7 @@
 
     console.groupEnd();
 
-    const topElementsData = Array.from(elementShifts.entries())
-      .sort((a, b) => b[1].totalShift - a[1].totalShift)
-      .slice(0, 5)
-      .map(([selector, data]) => ({ selector, shiftCount: data.count, totalImpact: Math.round(data.totalShift * 10000) / 10000 }));
+    const topElementsData = getTopElements();
     return {
       script: "Layout-Shift-Loading-and-Interaction",
       status: "ok",
@@ -227,6 +254,10 @@
     };
   };
 
+  // Buffered entries reach the observer callback asynchronously; wait for them so the
+  // summary below (and the return value) reflect shifts that happened before this ran.
+  await new Promise((resolve) => setTimeout(resolve, 100));
+
   // Initial message
   const rating = valueToRating(totalCLS);
   const icon = RATING_ICONS[rating];
@@ -240,11 +271,10 @@
     ""
   );
 
-  // Synchronous return for agent (buffered layout-shift entries)
-  const clsBufferedSync = performance.getEntriesByType("layout-shift")
-    .reduce((sum, e) => !e.hadRecentInput ? sum + e.value : sum, 0);
-  const countedSync = performance.getEntriesByType("layout-shift").filter((e) => !e.hadRecentInput).length;
-  const excludedSync = performance.getEntriesByType("layout-shift").filter((e) => e.hadRecentInput).length;
+  // Return for agent (shifts collected by the buffered observer above)
+  const clsBufferedSync = totalCLS;
+  const countedSync = allShifts.filter((s) => s.countedForCLS).length;
+  const excludedSync = allShifts.length - countedSync;
   const clsRatingSync = valueToRating(clsBufferedSync);
   return {
     script: "Layout-Shift-Loading-and-Interaction",
@@ -259,6 +289,7 @@
       shiftCount: countedSync + excludedSync,
       countedShifts: countedSync,
       excludedShifts: excludedSync,
+      topElements: getTopElements(),
     },
     message: "Layout shift tracking active. Call getLayoutShiftSummary() for full element attribution.",
     getDataFn: "getLayoutShiftSummary",

package/snippets/Interaction/Long-Animation-Frames-Helpers.js

@@ -354,6 +354,33 @@
       return capturedFrames;
     },
 
+    /**
+     * Get a structured summary (the value agents read through getDataFn)
+     */
+    getData() {
+      const blocking = capturedFrames.filter((f) => f.blockingDuration > 0);
+      const worst = capturedFrames.reduce((max, f) => Math.max(max, f.blockingDuration), 0);
+      return {
+        script: "Long-Animation-Frames-Helpers",
+        status: "ok",
+        count: capturedFrames.length,
+        details: {
+          withBlockingTime: blocking.length,
+          totalBlockingTimeMs: Math.round(blocking.reduce((sum, f) => sum + f.blockingDuration, 0)),
+          worstBlockingMs: Math.round(worst),
+        },
+        items: [...capturedFrames]
+          .sort((a, b) => b.duration - a.duration)
+          .slice(0, 20)
+          .map((f) => ({
+            startTimeMs: Math.round(f.startTime),
+            durationMs: Math.round(f.duration),
+            blockingDurationMs: Math.round(f.blockingDuration),
+            scriptCount: f.scripts.length,
+          })),
+      };
+    },
+
     /**
      * Clear all captured data
      */
@@ -392,6 +419,6 @@
     script: "Long-Animation-Frames-Helpers",
     status: "tracking",
     message: "LoAF Helpers loaded. Use loafHelpers.summary(), loafHelpers.topScripts(), etc. Call loafHelpers.getRawData() to get raw frame data.",
-    getDataFn: "loafHelpers.getRawData",
+    getDataFn: "loafHelpers.getData",
   };
 })();

package/snippets/Interaction/Long-Animation-Frames-Script-Attribution.js

@@ -132,6 +132,14 @@
       category: data.category,
       durationMs: Math.round(data.duration),
       count: data.count,
+      functions: [...data.functions]
+        .sort((a, b) => b.duration - a.duration)
+        .slice(0, 5)
+        .map((fn) => ({
+          name: fn.name,
+          invoker: fn.invoker,
+          durationMs: Math.round(fn.duration),
+        })),
     })),
   };
 })();

package/snippets/Interaction/Long-Animation-Frames.js

@@ -77,6 +77,27 @@
     };
   };
 
+  // Item returned for agents: the same shape at start and in the summary
+  const toItem = (frame) => ({
+    startTimeMs: frame.startTime,
+    durationMs: frame.duration,
+    blockingDurationMs: frame.blockingDuration,
+    scripts: [...frame.scripts]
+      .sort((a, b) => b.duration - a.duration)
+      .slice(0, 10)
+      .map((s) => ({
+        invoker: s.invoker,
+        source: s.source,
+        durationMs: s.duration,
+        forcedStyleAndLayoutMs: s.forcedStyleAndLayout,
+      })),
+  });
+  const topFrames = (frames) =>
+    [...frames]
+      .sort((a, b) => b.blockingDuration - a.blockingDuration)
+      .slice(0, 20)
+      .map(toItem);
+
   const overlap = (e1, e2) =>
     e1.startTime < e2.startTime + e2.duration &&
     e2.startTime < e1.startTime + e1.duration;
@@ -164,7 +185,7 @@
   });
 
   loafObserver.observe({ type: "long-animation-frame", buffered: true });
-  eventObserver.observe({ type: "event", buffered: true });
+  eventObserver.observe({ type: "event", buffered: true, durationThreshold: 16 });
 
   // Summary function
   window.getLoAFSummary = () => {
@@ -173,7 +194,13 @@
     if (allLoAFs.length === 0) {
       console.log("   No long animation frames recorded.");
       console.groupEnd();
-      return;
+      return {
+        script: "Long-Animation-Frames",
+        status: "ok",
+        count: 0,
+        details: { totalLoAFs: 0, withBlockingTime: 0, totalBlockingTimeMs: 0, worstBlockingMs: 0, topScripts: [] },
+        items: [],
+      };
     }
 
     const blocking = allLoAFs.filter((l) => l.blockingDuration > 0);
@@ -266,6 +293,7 @@
           .slice(0, 5)
           .map((s) => ({ invoker: s.invoker, source: s.source, totalDurationMs: Math.round(s.totalDuration), count: s.count })),
       },
+      items: topFrames(allLoAFs),
     };
   };
 
@@ -292,6 +320,7 @@
       totalBlockingTimeMs: Math.round(totalBlockingSync),
       worstBlockingMs: Math.round(worstBlockingSync),
     },
+    items: topFrames(loafBuffered.map(processLoAF)),
     message: "Tracking long animation frames. Call getLoAFSummary() for full script attribution.",
     getDataFn: "getLoAFSummary",
   };

package/snippets/Interaction/LongTask.js

@@ -1,7 +1,11 @@
 // Long Tasks Tracking
 // https://webperf-snippets.nucliweb.net
 
-(() => {
+(async () => {
+  if (!PerformanceObserver.supportedEntryTypes?.includes("longtask")) {
+    console.warn("⚠️ longtask entries are not supported in this browser.");
+    return { script: "LongTask", status: "unsupported", error: "longtask entries not supported in this browser" };
+  }
   const formatMs = (ms) => `${Math.round(ms)}ms`;
 
   // Severity helpers
@@ -14,6 +18,19 @@
 
   // Track all long tasks
   const allTasks = [];
+
+  // Item returned for agents: the same shape at start and in the summary. Slowest first, at most 50.
+  const toItems = (tasks) =>
+    [...tasks]
+      .sort((a, b) => b.duration - a.duration)
+      .slice(0, 50)
+      .map((t) => ({
+        startTimeMs: Math.round(t.startTime),
+        durationMs: Math.round(t.duration),
+        blockingTimeMs: Math.round(t.blockingTime),
+        severity: t.severity,
+        attribution: t.attribution,
+      }));
   let totalBlockingTime = 0;
 
   try {
@@ -79,7 +96,18 @@
         console.log("   No long tasks recorded.");
         console.log("   This is good! The main thread has been responsive.");
         console.groupEnd();
-        return;
+        return {
+          script: "LongTask",
+          status: "ok",
+          count: 0,
+          details: {
+            totalBlockingTimeMs: 0,
+            worstTaskMs: 0,
+            avgDurationMs: 0,
+            bySeverity: { critical: 0, high: 0, medium: 0, low: 0 },
+          },
+          items: [],
+        };
       }
 
       const durations = allTasks.map((t) => t.duration);
@@ -119,7 +147,7 @@
         console.log("");
         console.log("%c⏱️ Timeline:", "font-weight: bold;");
 
-        const tableData = allTasks
+        const tableData = [...allTasks]
           .sort((a, b) => b.duration - a.duration)
           .slice(0, 10)
           .map((t) => {
@@ -160,6 +188,7 @@
           avgDurationMs: Math.round(avg),
           bySeverity,
         },
+        items: toItems(allTasks),
       };
     };
 
@@ -172,8 +201,10 @@
       ""
     );
 
-    // Synchronous return for agent (buffered entries)
-    const longtaskBuffered = performance.getEntriesByType("longtask");
+    // Return for agent. Chrome only exposes longtask entries through a PerformanceObserver,
+    // so wait for the buffered observer above to deliver them.
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    const longtaskBuffered = allTasks;
     const totalBlockingSync = longtaskBuffered.reduce((sum, t) => sum + Math.max(0, t.duration - 50), 0);
     const worstTaskSync = longtaskBuffered.length > 0 ? Math.max(...longtaskBuffered.map((t) => t.duration)) : 0;
     const bySeveritySync = {
@@ -191,6 +222,7 @@
         worstTaskMs: Math.round(worstTaskSync),
         bySeverity: bySeveritySync,
       },
+      items: toItems(allTasks),
       message: "Tracking long tasks. Call getLongTaskSummary() for statistics.",
       getDataFn: "getLongTaskSummary",
     };