trace-engine-cli 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,11 @@
+import { type TimeRange } from '../../utils/filter.js';
+import type { LoadedTrace } from '../loader.js';
+import type { ShiftsResult } from '../types.js';
+export interface ExtractShiftsOptions {
+    timeRange?: TimeRange;
+    includeEvents?: boolean;
+}
+/**
+ * Extracts layout shift clusters, scores, and culprit elements.
+ */
+export declare function extractShifts(loadedTrace: LoadedTrace, options?: ExtractShiftsOptions): ShiftsResult;

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

@@ -0,0 +1,118 @@
+// 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 { isEventInBounds } from '../../utils/filter.js';
+import { microToMilli, round } from '../../utils/units.js';
+import { getPrimaryInsightSet } from '../helpers.js';
+/**
+ * Extracts layout shift clusters, scores, and culprit elements.
+ */
+export function extractShifts(loadedTrace, options) {
+    const { parsedTrace } = loadedTrace;
+    const timeRange = options?.timeRange;
+    const rawClusters = (parsedTrace.data.LayoutShifts?.clusters || []);
+    const clusters = [];
+    for (const cluster of rawClusters) {
+        const startMs = microToMilli(cluster.clusterWindow?.min ?? cluster.ts ?? 0);
+        const durMs = microToMilli(cluster.clusterWindow?.range ?? cluster.dur ?? 0);
+        const score = cluster.clusterCumulativeScore ?? 0;
+        if (!isEventInBounds(startMs, durMs, timeRange)) {
+            continue;
+        }
+        const culpritMap = new Map();
+        const individualEvents = [];
+        if (cluster.events) {
+            for (const ev of cluster.events) {
+                const scoreDelta = ev.args?.data?.weighted_score_delta;
+                const nodes = ev.args?.data?.impacted_nodes || [];
+                for (const n of nodes) {
+                    const key = n.selector ||
+                        (n.node_id ? `node:${n.node_id}` : n.debug_name || n.tag_name || 'unknown');
+                    const existing = culpritMap.get(key);
+                    if (existing) {
+                        if (scoreDelta !== undefined) {
+                            existing.scoreDelta = round((existing.scoreDelta ?? 0) + scoreDelta, 4);
+                        }
+                    }
+                    else {
+                        culpritMap.set(key, {
+                            nodeId: n.node_id,
+                            tagName: n.tag_name,
+                            selector: n.selector || (n.node_id ? `Node #${n.node_id}` : undefined),
+                            debugName: n.debug_name,
+                            scoreDelta: scoreDelta !== undefined ? round(scoreDelta, 4) : undefined,
+                        });
+                    }
+                }
+                if (options?.includeEvents) {
+                    const evTsMs = microToMilli(ev.ts ?? 0);
+                    const evScore = ev.args?.data?.score ?? ev.args?.data?.weighted_score_delta ?? 0;
+                    const evWeighted = ev.args?.data?.weighted_score_delta;
+                    const evNavId = ev.args?.data?.navigationId;
+                    const hadRecentInput = ev.args?.data?.had_recent_input;
+                    const impactedNodes = nodes.map((node) => ({
+                        nodeId: node.node_id,
+                        tagName: node.tag_name,
+                        selector: node.selector,
+                        debugName: node.debug_name,
+                        oldRect: node.old_rect,
+                        newRect: node.new_rect,
+                    }));
+                    individualEvents.push({
+                        timestampMs: round(evTsMs),
+                        score: round(evScore, 4),
+                        weightedScoreDelta: evWeighted !== undefined ? round(evWeighted, 4) : undefined,
+                        navigationId: evNavId,
+                        hadRecentInput,
+                        impactedNodes: impactedNodes.length > 0 ? impactedNodes : undefined,
+                    });
+                }
+            }
+        }
+        const clusterNavId = cluster.navigationId ||
+            (cluster.events ? cluster.events[0]?.args?.data?.navigationId : undefined);
+        clusters.push({
+            timestampMs: round(startMs),
+            durationMs: round(durMs),
+            cumulativeScore: round(score, 4),
+            navigationId: clusterNavId,
+            culprits: Array.from(culpritMap.values()),
+            ...(options?.includeEvents ? { events: individualEvents } : {}),
+        });
+    }
+    // If no clusters in handler, check insights
+    if (clusters.length === 0) {
+        const insightSet = getPrimaryInsightSet(parsedTrace);
+        const clsModel = insightSet?.CLSCulprits;
+        if (clsModel?.clusters && clsModel.clusters.length > 0) {
+            for (const c of clsModel.clusters) {
+                const startMs = microToMilli(c.clusterWindow?.min ?? 0);
+                const durMs = microToMilli(c.clusterWindow?.range ?? 0);
+                const score = c.clusterCumulativeScore ?? 0;
+                if (isEventInBounds(startMs, durMs, timeRange)) {
+                    clusters.push({
+                        timestampMs: round(startMs),
+                        durationMs: round(durMs),
+                        cumulativeScore: round(score, 4),
+                        culprits: [],
+                    });
+                }
+            }
+        }
+    }
+    // Sort by score descending
+    clusters.sort((a, b) => b.cumulativeScore - a.cumulativeScore);
+    return {
+        clusters,
+    };
+}

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

