webperf-snippets 0.2.0 → 0.3.0

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",
     };

package/snippets/Interaction/Scroll-Performance.js

@@ -188,6 +188,38 @@
     return results;
   };
 
+  // Findings as homogeneous items and actionable issues (same value at start and in the summary)
+  const buildFindings = (css) => {
+    const seen = new Set();
+    const items = [];
+    const add = (kind, target, detail) => {
+      const key = `${kind}|${target}|${detail}`;
+      if (seen.has(key)) return;
+      seen.add(key);
+      items.push({ kind, target, detail });
+    };
+    nonPassiveListeners.forEach((l) =>
+      add("non-passive-listener", `${l.element}${l.id ? `#${l.id}` : ""}`, l.type)
+    );
+    css.willChangeElements.forEach((e) => add("will-change", e.element, e.value));
+    css.overscrollElements.forEach((e) => add("overscroll", e.element, e.value));
+
+    const issues = [];
+    if (nonPassiveListeners.length > 0) {
+      issues.push({
+        severity: "warning",
+        message: `${nonPassiveListeners.length} non-passive scroll or touch listener(s). Add { passive: true } so scrolling does not wait for JavaScript.`,
+      });
+    }
+    if (css.willChangeElements.length > 0) {
+      issues.push({
+        severity: "info",
+        message: `will-change is set on ${css.willChangeElements.length} element(s). Remove it from elements that do not animate, since each one keeps a compositor layer.`,
+      });
+    }
+    return { items: items.slice(0, 50), issues };
+  };
+
   // ─── 4. SUMMARY ─────────────────────────────────────────────────────────────
 
   window.getScrollSummary = () => {
@@ -306,6 +338,7 @@
     console.groupEnd();
 
     const cssAuditResult = auditScrollCSS();
+    const findings = buildFindings(cssAuditResult);
     return {
       script: "Scroll-Performance",
       status: "ok",
@@ -315,6 +348,7 @@
           smoothScrollElements: cssAuditResult.smoothScrollElements.length,
           willChangeElements: cssAuditResult.willChangeElements.length,
           contentVisibilityElements: cssAuditResult.contentVisibilityElements.length,
+          overscrollElements: cssAuditResult.overscrollElements.length,
         },
         sessionCount: sessions.length,
         ...(sessions.length > 0 ? {
@@ -323,6 +357,8 @@
           totalDrops: sessions.reduce((a, s) => a + s.drops, 0),
         } : {}),
       },
+      items: findings.items,
+      issues: findings.issues,
     };
   };
 
@@ -342,6 +378,7 @@
   );
 
   const cssSnapshot = auditScrollCSS();
+  const initialFindings = buildFindings(cssSnapshot);
   return {
     script: "Scroll-Performance",
     status: "tracking",
@@ -351,8 +388,11 @@
         smoothScrollElements: cssSnapshot.smoothScrollElements.length,
         willChangeElements: cssSnapshot.willChangeElements.length,
         contentVisibilityElements: cssSnapshot.contentVisibilityElements.length,
+        overscrollElements: cssSnapshot.overscrollElements.length,
       },
     },
+    items: initialFindings.items,
+    issues: initialFindings.issues,
     message: "Scroll performance tracking active. Scroll the page then call getScrollSummary() for FPS data.",
     getDataFn: "getScrollSummary",
   };

package/snippets/Interaction/WORKFLOWS.md

@@ -58,6 +58,7 @@ When animations feel sluggish or the user asks "debug animation performance":
 2. **Long-Animation-Frames-Helpers.js** - Detailed frame timing analysis
 3. **Long-Animation-Frames-Script-Attribution.js** - Find scripts delaying frames
 4. **Scroll-Performance.js** - If scroll animations are involved
+5. **DOM-Size-and-Depth.js** - Check whether a large or deep DOM makes each style and layout pass expensive
 
 ### Third-Party Script Impact on Interactions
 
@@ -117,6 +118,7 @@ Use this decision tree to automatically run follow-up snippets based on results:
   - Debouncing/throttling event handlers
   - Web Workers for heavy computation
 - **If forced reflow/layout detected** → Analyze DOM manipulation patterns
+- **If time goes to style recalculation or layout** → Run **DOM-Size-and-Depth.js** to check the size of the tree
 
 ### After LongTask.js
 
@@ -130,6 +132,13 @@ Use this decision tree to automatically run follow-up snippets based on results:
   - Excessive DOM manipulation
 - **If long tasks correlate with interactions** → Run **Interactions.js** to see impact
 
+### After DOM-Size-and-Depth.js
+
+- **If total elements > 1400** → Recommend virtualizing long lists and loading off-screen content on demand
+- **If depth > 32** → Recommend flattening wrapper elements added by components
+- **If a single parent has > 60 children** → Recommend pagination or virtualization for that container
+- **If the DOM is within limits but interactions are still slow** → Run **Long-Animation-Frames-Script-Attribution.js** to find the scripts responsible
+
 ### After Scroll-Performance.js
 
 - **If scroll FPS < 30** → Severe jank, run: