browsertime 27.5.0 → 28.0.0

package/lib/chrome/trace/index.js

@@ -15,6 +15,13 @@ import { compute } from './main-thread-tasks.js';
 export { computeScriptCosts } from './script-costs.js';
 export { computeForcedReflows } from './forced-reflows.js';
 export { computeNonCompositedAnimations } from './non-composited-animations.js';
+export { computeFrameStability } from './frame-stability.js';
+export { computeFunctionCosts } from './function-costs.js';
+export { computeStyleInvalidations } from './style-invalidations.js';
+export { computeSelectorStats } from './selector-stats.js';
+export { computeTimerCosts } from './timer-costs.js';
+export { computeBlockingTime } from './blocking-time.js';
+export { computeDomainBreakdown } from './domain-breakdown.js';
 
 /**
  * Compute the hierarchical main-thread task tree for a trace.

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

@@ -0,0 +1,137 @@
+/**
+ * Per-module CPU attribution for script bundles that concatenate many
+ * logical modules into a single URL (e.g. MediaWiki ResourceLoader
+ * load.php responses). cpu.urls can only say "load.php used 267 ms of
+ * main thread"; this analysis splits that time across the modules
+ * inside each bundle so the owner of a slow module can be identified.
+ *
+ * This file is bundle-format agnostic. It walks the main-thread task
+ * tree and, for every task whose most-specific code location falls
+ * inside a known bundle URL, asks that bundle's resolver which module
+ * owns the source position. All knowledge about the bundle format
+ * (module delimiters, line/column → byte-offset math) lives in the
+ * resolver — see lib/chrome/mediawikiResourceLoader.js.
+ *
+ * Attribution rules per task (selfTime is exclusive of children, so
+ * nothing is counted twice):
+ *  - EvaluateScript / v8.compile / v8.compileModule on a bundle URL:
+ *    the event spans the whole script, not one module (module bodies
+ *    are only registered at evaluate time and executed later), so the
+ *    time goes to the bundle's `otherTime` bucket.
+ *  - FunctionCall: args.data carries the definition site of the
+ *    invoked function — resolve it to a module.
+ *  - Any other event with a stack trace: the innermost frame with a
+ *    URL decides — resolve when it is a bundle, skip the task when it
+ *    points at code outside any bundle.
+ *  - Tasks with no location of their own (layout, GC, microtasks
+ *    triggered by module code) fall back to the inherited
+ *    most-specific attributable URL; when that is a bundle the time
+ *    is in-bundle but not attributable to one module → `otherTime`.
+ *
+ * Because only a task's own most-specific location (or the inherited
+ * chain when it has none) is credited, the per-bundle sum of module
+ * selfTime + otherTime is always ≤ that URL's total in cpu.urls,
+ * which counts a task for every URL anywhere in its chain.
+ *
+ * Times are in ms rounded to one decimal, matching the sibling
+ * analyses. Modules that round to 0 are dropped; bundles are sorted
+ * by total time desc and modules by selfTime desc.
+ */
+
+import { compute } from './main-thread-tasks.js';
+
+const WHOLE_SCRIPT_EVENTS = new Set([
+  'EvaluateScript',
+  'v8.compile',
+  'v8.compileModule'
+]);
+
+function round(ms) {
+  return Math.round(ms * 10) / 10;
+}
+
+function attributeTask(task, bundles) {
+  const event = task.event;
+  const argsData = (event.args && event.args.data) || {};
+
+  if (WHOLE_SCRIPT_EVENTS.has(event.name)) {
+    const url =
+      event.name === 'v8.compileModule' ? event.args.fileName : argsData.url;
+    return url && bundles.has(url) ? { url } : undefined;
+  }
+
+  if (event.name === 'FunctionCall' && argsData.url) {
+    const bundle = bundles.get(argsData.url);
+    if (!bundle) return;
+    return {
+      url: argsData.url,
+      module: bundle.resolve(argsData.lineNumber, argsData.columnNumber)
+    };
+  }
+
+  for (const frame of argsData.stackTrace || []) {
+    if (!frame.url) continue;
+    const bundle = bundles.get(frame.url);
+    if (!bundle) return;
+    return {
+      url: frame.url,
+      module: bundle.resolve(frame.lineNumber, frame.columnNumber)
+    };
+  }
+
+  const inherited = task.attributableURLs.at(-1);
+  return inherited && bundles.has(inherited) ? { url: inherited } : undefined;
+}
+
+/**
+ * @param {Object} trace  Parsed Chrome trace.json (with .traceEvents).
+ * @param {Map<string, {resolve: Function}>} bundles  Bundle URL →
+ *   location resolver, built while collecting coverage.
+ * @returns {Array<{url:string,
+ *   modules:Array<{name:string, version:string, selfTime:number}>,
+ *   otherTime:number}>}
+ */
+export function computeModuleCosts(trace, bundles) {
+  if (!bundles || bundles.size === 0) return [];
+
+  const byBundle = new Map();
+  for (const task of compute(trace)) {
+    if (!(task.selfTime > 0)) continue;
+    const attribution = attributeTask(task, bundles);
+    if (!attribution) continue;
+
+    let entry = byBundle.get(attribution.url);
+    if (!entry) {
+      entry = { byModule: new Map(), otherTime: 0 };
+      byBundle.set(attribution.url, entry);
+    }
+    const module = attribution.module;
+    if (module) {
+      const key = `${module.name}@${module.version}`;
+      const moduleEntry = entry.byModule.get(key);
+      if (moduleEntry) {
+        moduleEntry.selfTime += task.selfTime;
+      } else {
+        entry.byModule.set(key, { ...module, selfTime: task.selfTime });
+      }
+    } else {
+      entry.otherTime += task.selfTime;
+    }
+  }
+
+  const result = [];
+  for (const [url, entry] of byBundle) {
+    const modules = [];
+    let total = entry.otherTime;
+    for (const moduleEntry of entry.byModule.values()) {
+      total += moduleEntry.selfTime;
+      moduleEntry.selfTime = round(moduleEntry.selfTime);
+      if (moduleEntry.selfTime > 0) modules.push(moduleEntry);
+    }
+    modules.sort((a, b) => b.selfTime - a.selfTime);
+    result.push({ url, modules, otherTime: round(entry.otherTime), total });
+  }
+  result.sort((a, b) => b.total - a.total);
+  for (const entry of result) delete entry.total;
+  return result;
+}

