webperf-snippets 0.1.0

package/snippets/Interaction/Scroll-Performance.js

@@ -0,0 +1,359 @@
+// Scroll Performance Analysis
+// https://webperf-snippets.nucliweb.net
+
+(() => {
+  const formatMs = (ms) => `${ms.toFixed(1)}ms`;
+  const formatFps = (fps) => `${fps.toFixed(0)} fps`;
+
+  const TARGET_FRAME_MS = 1000 / 60; // ~16.67ms at 60fps
+  const DROP_THRESHOLD_MS = TARGET_FRAME_MS * 1.5; // ~25ms = below 40fps
+
+  const RATING = {
+    good: { icon: "🟢", color: "#0CCE6A", label: "Good" },
+    "needs-improvement": { icon: "🟡", color: "#FFA400", label: "Needs Improvement" },
+    poor: { icon: "🔴", color: "#FF4E42", label: "Poor" },
+  };
+
+  const fpsRating = (fps) =>
+    fps >= 55 ? "good" : fps >= 40 ? "needs-improvement" : "poor";
+
+  // ─── 1. PASSIVE EVENT LISTENER DETECTION ────────────────────────────────────
+  // Detects scroll/touch listeners registered without { passive: true }.
+  // Non-passive listeners delay scroll by forcing the browser to wait for JS.
+
+  const nonPassiveListeners = [];
+  const SCROLL_EVENT_TYPES = new Set([
+    "scroll", "wheel", "touchstart", "touchmove", "touchend",
+  ]);
+
+  const _origAddEventListener = EventTarget.prototype.addEventListener;
+  EventTarget.prototype.addEventListener = function (type, listener, options) {
+    if (SCROLL_EVENT_TYPES.has(type)) {
+      const isPassive =
+        options === true
+          ? false // old-style capture boolean, not passive
+          : typeof options === "object" && options !== null
+          ? options.passive === true
+          : false;
+
+      if (!isPassive) {
+        const entry = {
+          type,
+          element: this.tagName || this.constructor?.name || "unknown",
+          id: this.id || "",
+          passive: false,
+        };
+        nonPassiveListeners.push(entry);
+        console.warn(
+          `%c⚠️ Non-passive "${type}" listener on <${entry.element}${
+            entry.id ? `#${entry.id}` : ""
+          }>`,
+          "color: #FFA400; font-weight: bold;",
+          this
+        );
+        console.warn(
+          "   Fix: add { passive: true } to improve scroll performance."
+        );
+      }
+    }
+    return _origAddEventListener.call(this, type, listener, options);
+  };
+
+  // ─── 2. SCROLL FPS MEASUREMENT ──────────────────────────────────────────────
+  // Tracks requestAnimationFrame timing during active scroll sessions.
+
+  const sessions = [];
+  let currentSession = null;
+  let rafId = null;
+  let lastFrameTime = null;
+  let endTimer = null;
+
+  const trackFrame = (now) => {
+    if (!currentSession) return;
+    if (lastFrameTime !== null) {
+      const frameTime = now - lastFrameTime;
+      currentSession.frames.push(frameTime);
+      if (frameTime > DROP_THRESHOLD_MS) currentSession.drops++;
+    }
+    lastFrameTime = now;
+    rafId = requestAnimationFrame(trackFrame);
+  };
+
+  const endSession = () => {
+    if (!currentSession) return;
+    cancelAnimationFrame(rafId);
+
+    const { frames, drops } = currentSession;
+    if (frames.length < 2) {
+      currentSession = null;
+      return;
+    }
+
+    const avgFrameTime = frames.reduce((a, b) => a + b, 0) / frames.length;
+    const avgFps = 1000 / avgFrameTime;
+    const minFps = 1000 / Math.max(...frames);
+    const dropRate = (drops / frames.length) * 100;
+    const rating = fpsRating(avgFps);
+    const r = RATING[rating];
+
+    const session = {
+      avgFps,
+      minFps,
+      frames: frames.length,
+      drops,
+      dropRate,
+      rating,
+    };
+    sessions.push(session);
+
+    console.groupCollapsed(
+      `%c${r.icon} Scroll: avg ${formatFps(avgFps)} — ${frames.length} frames, ${drops} drop(s)`,
+      `font-weight: bold; color: ${r.color};`
+    );
+    console.table([
+      {
+        "Avg FPS": formatFps(avgFps),
+        "Min FPS": formatFps(minFps),
+        "Frames": frames.length,
+        "Drops": drops,
+        "Drop Rate": `${dropRate.toFixed(1)}%`,
+        "Rating": r.label,
+      },
+    ]);
+    if (drops > 0) {
+      const worstMs = Math.max(...frames);
+      console.log(
+        `   Worst frame: ${formatMs(worstMs)} (target: ${formatMs(TARGET_FRAME_MS)})`
+      );
+    }
+    console.groupEnd();
+
+    currentSession = null;
+    lastFrameTime = null;
+  };
+
+  window.addEventListener(
+    "scroll",
+    () => {
+      if (!currentSession) {
+        currentSession = { frames: [], drops: 0 };
+        lastFrameTime = null;
+        rafId = requestAnimationFrame(trackFrame);
+      }
+      clearTimeout(endTimer);
+      endTimer = setTimeout(endSession, 200);
+    },
+    { passive: true }
+  );
+
+  // ─── 3. CSS SCROLL AUDIT ────────────────────────────────────────────────────
+  // Checks CSS properties that affect scroll compositing and performance.
+
+  const auditScrollCSS = () => {
+    const results = {
+      smoothScrollElements: [],
+      willChangeElements: [],
+      contentVisibilityElements: [],
+      overscrollElements: [],
+    };
+
+    document.querySelectorAll("*").forEach((el) => {
+      const cs = getComputedStyle(el);
+      const label =
+        el.tagName.toLowerCase() +
+        (el.id ? `#${el.id}` : el.className
+          ? `.${String(el.className).trim().split(/\s+/)[0]}`
+          : "");
+
+      if (cs.scrollBehavior === "smooth") {
+        results.smoothScrollElements.push(label);
+      }
+      if (cs.willChange && cs.willChange !== "auto") {
+        results.willChangeElements.push({ element: label, value: cs.willChange });
+      }
+      if (cs.contentVisibility && cs.contentVisibility !== "visible") {
+        results.contentVisibilityElements.push({
+          element: label,
+          value: cs.contentVisibility,
+        });
+      }
+      if (cs.overscrollBehavior && cs.overscrollBehavior !== "auto") {
+        results.overscrollElements.push({
+          element: label,
+          value: cs.overscrollBehavior,
+        });
+      }
+    });
+
+    return results;
+  };
+
+  // ─── 4. SUMMARY ─────────────────────────────────────────────────────────────
+
+  window.getScrollSummary = () => {
+    console.group(
+      "%c📜 Scroll Performance Summary",
+      "font-weight: bold; font-size: 14px;"
+    );
+
+    // — Session stats
+    if (sessions.length === 0) {
+      console.log("   No scroll sessions recorded yet. Scroll the page first.");
+    } else {
+      const allFps = sessions.map((s) => s.avgFps);
+      const overallAvg = allFps.reduce((a, b) => a + b, 0) / allFps.length;
+      const worstAvg = Math.min(...allFps);
+      const totalDrops = sessions.reduce((a, s) => a + s.drops, 0);
+
+      console.log("%cScroll Sessions:", "font-weight: bold;");
+      console.table(
+        sessions.map((s, i) => ({
+          "#": i + 1,
+          "Avg FPS": formatFps(s.avgFps),
+          "Min FPS": formatFps(s.minFps),
+          "Drops": s.drops,
+          "Drop Rate": `${s.dropRate.toFixed(1)}%`,
+          "Rating": RATING[s.rating].icon + " " + RATING[s.rating].label,
+        }))
+      );
+      console.log(`   Overall avg FPS: ${formatFps(overallAvg)}`);
+      console.log(`   Worst session avg: ${formatFps(worstAvg)}`);
+      console.log(`   Total frame drops: ${totalDrops}`);
+    }
+
+    // — Passive listeners
+    console.log("");
+    console.log("%cPassive Event Listeners:", "font-weight: bold;");
+    if (nonPassiveListeners.length === 0) {
+      console.log(
+        "   ✅ No non-passive scroll listeners detected since snippet loaded."
+      );
+    } else {
+      console.log(
+        `   ❌ ${nonPassiveListeners.length} non-passive listener(s) found:`
+      );
+      console.table(nonPassiveListeners);
+      console.log(
+        "   Fix: addEventListener('scroll', fn, { passive: true })"
+      );
+    }
+
+    // — CSS audit
+    console.log("");
+    console.log("%cCSS Scroll Audit:", "font-weight: bold;");
+    const css = auditScrollCSS();
+
+    if (css.contentVisibilityElements.length > 0) {
+      console.log(
+        `   ✅ content-visibility on ${css.contentVisibilityElements.length} element(s) — reduces off-screen layout cost.`
+      );
+    } else {
+      console.log(
+        "   ℹ️ content-visibility not used — consider it for long pages."
+      );
+    }
+
+    if (css.smoothScrollElements.length > 0) {
+      console.log(
+        `   ℹ️ scroll-behavior: smooth on ${css.smoothScrollElements.length} element(s).`
+      );
+      console.log(
+        "      Smooth scroll can cause jank if driven by JS instead of CSS."
+      );
+    }
+
+    if (css.willChangeElements.length > 0) {
+      console.log(
+        `   ⚠️ will-change set on ${css.willChangeElements.length} element(s):`
+      );
+      console.table(css.willChangeElements);
+      console.log(
+        "      will-change creates compositor layers — use sparingly to avoid memory overhead."
+      );
+    }
+
+    if (css.overscrollElements.length > 0) {
+      console.log(
+        `   ℹ️ overscroll-behavior set on ${css.overscrollElements.length} element(s):`
+      );
+      console.table(css.overscrollElements);
+    }
+
+    // — Recommendations
+    const hasJank = sessions.some((s) => s.rating !== "good");
+    const hasNonPassive = nonPassiveListeners.length > 0;
+
+    if (hasJank || hasNonPassive) {
+      console.log("");
+      console.log(
+        "%c💡 Recommendations:",
+        "font-weight: bold; color: #3b82f6;"
+      );
+      if (hasNonPassive) {
+        console.log(
+          "   • Add { passive: true } to all scroll/touch event listeners"
+        );
+      }
+      if (hasJank) {
+        console.log("   • Avoid reading layout properties during scroll (getBoundingClientRect, offsetTop)");
+        console.log("   • Debounce or throttle scroll event handlers");
+        console.log("   • Move scroll-driven animations to CSS or use Animation Worklet");
+        console.log("   • Use content-visibility: auto for long lists or off-screen sections");
+        console.log("   • Prefer transform over top/left for animated elements during scroll");
+      }
+    }
+
+    console.groupEnd();
+
+    const cssAuditResult = auditScrollCSS();
+    return {
+      script: "Scroll-Performance",
+      status: "ok",
+      details: {
+        nonPassiveListeners: nonPassiveListeners.length,
+        cssAudit: {
+          smoothScrollElements: cssAuditResult.smoothScrollElements.length,
+          willChangeElements: cssAuditResult.willChangeElements.length,
+          contentVisibilityElements: cssAuditResult.contentVisibilityElements.length,
+        },
+        sessionCount: sessions.length,
+        ...(sessions.length > 0 ? {
+          avgFps: Math.round(sessions.reduce((a, s) => a + s.avgFps, 0) / sessions.length),
+          worstSessionFps: Math.round(Math.min(...sessions.map((s) => s.avgFps))),
+          totalDrops: sessions.reduce((a, s) => a + s.drops, 0),
+        } : {}),
+      },
+    };
+  };
+
+  // ─── INIT ────────────────────────────────────────────────────────────────────
+
+  console.log(
+    "%c📜 Scroll Performance Analysis Active",
+    "font-weight: bold; font-size: 14px;"
+  );
+  console.log(
+    "   Scroll to measure FPS. Non-passive listener registrations will be warned."
+  );
+  console.log(
+    "   Call %cgetScrollSummary()%c for the full report.",
+    "font-family: monospace; background: #f3f4f6; padding: 2px 4px;",
+    ""
+  );
+
+  const cssSnapshot = auditScrollCSS();
+  return {
+    script: "Scroll-Performance",
+    status: "tracking",
+    details: {
+      nonPassiveListeners: nonPassiveListeners.length,
+      cssAudit: {
+        smoothScrollElements: cssSnapshot.smoothScrollElements.length,
+        willChangeElements: cssSnapshot.willChangeElements.length,
+        contentVisibilityElements: cssSnapshot.contentVisibilityElements.length,
+      },
+    },
+    message: "Scroll performance tracking active. Scroll the page then call getScrollSummary() for FPS data.",
+    getDataFn: "getScrollSummary",
+  };
+})();

