trace-engine-cli 0.0.0-stage → 0.0.1

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

@@ -0,0 +1,84 @@
+// 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 { getPropertyByPath } from '../helpers.js';
+/**
+ * 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 function extractEvents(loadedTrace, options) {
+    const { rawEvents } = loadedTrace;
+    const names = options?.names && options.names.length > 0 ? new Set(options.names) : null;
+    const category = options?.category;
+    const phase = options?.phase;
+    const timeRange = options?.timeRange;
+    const fields = options?.fields && options.fields.length > 0 ? options.fields : null;
+    const limit = options?.limit ?? 50;
+    const matchedEvents = [];
+    let totalMatched = 0;
+    for (const raw of rawEvents) {
+        if (!raw || typeof raw !== 'object') {
+            continue;
+        }
+        const event = raw;
+        const eventName = event.name ?? '';
+        if (names && !names.has(eventName)) {
+            continue;
+        }
+        const eventCat = event.cat;
+        if (category && eventCat !== category) {
+            continue;
+        }
+        const eventPh = event.ph;
+        if (phase && eventPh !== phase) {
+            continue;
+        }
+        const rawTs = event.ts ?? 0;
+        const rawDur = event.dur ?? 0;
+        const tsMs = microToMilli(rawTs);
+        const durMs = microToMilli(rawDur);
+        if (timeRange && !isEventInBounds(tsMs, durMs, timeRange)) {
+            continue;
+        }
+        totalMatched++;
+        if (matchedEvents.length < limit) {
+            const item = {
+                name: eventName,
+                tsMs: round(tsMs),
+                durMs: event.dur !== undefined ? round(durMs) : undefined,
+                cat: eventCat,
+                ph: eventPh,
+                pid: event.pid,
+                tid: event.tid,
+                args: event.args,
+            };
+            if (fields) {
+                const selectedFields = {};
+                for (const field of fields) {
+                    selectedFields[field] = getPropertyByPath(event, field);
+                }
+                item.selectedFields = selectedFields;
+            }
+            matchedEvents.push(item);
+        }
+    }
+    return {
+        totalMatched,
+        returned: matchedEvents.length,
+        events: matchedEvents,
+    };
+}

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

@@ -0,0 +1,12 @@
+import { type TimeRange } from '../../utils/filter.js';
+import type { LoadedTrace } from '../loader.js';
+import type { FindResult } from '../types.js';
+export interface ExtractFindOptions {
+    functionName: string;
+    timeRange?: TimeRange;
+    limit?: number;
+}
+/**
+ * Searches for all executions of a specific function name or pattern.
+ */
+export declare function extractFind(loadedTrace: LoadedTrace, options: ExtractFindOptions): FindResult;