package/lib/chrome/trace/non-composited-animations.js

@@ -10,20 +10,64 @@
  *
  * Chrome marks these in the trace via `Animation` events whose
  * `args.data.compositeFailed` bitmask is non-zero, plus a list of
- * `unsupportedProperties` strings. We surface the raw values; the
- * consumer can map the bitmask to human reasons (see Lighthouse's
- * non-composited-animations audit for the canonical mapping).
+ * `unsupportedProperties` strings. Chrome often omits the property
+ * list (the bitmask is the only signal), so the bitmask is decoded
+ * into `failureReasons` strings here — otherwise consumers show "an
+ * animation failed" with no way to say why.
  *
- * Returns: [{ name, id, compositeFailed, unsupportedProperties,
- *             startTime }, …]
+ * The bit meanings come from Blink's CompositorAnimations
+ * FailureReason enum (compositor_animations.h, kFailureReasonCount
+ * = 21 as of Chrome ~M140): bit values are stable and never reused,
+ * so decoding old traces is safe. Bits 8/11/14 are retired in
+ * current Blink but kept here for traces from older Chrome versions.
+ * Unknown future bits decode to 'unknown reason (bit N)' instead of
+ * being dropped.
+ *
+ * Returns: [{ name, id, compositeFailed, failureReasons,
+ *             unsupportedProperties, startTime }, …]
  *   name            — args.data.nodeName when present (rare)
  *   id              — args.data.id (compositor-internal)
  *   compositeFailed — bitmask of failure reasons
+ *   failureReasons  — the bitmask decoded to human-readable strings
  *   unsupportedProperties — array of property names that blocked
  *                           composite (e.g. ['top','box-shadow'])
  *   startTime       — event ts in microseconds (raw trace timestamp)
  */
 
+// Blink FailureReason bit → human-readable string, in bit order.
+const FAILURE_REASONS = [
+  'accelerated animations disabled', // 1 << 0
+  'effect suppressed by DevTools', // 1 << 1
+  'invalid animation or effect', // 1 << 2
+  'effect has unsupported timing parameters', // 1 << 3
+  "effect has composite mode other than 'replace'", // 1 << 4
+  'target has invalid compositing state', // 1 << 5
+  'target has another incompatible animation', // 1 << 6
+  'target has CSS offset', // 1 << 7
+  'target has multiple transform properties', // 1 << 8 (retired)
+  'animation affects non-CSS properties', // 1 << 9
+  'transform-related property cannot be accelerated on target', // 1 << 10
+  'transform-related property depends on box size', // 1 << 11 (retired)
+  'filter-related property may move pixels', // 1 << 12
+  'unsupported CSS property', // 1 << 13
+  'multiple transform animations on same target', // 1 << 14 (retired)
+  'mixed keyframe value types', // 1 << 15
+  'scroll timeline source has invalid compositing state', // 1 << 16
+  'animation has no visible change', // 1 << 17
+  'animation affects an !important property', // 1 << 18
+  'SVG target has independent transform property', // 1 << 19
+  "effect has iteration composite mode other than 'replace'" // 1 << 20
+];
+
+function decodeFailureReasons(bitmask) {
+  const reasons = [];
+  for (let bit = 0; bitmask >> bit > 0; bit++) {
+    if (((bitmask >> bit) & 1) === 0) continue;
+    reasons.push(FAILURE_REASONS[bit] || `unknown reason (bit ${bit})`);
+  }
+  return reasons;
+}
+
 export function computeNonCompositedAnimations(trace) {
   const seen = new Set();
   const animations = [];
@@ -46,6 +90,7 @@ export function computeNonCompositedAnimations(trace) {
       name: data.nodeName || '',
       id: data.id || '',
       compositeFailed: failed,
+      failureReasons: decodeFailureReasons(failed),
       unsupportedProperties: unsupported,
       startTime: event.ts
     });