package/snippets/Interaction/WORKFLOWS.md

@@ -0,0 +1,205 @@
+## Common Workflows
+
+### Complete Interaction Performance Audit
+
+When the user asks for interaction analysis or "audit responsiveness":
+
+1. **Interactions.js** - List all user interactions with timing
+2. **Input-Latency-Breakdown.js** - Break down interaction phases
+3. **Long-Animation-Frames.js** - Detect blocking animation frames
+4. **LongTask.js** - Identify long tasks blocking the main thread
+5. **Scroll-Performance.js** - Measure scroll smoothness
+
+### INP Deep Dive
+
+When INP is slow (>200ms) or the user asks "debug INP" or "slow interactions":
+
+1. **Interactions.js** - Identify which interactions are slow
+2. **Input-Latency-Breakdown.js** - Break down into input delay, processing time, presentation delay
+3. **Long-Animation-Frames.js** - Find animation frames >50ms that block interactions
+4. **Long-Animation-Frames-Script-Attribution.js** - Identify scripts causing the blocking
+5. **Long-Animation-Frames-Helpers.js** - Get detailed timing and attribution helpers
+
+### Scroll Jank Investigation
+
+When the user reports "scroll jank", "choppy scrolling", or "scroll performance issues":
+
+1. **Scroll-Performance.js** - Measure scroll smoothness and frame drops
+2. **Long-Animation-Frames.js** - Detect frames causing jank (>50ms)
+3. **Layout-Shift-Loading-and-Interaction.js** - Check for layout shifts during scroll
+4. **Long-Animation-Frames-Script-Attribution.js** - Find scripts running during scroll
+
+### Main Thread Blocking Analysis
+
+When the page feels unresponsive or the user asks "why is the page frozen":
+
+1. **LongTask.js** - List all tasks >50ms blocking the main thread
+2. **Long-Animation-Frames.js** - Correlate with animation frame timing
+3. **Long-Animation-Frames-Script-Attribution.js** - Attribute blocking to specific scripts
+4. Cross-reference with **webperf-loading** skill:
+   - JS-Execution-Time-Breakdown.js (script parsing/execution time)
+   - First-And-Third-Party-Script-Info.js (identify third-party blockers)
+
+### Layout Shift During Interaction
+
+When the user reports "things move when I click" or CLS issues during interaction:
+
+1. **Layout-Shift-Loading-and-Interaction.js** - Separate loading vs interaction shifts
+2. **Interactions.js** - Correlate shifts with specific interactions
+3. **CLS.js** (from Core Web Vitals skill) - Measure total CLS
+4. Cross-reference with **webperf-media** skill:
+   - Image-Element-Audit.js (images without dimensions causing shifts)
+
+### Animation Performance Analysis
+
+When animations feel sluggish or the user asks "debug animation performance":
+
+1. **Long-Animation-Frames.js** - Identify frames taking too long to render
+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
+
+### Third-Party Script Impact on Interactions
+
+When interactions are slow and third-party scripts are suspected:
+
+1. **Long-Animation-Frames-Script-Attribution.js** - Identify third-party scripts in long frames
+2. **LongTask.js** - Measure long task frequency
+3. Cross-reference with **webperf-loading** skill:
+   - First-And-Third-Party-Script-Info.js (list all third-party scripts)
+   - First-And-Third-Party-Script-Timings.js (measure script loading impact)
+   - Script-Loading.js (check for blocking scripts)
+
+## Decision Tree
+
+Use this decision tree to automatically run follow-up snippets based on results:
+
+### After Interactions.js
+
+- **If any interaction > 200ms** → Run **Input-Latency-Breakdown.js** on slow interactions; also run **webperf-core-web-vitals:INP.js** for official INP measurement
+- **If many interactions > 200ms** → Main thread congestion, run:
+  1. **Long-Animation-Frames.js** (blocking frames)
+  2. **LongTask.js** (long tasks)
+  3. **Long-Animation-Frames-Script-Attribution.js** (culprit scripts)
+- **If specific interaction types are slow (e.g., click vs keyboard)** → Focus on that interaction type
+- **If interactions occur during page load** → Cross-check with **webperf-loading:JS-Execution-Time-Breakdown.js**
+
+### After Input-Latency-Breakdown.js
+
+- **If Input Delay > 50ms** → Main thread was busy, run:
+  1. **Long-Animation-Frames.js** (what was blocking)
+  2. **LongTask.js** (long task before interaction)
+- **If Processing Time > 100ms** → Heavy event handlers, run:
+  1. **Long-Animation-Frames-Script-Attribution.js** (which scripts)
+  2. **webperf-loading:First-And-Third-Party-Script-Info.js** (third-party involvement)
+- **If Presentation Delay > 50ms** → Rendering bottleneck, run:
+  1. **Long-Animation-Frames.js** (frame rendering time)
+  2. **Layout-Shift-Loading-and-Interaction.js** (check for layout work)
+
+### After Long-Animation-Frames.js
+
+- **If many frames > 50ms** → Run **Long-Animation-Frames-Script-Attribution.js** to identify causes
+- **If frames > 100ms** → Critical blocking, run:
+  1. **Long-Animation-Frames-Script-Attribution.js** (detailed attribution)
+  2. **LongTask.js** (related long tasks)
+  3. **webperf-loading:JS-Execution-Time-Breakdown.js** (script execution cost)
+- **If frames occur during scroll** → Run **Scroll-Performance.js** to measure impact
+- **If frames occur during page load** → Cross-check with **webperf-loading:Event-Processing-Time.js**
+
+### After Long-Animation-Frames-Script-Attribution.js
+
+- **If third-party scripts are causing long frames** → Run:
+  1. **webperf-loading:First-And-Third-Party-Script-Info.js** (list all third-party scripts)
+  2. **webperf-loading:Script-Loading.js** (check loading strategy)
+  3. Recommend deferring or removing problematic scripts
+- **If first-party scripts are causing long frames** → Recommend:
+  - Code splitting
+  - Debouncing/throttling event handlers
+  - Web Workers for heavy computation
+- **If forced reflow/layout detected** → Analyze DOM manipulation patterns
+
+### After LongTask.js
+
+- **If many long tasks (>5)** → Main thread is congested, run:
+  1. **Long-Animation-Frames-Script-Attribution.js** (detailed attribution)
+  2. **webperf-loading:JS-Execution-Time-Breakdown.js** (script execution analysis)
+  3. **webperf-loading:First-And-Third-Party-Script-Info.js** (identify heavy scripts)
+- **If long tasks > 500ms** → Critical blocking, investigate:
+  - Synchronous third-party scripts
+  - Heavy computation without Web Workers
+  - Excessive DOM manipulation
+- **If long tasks correlate with interactions** → Run **Interactions.js** to see impact
+
+### After Scroll-Performance.js
+
+- **If scroll FPS < 30** → Severe jank, run:
+  1. **Long-Animation-Frames.js** (blocking frames during scroll)
+  2. **Long-Animation-Frames-Script-Attribution.js** (scripts running on scroll)
+  3. **Layout-Shift-Loading-and-Interaction.js** (layout work during scroll)
+- **If scroll FPS 30-50** → Noticeable jank, investigate:
+  - Scroll event handlers
+  - Passive event listeners
+  - CSS will-change properties
+- **If scroll FPS > 50** → Good, but check for layout shifts during scroll
+
+### After Layout-Shift-Loading-and-Interaction.js
+
+- **If shifts occur during page load** → Cross-reference with **webperf-core-web-vitals:CLS.js**
+- **If shifts occur during interaction** → This impacts INP and UX, investigate:
+  1. Dynamic content insertion
+  2. Images/ads loading without dimensions
+  3. Font swaps (run **webperf-loading:Fonts-Preloaded-Loaded-and-used-above-the-fold.js**)
+- **If shifts occur during scroll** → Run **Scroll-Performance.js** to measure impact
+
+### After Long-Animation-Frames-Helpers.js
+
+This is a utility snippet, use results to:
+- Understand frame timing in detail
+- Identify precise script attribution
+- Measure style/layout/paint phases
+- No automatic follow-up, use data to inform next steps
+
+### Performance Budget Thresholds
+
+Use these thresholds to automatically trigger follow-up analysis:
+
+**INP Thresholds:**
+- **Good**: ≤ 200ms → Monitor, no action needed
+- **Needs Improvement**: 200-500ms → Run Input-Latency-Breakdown.js
+- **Poor**: > 500ms → Run full INP debugging workflow (5 snippets)
+
+**Long Animation Frames:**
+- **Warning**: > 50ms → Run Long-Animation-Frames-Script-Attribution.js
+- **Critical**: > 100ms → Run full main thread blocking workflow
+
+**Long Tasks:**
+- **Warning**: > 50ms → Monitor frequency
+- **Critical**: > 200ms or >5 tasks per second → Run attribution and script analysis
+
+**Scroll Performance:**
+- **Good**: ≥ 50 FPS → Monitor
+- **Needs Improvement**: 30-50 FPS → Run Long-Animation-Frames.js
+- **Poor**: < 30 FPS → Run full scroll jank workflow
+
+**Interaction Frequency:**
+- **If >10 interactions/second** → User is actively interacting, prioritize INP optimization
+- **If <1 interaction/5 seconds** → Interactions are rare, focus on first interaction responsiveness
+
+### Multi-Metric Correlation
+
+When multiple interaction metrics are poor:
+
+- **If Long Tasks AND Long Animation Frames both detected** → Shared root cause:
+  1. Run Long-Animation-Frames-Script-Attribution.js
+  2. Likely heavy JavaScript execution
+  3. Consider code splitting or Web Workers
+
+- **If INP slow AND CLS high** → Interaction-triggered layout shifts:
+  1. Run Layout-Shift-Loading-and-Interaction.js
+  2. Correlate shift timing with interaction timing
+  3. Check for dynamic content insertion
+
+- **If Scroll jank AND Long Animation Frames** → Scroll handlers blocking main thread:
+  1. Run Long-Animation-Frames-Script-Attribution.js during scroll
+  2. Check for non-passive scroll listeners
+  3. Audit scroll-triggered animations