devtools-tracing 1.3.0 → 1.4.0

package/.vscode/launch.json

@@ -4,9 +4,33 @@
     {
       "type": "node",
       "request": "launch",
-      "name": "Debug sourcemap example",
+      "name": "Debug selector-stats",
       "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/tsx",
-      "args": ["examples/sourcemap.ts", "${input:traceFile}"],
+      "args": ["cli.ts", "selector-stats", "${input:traceFile}"],
+      "console": "integratedTerminal"
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug inp",
+      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/tsx",
+      "args": ["cli.ts", "inp", "${input:traceFile}"],
+      "console": "integratedTerminal"
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug sourcemap",
+      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/tsx",
+      "args": ["cli.ts", "sourcemap", "${input:traceFile}"],
+      "console": "integratedTerminal"
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug stats",
+      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/tsx",
+      "args": ["cli.ts", "stats", "${input:traceFile}"],
       "console": "integratedTerminal"
     }
   ],

package/README.md

@@ -8,7 +8,35 @@ Node.js library for programmatic analysis of Chrome DevTools performance traces.
 npm install devtools-tracing
 ```
 
-## Quick start
+## CLI
+
+Analyze traces directly from the command line:
+
+```sh
+npx devtools-tracing <command> <trace-file>
+```
+
+Supports both `.json` and `.json.gz` trace files.
+
+### Commands
+
+```sh
+# Top CSS selectors by elapsed time and match attempts, plus invalidation tracking
+npx devtools-tracing selector-stats trace.json.gz
+
+# INP (Interaction to Next Paint) breakdown
+npx devtools-tracing inp trace.json.gz
+
+# Timeline category statistics
+npx devtools-tracing stats trace.json.gz
+
+# Source map symbolication (writes a .symbolicated.json.gz alongside the input)
+npx devtools-tracing sourcemap trace.json.gz
+```
+
+See the [`commands/`](./commands) directory for full source.
+
+## Library usage
 
 ```ts
 import * as fs from 'node:fs';