package/lib/chrome/trace/selector-stats.js

@@ -0,0 +1,110 @@
+/**
+ * CSS selector matching cost, from Chrome's SelectorStats trace
+ * events (the disabled-by-default-blink.debug category, enabled on
+ * --enableProfileRun). For every style recalculation Chrome reports
+ * per-selector elapsed time, match attempts and match count — the
+ * same data DevTools' "CSS selector stats" checkbox shows. Style &
+ * layout often dominates main-thread blocking, and this is the only
+ * signal that says WHICH selectors the recalc time goes to.
+ *
+ * Selectors are aggregated across all recalcs in the trace. Two
+ * rankings matter and both are kept: elapsed time (what costs now)
+ * and match attempts with zero matches (pure waste — selectors
+ * evaluated against the whole document for rules that never apply,
+ * e.g. a lightbox selector on pages where the lightbox never opens).
+ *
+ * `styleSheetId` is Chrome's session-internal stylesheet handle —
+ * kept so consumers that also collect CSS coverage over CDP can join
+ * back to a stylesheet URL, but it is not stable across runs.
+ * 'ua-style-sheet' marks Chrome's own user-agent rules; those are
+ * not the page's to fix and are excluded from the reported lists
+ * (their time still counts in the totals).
+ *
+ * Returns undefined when the trace has no SelectorStats events (the
+ * category is only on for profile runs). Otherwise:
+ *   { totalElapsed, totalMatchAttempts, totalMatchCount,
+ *     selectors:      [{ selector, styleSheetId?, elapsed,
+ *                        matchAttempts, matchCount }, …],
+ *     wastedSelectors: [{ … same shape, matchCount always 0 }, …] }
+ * elapsed in ms with two decimals (individual selectors are sub-ms),
+ * both lists capped at 25 entries; selectors sorted by elapsed desc,
+ * wastedSelectors by matchAttempts desc.
+ */
+
+const MAX_SELECTORS = 25;
+const UA_STYLE_SHEET = 'ua-style-sheet';
+
+function round2(ms) {
+  return Math.round(ms * 100) / 100;
+}
+
+export function computeSelectorStats(trace) {
+  const bySelector = new Map();
+  let sawSelectorStats = false;
+  let totalElapsedUs = 0;
+  let totalMatchAttempts = 0;
+  let totalMatchCount = 0;
+
+  for (const event of trace.traceEvents) {
+    if (event.name !== 'SelectorStats') continue;
+    sawSelectorStats = true;
+    const timings =
+      (event.args &&
+        event.args.selector_stats &&
+        event.args.selector_stats.selector_timings) ||
+      [];
+    for (const timing of timings) {
+      const elapsedUs = timing['elapsed (us)'] || 0;
+      totalElapsedUs += elapsedUs;
+      totalMatchAttempts += timing.match_attempts || 0;
+      totalMatchCount += timing.match_count || 0;
+      if (timing.style_sheet_id === UA_STYLE_SHEET) continue;
+      const key = `${timing.selector}|${timing.style_sheet_id || ''}`;
+      let entry = bySelector.get(key);
+      if (!entry) {
+        entry = {
+          selector: timing.selector,
+          styleSheetId: timing.style_sheet_id,
+          elapsedUs: 0,
+          matchAttempts: 0,
+          matchCount: 0
+        };
+        bySelector.set(key, entry);
+      }
+      entry.elapsedUs += elapsedUs;
+      entry.matchAttempts += timing.match_attempts || 0;
+      entry.matchCount += timing.match_count || 0;
+    }
+  }
+  if (!sawSelectorStats) return;
+
+  function publish(entry) {
+    const result = {
+      selector: entry.selector,
+      elapsed: round2(entry.elapsedUs / 1000),
+      matchAttempts: entry.matchAttempts,
+      matchCount: entry.matchCount
+    };
+    if (entry.styleSheetId) result.styleSheetId = entry.styleSheetId;
+    return result;
+  }
+
+  const all = [...bySelector.values()];
+  const selectors = all
+    .toSorted((a, b) => b.elapsedUs - a.elapsedUs)
+    .slice(0, MAX_SELECTORS)
+    .map(entry => publish(entry));
+  const wastedSelectors = all
+    .filter(entry => entry.matchCount === 0)
+    .toSorted((a, b) => b.matchAttempts - a.matchAttempts)
+    .slice(0, MAX_SELECTORS)
+    .map(entry => publish(entry));
+
+  return {
+    totalElapsed: round2(totalElapsedUs / 1000),
+    totalMatchAttempts,
+    totalMatchCount,
+    selectors,
+    wastedSelectors
+  };
+}

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: {