package/dist/src/engine/extractors/find.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 { isEventInBounds } from '../../utils/filter.js';
+import { microToMilli, round } from '../../utils/units.js';
+import { getMainRendererThread } from '../helpers.js';
+/**
+ * Searches for all executions of a specific function name or pattern.
+ */
+export function extractFind(loadedTrace, options) {
+    const { engine, parsedTrace } = loadedTrace;
+    const functionQuery = options.functionName.trim();
+    const timeRange = options.timeRange;
+    const limit = options.limit ?? 50;
+    const result = {
+        functionQuery,
+        timeRange,
+        totalCalls: 0,
+        totalDurationMs: 0,
+        avgDurationMs: 0,
+        calls: [],
+    };
+    const mainThread = getMainRendererThread(parsedTrace.data);
+    if (!mainThread || !functionQuery) {
+        return result;
+    }
+    const queryLower = functionQuery.toLowerCase();
+    const matchedCalls = [];
+    for (const entry of mainThread.entries) {
+        const startMs = microToMilli(entry.ts);
+        const durMs = microToMilli(entry.dur ?? 0);
+        if (!isEventInBounds(startMs, durMs, timeRange)) {
+            continue;
+        }
+        // biome-ignore lint/suspicious/noExplicitAny: stack frame extraction accepts generic event
+        const frame = engine.Extras.TraceTree.eventStackFrame(entry);
+        const fnName = frame?.functionName || entry.name || '';
+        if (fnName.toLowerCase().includes(queryLower)) {
+            matchedCalls.push({
+                timestampMs: round(startMs),
+                durationMs: round(durMs),
+                url: frame?.url,
+                lineNumber: frame?.lineNumber,
+                columnNumber: frame?.columnNumber,
+            });
+        }
+    }
+    result.totalCalls = matchedCalls.length;
+    if (matchedCalls.length > 0) {
+        let totalDur = 0;
+        for (const c of matchedCalls) {
+            totalDur += c.durationMs;
+        }
+        result.totalDurationMs = round(totalDur);
+        result.avgDurationMs = round(totalDur / matchedCalls.length);
+        result.firstCallMs = matchedCalls[0].timestampMs;
+        result.lastCallMs = matchedCalls[matchedCalls.length - 1].timestampMs;
+        result.calls = matchedCalls.slice(0, limit);
+        // Build interval distribution if timeRange or trace bounds exist
+        const traceBounds = parsedTrace.data.Meta.traceBounds;
+        const windowStart = timeRange ? timeRange.startMs : microToMilli(traceBounds.min);
+        const windowEnd = timeRange ? timeRange.endMs : microToMilli(traceBounds.max);
+        const totalSpan = windowEnd - windowStart;
+        if (totalSpan > 0) {
+            const numIntervals = Math.min(5, Math.max(2, Math.floor(totalSpan / 100)));
+            const intervalSize = totalSpan / numIntervals;
+            const intervals = [];
+            for (let i = 0; i < numIntervals; i++) {
+                const iStart = round(windowStart + i * intervalSize);
+                const iEnd = round(i === numIntervals - 1 ? windowEnd : windowStart + (i + 1) * intervalSize);
+                let callsInInterval = 0;
+                let durInInterval = 0;
+                for (const c of matchedCalls) {
+                    if (c.timestampMs >= iStart && c.timestampMs < iEnd) {
+                        callsInInterval++;
+                        durInInterval += c.durationMs;
+                    }
+                }
+                intervals.push({
+                    startMs: iStart,
+                    endMs: iEnd,
+                    calls: callsInInterval,
+                    totalDurationMs: round(durInInterval),
+                });
+            }
+            result.intervals = intervals;
+        }
+    }
+    return result;
+}

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

@@ -0,0 +1,15 @@
+import type { LoadedTrace } from '../loader.js';
+import type { InsightsResult } from '../types.js';
+/**
+ * Configuration options for diagnostic insights extraction.
+ */
+export interface ExtractInsightsOptions {
+    /** Filter insights by diagnostic category. Network requests are handled by extractNetwork. */
+    category?: 'lcp' | 'inp' | 'cls' | 'render-blocking' | 'third-parties';
+    /** Target navigation ID or InsightSet ID. Defaults to the first InsightSet in the trace. */
+    navigationId?: string;
+}
+/**
+ * Extracts diagnostic insight cards for Web Vitals (LCP, INP, CLS, render blocking, 3rd party).
+ */
+export declare function extractInsights(loadedTrace: LoadedTrace, options?: ExtractInsightsOptions): InsightsResult;

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

