webperf-snippets 1.15.0 → 1.17.0

package/snippets/Loading/Content-Visibility.js

@@ -1,320 +1,329 @@
 // Detect elements with content-visibility: auto and analyze optimization opportunities
 
-// @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})`;
+(() => {
+  // @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;
     }
-    parts.unshift(part);
-    if (matchesOne(parts.join(" > "))) break;
-    node = node.parentElement;
+    return parts.join(" > ");
   }
-  return parts.join(" > ");
-}
-// @end-shared uniqueSelector
-
-// An element with content-visibility: auto has no size before it first renders unless
-// contain-intrinsic-size gives one, so the page moves when it does. content-visibility: auto adds auto
-// to contain-intrinsic-size, so Chrome reports an element with no size as "auto none", also when the CSS
-// says none: what counts is whether the value has a length, as in "auto 500px".
-function lacksIntrinsicSize(value) {
-  return !/\d/.test(value);
-}
-
-function detectContentVisibility() {
-  // Create an object to store the results
-  const results = {
-    autoElements: [],
-    hiddenElements: [],
-    visibleElements: [],
-    nodeArray: [],
-  };
-
-  // Check if element is in viewport
-  function isInViewport(element) {
-    const rect = element.getBoundingClientRect();
-    return (
-      rect.top < window.innerHeight &&
-      rect.bottom > 0 &&
-      rect.left < window.innerWidth &&
-      rect.right > 0
-    );
+  // @end-shared uniqueSelector
+
+  // An element with content-visibility: auto has no size before it first renders unless
+  // contain-intrinsic-size gives one, so the page moves when it does. content-visibility: auto adds auto
+  // to contain-intrinsic-size, so Chrome reports an element with no size as "auto none", also when the CSS
+  // says none: what counts is whether the value has a length, as in "auto 500px".
+  function lacksIntrinsicSize(value) {
+    return !/\d/.test(value);
   }
 
-  // Get element dimensions and position
-  function getElementInfo(node) {
-    const rect = node.getBoundingClientRect();
-    const cs = window.getComputedStyle(node);
-
-    return {
-      selector: uniqueSelector(node),
-      contentVisibility: cs["content-visibility"],
-      containIntrinsicSize: cs["contain-intrinsic-size"] || "not set",
-      width: Math.round(rect.width),
-      height: Math.round(rect.height),
-      top: Math.round(rect.top + window.scrollY),
-      inViewport: isInViewport(node),
+  function detectContentVisibility() {
+    // Create an object to store the results
+    const results = {
+      autoElements: [],
+      hiddenElements: [],
+      visibleElements: [],
+      nodeArray: [],
     };
-  }
 
-  // Recursively find all elements with content-visibility
-  function findContentVisibilityElements(node) {
-    const cs = window.getComputedStyle(node);
-    const cv = cs["content-visibility"];
-
-    if (cv && cv !== "visible") {
-      const info = getElementInfo(node);
-
-      if (cv === "auto") {
-        results.autoElements.push(info);
-        results.nodeArray.push(node);
-      } else if (cv === "hidden") {
-        results.hiddenElements.push(info);
-      }
+    // Check if element is in viewport
+    function isInViewport(element) {
+      const rect = element.getBoundingClientRect();
+      return (
+        rect.top < window.innerHeight &&
+        rect.bottom > 0 &&
+        rect.left < window.innerWidth &&
+        rect.right > 0
+      );
     }
 
-    for (let i = 0; i < node.children.length; i++) {
-      findContentVisibilityElements(node.children[i]);
+    // Get element dimensions and position
+    function getElementInfo(node) {
+      const rect = node.getBoundingClientRect();
+      const cs = window.getComputedStyle(node);
+
+      return {
+        selector: uniqueSelector(node),
+        contentVisibility: cs["content-visibility"],
+        containIntrinsicSize: cs["contain-intrinsic-size"] || "not set",
+        width: Math.round(rect.width),
+        height: Math.round(rect.height),
+        top: Math.round(rect.top + window.scrollY),
+        inViewport: isInViewport(node),
+      };
     }
-  }
 
-  // Run the detection
-  findContentVisibilityElements(document.body);
+    // Recursively find all elements with content-visibility
+    function findContentVisibilityElements(node) {
+      const cs = window.getComputedStyle(node);
+      const cv = cs["content-visibility"];
 
-  // Display results
-  console.group("🔍 Content-Visibility Detection");
+      if (cv && cv !== "visible") {
+        const info = getElementInfo(node);
 
-  if (results.autoElements.length === 0 && results.hiddenElements.length === 0) {
-    console.log("%cNo content-visibility usage found.", "color: orange; font-weight: bold;");
-    console.log("");
-    console.log("💡 Consider applying content-visibility: auto to:");
-    console.log("   • Footer sections");
-    console.log("   • Below-the-fold content");
-    console.log("   • Long lists or card grids");
-    console.log("   • Tab content that is not initially visible");
-    console.log("   • Accordion/collapsible content");
-  } else {
-    // Auto elements
-    if (results.autoElements.length > 0) {
-      console.group("✅ content-visibility: auto");
-      console.log(`Found ${results.autoElements.length} element(s)`);
-      console.table(results.autoElements);
-      console.groupEnd();
-    }
+        if (cv === "auto") {
+          results.autoElements.push(info);
+          results.nodeArray.push(node);
+        } else if (cv === "hidden") {
+          results.hiddenElements.push(info);
+        }
+      }
 
-    // Hidden elements
-    if (results.hiddenElements.length > 0) {
-      console.group("🔒 content-visibility: hidden");
-      console.log(`Found ${results.hiddenElements.length} element(s)`);
-      console.table(results.hiddenElements);
-      console.groupEnd();
+      for (let i = 0; i < node.children.length; i++) {
+        findContentVisibilityElements(node.children[i]);
+      }
     }
 
-    // Check for missing contain-intrinsic-size
-    const missingIntrinsicSize = results.autoElements.filter(
-      (el) => lacksIntrinsicSize(el.containIntrinsicSize),
-    );
+    // Run the detection
+    findContentVisibilityElements(document.body);
 
-    if (missingIntrinsicSize.length > 0) {
-      console.group("⚠️ Missing contain-intrinsic-size");
-      console.log(
-        "%cThese elements lack contain-intrinsic-size, which may cause layout shifts:",
-        "color: #f59e0b; font-weight: bold",
-      );
-      console.table(
-        missingIntrinsicSize.map((el) => ({
-          selector: el.selector,
-          height: el.height + "px",
-        })),
-      );
+    // Display results
+    console.group("🔍 Content-Visibility Detection");
+
+    if (results.autoElements.length === 0 && results.hiddenElements.length === 0) {
+      console.log("%cNo content-visibility usage found.", "color: orange; font-weight: bold;");
       console.log("");
-      console.log("💡 Add contain-intrinsic-size to prevent CLS:");
-      console.log("   contain-intrinsic-size: auto 500px;");
-      console.groupEnd();
-    }
+      console.log("💡 Consider applying content-visibility: auto to:");
+      console.log("   • Footer sections");
+      console.log("   • Below-the-fold content");
+      console.log("   • Long lists or card grids");
+      console.log("   • Tab content that is not initially visible");
+      console.log("   • Accordion/collapsible content");
+    } else {
+      // Auto elements
+      if (results.autoElements.length > 0) {
+        console.group("✅ content-visibility: auto");
+        console.log(`Found ${results.autoElements.length} element(s)`);
+        console.table(results.autoElements);
+        console.groupEnd();
+      }
 
-    // Nodes for inspection
-    console.group("🔎 Elements for inspection");
-    console.log("Click to expand and inspect in Elements panel:");
-    results.nodeArray.forEach((node, i) => {
-      console.log(`${i + 1}. `, node);
-    });
-    console.groupEnd();
-  }
+      // Hidden elements
+      if (results.hiddenElements.length > 0) {
+        console.group("🔒 content-visibility: hidden");
+        console.log(`Found ${results.hiddenElements.length} element(s)`);
+        console.table(results.hiddenElements);
+        console.groupEnd();
+      }
 
-  console.groupEnd();
+      // Check for missing contain-intrinsic-size
+      const missingIntrinsicSize = results.autoElements.filter(
+        (el) => lacksIntrinsicSize(el.containIntrinsicSize),
+      );
 
-  return results;
-}
+      if (missingIntrinsicSize.length > 0) {
+        console.group("⚠️ Missing contain-intrinsic-size");
+        console.log(
+          "%cThese elements lack contain-intrinsic-size, which may cause layout shifts:",
+          "color: #f59e0b; font-weight: bold",
+        );
+        console.table(
+          missingIntrinsicSize.map((el) => ({
+            selector: el.selector,
+            height: el.height + "px",
+          })),
+        );
+        console.log("");
+        console.log("💡 Add contain-intrinsic-size to prevent CLS:");
+        console.log("   contain-intrinsic-size: auto 500px;");
+        console.groupEnd();
+      }
 
-// Analyze opportunities for content-visibility optimization
-// Options:
-//   - threshold: distance from viewport bottom to consider "offscreen" (default: 0)
-//   - minHeight: minimum element height in px (default: 100)
-//   - minChildren: minimum child elements to be considered (default: 5)
-function analyzeContentVisibilityOpportunities(options = {}) {
-  const { threshold = 0, minHeight = 100, minChildren = 5 } = options;
+      // Nodes for inspection
+      console.group("🔎 Elements for inspection");
+      console.log("Click to expand and inspect in Elements panel:");
+      results.nodeArray.forEach((node, i) => {
+        console.log(`${i + 1}. `, node);
+      });
+      console.groupEnd();
+    }
 
-  const viewportHeight = window.innerHeight;
-  const opportunities = [];
-  const processedElements = new Set();
+    console.groupEnd();
 
-  function estimateRenderSavings(childCount) {
-    const baseMs = childCount * 0.2;
-    if (baseMs < 5) return "Low (~" + baseMs.toFixed(1) + "ms)";
-    if (baseMs < 20) return "Medium (~" + baseMs.toFixed(1) + "ms)";
-    return "High (~" + baseMs.toFixed(1) + "ms)";
+    return results;
   }
 
-  function isAncestorProcessed(el) {
-    let parent = el.parentElement;
-    while (parent) {
-      if (processedElements.has(parent)) return true;
-      parent = parent.parentElement;
+  // Analyze opportunities for content-visibility optimization
+  // Options:
+  //   - threshold: distance from viewport bottom to consider "offscreen" (default: 0)
+  //   - minHeight: minimum element height in px (default: 100)
+  //   - minChildren: minimum child elements to be considered (default: 5)
+  function analyzeContentVisibilityOpportunities(options = {}) {
+    const { threshold = 0, minHeight = 100, minChildren = 5 } = options;
+
+    const viewportHeight = window.innerHeight;
+    const opportunities = [];
+    const processedElements = new Set();
+
+    function estimateRenderSavings(childCount) {
+      const baseMs = childCount * 0.2;
+      if (baseMs < 5) return "Low (~" + baseMs.toFixed(1) + "ms)";
+      if (baseMs < 20) return "Medium (~" + baseMs.toFixed(1) + "ms)";
+      return "High (~" + baseMs.toFixed(1) + "ms)";
     }
-    return false;
-  }
 
-  function analyzeElement(el) {
-    // Skip already processed or descendant of processed
-    if (processedElements.has(el) || isAncestorProcessed(el)) return;
+    function isAncestorProcessed(el) {
+      let parent = el.parentElement;
+      while (parent) {
+        if (processedElements.has(parent)) return true;
+        parent = parent.parentElement;
+      }
+      return false;
+    }
 
-    const rect = el.getBoundingClientRect();
-    const cs = window.getComputedStyle(el);
+    function analyzeElement(el) {
+      // Skip already processed or descendant of processed
+      if (processedElements.has(el) || isAncestorProcessed(el)) return;
 
-    // Skip if already using content-visibility
-    if (cs["content-visibility"] && cs["content-visibility"] !== "visible") return;
+      const rect = el.getBoundingClientRect();
+      const cs = window.getComputedStyle(el);
 
-    // Skip elements not meeting size criteria
-    if (rect.height < minHeight || rect.width === 0) return;
+      // Skip if already using content-visibility
+      if (cs["content-visibility"] && cs["content-visibility"] !== "visible") return;
 
-    // Check if element is below the viewport + threshold
-    const distanceFromViewport = rect.top - viewportHeight;
-    if (distanceFromViewport < threshold) return;
+      // Skip elements not meeting size criteria
+      if (rect.height < minHeight || rect.width === 0) return;
 
-    const childCount = el.querySelectorAll("*").length;
+      // Check if element is below the viewport + threshold
+      const distanceFromViewport = rect.top - viewportHeight;
+      if (distanceFromViewport < threshold) return;
 
-    // Skip elements with too few children
-    if (childCount < minChildren) return;
+      const childCount = el.querySelectorAll("*").length;
 
-    processedElements.add(el);
+      // Skip elements with too few children
+      if (childCount < minChildren) return;
 
-    opportunities.push({
-      selector: uniqueSelector(el),
-      height: Math.round(rect.height) + "px",
-      distanceFromViewport: Math.round(distanceFromViewport) + "px",
-      childElements: childCount,
-      estimatedSavings: estimateRenderSavings(childCount),
-      element: el,
-    });
-  }
+      processedElements.add(el);
 
-  // Walk all elements in the DOM
-  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT, null, false);
+      opportunities.push({
+        selector: uniqueSelector(el),
+        height: Math.round(rect.height) + "px",
+        distanceFromViewport: Math.round(distanceFromViewport) + "px",
+        childElements: childCount,
+        estimatedSavings: estimateRenderSavings(childCount),
+        element: el,
+      });
+    }
 
-  while (walker.nextNode()) {
-    analyzeElement(walker.currentNode);
-  }
+    // Walk all elements in the DOM
+    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT, null, false);
 
-  // Sort by child count (highest impact first)
-  opportunities.sort((a, b) => b.childElements - a.childElements);
+    while (walker.nextNode()) {
+      analyzeElement(walker.currentNode);
+    }
 
-  // Display results
-  console.group("💡 Content-Visibility Opportunities");
-  console.log(
-    `%cSettings: threshold=${threshold}px, minHeight=${minHeight}px, minChildren=${minChildren}`,
-    "color: #888;",
-  );
-  console.log("");
+    // Sort by child count (highest impact first)
+    opportunities.sort((a, b) => b.childElements - a.childElements);
 
-  if (opportunities.length === 0) {
-    console.log("%c✅ No opportunities found with current settings.", "color: #22c55e; font-weight: bold");
-    console.log("Try adjusting: analyzeContentVisibilityOpportunities({ threshold: -200, minHeight: 50, minChildren: 3 })");
-  } else {
+    // Display results
+    console.group("💡 Content-Visibility Opportunities");
     console.log(
-      `%cFound ${opportunities.length} element(s) that could benefit from content-visibility: auto`,
-      "font-weight: bold;",
+      `%cSettings: threshold=${threshold}px, minHeight=${minHeight}px, minChildren=${minChildren}`,
+      "color: #888;",
     );
     console.log("");
 
-    // Show table without element reference
-    const tableData = opportunities.slice(0, 20).map((opportunity) => ({
-      selector: opportunity.selector,
-      height: opportunity.height,
-      distanceFromViewport: opportunity.distanceFromViewport,
-      childElements: opportunity.childElements,
-      estimatedSavings: opportunity.estimatedSavings,
-    }));
-    console.table(tableData);
-
-    if (opportunities.length > 20) {
-      console.log(`... and ${opportunities.length - 20} more elements`);
+    if (opportunities.length === 0) {
+      console.log("%c✅ No opportunities found with current settings.", "color: #22c55e; font-weight: bold");
+      console.log("Try adjusting: analyzeContentVisibilityOpportunities({ threshold: -200, minHeight: 50, minChildren: 3 })");
+    } else {
+      console.log(
+        `%cFound ${opportunities.length} element(s) that could benefit from content-visibility: auto`,
+        "font-weight: bold;",
+      );
+      console.log("");
+
+      // Show table without element reference
+      const tableData = opportunities.slice(0, 20).map((opportunity) => ({
+        selector: opportunity.selector,
+        height: opportunity.height,
+        distanceFromViewport: opportunity.distanceFromViewport,
+        childElements: opportunity.childElements,
+        estimatedSavings: opportunity.estimatedSavings,
+      }));
+      console.table(tableData);
+
+      if (opportunities.length > 20) {
+        console.log(`... and ${opportunities.length - 20} more elements`);
+      }
+
+      // Log elements for inspection
+      console.log("");
+      console.group("🔎 Elements for inspection");
+      opportunities.slice(0, 10).forEach((opp, i) => {
+        console.log(`${i + 1}. `, opp.element);
+      });
+      console.groupEnd();
+
+      console.log("");
+      console.group("📝 Implementation Example");
+      console.log("Add this CSS to optimize rendering:");
+      console.log("");
+      console.log(
+        "%c/* Optimize offscreen content */\n" +
+          ".your-selector {\n" +
+          "  content-visibility: auto;\n" +
+          "  contain-intrinsic-size: auto 500px; /* Use actual height */\n" +
+          "}",
+        "font-family: monospace; background: #1e1e1e; color: #9cdcfe; padding: 10px; border-radius: 4px;",
+      );
+      console.groupEnd();
     }
 
-    // Log elements for inspection
-    console.log("");
-    console.group("🔎 Elements for inspection");
-    opportunities.slice(0, 10).forEach((opp, i) => {
-      console.log(`${i + 1}. `, opp.element);
-    });
     console.groupEnd();
 
-    console.log("");
-    console.group("📝 Implementation Example");
-    console.log("Add this CSS to optimize rendering:");
-    console.log("");
-    console.log(
-      "%c/* Optimize offscreen content */\n" +
-        ".your-selector {\n" +
-        "  content-visibility: auto;\n" +
-        "  contain-intrinsic-size: auto 500px; /* Use actual height */\n" +
-        "}",
-      "font-family: monospace; background: #1e1e1e; color: #9cdcfe; padding: 10px; border-radius: 4px;",
-    );
-    console.groupEnd();
+    // The shape of every result (snippets/SCHEMA.md). The elements themselves are in the console,
+    // above: a DOM node is not data a script or an agent can read
+    return {
+      script: "Content-Visibility",
+      status: "ok",
+      count: opportunities.length,
+      details: {
+        highImpact: opportunities.filter((o) => o.estimatedSavings.startsWith("High")).length,
+        threshold,
+        minHeight,
+        minChildren,
+      },
+      items: opportunities.slice(0, 50).map((opportunity) => ({
+        selector: opportunity.selector,
+        height: opportunity.height,
+        distanceFromViewport: opportunity.distanceFromViewport,
+        childElements: opportunity.childElements,
+        estimatedSavings: opportunity.estimatedSavings,
+      })),
+      issues: [],
+    };
   }
 
-  console.groupEnd();
+  window.analyzeContentVisibilityOpportunities = analyzeContentVisibilityOpportunities;
 
-  return {
-    opportunities: opportunities.map((opportunity) => ({
-      selector: opportunity.selector,
-      height: opportunity.height,
-      distanceFromViewport: opportunity.distanceFromViewport,
-      childElements: opportunity.childElements,
-      estimatedSavings: opportunity.estimatedSavings,
-    })),
-    totalElements: opportunities.length,
-    highImpact: opportunities.filter((o) => o.estimatedSavings.startsWith("High")).length,
-    elements: opportunities.map((o) => o.element),
-  };
-}
-
-window.analyzeContentVisibilityOpportunities = analyzeContentVisibilityOpportunities;
-
-// Run detection
-(() => {
+  // Run detection
   const cvResults = detectContentVisibility();
   console.log(
     "%c\n To find optimization opportunities, run: %canalyzeContentVisibilityOpportunities()",

package/snippets/SCHEMA.md

@@ -912,6 +912,19 @@ With no usage the script returns `count: 0`, no items and an `info` issue.
 }
 ```
 
+`analyzeContentVisibilityOpportunities(options)`, which the script leaves on `window`, returns the elements below the viewport that could use `content-visibility: auto`, the ones with more descendants first and up to 50; `count` holds the total. `details` has how many have a high estimated saving and the options the search used. `issues` is always empty.
+
+```json
+{
+  "script": "Content-Visibility",
+  "status": "ok",
+  "count": 1,
+  "details": { "highImpact": 0, "threshold": 0, "minHeight": 100, "minChildren": 5 },
+  "items": [{ "selector": "#comments", "height": "640px", "distanceFromViewport": "1200px", "childElements": 48, "estimatedSavings": "Medium (~9.6ms)" }],
+  "issues": []
+}
+```
+
 ### Interaction
 
 Tracking scripts return `status: "tracking"` first. The function named by `getDataFn` returns the full result. Items are capped at 50 (20 for frames) and sorted by relevance; `count` holds the total.

package/snippets/_view/index.js

@@ -9,6 +9,7 @@ import en from './locales/en.js'
 import { formatOfKey, formatValue, SUFFIXES } from './format.js'
 
 export { formatValue }
+export { auditReport, describeOverview, issueList, issuesOf, overviewOf, summarizeIssues } from './report.js'
 
 const LOCALES = { en }