@@ -0,0 +1,13 @@
+import { type TimeRange } from '../../utils/filter.js';
+import type { LoadedTrace } from '../loader.js';
+import type { TasksResult } from '../types.js';
+export interface ExtractTasksOptions {
+    minDurationMs?: number;
+    tree?: 'bottom-up' | 'top-down';
+    top?: number;
+    timeRange?: TimeRange;
+}
+/**
+ * Extracts long main thread tasks and aggregated top-down / bottom-up call trees.
+ */
+export declare function extractTasks(loadedTrace: LoadedTrace, options?: ExtractTasksOptions): TasksResult;

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

@@ -0,0 +1,156 @@
+// 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 { isEventInBounds } from '../../utils/filter.js';
+import { microToMilli, round } from '../../utils/units.js';
+import { getMainRendererThread } from '../helpers.js';
+/**
+ * Extracts long main thread tasks and aggregated top-down / bottom-up call trees.
+ */
+export function extractTasks(loadedTrace, options) {
+    const { engine, parsedTrace } = loadedTrace;
+    const minDurationMs = options?.minDurationMs ?? 50;
+    const top = options?.top ?? 20;
+    const treeMode = options?.tree;
+    const timeRange = options?.timeRange;
+    const mainThread = getMainRendererThread(parsedTrace.data);
+    if (!mainThread) {
+        return {
+            mode: treeMode || 'list',
+            tasks: [],
+        };
+    }
+    const traceBounds = parsedTrace.data.Meta.traceBounds;
+    const startMs = timeRange ? timeRange.startMs : microToMilli(traceBounds.min);
+    const endMs = timeRange ? timeRange.endMs : microToMilli(traceBounds.max);
+    if (treeMode === 'bottom-up') {
+        const bottomUp = new engine.Extras.TraceTree.BottomUpRootNode(mainThread.entries, {
+            textFilter: { accept: () => true },
+            filters: [],
+            startTime: engine.Types.Timing.Milli(startMs),
+            endTime: engine.Types.Timing.Milli(endMs),
+        });
+        const tasks = [];
+        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);
+            tasks.push({
+                startTimeMs: round(startMs),
+                durationMs: round(node.totalTime),
+                selfTimeMs: round(node.selfTime),
+                functionName: frame?.functionName || node.event?.name || String(node.id) || 'Unknown',
+                url: frame?.url || undefined,
+                lineNumber: frame?.lineNumber,
+                columnNumber: frame?.columnNumber,
+            });
+        }
+        tasks.sort((a, b) => b.selfTimeMs - a.selfTimeMs);
+        return {
+            mode: 'bottom-up',
+            tasks: tasks.slice(0, top),
+        };
+    }
+    if (treeMode === 'top-down') {
+        const topDown = new engine.Extras.TraceTree.TopDownRootNode(mainThread.entries, {
+            filters: [],
+            startTime: engine.Types.Timing.Milli(startMs),
+            endTime: engine.Types.Timing.Milli(endMs),
+        });
+        const tasks = [];
+        const children = topDown.children();
+        for (const node of children.values()) {
+            // biome-ignore lint/suspicious/noExplicitAny: generic trace event
+            const frame = engine.Extras.TraceTree.eventStackFrame(node.event);
+            tasks.push({
+                startTimeMs: round(startMs),
+                durationMs: round(node.totalTime),
+                selfTimeMs: round(node.selfTime),
+                functionName: frame?.functionName || node.event?.name || String(node.id) || 'Unknown',
+                url: frame?.url || undefined,
+                lineNumber: frame?.lineNumber,
+                columnNumber: frame?.columnNumber,
+            });
+        }
+        tasks.sort((a, b) => b.durationMs - a.durationMs);
+        return {
+            mode: 'top-down',
+            tasks: tasks.slice(0, top),
+        };
+    }
+    // Default List Mode
+    const tasks = [];
+    const entryToNode = parsedTrace.data.Renderer?.entryToNode;
+    for (const entry of mainThread.entries) {
+        if (!entry.dur)
+            continue;
+        const durMs = microToMilli(entry.dur);
+        const startEntryMs = microToMilli(entry.ts);
+        if (durMs < minDurationMs)
+            continue;
+        if (!isEventInBounds(startEntryMs, durMs, timeRange))
+            continue;
+        // biome-ignore lint/suspicious/noExplicitAny: trace helper accepts generic event
+        const isTop = entry.name === 'RunTask' || engine.Helpers.Trace.isTopLevelEvent(entry);
+        if (isTop) {
+            let functionName = entry.name;
+            let url;
+            let lineNumber;
+            let columnNumber;
+            let selfTimeMs = durMs;
+            // biome-ignore lint/suspicious/noExplicitAny: stack frame extraction accepts generic event
+            const frame = engine.Extras.TraceTree.eventStackFrame(entry);
+            if (frame?.functionName) {
+                functionName = frame.functionName;
+                url = frame.url;
+                lineNumber = frame.lineNumber;
+                columnNumber = frame.columnNumber;
+            }
+            if (entryToNode) {
+                const node = entryToNode.get(entry);
+                if (node?.children && node.children.length > 0) {
+                    let childDurationSum = 0;
+                    for (const c of node.children) {
+                        childDurationSum += microToMilli(c.entry.dur ?? 0);
+                    }
+                    selfTimeMs = Math.max(0, durMs - childDurationSum);
+                    if (!frame?.functionName) {
+                        const mainChild = node.children[0].entry;
+                        // biome-ignore lint/suspicious/noExplicitAny: stack frame extraction accepts generic event
+                        const childFrame = engine.Extras.TraceTree.eventStackFrame(mainChild);
+                        functionName = `${entry.name} > ${childFrame?.functionName || mainChild.name}`;
+                        url = childFrame?.url;
+                        lineNumber = childFrame?.lineNumber;
+                        columnNumber = childFrame?.columnNumber;
+                    }
+                }
+            }
+            tasks.push({
+                startTimeMs: round(startEntryMs),
+                durationMs: round(durMs),
+                selfTimeMs: round(selfTimeMs),
+                functionName,
+                url,
+                lineNumber,
+                columnNumber,
+            });
+        }
+    }
+    tasks.sort((a, b) => b.durationMs - a.durationMs);
+    return {
+        mode: 'list',
+        tasks: tasks.slice(0, top),
+    };
+}

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