@@ -0,0 +1,153 @@
+// 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 { microToMilli, round } from '../../utils/units.js';
+import { getPrimaryInsightSet } from '../helpers.js';
+/**
+ * Extracts diagnostic insight cards for Web Vitals (LCP, INP, CLS, render blocking, 3rd party).
+ */
+export function extractInsights(loadedTrace, options) {
+    const { parsedTrace } = loadedTrace;
+    const result = {
+        navigationId: options?.navigationId,
+    };
+    const warnings = [];
+    const insightSet = getPrimaryInsightSet(parsedTrace, options?.navigationId);
+    if (options?.navigationId && !insightSet) {
+        warnings.push(`No insights found for navigation ID: ${options.navigationId}`);
+    }
+    const category = options?.category;
+    const shouldInclude = (cat) => !category || category === cat;
+    const allowGlobalFallback = !options?.navigationId;
+    // 1. LCP Breakdown
+    if (shouldInclude('lcp') && insightSet?.LCPBreakdown) {
+        const l = insightSet.LCPBreakdown;
+        const subparts = l.subparts;
+        const lcpInsight = {
+            totalLcpMs: round(l.lcpMs ?? (l.lcpTs ? microToMilli(l.lcpTs) : 0)),
+            ttfbMs: subparts?.ttfb?.range ? round(microToMilli(subparts.ttfb.range)) : 0,
+            loadDelayMs: subparts?.loadDelay?.range ? round(microToMilli(subparts.loadDelay.range)) : 0,
+            loadDurationMs: subparts?.loadDuration?.range
+                ? round(microToMilli(subparts.loadDuration.range))
+                : 0,
+            renderDelayMs: subparts?.renderDelay?.range
+                ? round(microToMilli(subparts.renderDelay.range))
+                : 0,
+            lcpElement: l.lcpEvent?.args?.data?.nodeName,
+            lcpUrl: l.lcpRequest?.args?.data?.url,
+        };
+        result.lcpBreakdown = lcpInsight;
+        if (lcpInsight.renderDelayMs > 1000) {
+            warnings.push(`High LCP element render delay: ${lcpInsight.renderDelayMs}ms.`);
+        }
+        if (lcpInsight.loadDelayMs > 1000) {
+            warnings.push(`High LCP resource load delay: ${lcpInsight.loadDelayMs}ms.`);
+        }
+    }
+    // 2. INP Breakdown
+    if (shouldInclude('inp') &&
+        (insightSet?.INPBreakdown || (allowGlobalFallback && parsedTrace.data.UserInteractions))) {
+        const inpModel = insightSet?.INPBreakdown;
+        const longestEvent = inpModel?.longestInteractionEvent ||
+            (allowGlobalFallback
+                ? parsedTrace.data.UserInteractions?.longestInteractionEvent
+                : undefined);
+        if (longestEvent) {
+            const inpInsight = {
+                totalDurationMs: round(microToMilli(longestEvent.dur)),
+                inputDelayMs: round(microToMilli(longestEvent.inputDelay ?? 0)),
+                processingDurationMs: round(microToMilli(longestEvent.mainThreadHandling ?? longestEvent.processingDuration ?? 0)),
+                presentationDelayMs: round(microToMilli(longestEvent.presentationDelay ?? 0)),
+                eventType: longestEvent.type || longestEvent.name || 'unknown',
+                target: longestEvent.args?.data?.nodeName,
+            };
+            result.inpBreakdown = inpInsight;
+            if (inpInsight.totalDurationMs > 200) {
+                warnings.push(`Longest interaction (${inpInsight.eventType}) exceeded 200ms threshold: ${inpInsight.totalDurationMs}ms.`);
+            }
+        }
+    }
+    // 3. CLS Culprits
+    if (shouldInclude('cls')) {
+        const clsList = [];
+        const clsModel = insightSet?.CLSCulprits;
+        if (clsModel?.clusters && clsModel.clusters.length > 0) {
+            for (const cluster of clsModel.clusters) {
+                const score = cluster.clusterCumulativeScore ?? 0;
+                const tsMs = round(microToMilli(cluster.clusterWindow?.min ?? cluster.ts ?? 0));
+                const culpritNodes = [];
+                if (cluster.events) {
+                    for (const ev of cluster.events) {
+                        const nodes = ev.args?.data?.impacted_nodes || [];
+                        for (const n of nodes) {
+                            if (n.node_id !== undefined)
+                                culpritNodes.push(`Node #${n.node_id}`);
+                        }
+                    }
+                }
+                clsList.push({
+                    score: round(score, 4),
+                    timestampMs: tsMs,
+                    culpritNodes,
+                });
+            }
+        }
+        else if (allowGlobalFallback && parsedTrace.data.LayoutShifts?.clusters) {
+            for (const cluster of parsedTrace.data.LayoutShifts.clusters) {
+                clsList.push({
+                    score: round(cluster.clusterCumulativeScore ?? 0, 4),
+                    timestampMs: round(microToMilli(cluster.clusterWindow?.min ?? 0)),
+                    culpritNodes: [],
+                });
+            }
+        }
+        if (clsList.length > 0) {
+            result.clsCulprits = clsList;
+        }
+    }
+    // 4. Render Blocking Resources
+    if (shouldInclude('render-blocking') && insightSet?.RenderBlocking) {
+        const blocking = [];
+        const reqs = insightSet.RenderBlocking.renderBlockingRequests || [];
+        for (const req of reqs) {
+            blocking.push({
+                url: req.args?.data?.url || '',
+                durationMs: round(microToMilli(req.dur ?? 0)),
+                transferSizeBytes: req.args?.data?.encodedDataLength ?? 0,
+            });
+        }
+        if (blocking.length > 0) {
+            result.renderBlocking = blocking;
+            warnings.push(`${blocking.length} render-blocking requests found.`);
+        }
+    }
+    // 5. Third Parties
+    if (shouldInclude('third-parties') && insightSet?.ThirdParties) {
+        const thirdParties = [];
+        const summaries = insightSet.ThirdParties.entitySummaries || [];
+        for (const s of summaries) {
+            thirdParties.push({
+                entityName: s.entity?.name || 'Unknown',
+                transferSizeBytes: s.transferSize ?? 0,
+                mainThreadTimeMs: round(s.mainThreadTime ?? 0),
+            });
+        }
+        if (thirdParties.length > 0) {
+            result.thirdParties = thirdParties;
+        }
+    }
+    if (warnings.length > 0) {
+        result.warnings = warnings;
+    }
+    return result;
+}

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

