browsertime 27.5.0 → 28.1.0

package/lib/chrome/trace/style-invalidations.js

@@ -0,0 +1,162 @@
+/**
+ * Style/layout invalidation attribution, from the
+ * devtools.timeline.invalidationTracking events browsertime has
+ * always collected with --chrome.timeline but never parsed. The
+ * recalculate-style and layout totals say HOW MUCH invalidation work
+ * happened; these events say WHY and WHO:
+ *
+ *  - StyleRecalcInvalidationTracking: one event per invalidated node
+ *    with the reason ("Style rule change", "Node was inserted into
+ *    tree", "Affected by :has()", …) and often the JS stack that
+ *    caused it.
+ *  - ScheduleStyleInvalidationTracking: the DOM change that scheduled
+ *    an invalidation — which class/attribute/id/pseudo changed on
+ *    which node.
+ *  - LayoutInvalidationTracking: one event per node whose layout was
+ *    invalidated, with reason and often a stack.
+ *
+ * Aggregated three ways: reason counts (what kind of churn),
+ * trigger counts (which class/attribute names keep changing) and
+ * source counts (which script did it, from the innermost stack frame
+ * with a URL). One noisy script toggling a class on N nodes shows up
+ * as N invalidations from that URL with that class as the trigger —
+ * exactly the row a developer can act on.
+ *
+ * Counts, not milliseconds: the events are instant markers, the time
+ * they cause is already in cpu.categories.styleLayout and the
+ * recalculateStyle summaries.
+ *
+ * When the optional `bundles` map (url → location resolver from the
+ * coverage path) is passed, source frames inside concatenated
+ * bundles resolve to the owning module — thousands of invalidations
+ * from one giant load.php URL split into per-module rows.
+ *
+ * Returns undefined when the trace has no invalidation events.
+ * Otherwise:
+ *   { styleRecalcs, layoutInvalidations,
+ *     recalcReasons: [{ reason, count }, …],
+ *     layoutReasons: [{ reason, count }, …],
+ *     triggers:      [{ kind, name, count }, …],
+ *     sources:       [{ url, module?, count }, …] }
+ */
+
+const MAX_REASONS = 10;
+const MAX_TRIGGERS = 15;
+const MAX_SOURCES = 10;
+
+function increment(map, key) {
+  if (!key) return;
+  map.set(key, (map.get(key) || 0) + 1);
+}
+
+// Source identity for an invalidation: the innermost stack frame
+// with a URL, resolved to the owning module when the frame lands in
+// a known concatenated bundle (trace stack-frame positions are
+// 1-based, matching the resolvers). Without bundles the identity is
+// just the URL — the pre-existing behaviour.
+function sourceEntryFor(sources, data, bundles) {
+  for (const frame of data.stackTrace || []) {
+    if (!frame.url) continue;
+    let module_;
+    if (bundles && frame.lineNumber !== undefined) {
+      const resolver = bundles.get(frame.url);
+      if (resolver) {
+        module_ = resolver.resolve(frame.lineNumber, frame.columnNumber);
+      }
+    }
+    const key = module_ ? `${frame.url}|${module_.name}` : frame.url;
+    let entry = sources.get(key);
+    if (!entry) {
+      entry = { url: frame.url, count: 0 };
+      if (module_) entry.module = module_.name;
+      sources.set(key, entry);
+    }
+    entry.count++;
+    return;
+  }
+}
+
+function topEntries(map, limit, publish) {
+  return [...map.entries()]
+    .toSorted((a, b) => b[1] - a[1])
+    .slice(0, limit)
+    .map(entry => publish(entry));
+}
+
+export function computeStyleInvalidations(trace, bundles) {
+  const recalcReasons = new Map();
+  const layoutReasons = new Map();
+  const triggers = new Map();
+  const sources = new Map();
+  let styleRecalcs = 0;
+  let layoutInvalidations = 0;
+  let sawInvalidations = false;
+
+  for (const event of trace.traceEvents) {
+    const data = (event.args && event.args.data) || {};
+    switch (event.name) {
+      case 'StyleRecalcInvalidationTracking': {
+        sawInvalidations = true;
+        styleRecalcs++;
+        increment(recalcReasons, data.reason);
+        sourceEntryFor(sources, data, bundles);
+        break;
+      }
+      case 'LayoutInvalidationTracking': {
+        sawInvalidations = true;
+        layoutInvalidations++;
+        increment(layoutReasons, data.reason);
+        sourceEntryFor(sources, data, bundles);
+        break;
+      }
+      case 'ScheduleStyleInvalidationTracking': {
+        sawInvalidations = true;
+        if (data.changedClass) {
+          increment(triggers, `class|${data.changedClass}`);
+        }
+        if (data.changedAttribute) {
+          increment(triggers, `attribute|${data.changedAttribute}`);
+        }
+        if (data.changedId) {
+          increment(triggers, `id|${data.changedId}`);
+        }
+        if (data.changedPseudo) {
+          increment(triggers, `pseudo|${data.changedPseudo}`);
+        }
+        break;
+      }
+      default: {
+        continue;
+      }
+    }
+  }
+  if (!sawInvalidations) return;
+
+  return {
+    styleRecalcs,
+    layoutInvalidations,
+    recalcReasons: topEntries(
+      recalcReasons,
+      MAX_REASONS,
+      ([reason, count]) => ({
+        reason,
+        count
+      })
+    ),
+    layoutReasons: topEntries(
+      layoutReasons,
+      MAX_REASONS,
+      ([reason, count]) => ({
+        reason,
+        count
+      })
+    ),
+    triggers: topEntries(triggers, MAX_TRIGGERS, ([key, count]) => {
+      const [kind, ...name] = key.split('|');
+      return { kind, name: name.join('|'), count };
+    }),
+    sources: [...sources.values()]
+      .toSorted((a, b) => b.count - a.count)
+      .slice(0, MAX_SOURCES)
+  };
+}

