trace-engine-cli 0.0.0-stage → 0.1.0

package/dist/src/cli.js

@@ -0,0 +1,477 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { extractDiff } from './engine/extractors/diff.js';
+import { extractEvents } from './engine/extractors/events.js';
+import { extractFind } from './engine/extractors/find.js';
+import { extractInsights } from './engine/extractors/insights.js';
+import { extractInteractions } from './engine/extractors/interactions.js';
+import { extractNavigations } from './engine/extractors/navigations.js';
+import { extractNetwork } from './engine/extractors/network.js';
+import { extractOverview } from './engine/extractors/overview.js';
+import { extractProfile } from './engine/extractors/profile.js';
+import { scanTraces } from './engine/extractors/scan.js';
+import { extractScheduling } from './engine/extractors/scheduling.js';
+import { extractShifts } from './engine/extractors/shifts.js';
+import { extractTasks } from './engine/extractors/tasks.js';
+import { loadTraceFromFile } from './engine/loader.js';
+import { formatResult } from './formatters/index.js';
+import { parseTimeRange, parseTimeValue, resolveTimeRange } from './utils/filter.js';
+/**
+ * Splits a comma-separated argument into trimmed, non-empty tokens.
+ */
+function parseCommaList(val) {
+    if (!val) {
+        return undefined;
+    }
+    const items = String(val)
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return items.length > 0 ? items : undefined;
+}
+export async function runCli(argv) {
+    const cli = yargs(hideBin(argv))
+        .scriptName('trace-cli')
+        .usage('$0 [command] <file> [options]')
+        .option('format', {
+        alias: 'f',
+        type: 'string',
+        choices: ['toon', 'md'],
+        default: 'toon',
+        describe: 'Output format (toon or md)',
+    })
+        .option('trace-engine', {
+        type: 'string',
+        describe: 'Path to custom trace engine bundle',
+    })
+        .option('time-range', {
+        type: 'string',
+        describe: 'Time window (relative to trace start by default, e.g. "3500,4200", "3.5s,4.2s", "100ms-500ms")',
+    })
+        .option('absolute-timestamps', {
+        type: 'boolean',
+        default: false,
+        describe: 'Treat time ranges as raw absolute trace timestamps rather than relative to trace start (default: false)',
+    })
+        .command(['overview <file>', '$0 <file>'], 'High-level trace metadata, Core Web Vitals, and main thread category breakdown (default command)', (y) => y.positional('file', {
+        describe: 'Path to trace file (.json or .json.gz)',
+        type: 'string',
+        demandOption: true,
+    }), async (args) => {
+        const loaded = await loadTraceFromFile(args.file, args.traceEngine);
+        const rawRange = parseTimeRange(args.timeRange);
+        const timeRange = resolveTimeRange(rawRange, loaded.parsedTrace.data.Meta.traceBounds, args.absoluteTimestamps);
+        const result = extractOverview(loaded, { timeRange });
+        const isDefaultCmd = !args._.includes('overview');
+        console.log(formatResult(result, {
+            format: args.format,
+            type: 'overview',
+            includeHint: isDefaultCmd,
+        }));
+    })
+        .command('insights <file>', 'Diagnostic insight cards (LCP, INP, CLS, render-blocking, third-parties)', (y) => y
+        .positional('file', {
+        describe: 'Path to trace file (.json or .json.gz)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('category', {
+        type: 'string',
+        choices: ['lcp', 'inp', 'cls', 'render-blocking', 'third-parties'],
+        describe: 'Filter insights by specific diagnostic category',
+    })
+        .option('navigation', {
+        alias: ['nav'],
+        type: 'string',
+        describe: 'Navigation ID to inspect insights for',
+    }), async (args) => {
+        const loaded = await loadTraceFromFile(args.file, args.traceEngine);
+        const result = extractInsights(loaded, {
+            category: args.category,
+            navigationId: args.navigation,
+        });
+        console.log(formatResult(result, {
+            format: args.format,
+            type: 'insights',
+        }));
+    })
+        .command('tasks <file>', 'Long tasks, bottom-up and top-down TraceTree call aggregations', (y) => y
+        .positional('file', {
+        describe: 'Path to trace file (.json or .json.gz)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('min-duration', {
+        type: 'number',
+        default: 50,
+        describe: 'Minimum task duration threshold in milliseconds (default: 50ms)',
+    })
+        .option('tree', {
+        type: 'string',
+        choices: ['bottom-up', 'top-down'],
+        describe: "Generate aggregated call tree ('bottom-up' sorted by self-time, 'top-down' sorted by total duration)",
+    })
+        .option('top', {
+        alias: ['limit'],
+        type: 'number',
+        default: 20,
+        describe: 'Limit output to top N tasks (default: 20)',
+    }), async (args) => {
+        const loaded = await loadTraceFromFile(args.file, args.traceEngine);
+        const rawRange = parseTimeRange(args.timeRange);
+        const timeRange = resolveTimeRange(rawRange, loaded.parsedTrace.data.Meta.traceBounds, args.absoluteTimestamps);
+        const result = extractTasks(loaded, {
+            minDurationMs: args.minDuration,
+            tree: args.tree,
+            top: args.top,
+            timeRange,
+        });
+        console.log(formatResult(result, {
+            format: args.format,
+            type: 'tasks',
+        }));
+    })
+        .command('find <file>', 'Search for function execution instances, call frequency, and starvation intervals', (y) => y
+        .positional('file', {
+        describe: 'Path to trace file (.json or .json.gz)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('function', {
+        alias: ['fn', 'name'],
+        type: 'string',
+        demandOption: true,
+        describe: 'Function name or pattern to search for',
+    })
+        .option('top', {
+        alias: ['limit'],
+        type: 'number',
+        default: 50,
+        describe: 'Maximum number of invocation entries to list (default: 50)',
+    }), async (args) => {
+        const loaded = await loadTraceFromFile(args.file, args.traceEngine);
+        const rawRange = parseTimeRange(args.timeRange);
+        const timeRange = resolveTimeRange(rawRange, loaded.parsedTrace.data.Meta.traceBounds, args.absoluteTimestamps);
+        const result = extractFind(loaded, {
+            functionName: args.function,
+            timeRange,
+            limit: args.top,
+        });
+        console.log(formatResult(result, {
+            format: args.format,
+            type: 'find',
+        }));
+    })
+        .command('profile <file>', 'Time-bucketed CPU profiling progression across discrete intervals', (y) => y
+        .positional('file', {
+        describe: 'Path to trace file (.json or .json.gz)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('bucket', {
+        type: 'string',
+        describe: 'Bucket slice duration with optional unit (e.g. "50ms", "0.1s", "50", default: dynamic ~50ms)',
+    })
+        .option('top', {
+        alias: ['limit'],
+        type: 'number',
+        default: 3,
+        describe: 'Top N functions to include per time bucket (default: 3)',
+    }), async (args) => {
+        const loaded = await loadTraceFromFile(args.file, args.traceEngine);
+        const rawRange = parseTimeRange(args.timeRange);
+        const timeRange = resolveTimeRange(rawRange, loaded.parsedTrace.data.Meta.traceBounds, args.absoluteTimestamps);
+        const bucketMs = args.bucket ? parseTimeValue(String(args.bucket)) : undefined;
+        const result = extractProfile(loaded, {
+            timeRange,
+            bucketMs,
+            top: args.top,
+        });
+        console.log(formatResult(result, {
+            format: args.format,
+            type: 'profile',
+        }));
+    })
+        .command('diff <file>', 'Differential CPU profiling comparing two time windows in the trace', (y) => y
+        .positional('file', {
+        describe: 'Path to trace file (.json or .json.gz)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('window-a', {
+        type: 'string',
+        demandOption: true,
+        describe: 'Baseline time window (e.g. "3500,4000", "3.5s,4.0s", relative to start by default)',
+    })
+        .option('window-b', {
+        type: 'string',
+        demandOption: true,
+        describe: 'Comparison time window (e.g. "4000,4500", "4.0s,4.5s", relative to start by default)',
+    })
+        .option('top', {
+        alias: ['limit'],
+        type: 'number',
+        default: 20,
+        describe: 'Maximum differential entries to return (default: 20)',
+    }), async (args) => {
+        const loaded = await loadTraceFromFile(args.file, args.traceEngine);
+        const rawRangeA = parseTimeRange(args['window-a']);
+        const rawRangeB = parseTimeRange(args['window-b']);
+        const bounds = loaded.parsedTrace.data.Meta.traceBounds;
+        const isAbsolute = args.absoluteTimestamps;
+        const windowA = resolveTimeRange(rawRangeA, bounds, isAbsolute);
+        const windowB = resolveTimeRange(rawRangeB, bounds, isAbsolute);
+        if (!windowA || !windowB) {
+            throw new Error('Both --window-a and --window-b must be valid time ranges.');
+        }
+        const result = extractDiff(loaded, {
+            windowA,
+            windowB,
+            top: args.top,
+        });
+        console.log(formatResult(result, {
+            format: args.format,
+            type: 'diff',
+        }));
+    })
+        .command('scheduling <file>', 'Async task and animation frame scheduling, cancellation, and churn metrics', (y) => y.positional('file', {
+        describe: 'Path to trace file (.json or .json.gz)',
+        type: 'string',
+        demandOption: true,
+    }), async (args) => {
+        const loaded = await loadTraceFromFile(args.file, args.traceEngine);
+        const rawRange = parseTimeRange(args.timeRange);
+        const timeRange = resolveTimeRange(rawRange, loaded.parsedTrace.data.Meta.traceBounds, args.absoluteTimestamps);
+        const result = extractScheduling(loaded, { timeRange });
+        console.log(formatResult(result, {
+            format: args.format,
+            type: 'scheduling',
+        }));
+    })
+        .command('network <file>', 'Network request waterfall, timings, and initiator chains', (y) => y
+        .positional('file', {
+        describe: 'Path to trace file (.json or .json.gz)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('render-blocking', {
+        type: 'boolean',
+        default: false,
+        describe: 'Filter only render-blocking requests',
+    })
+        .option('slowest', {
+        alias: ['top', 'limit'],
+        type: 'number',
+        default: 20,
+        describe: 'Limit output to N slowest requests (default: 20)',
+    })
+        .option('initiator-chain', {
+        type: 'string',
+        describe: 'Trace the upstream request initiator chain matching a requestId or URL substring',
+    }), async (args) => {
+        const loaded = await loadTraceFromFile(args.file, args.traceEngine);
+        const rawRange = parseTimeRange(args.timeRange);
+        const timeRange = resolveTimeRange(rawRange, loaded.parsedTrace.data.Meta.traceBounds, args.absoluteTimestamps);
+        const result = extractNetwork(loaded, {
+            renderBlocking: args.renderBlocking,
+            slowest: args.slowest,
+            initiatorChain: args.initiatorChain,
+            timeRange,
+        });
+        console.log(formatResult(result, {
+            format: args.format,
+            type: 'network',
+        }));
+    })
+        .command('interactions <file>', 'User interaction latencies and target DOM elements', (y) => y.positional('file', {
+        describe: 'Path to trace file (.json or .json.gz)',
+        type: 'string',
+        demandOption: true,
+    }), async (args) => {
+        const loaded = await loadTraceFromFile(args.file, args.traceEngine);
+        const rawRange = parseTimeRange(args.timeRange);
+        const timeRange = resolveTimeRange(rawRange, loaded.parsedTrace.data.Meta.traceBounds, args.absoluteTimestamps);
+        const result = extractInteractions(loaded, { timeRange });
+        console.log(formatResult(result, {
+            format: args.format,
+            type: 'interactions',
+        }));
+    })
+        .command('shifts <file>', 'Layout shift clusters, scores, and culprit elements', (y) => y
+        .positional('file', {
+        describe: 'Path to trace file (.json or .json.gz)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('events', {
+        type: 'boolean',
+        default: false,
+        describe: 'Include individual shift events within each cluster',
+    }), async (args) => {
+        const loaded = await loadTraceFromFile(args.file, args.traceEngine);
+        const rawRange = parseTimeRange(args.timeRange);
+        const timeRange = resolveTimeRange(rawRange, loaded.parsedTrace.data.Meta.traceBounds, args.absoluteTimestamps);
+        const result = extractShifts(loaded, {
+            timeRange,
+            includeEvents: args.events,
+        });
+        console.log(formatResult(result, {
+            format: args.format,
+            type: 'shifts',
+        }));
+    })
+        .command('events <file>', 'Inspect and filter raw trace events by name, category, phase, or payload fields', (y) => y
+        .positional('file', {
+        describe: 'Path to trace file (.json or .json.gz)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('name', {
+        alias: ['event'],
+        type: 'string',
+        describe: 'Event name or comma-separated event names (e.g. "LayoutShift,navigationStart")',
+    })
+        .option('category', {
+        alias: ['cat'],
+        type: 'string',
+        describe: 'Filter by event category',
+    })
+        .option('phase', {
+        alias: ['ph'],
+        type: 'string',
+        describe: 'Filter by event phase (e.g. "I", "X", "B", "E")',
+    })
+        .option('fields', {
+        type: 'string',
+        describe: 'Comma-separated dot-notation field paths to extract (e.g. "name,ts,args.data.navigationId")',
+    })
+        .option('top', {
+        alias: ['limit'],
+        type: 'number',
+        default: 50,
+        describe: 'Maximum number of matching events to return (default: 50)',
+    }), async (args) => {
+        const loaded = await loadTraceFromFile(args.file, args.traceEngine);
+        const rawRange = parseTimeRange(args.timeRange);
+        const timeRange = resolveTimeRange(rawRange, loaded.parsedTrace.data.Meta.traceBounds, args.absoluteTimestamps);
+        const names = parseCommaList(args.name);
+        const fields = parseCommaList(args.fields);
+        const result = extractEvents(loaded, {
+            names,
+            category: args.category,
+            phase: args.phase,
+            fields,
+            timeRange,
+            limit: args.top,
+        });
+        console.log(formatResult(result, {
+            format: args.format,
+            type: 'events',
+        }));
+    })
+        .command(['navigations <file>', 'navs <file>'], 'List all navigations in the trace and their InsightSet mappings', (y) => y.positional('file', {
+        describe: 'Path to trace file (.json or .json.gz)',
+        type: 'string',
+        demandOption: true,
+    }), async (args) => {
+        const loaded = await loadTraceFromFile(args.file, args.traceEngine);
+        const result = extractNavigations(loaded);
+        console.log(formatResult(result, {
+            format: args.format,
+            type: 'navigations',
+        }));
+    })
+        .command('scan <targets..>', 'Scan multiple trace files or directories for events, categories, phases, or text patterns', (y) => y
+        .positional('targets', {
+        describe: 'Directory paths, glob patterns, or trace file paths (.json, .json.gz)',
+        type: 'string',
+        array: true,
+        demandOption: true,
+    })
+        .option('name', {
+        alias: ['event'],
+        type: 'string',
+        describe: 'Event name or comma-separated event names (e.g. "LayoutShift,RunTask")',
+    })
+        .option('category', {
+        alias: ['cat'],
+        type: 'string',
+        describe: 'Filter by event category',
+    })
+        .option('phase', {
+        alias: ['ph'],
+        type: 'string',
+        describe: 'Filter by event phase (e.g. "X", "I", "B", "E")',
+    })
+        .option('grep', {
+        alias: ['pattern'],
+        type: 'string',
+        describe: 'Raw text or substring to search for within trace events or payloads',
+    })
+        .option('fields', {
+        type: 'string',
+        describe: 'Comma-separated dot-notation property paths that must exist on matching events',
+    })
+        .option('top', {
+        alias: ['limit'],
+        type: 'number',
+        default: 50,
+        describe: 'Maximum number of matched files to return (default: 50)',
+    }), async (args) => {
+        const rawTargets = Array.isArray(args.targets)
+            ? args.targets
+            : [String(args.targets)];
+        const names = parseCommaList(args.name);
+        const fields = parseCommaList(args.fields);
+        const result = scanTraces({
+            targets: rawTargets,
+            names,
+            category: args.category,
+            phase: args.phase,
+            grep: args.grep,
+            fields,
+            limit: args.top,
+        });
+        console.log(formatResult(result, {
+            format: args.format,
+            type: 'scan',
+        }));
+    })
+        .demandCommand(1, 'Please specify a trace file or subcommand.')
+        .strict()
+        .fail((msg, err) => {
+        if (err) {
+            throw err;
+        }
+        if (msg) {
+            if (msg.startsWith('Unknown argument:')) {
+                const arg = msg.replace('Unknown argument:', '').trim();
+                if (arg.endsWith('.json') || arg.endsWith('.json.gz')) {
+                    throw new Error(`Command accepts only a single trace file. Received multiple files. To search across multiple files or directories, use:\n  trace-cli scan <dir-or-glob> [options]`);
+                }
+            }
+            throw new Error(msg);
+        }
+        throw new Error('Command execution failed.');
+    })
+        .help();
+    const userArgs = hideBin(argv);
+    if (userArgs.length === 0) {
+        cli.showHelp();
+        return;
+    }
+    await cli.parseAsync();
+}