@@ -0,0 +1,157 @@
+export interface RawThreadEntry {
+    name: string;
+    ts: number;
+    dur?: number;
+    args?: {
+        data?: Record<string, unknown>;
+    };
+}
+export interface RawRendererThread {
+    name: string;
+    entries: RawThreadEntry[];
+    tree?: unknown;
+    layoutEvents?: RawThreadEntry[];
+    recalcStyleEvents?: RawThreadEntry[];
+}
+export interface RawRendererProcess {
+    isOnMainFrame?: boolean;
+    url?: string;
+    threads: Map<number, RawRendererThread>;
+}
+export interface RawInsightModel {
+    LCPBreakdown?: {
+        lcpMs?: number;
+        lcpTs?: number;
+        subparts?: {
+            ttfb?: {
+                range?: number;
+            };
+            loadDelay?: {
+                range?: number;
+            };
+            loadDuration?: {
+                range?: number;
+            };
+            renderDelay?: {
+                range?: number;
+            };
+        };
+        lcpRequest?: {
+            args?: {
+                data?: {
+                    url?: string;
+                };
+            };
+        };
+        lcpEvent?: {
+            args?: {
+                data?: {
+                    nodeName?: string;
+                };
+            };
+        };
+    };
+    INPBreakdown?: {
+        longestInteractionEvent?: {
+            dur: number;
+            ts?: number;
+            type?: string;
+            name?: string;
+            inputDelay?: number;
+            mainThreadHandling?: number;
+            processingDuration?: number;
+            presentationDelay?: number;
+            args?: {
+                data?: {
+                    nodeName?: string;
+                    beginEvent?: {
+                        args?: {
+                            data?: {
+                                nodeName?: string;
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+    CLSCulprits?: {
+        clusters?: Array<{
+            clusterCumulativeScore?: number;
+            ts?: number;
+            dur?: number;
+            clusterWindow?: {
+                min?: number;
+                range?: number;
+            };
+            events?: Array<{
+                args?: {
+                    data?: {
+                        weighted_score_delta?: number;
+                        impacted_nodes?: Array<{
+                            node_id?: number;
+                            tag_name?: string;
+                            selector?: string;
+                            debug_name?: string;
+                            old_rect?: [number, number, number, number];
+                            new_rect?: [number, number, number, number];
+                        }>;
+                    };
+                };
+            }>;
+        }>;
+    };
+    RenderBlocking?: {
+        renderBlockingRequests?: Array<{
+            dur?: number;
+            args?: {
+                data?: {
+                    url?: string;
+                    encodedDataLength?: number;
+                };
+            };
+        }>;
+    };
+    ThirdParties?: {
+        entitySummaries?: Array<{
+            entity?: {
+                name?: string;
+            };
+            transferSize?: number;
+            mainThreadTime?: number;
+        }>;
+    };
+}
+/**
+ * Finds the primary main renderer thread (CrRendererMain) in the trace.
+ */
+export declare function getMainRendererThread(data: any): RawRendererThread | null;
+export interface ParsedTraceWithInsights {
+    insights?: Map<string, {
+        id?: string;
+        model?: RawInsightModel;
+        navigation?: {
+            args?: {
+                data?: {
+                    navigationId?: string;
+                };
+            };
+        };
+    }>;
+}
+export interface InsightEntryResult {
+    insightSetId: string;
+    model: RawInsightModel;
+}
+/**
+ * Finds an insight set entry matching a navigation ID or key.
+ */
+export declare function findInsightEntry(parsedTrace: ParsedTraceWithInsights, navigationId?: string): InsightEntryResult | null;
+/**
+ * Retrieves the insight model set from the parsed trace, optionally filtered by navigation ID.
+ */
+export declare function getPrimaryInsightSet(parsedTrace: ParsedTraceWithInsights, navigationId?: string): RawInsightModel | null;
+/**
+ * Traverses an object along a dot-separated property path.
+ */
+export declare function getPropertyByPath(obj: unknown, path: string): unknown;

package/dist/src/engine/helpers.js

@@ -0,0 +1,95 @@
+// 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.
+/**
+ * Finds the primary main renderer thread (CrRendererMain) in the trace.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: generic trace data
+export function getMainRendererThread(data) {
+    const processes = data?.Renderer?.processes;
+    if (!processes)
+        return null;
+    // 1. Prefer main frame process
+    for (const proc of processes.values()) {
+        if (proc.isOnMainFrame && proc.threads) {
+            for (const thread of proc.threads.values()) {
+                if (thread.name === 'CrRendererMain' && thread.entries?.length > 0) {
+                    return thread;
+                }
+            }
+        }
+    }
+    // 2. Fallback to any process with CrRendererMain
+    for (const proc of processes.values()) {
+        if (proc.threads) {
+            for (const thread of proc.threads.values()) {
+                if (thread.name === 'CrRendererMain' && thread.entries?.length > 0) {
+                    return thread;
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Finds an insight set entry matching a navigation ID or key.
+ */
+export function findInsightEntry(parsedTrace, navigationId) {
+    if (!parsedTrace?.insights || parsedTrace.insights.size === 0) {
+        return null;
+    }
+    if (navigationId) {
+        const directMatch = parsedTrace.insights.get(navigationId);
+        if (directMatch) {
+            const model = (directMatch.model ||
+                directMatch);
+            return { insightSetId: navigationId, model };
+        }
+        for (const [key, val] of parsedTrace.insights.entries()) {
+            const rawVal = val;
+            if (key === navigationId ||
+                rawVal?.id === navigationId ||
+                rawVal?.navigation?.args?.data?.navigationId === navigationId) {
+                const model = (rawVal?.model || val);
+                return { insightSetId: key || rawVal?.id || navigationId, model };
+            }
+        }
+        return null;
+    }
+    for (const [key, val] of parsedTrace.insights.entries()) {
+        const rawVal = val;
+        const model = (rawVal?.model || val);
+        return { insightSetId: key || rawVal?.id || '', model };
+    }
+    return null;
+}
+/**
+ * Retrieves the insight model set from the parsed trace, optionally filtered by navigation ID.
+ */
+export function getPrimaryInsightSet(parsedTrace, navigationId) {
+    return findInsightEntry(parsedTrace, navigationId)?.model ?? null;
+}
+/**
+ * Traverses an object along a dot-separated property path.
+ */
+export function getPropertyByPath(obj, path) {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}

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

@@ -0,0 +1,34 @@
+import { type TraceEngine } from './adapter.js';
+export interface LoadedTrace {
+    engine: TraceEngine;
+    parsedTrace: any;
+    rawEvents: any[];
+}
+/**
+ * Checks if the buffer starts with the gzip magic header bytes (0x1f, 0x8b).
+ */
+export declare function isGzipBuffer(buffer: Buffer): boolean;
+/**
+ * Decompresses a trace buffer if it is gzip-compressed or has a .gz extension.
+ */
+export declare function decompressTraceBuffer(buffer: Buffer, filePath?: string): string;
+/**
+ * Parses raw JSON string into an array of trace events.
+ * Accepts both raw arrays `[...]` and wrapped objects `{"traceEvents": [...]}`.
+ */
+export declare function parseTraceJson(jsonString: string): unknown[];
+/**
+ * Loads, decompresses, and parses a Chromium performance trace file using DevTools Trace Engine.
+ *
+ * Capabilities:
+ * - Transparently gunzips files with `.gz` extensions or gzip magic bytes (`0x1f 0x8b`).
+ * - Supports raw event arrays (`[...]`) and standard Chrome wrapper objects (`{ traceEvents: [...] }`).
+ * - Normalizes `parsedTrace` retrieval across different DevTools engine versions (`parsedTrace(0)` vs `traceParsedData(0)`).
+ * - Filters internal non-fatal Lantern simulation errors during model parsing.
+ *
+ * @param filePath - Relative or absolute path to the trace file.
+ * @param customEnginePath - Optional custom Trace Engine bundle path.
+ * @returns Object containing the TraceEngine instance, parsedTrace data, and rawEvents.
+ * @throws {Error} If the file does not exist, is invalid JSON, or lacks trace events.
+ */
+export declare function loadTraceFromFile(filePath: string, customEnginePath?: string): Promise<LoadedTrace>;