package/lib/chrome/trace/task-groups.js

@@ -43,7 +43,26 @@ export const taskGroups = {
       'ResourceReceiveResponse',
       'ResourceReceivedData',
       'ResourceReceivedResponse',
-      'ResourceFinish'
+      'ResourceFinish',
+      'ResourceChangePriority',
+      // Document/navigation body loading internals (sampled from real
+      // Wikipedia traces, July 2026) — the main-thread side of
+      // streaming the document into the parser. Same rationale as the
+      // resource lifecycle events above.
+      'DocumentLoader::DocumentLoader',
+      'DocumentLoader::HandleData',
+      'DocumentLoader::CommitData',
+      'DocumentLoader::BodyDataReceivedImpl',
+      'DocumentLoader::BodyLoadingFinished',
+      'DocumentLoader::FinishedLoading',
+      'NavigationBodyLoader::OnReadable',
+      'NavigationBodyLoader::ReadFromDataPipe',
+      'URLLoader::Context::OnReceivedResponse',
+      'URLLoader::Context::OnCompletedRequest',
+      'URLLoader::Context::Cancel',
+      'ThrottlingURLLoader::OnReceiveResponse',
+      'ResourceRequestSender::OnReceivedResponse',
+      'ResourceRequestSender::OnRequestComplete'
     ]
   },
   styleLayout: {
@@ -129,7 +148,14 @@ export const taskGroups = {
       'v8.callFunction',
       'v8.callModuleMethod',
       'XHRLoad',
-      'XHRReadyStateChange'
+      'XHRReadyStateChange',
+      // V8 housekeeping that only runs because JS is executing —
+      // interrupt handling, stack guards, constructor instantiation.
+      'v8.newInstance',
+      'V8.InvokeApiInterruptCallbacks',
+      'V8.HandleInterrupts',
+      'V8.BytecodeBudgetInterrupt',
+      'V8.StackGuard'
     ]
   },
   garbageCollection: {

package/lib/chrome/trace/timer-costs.js

@@ -0,0 +1,183 @@
+/**
+ * Timer pressure per script — how much setTimeout/setInterval churn
+ * a page runs, from trace events already collected with
+ * --chrome.timeline.
+ *
+ * Two sides are joined per URL:
+ *  - TimerInstall events (instant): who schedules timers, how many,
+ *    how many with timeout 0 (the "yield" pattern that turns into
+ *    main-thread machine-gunning) and how many recurring
+ *    (setInterval / singleShot: false). Attribution from the
+ *    innermost stack frame with a URL.
+ *  - TimerFire tasks from the main-thread task tree: what running
+ *    those timers actually cost. main-thread-tasks.js already chains
+ *    TimerFire back to the installing script's URLs, so the cost
+ *    lands on the script that scheduled the timer even when the
+ *    callback is anonymous.
+ *
+ * Polling loops show up as a high install/fire count with recurring
+ * installs on one URL; oversliced work shows up as hundreds of
+ * timeout-0 installs. Fire time is inclusive task duration — what
+ * the main thread was occupied with when the timer ran.
+ *
+ * Returns undefined when the trace has no timer events. Otherwise:
+ *   { installs, fires, fireTime, timeoutZeroInstalls,
+ *     recurringInstalls,
+ *     byUrl: [{ url, installs, fires, fireTime,
+ *               timeoutZeroInstalls, recurringInstalls }, …],
+ *     sites: [{ url, line?, column?, functionName?, timeout,
+ *               recurring, installs, fires, fireTime }, …] }
+ * fireTime in ms with one decimal; byUrl sorted by fireTime desc,
+ * capped at 10 entries with sub-0.1 ms/zero-install rows dropped.
+ * `sites` lists the individual timers grouped by install site
+ * (installer source position + timeout + kind) — the closest thing
+ * to a timer's identity the trace offers — top 10 by fire time.
+ * Positions are 1-based (trace stack-frame convention).
+ */
+
+import { compute } from './main-thread-tasks.js';
+
+const MAX_URLS = 10;
+const MAX_SITES = 10;
+const UNKNOWN = 'unknown';
+
+function round(ms) {
+  return Math.round(ms * 10) / 10;
+}
+
+function installFrame(data) {
+  for (const frame of data.stackTrace || []) {
+    if (frame.url) return frame;
+  }
+}
+
+export function computeTimerCosts(trace) {
+  const byUrl = new Map();
+  // Individual timers grouped by install site (installer source
+  // position + timeout + kind): a polling loop reinstalling from the
+  // same line collapses into one row with its install/fire counts.
+  const bySite = new Map();
+  const siteForTimerId = new Map();
+  let installs = 0;
+  let fires = 0;
+  let fireTimeMs = 0;
+  let timeoutZeroInstalls = 0;
+  let recurringInstalls = 0;
+
+  function entryFor(url) {
+    let entry = byUrl.get(url);
+    if (!entry) {
+      entry = {
+        url,
+        installs: 0,
+        fires: 0,
+        fireTimeMs: 0,
+        timeoutZeroInstalls: 0,
+        recurringInstalls: 0
+      };
+      byUrl.set(url, entry);
+    }
+    return entry;
+  }
+
+  for (const event of trace.traceEvents) {
+    if (event.name !== 'TimerInstall') continue;
+    const data = (event.args && event.args.data) || {};
+    const frame = installFrame(data);
+    const entry = entryFor(frame ? frame.url : UNKNOWN);
+    installs++;
+    entry.installs++;
+    const timeout = data.timeout || 0;
+    if (timeout === 0) {
+      timeoutZeroInstalls++;
+      entry.timeoutZeroInstalls++;
+    }
+    const recurring = data.singleShot === false;
+    if (recurring) {
+      recurringInstalls++;
+      entry.recurringInstalls++;
+    }
+
+    const siteKey = frame
+      ? `${frame.url}|${frame.lineNumber}|${frame.columnNumber}|${timeout}|${recurring}`
+      : `${UNKNOWN}|${timeout}|${recurring}`;
+    let site = bySite.get(siteKey);
+    if (!site) {
+      site = {
+        url: frame ? frame.url : UNKNOWN,
+        timeout,
+        recurring,
+        installs: 0,
+        fires: 0,
+        fireTimeMs: 0
+      };
+      if (frame) {
+        site.line = frame.lineNumber;
+        site.column = frame.columnNumber;
+        if (frame.functionName) site.functionName = frame.functionName;
+      }
+      bySite.set(siteKey, site);
+    }
+    site.installs++;
+    if (data.timerId !== undefined) siteForTimerId.set(data.timerId, site);
+  }
+
+  const tasks = compute(trace);
+  for (const task of tasks) {
+    if (task.event.name !== 'TimerFire') continue;
+    const entry = entryFor(task.attributableURLs.at(-1) || UNKNOWN);
+    fires++;
+    fireTimeMs += task.duration;
+    entry.fires++;
+    entry.fireTimeMs += task.duration;
+    const fireData = (task.event.args && task.event.args.data) || {};
+    const site = siteForTimerId.get(fireData.timerId);
+    if (site) {
+      site.fires++;
+      site.fireTimeMs += task.duration;
+    }
+  }
+
+  if (installs === 0 && fires === 0) return;
+
+  const urls = [...byUrl.values()]
+    .filter(entry => entry.fireTimeMs >= 0.1 || entry.installs > 0)
+    .toSorted((a, b) => b.fireTimeMs - a.fireTimeMs || b.installs - a.installs)
+    .slice(0, MAX_URLS)
+    .map(entry => ({
+      url: entry.url,
+      installs: entry.installs,
+      fires: entry.fires,
+      fireTime: round(entry.fireTimeMs),
+      timeoutZeroInstalls: entry.timeoutZeroInstalls,
+      recurringInstalls: entry.recurringInstalls
+    }));
+
+  const sites = [...bySite.values()]
+    .toSorted((a, b) => b.fireTimeMs - a.fireTimeMs || b.installs - a.installs)
+    .slice(0, MAX_SITES)
+    .map(site => {
+      const published = {
+        url: site.url,
+        timeout: site.timeout,
+        recurring: site.recurring,
+        installs: site.installs,
+        fires: site.fires,
+        fireTime: round(site.fireTimeMs)
+      };
+      if (site.line !== undefined) published.line = site.line;
+      if (site.column !== undefined) published.column = site.column;
+      if (site.functionName) published.functionName = site.functionName;
+      return published;
+    });
+
+  return {
+    installs,
+    fires,
+    fireTime: round(fireTimeMs),
+    timeoutZeroInstalls,
+    recurringInstalls,
+    byUrl: urls,
+    sites
+  };
+}

package/lib/chrome/webdriver/chromium.js

@@ -7,6 +7,10 @@ const log = getLogger('browsertime.chrome');
 const { Type } = logging;
 import { longTaskMetrics } from '../longTaskMetrics.js';
 import { parseCPUTrace } from '../parseCpuTrace.js';
+import { computeModuleCosts } from '../trace/module-costs.js';
+import { computeFunctionCosts } from '../trace/function-costs.js';
+import { computeStyleInvalidations } from '../trace/style-invalidations.js';
+import { labelForUrl } from '../mediawikiResourceLoader.js';
 import { getHar } from '../har.js';
 import { getEmptyHAR, mergeHars } from '../../support/har/index.js';
 import { toArray } from '../../support/util.js';
@@ -335,6 +339,12 @@ export class Chromium {
       const coverage = await this.coverage.collect();
       this.coverage = undefined;
       if (coverage) {
+        // Bundle location resolvers are plumbing for the CPU trace
+        // parser (per-module CPU attribution), not part of the
+        // coverage result contract — lift them off before the
+        // coverage object is serialized.
+        this.resourceLoaderBundles = coverage.resourceLoaderBundles;
+        delete coverage.resourceLoaderBundles;
         result.coverage = coverage;
       }
     }
@@ -385,6 +395,20 @@ export class Chromium {
     // this hack fixes that
     if (result.browserScripts && result.browserScripts.pageinfo) {
       result.browserScripts.pageinfo.longTask = this.longTaskInfo;
+
+      // Resolve LoAF script URLs to ResourceLoader module labels the
+      // same way cpu.urls gets them — several frames all blaming one
+      // giant load.php URL say nothing without the module name.
+      if (Array.isArray(result.browserScripts.pageinfo.loaf)) {
+        for (const frame of result.browserScripts.pageinfo.loaf) {
+          for (const script of frame.scripts || []) {
+            const label = labelForUrl(script.sourceURL);
+            if (label) {
+              script.label = label;
+            }
+          }
+        }
+      }
     }
 
     if (this.chrome.collectNetLog && this.chrome.android) {
@@ -416,6 +440,110 @@ export class Chromium {
       result.extraJson[name] = trace;
 
       const cpu = await parseCPUTrace(trace, result.url);
+
+      // Per-module CPU inside concatenated bundles (MediaWiki
+      // ResourceLoader). The only analysis that needs both the trace
+      // and the bundle boundaries from the coverage path, so it runs
+      // here where the two meet — only when coverage found bundles on
+      // the page, otherwise zero cost and no output key.
+      if (this.resourceLoaderBundles && this.resourceLoaderBundles.size > 0) {
+        try {
+          const moduleCosts = computeModuleCosts(
+            trace,
+            this.resourceLoaderBundles
+          );
+          if (moduleCosts.length > 0) {
+            for (const bundle of moduleCosts) {
+              const label = labelForUrl(bundle.url);
+              if (label) {
+                bundle.label = label;
+              }
+            }
+            cpu.moduleCosts = moduleCosts;
+          }
+        } catch (error) {
+          log.debug('computeModuleCosts failed: %s', error.message);
+        }
+      }
+      // Per-function self/total time from the V8 sampling profiler —
+      // only produces output on runs with the cpu_profiler trace
+      // category (--enableProfileRun). Reuses the bundle resolvers so
+      // functions inside concatenated bundles get a module name.
+      try {
+        const functionCosts = computeFunctionCosts(
+          trace,
+          this.resourceLoaderBundles
+        );
+        if (functionCosts.length > 0) {
+          for (const functionCost of functionCosts) {
+            const label = labelForUrl(functionCost.url);
+            if (label) {
+              functionCost.label = label;
+            }
+            for (const callee of functionCost.callees || []) {
+              const calleeLabel = labelForUrl(callee.url);
+              if (calleeLabel) {
+                callee.label = calleeLabel;
+              }
+            }
+          }
+          cpu.functionCosts = functionCosts;
+        }
+      } catch (error) {
+        log.debug('computeFunctionCosts failed: %s', error.message);
+      }
+      // Invalidation sources resolve to modules the same way —
+      // thousands of invalidations from one giant load.php URL say
+      // nothing, the per-module split says whose code churns the
+      // DOM. Recomputing with the bundles replaces the unresolved
+      // sources parseCpuTrace produced.
+      if (
+        cpu.styleInvalidations &&
+        this.resourceLoaderBundles &&
+        this.resourceLoaderBundles.size > 0
+      ) {
+        try {
+          const enriched = computeStyleInvalidations(
+            trace,
+            this.resourceLoaderBundles
+          );
+          if (enriched) {
+            for (const source of enriched.sources) {
+              const label = labelForUrl(source.url);
+              if (label) {
+                source.label = label;
+              }
+            }
+            cpu.styleInvalidations = enriched;
+          }
+        } catch (error) {
+          log.debug(
+            'computeStyleInvalidations with bundles failed: %s',
+            error.message
+          );
+        }
+      }
+      // Timer install sites inside concatenated bundles resolve to
+      // the owning module — "load.php[scripts]:418" says nothing,
+      // the module name says whose timer it is. Trace stack-frame
+      // positions are 1-based, matching the resolvers.
+      if (
+        cpu.timers &&
+        cpu.timers.sites &&
+        this.resourceLoaderBundles &&
+        this.resourceLoaderBundles.size > 0
+      ) {
+        for (const site of cpu.timers.sites) {
+          if (site.line === undefined) continue;
+          const resolver = this.resourceLoaderBundles.get(site.url);
+          if (!resolver) continue;
+          const module_ = resolver.resolve(site.line, site.column);
+          if (module_) {
+            site.module = module_.name;
+          }
+        }
+      }
+      this.resourceLoaderBundles = undefined;
       result.cpu = cpu;
 
       // Collect render blocking info

package/lib/chrome/webdriver/traceUtilities.js

@@ -52,12 +52,22 @@ function getRecalculateStyleElementsAndTimeBefore(traceEvents, timestamp) {
   );
   let elements = 0;
   let duration = 0;
+  let maxElements = 0;
+  let maxDuration = 0;
   for (let a of updateLayoutTree) {
     elements += a.args.elementCount;
     duration += a.dur;
+    maxElements = Math.max(maxElements, a.args.elementCount);
+    maxDuration = Math.max(maxDuration, a.dur);
   }
 
-  return { elements, durationInMillis: duration / 1000 };
+  return {
+    count: updateLayoutTree.length,
+    elements,
+    durationInMillis: duration / 1000,
+    maxElements,
+    maxDurationInMillis: maxDuration / 1000
+  };
 }
 
 export async function getRenderBlocking(trace) {

package/lib/core/engine/collector.js

@@ -136,6 +136,18 @@ export class Collector {
     }
   }
 
+  // Header values are strings so they are kept out of the statistics.
+  addMainDocument(url, mainDocument) {
+    const results =
+      this.allResults[url] || this.allResults[this.urlAndActualUrl[url]];
+    if (results) {
+      if (!results.mainDocument) {
+        results.mainDocument = [];
+      }
+      results.mainDocument.push(mainDocument);
+    }
+  }
+
   /**
    * Collect all individual runs, add it to the statistics, and store
    * data that needs to be on disk (trace logs, sceenshots etc).

package/lib/core/engine/index.js

@@ -18,6 +18,7 @@ import {
 import {
   getFullyLoaded,
   getMainDocumentTimings,
+  getMainDocuments,
   addExtraFieldsToHar
 } from '../../support/har/index.js';
 import { XVFB } from '../../support/xvfb.js';
@@ -374,6 +375,11 @@ export class Engine {
       for (let timing of timings) {
         collector.addMainDocumentTimings(timing.url, timing.timings);
       }
+
+      const mainDocuments = getMainDocuments(extras.har);
+      for (let document of mainDocuments) {
+        collector.addMainDocument(document.url, document.mainDocument);
+      }
     }
   }
 

package/lib/support/cli.js

@@ -51,7 +51,7 @@ function hasbin(bin) {
 function validateInput(argv) {
   // Check NodeJS major version
   const fullVersion = process.versions.node;
-  const minVersion = 20;
+  const minVersion = 22;
   const majorVersion = fullVersion.split('.')[0];
   if (majorVersion < minVersion) {
     return (

package/lib/support/har/index.js

@@ -269,6 +269,45 @@ export function getMainDocumentTimings(har) {
     return [];
   }
 }
+export function getMainDocuments(har) {
+  // Sometimes the HAR is dirty
+  try {
+    const mainDocuments = [];
+    for (let page of har.log.pages) {
+      const url = page._url;
+      if (url === undefined) continue;
+
+      const requests = getDocumentRequests(har.log.entries, page.id);
+      const finalEntry = requests.at(-1);
+      if (!finalEntry) continue;
+
+      const headers = {};
+      for (let header of finalEntry.response.headers || []) {
+        const name = header.name.toLowerCase();
+        // Always drop sensitive headers (the same list as
+        // --cleanSensitiveHeaders uses) since browsertime.json often ends
+        // up in dashboards even when the HAR stays local.
+        if (isSensitiveHeader(name)) continue;
+        headers[name] =
+          name in headers ? headers[name] + ', ' + header.value : header.value;
+      }
+
+      mainDocuments.push({
+        url,
+        mainDocument: {
+          url: finalEntry.request.url,
+          status: finalEntry.response.status,
+          redirects: requests.length - 1,
+          headers
+        }
+      });
+    }
+    return mainDocuments;
+  } catch (error) {
+    log.error('Could not get main document headers ' + error);
+    return [];
+  }
+}
 export function getFullyLoaded(har) {
   const fullyLoaded = [];
   const entries = [...har.log.entries];
@@ -464,8 +503,12 @@ export function addExtraFieldsToHar(totalResults, har, options) {
   }
 }
 
+export function isSensitiveHeader(name) {
+  return sensitiveHeaders.has(name.toLowerCase());
+}
+
 export function cleanSensitiveHeaders(name, value) {
-  if (sensitiveHeaders.has(name.toLowerCase())) {
+  if (isSensitiveHeader(name)) {
     return '[REMOVED]';
   }
   return value;