package/dist/src/engine/adapter.d.ts

@@ -0,0 +1,13 @@
+export type TraceEngine = typeof import('@paulirish/trace_engine');
+/**
+ * Dynamically resolves and imports the DevTools Trace Engine module.
+ *
+ * Resolution priority:
+ * 1. Explicit path passed via `customPath` (e.g. `--trace-engine=<path>`)
+ * 2. Locally vendored engine bundle at `./vendor/trace_engine.js` (generated via `npm run bundle:engine`)
+ * 3. Default npm package distribution `@paulirish/trace_engine`
+ *
+ * @param customPath - Optional filesystem path to a custom Trace Engine bundle.
+ * @returns The imported TraceEngine module namespace.
+ */
+export declare function loadTraceEngine(customPath?: string): Promise<TraceEngine>;

package/dist/src/engine/adapter.js

@@ -0,0 +1,51 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+let cachedEngine = null;
+let cachedCustomPath;
+/**
+ * Dynamically resolves and imports the DevTools Trace Engine module.
+ *
+ * Resolution priority:
+ * 1. Explicit path passed via `customPath` (e.g. `--trace-engine=<path>`)
+ * 2. Locally vendored engine bundle at `./vendor/trace_engine.js` (generated via `npm run bundle:engine`)
+ * 3. Default npm package distribution `@paulirish/trace_engine`
+ *
+ * @param customPath - Optional filesystem path to a custom Trace Engine bundle.
+ * @returns The imported TraceEngine module namespace.
+ */
+export async function loadTraceEngine(customPath) {
+    if (cachedEngine && cachedCustomPath === customPath) {
+        return cachedEngine;
+    }
+    let engine;
+    if (customPath) {
+        const resolved = path.resolve(process.cwd(), customPath);
+        engine = (await import(pathToFileURL(resolved).href));
+    }
+    else {
+        const vendoredPath = path.resolve(import.meta.dirname, 'vendor/trace_engine.js');
+        if (fs.existsSync(vendoredPath)) {
+            engine = (await import(pathToFileURL(vendoredPath).href));
+        }
+        else {
+            engine = (await import('@paulirish/trace_engine'));
+        }
+    }
+    cachedEngine = engine;
+    cachedCustomPath = customPath;
+    return engine;
+}