@@ -0,0 +1,7 @@
+import { type TimeRange } from '../../utils/filter.js';
+import type { LoadedTrace } from '../loader.js';
+import type { InteractionsResult } from '../types.js';
+export interface ExtractInteractionsOptions {
+    timeRange?: TimeRange;
+}
+export declare function extractInteractions(loadedTrace: LoadedTrace, options?: ExtractInteractionsOptions): InteractionsResult;

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

@@ -0,0 +1,55 @@
+// 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';
+export function extractInteractions(loadedTrace, options) {
+    const { parsedTrace } = loadedTrace;
+    const timeRange = options?.timeRange;
+    const rawEvents = (parsedTrace.data.UserInteractions?.interactionEventsWithNoNesting ||
+        parsedTrace.data.UserInteractions?.interactionEvents ||
+        []);
+    const interactions = [];
+    for (const ev of rawEvents) {
+        const startMs = microToMilli(ev.ts);
+        const durMs = microToMilli(ev.dur ?? 0);
+        if (!isEventInBounds(startMs, durMs, timeRange)) {
+            continue;
+        }
+        const inputDelayMs = microToMilli(ev.inputDelay ?? 0);
+        const processingMs = microToMilli(ev.mainThreadHandling ?? ev.processingDuration ?? 0);
+        const presentationDelayMs = microToMilli(ev.presentationDelay ?? 0);
+        let targetElement;
+        if (ev.args?.data?.nodeName) {
+            targetElement = ev.args.data.nodeName;
+        }
+        else if (ev.args?.data?.beginEvent?.args?.data?.nodeName) {
+            targetElement = ev.args.data.beginEvent.args.data.nodeName;
+        }
+        interactions.push({
+            eventType: ev.type || ev.name || 'interaction',
+            startTimeMs: round(startMs),
+            durationMs: round(durMs),
+            inputDelayMs: round(inputDelayMs),
+            processingDurationMs: round(processingMs),
+            presentationDelayMs: round(presentationDelayMs),
+            targetElement,
+            interactionId: ev.interactionId,
+        });
+    }
+    // Sort by duration descending
+    interactions.sort((a, b) => b.durationMs - a.durationMs);
+    return {
+        interactions,
+    };
+}

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

@@ -0,0 +1,10 @@
+import type { LoadedTrace } from '../loader.js';
+import type { NavigationsResult } from '../types.js';
+/**
+ * Extracts navigation events and associated insight mappings from trace metadata.
+ *
+ * Discovers navigations from Meta.navigationsByNavigationId and Meta.mainFrameNavigations,
+ * maps each navigation to its corresponding InsightSet ID (e.g. 'NAVIGATION_0'),
+ * and determines whether the navigation belongs to the primary main frame.
+ */
+export declare function extractNavigations(loadedTrace: LoadedTrace): NavigationsResult;

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