@@ -33,23 +61,6 @@ await model.parse(traceData.traceEvents, {
 const parsedTrace = model.parsedTrace(0);
 ```
 
-## Examples
-
-Run with a trace file (`.json` or `.json.gz`):
-
-```sh
-# INP breakdown
-npm run example:inp -- trace.json.gz
-
-# Timeline category stats
-npm run example:stats -- trace.json.gz
-
-# Source map symbolication
-npm run example:sourcemap -- trace.json.gz
-```
-
-See the [`examples/`](./examples) directory for full source.
-
 ## How it works
 
 A [build script](./generate.ts) extracts trace-related code from the `chrome-devtools-frontend` npm package into `lib/`, resolving dependencies via AST analysis and stubbing browser APIs. The result is bundled into a single CommonJS file via esbuild.

package/cli.ts

@@ -0,0 +1,46 @@
+import { run as cssSelectors } from './commands/selector-stats.js';
+import { run as inp } from './commands/inp.js';
+import { run as sourcemap } from './commands/sourcemap.js';
+import { run as stats } from './commands/stats.js';
+
+const commands: Record<string, (tracePath: string) => Promise<void>> = {
+  'selector-stats': cssSelectors,
+  inp,
+  sourcemap,
+  stats,
+};
+
+function printUsage() {
+  console.log('Usage: devtools-tracing <command> <trace-file>');
+  console.log('\nCommands:');
+  console.log('  selector-stats  Top CSS selectors from selector stats and invalidation tracking');
+  console.log('  inp            Extract INP (Interaction to Next Paint) breakdown');
+  console.log('  sourcemap      Symbolicate a trace using source maps');
+  console.log('  stats          Generate timeline category statistics');
+}
+
+async function main() {
+  const [command, tracePath] = process.argv.slice(2);
+
+  if (!command || command === '--help' || command === '-h') {
+    printUsage();
+    process.exit(0);
+  }
+
+  const run = commands[command];
+  if (!run) {
+    console.error(`Unknown command: ${command}`);
+    printUsage();
+    process.exit(1);
+  }
+
+  if (!tracePath) {
+    console.error(`Missing trace file path.`);
+    console.error(`Usage: devtools-tracing ${command} <trace-file>`);
+    process.exit(1);
+  }
+
+  await run(tracePath);
+}
+
+main();

package/{examples → commands}/inp.ts

@@ -3,12 +3,7 @@ import * as zlib from 'node:zlib';
 
 import { initDevToolsTracing, Trace } from '../';
 
-async function main() {
-  const tracePath = process.argv[2];
-  if (!tracePath) {
-    console.error('Usage: npm run examples:inp <path-to-trace-file>');
-    process.exit(1);
-  }
+export async function run(tracePath: string) {
   initDevToolsTracing();
 
   const fileData = fs.readFileSync(tracePath);
@@ -30,5 +25,3 @@ async function main() {
     inp,
   });
 }
-
-main();

package/commands/selector-stats.ts

@@ -0,0 +1,145 @@
+import * as fs from 'node:fs';
+import * as zlib from 'node:zlib';
+
+import { initDevToolsTracing, Trace } from '../';
+
+const SelectorTimingsKey = Trace.Types.Events.SelectorTimingsKey;
+
+export async function run(tracePath: string) {
+  initDevToolsTracing();
+
+  const fileData = fs.readFileSync(tracePath);
+  const decompressedData = tracePath.endsWith('.gz')
+    ? zlib.gunzipSync(fileData)
+    : fileData;
+  const traceData = JSON.parse(
+    decompressedData.toString(),
+  ) as Trace.Types.File.TraceFile;
+
+  const traceModel = Trace.TraceModel.Model.createWithAllHandlers({
+    debugMode: true,
+    enableAnimationsFrameHandler: false,
+    maxInvalidationEventsPerEvent: 20,
+    showAllEvents: false,
+  });
+  await traceModel.parse(traceData.traceEvents, {
+    isCPUProfile: false,
+    isFreshRecording: false,
+    metadata: traceData.metadata,
+    showAllEvents: false,
+  });
+  const parsedTrace = traceModel.parsedTrace(0)!;
+  const parsedTraceData = parsedTrace.data;
+
+  // --- Selector Stats ---
+  const selectorStatsData = parsedTraceData.SelectorStats;
+  const selectorMap = new Map<
+    string,
+    Trace.Types.Events.SelectorTiming
+  >();
+
+  for (const [, value] of selectorStatsData.dataForRecalcStyleEvent) {
+    for (const timing of value.timings) {
+      const key =
+        timing[SelectorTimingsKey.Selector] +
+        '_' +
+        timing[SelectorTimingsKey.StyleSheetId];
+      const existing = selectorMap.get(key);
+      if (existing) {
+        existing[SelectorTimingsKey.Elapsed] +=
+          timing[SelectorTimingsKey.Elapsed];
+        existing[SelectorTimingsKey.MatchAttempts] +=
+          timing[SelectorTimingsKey.MatchAttempts];
+        existing[SelectorTimingsKey.MatchCount] +=
+          timing[SelectorTimingsKey.MatchCount];
+        existing[SelectorTimingsKey.FastRejectCount] +=
+          timing[SelectorTimingsKey.FastRejectCount];
+      } else {
+        selectorMap.set(key, { ...timing });
+      }
+    }
+  }
+
+  const allTimings = [...selectorMap.values()];
+  const TOP_N = 15;
+
+  // Top selectors by elapsed time
+  const byElapsed = allTimings
+    .sort(
+      (a, b) =>
+        b[SelectorTimingsKey.Elapsed] - a[SelectorTimingsKey.Elapsed],
+    )
+    .slice(0, TOP_N);
+
+  console.log(`\n=== Top ${TOP_N} CSS Selectors by Elapsed Time ===\n`);
+  for (const t of byElapsed) {
+    const elapsedMs = (t[SelectorTimingsKey.Elapsed] / 1000).toFixed(2);
+    console.log(
+      `  ${elapsedMs}ms | attempts: ${t[SelectorTimingsKey.MatchAttempts]} | matches: ${t[SelectorTimingsKey.MatchCount]} | ${t[SelectorTimingsKey.Selector]}`,
+    );
+  }
+
+  // Top selectors by match attempts
+  const byAttempts = [...selectorMap.values()]
+    .sort(
+      (a, b) =>
+        b[SelectorTimingsKey.MatchAttempts] -
+        a[SelectorTimingsKey.MatchAttempts],
+    )
+    .slice(0, TOP_N);
+
+  console.log(`\n=== Top ${TOP_N} CSS Selectors by Match Attempts ===\n`);
+  for (const t of byAttempts) {
+    const elapsedMs = (t[SelectorTimingsKey.Elapsed] / 1000).toFixed(2);
+    console.log(
+      `  ${t[SelectorTimingsKey.MatchAttempts]} attempts | ${elapsedMs}ms | matches: ${t[SelectorTimingsKey.MatchCount]} | ${t[SelectorTimingsKey.Selector]}`,
+    );
+  }
+
+  // --- Invalidation Tracking ---
+  const invalidatedNodes = selectorStatsData.invalidatedNodeList;
+  console.log(
+    `\n=== Invalidation Tracking (${invalidatedNodes.length} invalidated nodes) ===\n`,
+  );
+
+  // Aggregate selectors that caused invalidations
+  const invalidationSelectorCounts = new Map<string, number>();
+  for (const node of invalidatedNodes) {
+    for (const sel of node.selectorList) {
+      const count = invalidationSelectorCounts.get(sel.selector) ?? 0;
+      invalidationSelectorCounts.set(sel.selector, count + 1);
+    }
+  }
+
+  const topInvalidationSelectors = [...invalidationSelectorCounts.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, TOP_N);
+
+  console.log(
+    `  Top ${TOP_N} selectors causing invalidations:\n`,
+  );
+  for (const [selector, count] of topInvalidationSelectors) {
+    console.log(`  ${count}x | ${selector}`);
+  }
+
+  // Subtree vs single-node invalidations
+  const subtreeCount = invalidatedNodes.filter((n) => n.subtree).length;
+  console.log(
+    `\n  Subtree invalidations: ${subtreeCount} / ${invalidatedNodes.length} total`,
+  );
+
+  // --- Totals ---
+  let totalElapsedUs = 0;
+  let totalMatchAttempts = 0;
+  let totalMatchCount = 0;
+  for (const t of allTimings) {
+    totalElapsedUs += t[SelectorTimingsKey.Elapsed];
+    totalMatchAttempts += t[SelectorTimingsKey.MatchAttempts];
+    totalMatchCount += t[SelectorTimingsKey.MatchCount];
+  }
+  console.log(`\n=== Totals ===\n`);
+  console.log(`  Unique selectors: ${allTimings.length}`);
+  console.log(`  Total elapsed: ${(totalElapsedUs / 1000).toFixed(2)}ms`);
+  console.log(`  Total match attempts: ${totalMatchAttempts}`);
+  console.log(`  Total match count: ${totalMatchCount}`);
+}

package/{examples → commands}/sourcemap.ts

@@ -8,12 +8,7 @@ import {
   Trace,
 } from '../';
 
-async function main() {
-  const tracePath = process.argv[2];
-  if (!tracePath) {
-    console.error('Usage: npm run example:sourcemap <path-to-trace-file>');
-    process.exit(1);
-  }
+export async function run(tracePath: string) {
   initDevToolsTracing();
 
   const fileData = fs.readFileSync(tracePath);
@@ -117,5 +112,3 @@ async function verboseFetch(url: string): Promise<Response> {
   }
   return response;
 }
-
-main();

package/{examples → commands}/stats.ts

@@ -8,12 +8,7 @@ import {
   Trace,
 } from '../';
 
-async function main() {
-  const tracePath = process.argv[2];
-  if (!tracePath) {
-    console.error('Usage: npm run examples:stats <path-to-trace-file>');
-    process.exit(1);
-  }
+export async function run(tracePath: string) {
   initDevToolsTracing();
 
   const fileData = fs.readFileSync(tracePath);
@@ -27,7 +22,6 @@ async function main() {
   const traceModel = Trace.TraceModel.Model.createWithAllHandlers({
     debugMode: true,
     enableAnimationsFrameHandler: false,
-    // includeRuntimeCallStats: false,
     maxInvalidationEventsPerEvent: 20,
     showAllEvents: false,
   });
@@ -62,5 +56,3 @@ async function main() {
 
   console.log(stats);
 }
-
-main();

package/dist/cli.js

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// commands/selector-stats.ts
+var fs = __toESM(require("node:fs"));
+var zlib = __toESM(require("node:zlib"));
+var import__ = require("../");
+var SelectorTimingsKey = import__.Trace.Types.Events.SelectorTimingsKey;
+async function run(tracePath) {
+  (0, import__.initDevToolsTracing)();
+  const fileData = fs.readFileSync(tracePath);
+  const decompressedData = tracePath.endsWith(".gz") ? zlib.gunzipSync(fileData) : fileData;
+  const traceData = JSON.parse(
+    decompressedData.toString()
+  );
+  const traceModel = import__.Trace.TraceModel.Model.createWithAllHandlers({
+    debugMode: true,
+    enableAnimationsFrameHandler: false,
+    maxInvalidationEventsPerEvent: 20,
+    showAllEvents: false
+  });
+  await traceModel.parse(traceData.traceEvents, {
+    isCPUProfile: false,
+    isFreshRecording: false,
+    metadata: traceData.metadata,
+    showAllEvents: false
+  });
+  const parsedTrace = traceModel.parsedTrace(0);
+  const parsedTraceData = parsedTrace.data;
+  const selectorStatsData = parsedTraceData.SelectorStats;
+  const selectorMap = /* @__PURE__ */ new Map();
+  for (const [, value] of selectorStatsData.dataForRecalcStyleEvent) {
+    for (const timing of value.timings) {
+      const key = timing[SelectorTimingsKey.Selector] + "_" + timing[SelectorTimingsKey.StyleSheetId];
+      const existing = selectorMap.get(key);
+      if (existing) {
+        existing[SelectorTimingsKey.Elapsed] += timing[SelectorTimingsKey.Elapsed];
+        existing[SelectorTimingsKey.MatchAttempts] += timing[SelectorTimingsKey.MatchAttempts];
+        existing[SelectorTimingsKey.MatchCount] += timing[SelectorTimingsKey.MatchCount];
+        existing[SelectorTimingsKey.FastRejectCount] += timing[SelectorTimingsKey.FastRejectCount];
+      } else {
+        selectorMap.set(key, { ...timing });
+      }
+    }
+  }
+  const allTimings = [...selectorMap.values()];
+  const TOP_N = 15;
+  const byElapsed = allTimings.sort(
+    (a, b) => b[SelectorTimingsKey.Elapsed] - a[SelectorTimingsKey.Elapsed]
+  ).slice(0, TOP_N);
+  console.log(`
+=== Top ${TOP_N} CSS Selectors by Elapsed Time ===
+`);
+  for (const t of byElapsed) {
+    const elapsedMs = (t[SelectorTimingsKey.Elapsed] / 1e3).toFixed(2);
+    console.log(
+      `  ${elapsedMs}ms | attempts: ${t[SelectorTimingsKey.MatchAttempts]} | matches: ${t[SelectorTimingsKey.MatchCount]} | ${t[SelectorTimingsKey.Selector]}`
+    );
+  }
+  const byAttempts = [...selectorMap.values()].sort(
+    (a, b) => b[SelectorTimingsKey.MatchAttempts] - a[SelectorTimingsKey.MatchAttempts]
+  ).slice(0, TOP_N);
+  console.log(`
+=== Top ${TOP_N} CSS Selectors by Match Attempts ===
+`);
+  for (const t of byAttempts) {
+    const elapsedMs = (t[SelectorTimingsKey.Elapsed] / 1e3).toFixed(2);
+    console.log(
+      `  ${t[SelectorTimingsKey.MatchAttempts]} attempts | ${elapsedMs}ms | matches: ${t[SelectorTimingsKey.MatchCount]} | ${t[SelectorTimingsKey.Selector]}`
+    );
+  }
+  const invalidatedNodes = selectorStatsData.invalidatedNodeList;
+  console.log(
+    `
+=== Invalidation Tracking (${invalidatedNodes.length} invalidated nodes) ===
+`
+  );
+  const invalidationSelectorCounts = /* @__PURE__ */ new Map();
+  for (const node of invalidatedNodes) {
+    for (const sel of node.selectorList) {
+      const count = invalidationSelectorCounts.get(sel.selector) ?? 0;
+      invalidationSelectorCounts.set(sel.selector, count + 1);
+    }
+  }
+  const topInvalidationSelectors = [...invalidationSelectorCounts.entries()].sort((a, b) => b[1] - a[1]).slice(0, TOP_N);
+  console.log(
+    `  Top ${TOP_N} selectors causing invalidations:
+`
+  );
+  for (const [selector, count] of topInvalidationSelectors) {
+    console.log(`  ${count}x | ${selector}`);
+  }
+  const subtreeCount = invalidatedNodes.filter((n) => n.subtree).length;
+  console.log(
+    `
+  Subtree invalidations: ${subtreeCount} / ${invalidatedNodes.length} total`
+  );
+  let totalElapsedUs = 0;
+  let totalMatchAttempts = 0;
+  let totalMatchCount = 0;
+  for (const t of allTimings) {
+    totalElapsedUs += t[SelectorTimingsKey.Elapsed];
+    totalMatchAttempts += t[SelectorTimingsKey.MatchAttempts];
+    totalMatchCount += t[SelectorTimingsKey.MatchCount];
+  }
+  console.log(`
+=== Totals ===
+`);
+  console.log(`  Unique selectors: ${allTimings.length}`);
+  console.log(`  Total elapsed: ${(totalElapsedUs / 1e3).toFixed(2)}ms`);
+  console.log(`  Total match attempts: ${totalMatchAttempts}`);
+  console.log(`  Total match count: ${totalMatchCount}`);
+}
+
+// commands/inp.ts
+var fs2 = __toESM(require("node:fs"));
+var zlib2 = __toESM(require("node:zlib"));
+var import__2 = require("../");
+async function run2(tracePath) {
+  (0, import__2.initDevToolsTracing)();
+  const fileData = fs2.readFileSync(tracePath);
+  const decompressedData = tracePath.endsWith(".gz") ? zlib2.gunzipSync(fileData) : fileData;
+  const traceData = JSON.parse(
+    decompressedData.toString()
+  );
+  const processor = import__2.Trace.Processor.TraceProcessor.createWithAllHandlers();
+  await processor.parse(traceData.traceEvents, {});
+  const insights = processor.insights.get("NO_NAVIGATION");
+  const longestInteractionEvent = insights.model.INPBreakdown.longestInteractionEvent;
+  const inp = longestInteractionEvent.dur / 1e3;
+  console.log({
+    insights: insights?.model.INPBreakdown,
+    inp
+  });
+}
+
+// commands/sourcemap.ts
+var fs3 = __toESM(require("node:fs"));
+var zlib3 = __toESM(require("node:zlib"));
+var import__3 = require("../");
+async function run3(tracePath) {
+  (0, import__3.initDevToolsTracing)();
+  const fileData = fs3.readFileSync(tracePath);
+  const decompressedData = tracePath.endsWith(".gz") ? zlib3.gunzipSync(fileData) : fileData;
+  const traceData = JSON.parse(
+    decompressedData.toString()
+  );
+  const traceModel = import__3.Trace.TraceModel.Model.createWithAllHandlers();
+  const resolveSourceMap = (0, import__3.createSourceMapResolver)({
+    fetch: verboseFetch
+  });
+  await traceModel.parse(traceData.traceEvents, {
+    isCPUProfile: false,
+    isFreshRecording: false,
+    metadata: traceData.metadata,
+    showAllEvents: false,
+    resolveSourceMap
+  });
+  const parsedTrace = traceModel.parsedTrace(0);
+  const parsedTraceData = parsedTrace.data;
+  const scripts = parsedTraceData.Scripts.scripts;
+  const metadataSourceMaps = traceData.metadata?.sourceMaps?.length ?? 0;
+  console.log(`Found ${scripts.length} scripts in trace`);
+  console.log(`Source maps in trace metadata: ${metadataSourceMaps}
+`);
+  let withUrl = 0;
+  let withFrame = 0;
+  let withSourceMapUrl = 0;
+  let withElided = 0;
+  for (const script of scripts) {
+    if (script.url) withUrl++;
+    if (script.frame) withFrame++;
+    if (script.sourceMapUrl) withSourceMapUrl++;
+    if (script.sourceMapUrlElided) withElided++;
+  }
+  console.log("Script breakdown:");
+  console.log(`  with url:                ${withUrl}`);
+  console.log(`  with frame:              ${withFrame}`);
+  console.log(`  with sourceMapUrl:       ${withSourceMapUrl}`);
+  console.log(`  with sourceMapUrlElided: ${withElided}`);
+  console.log(`  (resolution requires url + frame + sourceMapUrl/elided)
+`);
+  let resolvedCount = 0;
+  for (const script of scripts) {
+    if (!script.sourceMap) {
+      continue;
+    }
+    resolvedCount++;
+    const sourceMap = script.sourceMap;
+    const sourceURLs = sourceMap.sourceURLs();
+    console.log(
+      `  ${script.url || script.scriptId} -> ${sourceURLs.length} sources, ${sourceMap.mappings().length} mappings`
+    );
+  }
+  console.log(
+    `Resolved source maps for ${resolvedCount} of ${scripts.length} scripts
+`
+  );
+  const result = (0, import__3.symbolicateTrace)(traceData.traceEvents, scripts);
+  console.log(
+    `Symbolicated ${result.symbolicatedFrames} frames across ${result.symbolicatedEvents} events`
+  );
+  const outPath = tracePath.replace(/(\.(json|json\.gz))$/i, ".symbolicated$1");
+  if (outPath === tracePath) {
+    console.error(
+      "Could not determine output path (expected .json or .json.gz extension)"
+    );
+    process.exit(1);
+  }
+  const outputJson = JSON.stringify(traceData);
+  if (outPath.endsWith(".gz")) {
+    fs3.writeFileSync(outPath, zlib3.gzipSync(outputJson));
+  } else {
+    fs3.writeFileSync(outPath, outputJson);
+  }
+  console.log(`Wrote symbolicated trace to ${outPath}`);
+}
+async function verboseFetch(url) {
+  console.log(`[sourcemap] fetching ${url}`);
+  const response = await fetch(url);
+  if (!response.ok) {
+    console.warn(
+      `[sourcemap] ${url} -> ${response.status} ${response.statusText}`
+    );
+  } else {
+    console.log(`[sourcemap] ${url} -> ok`);
+  }
+  return response;
+}
+
+// commands/stats.ts
+var fs4 = __toESM(require("node:fs"));
+var zlib4 = __toESM(require("node:zlib"));
+var import__4 = require("../");
+async function run4(tracePath) {
+  (0, import__4.initDevToolsTracing)();
+  const fileData = fs4.readFileSync(tracePath);
+  const decompressedData = tracePath.endsWith(".gz") ? zlib4.gunzipSync(fileData) : fileData;
+  const traceData = JSON.parse(
+    decompressedData.toString()
+  );
+  const traceModel = import__4.Trace.TraceModel.Model.createWithAllHandlers({
+    debugMode: true,
+    enableAnimationsFrameHandler: false,
+    maxInvalidationEventsPerEvent: 20,
+    showAllEvents: false
+  });
+  await traceModel.parse(traceData.traceEvents, {
+    isCPUProfile: false,
+    isFreshRecording: false,
+    metadata: traceData.metadata,
+    showAllEvents: false
+  });
+  const parsedTrace = traceModel.parsedTrace(0);
+  const parsedTraceData = parsedTrace.data;
+  const startTime = import__4.Trace.Helpers.Timing.microToMilli(
+    parsedTraceData.Meta.traceBounds.min
+  );
+  const endTime = import__4.Trace.Helpers.Timing.microToMilli(
+    parsedTraceData.Meta.traceBounds.max
+  );
+  const threads = import__4.Trace.Handlers.Threads.threadsInTrace(parsedTrace.data);
+  const mainThread = threads.find(
+    (t) => t.type === import__4.Trace.Handlers.Threads.ThreadType.MAIN_THREAD
+  );
+  if (!mainThread) {
+    throw new Error("No renderer main thread found in trace file");
+  }
+  const rendererEvents = [...mainThread.entries].filter(
+    (e) => (0, import__4.entryIsVisibleInTimeline)(e, parsedTrace)
+  );
+  const stats = (0, import__4.statsForTimeRange)(rendererEvents, startTime, endTime);
+  console.log(stats);
+}
+
+// cli.ts
+var commands = {
+  "selector-stats": run,
+  inp: run2,
+  sourcemap: run3,
+  stats: run4
+};
+function printUsage() {
+  console.log("Usage: devtools-tracing <command> <trace-file>");
+  console.log("\nCommands:");
+  console.log("  selector-stats  Top CSS selectors from selector stats and invalidation tracking");
+  console.log("  inp            Extract INP (Interaction to Next Paint) breakdown");
+  console.log("  sourcemap      Symbolicate a trace using source maps");
+  console.log("  stats          Generate timeline category statistics");
+}
+async function main() {
+  const [command, tracePath] = process.argv.slice(2);
+  if (!command || command === "--help" || command === "-h") {
+    printUsage();
+    process.exit(0);
+  }
+  const run5 = commands[command];
+  if (!run5) {
+    console.error(`Unknown command: ${command}`);
+    printUsage();
+    process.exit(1);
+  }
+  if (!tracePath) {
+    console.error(`Missing trace file path.`);
+    console.error(`Usage: devtools-tracing ${command} <trace-file>`);
+    process.exit(1);
+  }
+  await run5(tracePath);
+}
+main();

package/dist/index.js

@@ -14414,6 +14414,15 @@ function initDevToolsTracing() {
     lookupClosestDevToolsLocale: identity
   };
   DevToolsLocale.instance({ create: true, data: data31 });
+  for (const name of Object.values(ExperimentName)) {
+    if (name === "*" /* ALL */) {
+      continue;
+    }
+    try {
+      experiments.register(name, name);
+    } catch {
+    }
+  }
 }
 
 // lib/front_end/models/trace/trace.ts

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "devtools-tracing",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Utilities for working with trace files",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "devtools-tracing": "dist/cli.js"
+  },
   "scripts": {
-    "build": "tsc --emitDeclarationOnly || true; esbuild index.ts --bundle --platform=node --outfile=dist/index.js --format=cjs",
+    "build": "tsc --emitDeclarationOnly || true; esbuild index.ts --bundle --platform=node --outfile=dist/index.js --format=cjs && esbuild cli.ts --bundle --platform=node --outfile=dist/cli.js --format=cjs --banner:js='#!/usr/bin/env node' --external:../",
     "generate": "tsx generate.ts",
-    "example:inp": "tsx examples/inp.ts",
-    "example:sourcemap": "tsx examples/sourcemap.ts",
-    "example:stats": "tsx examples/stats.ts",
     "size": "du -sh dist/",
     "prepublishOnly": "npm run generate && npm run build"
   },