package/dist/src/engine/extractors/diff.d.ts

@@ -0,0 +1,12 @@
+import type { TimeRange } from '../../utils/filter.js';
+import type { LoadedTrace } from '../loader.js';
+import type { DiffResult } from '../types.js';
+export interface ExtractDiffOptions {
+    windowA: TimeRange;
+    windowB: TimeRange;
+    top?: number;
+}
+/**
+ * Compares CPU activity between two time windows within a single trace.
+ */
+export declare function extractDiff(loadedTrace: LoadedTrace, options: ExtractDiffOptions): DiffResult;

package/dist/src/engine/extractors/diff.js

@@ -0,0 +1,100 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import { round } from '../../utils/units.js';
+import { getMainRendererThread } from '../helpers.js';
+/**
+ * Compares CPU activity between two time windows within a single trace.
+ */
+export function extractDiff(loadedTrace, options) {
+    const { engine, parsedTrace } = loadedTrace;
+    const { windowA, windowB } = options;
+    const topCount = options.top ?? 20;
+    const result = {
+        windowA: {
+            startMs: windowA.startMs,
+            endMs: windowA.endMs,
+            durationMs: round(windowA.endMs - windowA.startMs),
+        },
+        windowB: {
+            startMs: windowB.startMs,
+            endMs: windowB.endMs,
+            durationMs: round(windowB.endMs - windowB.startMs),
+        },
+        entries: [],
+    };
+    const mainThread = getMainRendererThread(parsedTrace.data);
+    if (!mainThread?.entries?.length) {
+        return result;
+    }
+    const entriesParam = mainThread.entries;
+    function profileWindow(range) {
+        const bottomUp = new engine.Extras.TraceTree.BottomUpRootNode(entriesParam, {
+            textFilter: { accept: () => true },
+            filters: [],
+            startTime: engine.Types.Timing.Milli(range.startMs),
+            endTime: engine.Types.Timing.Milli(range.endMs),
+        });
+        const map = new Map();
+        let totalActive = 0;
+        const children = bottomUp.children();
+        for (const node of children.values()) {
+            if (node.selfTime <= 0)
+                continue;
+            // biome-ignore lint/suspicious/noExplicitAny: generic trace event
+            const frame = engine.Extras.TraceTree.eventStackFrame(node.event);
+            const fnName = frame?.functionName || node.event?.name || String(node.id) || 'Unknown';
+            if (fnName === '(root)' || fnName === '(idle)')
+                continue;
+            totalActive += node.selfTime;
+            const existing = map.get(fnName);
+            if (existing) {
+                existing.selfTimeMs += node.selfTime;
+            }
+            else {
+                map.set(fnName, {
+                    name: fnName,
+                    url: frame?.url,
+                    selfTimeMs: node.selfTime,
+                });
+            }
+        }
+        return { map, totalActive };
+    }
+    const profA = profileWindow(windowA);
+    const profB = profileWindow(windowB);
+    const allNames = new Set([...profA.map.keys(), ...profB.map.keys()]);
+    const diffs = [];
+    for (const name of allNames) {
+        const a = profA.map.get(name);
+        const b = profB.map.get(name);
+        const msA = a ? round(a.selfTimeMs) : 0;
+        const msB = b ? round(b.selfTimeMs) : 0;
+        const pctA = profA.totalActive > 0 && a ? round((a.selfTimeMs / profA.totalActive) * 100, 1) : 0;
+        const pctB = profB.totalActive > 0 && b ? round((b.selfTimeMs / profB.totalActive) * 100, 1) : 0;
+        const deltaPct = round(pctB - pctA, 1);
+        diffs.push({
+            functionName: name,
+            url: b?.url || a?.url,
+            selfTimeMsA: msA,
+            selfTimePctA: pctA,
+            selfTimeMsB: msB,
+            selfTimePctB: pctB,
+            deltaPct,
+        });
+    }
+    // Sort by greatest absolute percentage shift
+    diffs.sort((x, y) => Math.abs(y.deltaPct) - Math.abs(x.deltaPct));
+    result.entries = diffs.slice(0, topCount);
+    return result;
+}