@@ -0,0 +1,82 @@
+// 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 { microToMilli, round } from '../../utils/units.js';
+import { findInsightEntry } from '../helpers.js';
+function buildNavigationItem(navId, navEvent, finalUrls, isMainFrame, parsedTrace) {
+    const url = finalUrls?.get(navId) ||
+        navEvent?.args?.data?.documentLoaderURL ||
+        navEvent?.args?.data?.url ||
+        '';
+    const frameId = navEvent?.args?.frame || navEvent?.args?.data?.frame;
+    const tsMs = round(microToMilli(navEvent?.ts ?? 0));
+    const insightEntry = findInsightEntry(parsedTrace, navId);
+    return {
+        navigationId: navId,
+        insightSetId: insightEntry?.insightSetId,
+        frameId,
+        url,
+        timestampMs: tsMs,
+        isMainFrame,
+        hasInsights: Boolean(insightEntry),
+    };
+}
+/**
+ * Extracts navigation events and associated insight mappings from trace metadata.
+ *
+ * Discovers navigations from Meta.navigationsByNavigationId and Meta.mainFrameNavigations,
+ * maps each navigation to its corresponding InsightSet ID (e.g. 'NAVIGATION_0'),
+ * and determines whether the navigation belongs to the primary main frame.
+ */
+export function extractNavigations(loadedTrace) {
+    const { parsedTrace } = loadedTrace;
+    const meta = parsedTrace.data?.Meta;
+    const navigationsMap = meta?.navigationsByNavigationId;
+    const finalUrls = meta?.finalDisplayUrlByNavigationId;
+    const mainFrameId = meta?.mainFrameId;
+    const mainFrameNavs = meta?.mainFrameNavigations;
+    const insightsMap = parsedTrace.insights;
+    const insightSetIds = insightsMap ? Array.from(insightsMap.keys()) : [];
+    const navigations = [];
+    const seenIds = new Set();
+    const mainFrameNavIdSet = new Set((mainFrameNavs || [])
+        .map((m) => m?.args?.data?.navigationId)
+        .filter((id) => typeof id === 'string' && id.length > 0));
+    if (navigationsMap && navigationsMap.size > 0) {
+        for (const [navId, navEvent] of navigationsMap.entries()) {
+            seenIds.add(navId);
+            const frameId = navEvent?.args?.frame || navEvent?.args?.data?.frame;
+            const isMainFrame = Boolean(navEvent?.args?.data?.isOutermostMainFrame ??
+                navEvent?.args?.data?.isInPrimaryMainFrame ??
+                navEvent?.args?.data?.isMainFrame ??
+                mainFrameNavIdSet.has(navId) ??
+                (frameId && frameId === mainFrameId));
+            navigations.push(buildNavigationItem(navId, navEvent, finalUrls, isMainFrame, parsedTrace));
+        }
+    }
+    if (mainFrameNavs && mainFrameNavs.length > 0) {
+        for (const navEvent of mainFrameNavs) {
+            const navId = navEvent?.args?.data?.navigationId;
+            if (navId && !seenIds.has(navId)) {
+                seenIds.add(navId);
+                navigations.push(buildNavigationItem(navId, navEvent, finalUrls, true, parsedTrace));
+            }
+        }
+    }
+    navigations.sort((a, b) => a.timestampMs - b.timestampMs);
+    return {
+        total: navigations.length,
+        navigations,
+        insightSetIds,
+    };
+}

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

@@ -0,0 +1,10 @@
+import { type TimeRange } from '../../utils/filter.js';
+import type { LoadedTrace } from '../loader.js';
+import type { NetworkResult } from '../types.js';
+export interface ExtractNetworkOptions {
+    renderBlocking?: boolean;
+    slowest?: number;
+    initiatorChain?: string;
+    timeRange?: TimeRange;
+}
+export declare function extractNetwork(loadedTrace: LoadedTrace, options?: ExtractNetworkOptions): NetworkResult;

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

@@ -0,0 +1,105 @@
+// 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';
+export function extractNetwork(loadedTrace, options) {
+    const { engine, parsedTrace } = loadedTrace;
+    const renderBlockingOnly = options?.renderBlocking ?? false;
+    const slowest = options?.slowest ?? 20;
+    const initiatorTarget = options?.initiatorChain;
+    const timeRange = options?.timeRange;
+    const rawRequests = (parsedTrace.data.NetworkRequests?.byTime || []);
+    const result = {
+        requests: [],
+    };
+    // 1. Check Initiator Chain if requested
+    if (initiatorTarget) {
+        const targetReq = rawRequests.find((r) => r.args?.data?.requestId === initiatorTarget ||
+            Boolean(r.args?.data?.url?.includes(initiatorTarget)));
+        if (targetReq) {
+            const chain = [];
+            let current = targetReq;
+            const visited = new Set();
+            while (current && !visited.has(current)) {
+                visited.add(current);
+                const url = current.args?.data?.url || current.name || 'Unknown';
+                const initiator = engine.Extras.Initiators.getNetworkInitiator(parsedTrace.data, current);
+                const initiatorUrl = initiator?.args?.data?.url || initiator?.name;
+                chain.push({
+                    url,
+                    initiatorUrl,
+                    type: current.args?.data?.mimeType || current.name,
+                });
+                current = initiator;
+            }
+            result.initiatorChain = chain;
+        }
+    }
+    // 2. Identify render-blocking requests from insights if available
+    const blockingUrls = new Set();
+    if (parsedTrace.insights) {
+        for (const val of parsedTrace.insights.values()) {
+            const insight = val.model || val;
+            if (insight?.RenderBlocking?.renderBlockingRequests) {
+                for (const req of insight.RenderBlocking.renderBlockingRequests) {
+                    if (req.args?.data?.url) {
+                        blockingUrls.add(req.args.data.url);
+                    }
+                }
+            }
+        }
+    }
+    // 3. Process requests
+    const processed = [];
+    for (const req of rawRequests) {
+        const startMs = microToMilli(req.ts);
+        const durMs = microToMilli(req.dur ?? 0);
+        const url = req.args?.data?.url || '';
+        if (!isEventInBounds(startMs, durMs, timeRange)) {
+            continue;
+        }
+        const isBlocking = req.args?.data?.renderBlocking === 'blocking' ||
+            req.args?.data?.renderBlocking === 'in_body_parser_blocking' ||
+            blockingUrls.has(url);
+        if (renderBlockingOnly && !isBlocking) {
+            continue;
+        }
+        const syn = req.args?.data?.syntheticData;
+        const queueingMs = syn?.queueing ? microToMilli(syn.queueing) : 0;
+        const dnsMs = syn?.dnsLookup ? microToMilli(syn.dnsLookup) : 0;
+        const sslMs = syn?.ssl ? microToMilli(syn.ssl) : 0;
+        const ttfbMs = syn?.waiting ? microToMilli(syn.waiting) : 0;
+        const downloadMs = syn?.download ? microToMilli(syn.download) : 0;
+        processed.push({
+            requestId: req.args?.data?.requestId,
+            url,
+            mimeType: req.args?.data?.mimeType || '',
+            priority: req.args?.data?.priority || 'Normal',
+            timing: {
+                queueingMs: round(queueingMs),
+                dnsMs: round(dnsMs),
+                sslMs: round(sslMs),
+                ttfbMs: round(ttfbMs),
+                downloadMs: round(downloadMs),
+                totalDurationMs: round(durMs),
+            },
+            transferSizeBytes: req.args?.data?.encodedDataLength ?? 0,
+            renderBlocking: isBlocking,
+        });
+    }
+    // Sort by totalDurationMs descending
+    processed.sort((a, b) => b.timing.totalDurationMs - a.timing.totalDurationMs);
+    result.requests = processed.slice(0, slowest);
+    return result;
+}

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

@@ -0,0 +1,11 @@
+import type { TimeRange } from '../../utils/filter.js';
+import type { LoadedTrace } from '../loader.js';
+import type { OverviewResult } from '../types.js';
+export interface ExtractOverviewOptions {
+    timeRange?: TimeRange;
+}
+/**
+ * Extracts high-level trace metadata, Core Web Vitals, and main thread category distribution.
+ * All duration and timestamp properties are normalized to milliseconds (ms).
+ */
+export declare function extractOverview(loadedTrace: LoadedTrace, options?: ExtractOverviewOptions): OverviewResult;