package/dist/src/engine/extractors/events.d.ts

@@ -0,0 +1,27 @@
+import { type TimeRange } from '../../utils/filter.js';
+import type { LoadedTrace } from '../loader.js';
+import type { EventsResult } from '../types.js';
+/**
+ * Configuration options for filtering and extracting raw trace events.
+ */
+export interface ExtractEventsOptions {
+    /** Event names to match (exact match). Multiple names match as a union. */
+    names?: string[];
+    /** Exact trace event category (e.g. 'devtools.timeline', 'v8'). */
+    category?: string;
+    /** Chromium event phase code (e.g. 'X' for complete, 'I' for instant, 'B'/'E' for begin/end). */
+    phase?: string;
+    /** Dot-notation property paths to project into selectedFields (e.g. 'args.data.navigationId'). */
+    fields?: string[];
+    /** Time window in milliseconds (relative or absolute, matching trace bounds). */
+    timeRange?: TimeRange;
+    /** Maximum number of events to return in the events array. Default: 50. */
+    limit?: number;
+}
+/**
+ * Filters and extracts raw trace events matching query criteria.
+ *
+ * Normalizes event timestamps and durations to milliseconds.
+ * Returns the total number of matched events and a capped array of event items.
+ */
+export declare function extractEvents(loadedTrace: LoadedTrace, options?: ExtractEventsOptions): EventsResult;