trace-engine-cli 0.0.0-stage → 0.0.1

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

@@ -0,0 +1,232 @@
+// 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 { getMainRendererThread, getPrimaryInsightSet } from '../helpers.js';
+function rateFcp(fcpMs) {
+    if (fcpMs <= 1800)
+        return 'good';
+    if (fcpMs <= 3000)
+        return 'needs-improvement';
+    return 'poor';
+}
+function rateLcp(lcpMs) {
+    if (lcpMs <= 2500)
+        return 'good';
+    if (lcpMs <= 4000)
+        return 'needs-improvement';
+    return 'poor';
+}
+function rateCls(cls) {
+    if (cls <= 0.1)
+        return 'good';
+    if (cls <= 0.25)
+        return 'needs-improvement';
+    return 'poor';
+}
+function rateInp(inpMs) {
+    if (inpMs <= 200)
+        return 'good';
+    if (inpMs <= 500)
+        return 'needs-improvement';
+    return 'poor';
+}
+/**
+ * Extracts high-level trace metadata, Core Web Vitals, and main thread category distribution.
+ * All duration and timestamp properties are normalized to milliseconds (ms).
+ */
+export function extractOverview(loadedTrace, options) {
+    const { engine, parsedTrace } = loadedTrace;
+    const data = parsedTrace.data;
+    const timeRange = options?.timeRange;
+    // 1. Trace Bounds & Duration
+    const traceBounds = data.Meta.traceBounds;
+    const minMs = timeRange ? timeRange.startMs : round(microToMilli(traceBounds.min));
+    const maxMs = timeRange ? timeRange.endMs : round(microToMilli(traceBounds.max));
+    const durationMs = round(maxMs - minMs);
+    // 2. Main URL & Navigation Start
+    const mainUrl = data.Meta.mainFrameURL || null;
+    const mainNavs = (data.Meta.mainFrameNavigations || []);
+    const allNavs = Array.from((data.Meta.navigationsByNavigationId?.values() || []));
+    const firstNav = mainNavs[0] || allNavs[0];
+    const navigationStartMs = firstNav ? round(microToMilli(firstNav.ts)) : null;
+    // 3. Core Web Vitals
+    const mainFrameId = data.Meta.mainFrameId;
+    const pageMetrics = data.PageLoadMetrics?.metricScoresByFrameId?.get(mainFrameId);
+    let fcp = null;
+    let lcp = null;
+    if (pageMetrics) {
+        for (const navMetrics of pageMetrics.values()) {
+            const fcpMetric = navMetrics.get('FCP');
+            if (fcpMetric && fcpMetric.timing !== undefined && !fcp) {
+                const valMs = round(microToMilli(fcpMetric.timing));
+                fcp = {
+                    valueMs: valMs,
+                    rating: fcpMetric.classification || rateFcp(valMs),
+                };
+            }
+            const lcpMetric = navMetrics.get('LCP');
+            if (lcpMetric && lcpMetric.timing !== undefined && !lcp) {
+                const valMs = round(microToMilli(lcpMetric.timing));
+                lcp = {
+                    valueMs: valMs,
+                    rating: lcpMetric.classification || rateLcp(valMs),
+                };
+            }
+        }
+    }
+    // Check insights for LCP URL / Element if available
+    const insightSet = getPrimaryInsightSet(parsedTrace);
+    if (insightSet?.LCPBreakdown) {
+        const lcpInsight = insightSet.LCPBreakdown;
+        if (lcpInsight.lcpMs !== undefined && !lcp) {
+            const valMs = round(lcpInsight.lcpMs);
+            lcp = {
+                valueMs: valMs,
+                rating: rateLcp(valMs),
+            };
+        }
+        if (lcp) {
+            if (lcpInsight.lcpRequest?.args?.data?.url) {
+                lcp.url = lcpInsight.lcpRequest.args.data.url;
+            }
+            if (lcpInsight.lcpEvent?.args?.data?.nodeName) {
+                lcp.element = lcpInsight.lcpEvent.args.data.nodeName;
+            }
+        }
+    }
+    // CLS
+    let cls = null;
+    const layoutShifts = data.LayoutShifts;
+    if (layoutShifts) {
+        const score = layoutShifts.sessionMaxScore ?? 0;
+        const worstCluster = layoutShifts.clusters?.[0]?.clusterCumulativeScore;
+        cls = {
+            value: round(score, 4),
+            rating: rateCls(score),
+            worstClusterScore: worstCluster !== undefined ? round(worstCluster, 4) : undefined,
+        };
+    }
+    // INP
+    let inp = null;
+    const userInteractions = data.UserInteractions;
+    const longestInteraction = userInteractions?.longestInteractionEvent;
+    if (longestInteraction) {
+        const durMs = round(microToMilli(longestInteraction.dur));
+        inp = {
+            valueMs: durMs,
+            rating: rateInp(durMs),
+            interactionType: longestInteraction.type,
+        };
+    }
+    else if (insightSet?.INPBreakdown?.longestInteractionEvent) {
+        const ev = insightSet.INPBreakdown.longestInteractionEvent;
+        const durMs = round(microToMilli(ev.dur));
+        inp = {
+            valueMs: durMs,
+            rating: rateInp(durMs),
+            interactionType: ev.type,
+        };
+    }
+    // 4. Main Thread Breakdown (Derived from TraceTree self-times to eliminate double-counting)
+    const breakdown = {
+        scriptingMs: 0,
+        layoutMs: 0,
+        renderingMs: 0,
+        gcMs: 0,
+        systemMs: 0,
+        idleMs: 0,
+        totalMs: 0,
+    };
+    const mainThread = getMainRendererThread(data);
+    if (mainThread?.entries && mainThread.entries.length > 0) {
+        const bottomUp = new engine.Extras.TraceTree.BottomUpRootNode(mainThread.entries, {
+            textFilter: { accept: () => true },
+            filters: [],
+            startTime: engine.Types.Timing.Milli(minMs),
+            endTime: engine.Types.Timing.Milli(maxMs),
+        });
+        const children = bottomUp.children();
+        for (const node of children.values()) {
+            if (node.selfTime <= 0)
+                continue;
+            const name = node.event?.name || String(node.id) || '';
+            if (name === 'MajorGC' ||
+                name === 'MinorGC' ||
+                name === 'GCEvent' ||
+                name.startsWith('v8.gc')) {
+                breakdown.gcMs += node.selfTime;
+            }
+            else if (name === 'Layout' || name === 'UpdateLayoutTree' || name === 'InvalidateLayout') {
+                breakdown.layoutMs += node.selfTime;
+            }
+            else if (name === 'UpdateLayerTree' ||
+                name === 'Paint' ||
+                name === 'CompositeLayers' ||
+                name === 'RasterTask' ||
+                name === 'DecodeImage') {
+                breakdown.renderingMs += node.selfTime;
+            }
+            else if (name.startsWith('f:') ||
+                name === 'EvaluateScript' ||
+                name === 'FunctionCall' ||
+                name === 'v8.compile' ||
+                name === 'v8.run' ||
+                name === 'TimerFire' ||
+                name === 'FireAnimationFrame' ||
+                name === 'EventDispatch') {
+                breakdown.scriptingMs += node.selfTime;
+            }
+            else {
+                breakdown.systemMs += node.selfTime;
+            }
+        }
+    }
+    const activeWork = breakdown.scriptingMs +
+        breakdown.layoutMs +
+        breakdown.renderingMs +
+        breakdown.gcMs +
+        breakdown.systemMs;
+    breakdown.idleMs = round(Math.max(0, durationMs - activeWork));
+    breakdown.scriptingMs = round(breakdown.scriptingMs);
+    breakdown.layoutMs = round(breakdown.layoutMs);
+    breakdown.renderingMs = round(breakdown.renderingMs);
+    breakdown.gcMs = round(breakdown.gcMs);
+    breakdown.systemMs = round(breakdown.systemMs);
+    breakdown.totalMs = durationMs;
+    // 5. Warnings
+    const warnings = [];
+    if (fcp && fcp.rating === 'poor') {
+        warnings.push(`Poor First Contentful Paint: ${fcp.valueMs}ms (threshold: 1800ms)`);
+    }
+    if (lcp && lcp.rating === 'poor') {
+        warnings.push(`Poor Largest Contentful Paint: ${lcp.valueMs}ms (threshold: 2500ms)`);
+    }
+    if (cls && cls.rating === 'poor') {
+        warnings.push(`Poor Cumulative Layout Shift: ${cls.value} (threshold: 0.1)`);
+    }
+    if (inp && inp.rating === 'poor') {
+        warnings.push(`Poor Interaction to Next Paint: ${inp.valueMs}ms (threshold: 200ms)`);
+    }
+    if ((insightSet?.RenderBlocking?.renderBlockingRequests?.length ?? 0) > 0) {
+        warnings.push(`${insightSet?.RenderBlocking?.renderBlockingRequests?.length} render-blocking resource(s) detected.`);
+    }
+    return {
+        bounds: { minMs, maxMs, durationMs },
+        mainUrl,
+        navigationStartMs,
+        coreWebVitals: { fcp, lcp, cls, inp },
+        mainThreadBreakdown: breakdown,
+        warnings,
+    };
+}

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

@@ -0,0 +1,12 @@
+import type { TimeRange } from '../../utils/filter.js';
+import type { LoadedTrace } from '../loader.js';
+import type { ProfileResult } from '../types.js';
+export interface ExtractProfileOptions {
+    timeRange?: TimeRange;
+    bucketMs?: number;
+    top?: number;
+}
+/**
+ * Generates time-bucketed CPU profiles across a time range.
+ */
+export declare function extractProfile(loadedTrace: LoadedTrace, options?: ExtractProfileOptions): ProfileResult;

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

@@ -0,0 +1,83 @@
+// 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 { getMainRendererThread } from '../helpers.js';
+/**
+ * Generates time-bucketed CPU profiles across a time range.
+ */
+export function extractProfile(loadedTrace, options) {
+    const { engine, parsedTrace } = loadedTrace;
+    const traceBounds = parsedTrace.data.Meta.traceBounds;
+    const startMs = options?.timeRange
+        ? options.timeRange.startMs
+        : round(microToMilli(traceBounds.min));
+    const endMs = options?.timeRange ? options.timeRange.endMs : round(microToMilli(traceBounds.max));
+    const totalRangeMs = Math.max(1, endMs - startMs);
+    const bucketSizeMs = options?.bucketMs ?? Math.max(10, round(totalRangeMs / 20));
+    const topCount = options?.top ?? 3;
+    const result = {
+        timeRange: { startMs, endMs },
+        bucketSizeMs,
+        buckets: [],
+    };
+    const mainThread = getMainRendererThread(parsedTrace.data);
+    if (!mainThread?.entries?.length) {
+        return result;
+    }
+    const entriesParam = mainThread.entries;
+    let currentStart = startMs;
+    while (currentStart < endMs) {
+        const currentEnd = Math.min(endMs, round(currentStart + bucketSizeMs));
+        if (currentEnd <= currentStart)
+            break;
+        const bottomUp = new engine.Extras.TraceTree.BottomUpRootNode(entriesParam, {
+            textFilter: { accept: () => true },
+            filters: [],
+            startTime: engine.Types.Timing.Milli(currentStart),
+            endTime: engine.Types.Timing.Milli(currentEnd),
+        });
+        const funcList = [];
+        let totalActiveMs = 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';
+            // Exclude generic root markers from active work
+            if (fnName === '(root)' || fnName === '(idle)')
+                continue;
+            totalActiveMs += node.selfTime;
+            funcList.push({
+                name: fnName,
+                selfTimeMs: round(node.selfTime),
+            });
+        }
+        funcList.sort((a, b) => b.selfTimeMs - a.selfTimeMs);
+        const topFunctions = funcList.slice(0, topCount).map((f) => ({
+            name: f.name,
+            selfTimeMs: f.selfTimeMs,
+            selfTimePct: totalActiveMs > 0 ? round((f.selfTimeMs / totalActiveMs) * 100, 1) : 0,
+        }));
+        result.buckets.push({
+            startMs: round(currentStart),
+            endMs: round(currentEnd),
+            totalActiveMs: round(totalActiveMs),
+            topFunctions,
+        });
+        currentStart = currentEnd;
+    }
+    return result;
+}

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

@@ -0,0 +1,37 @@
+import type { ScanResult } from '../types.js';
+/**
+ * Options for scanning multiple trace files or directories.
+ */
+export interface ScanOptions {
+    /** Target directories, glob patterns, or file paths (.json, .json.gz). */
+    targets: string[];
+    /** Exact event name or list of event names to match. */
+    names?: string[];
+    /** Exact event category to match. */
+    category?: string;
+    /** Exact event phase to match (e.g. 'X', 'I', 'B', 'E'). */
+    phase?: string;
+    /** Substring to match across event names, categories, or payload arguments. */
+    grep?: string;
+    /** Dot-notation property paths that must exist on matching events. */
+    fields?: string[];
+    /** Maximum number of matching files to return in the result. Default: 50. */
+    limit?: number;
+}
+/**
+ * Resolves a list of directory paths, glob patterns, or file paths into a deduplicated list of trace files.
+ *
+ * @throws {Error} When a literal target path does not exist.
+ * @throws {Error} When no trace files (.json, .json.gz) are matched across all targets.
+ */
+export declare function resolveScanTargets(targets: string[]): string[];
+/**
+ * Scans multiple trace files or directories for events matching query criteria.
+ *
+ * Uses fast string pre-filtering before JSON parsing to achieve high scanning throughput
+ * across hundreds of fixtures without running heavyweight DevTools Trace Engine pipelines.
+ *
+ * @throws {Error} When no search filter options are provided.
+ * @throws {Error} When resolveScanTargets fails to match trace files.
+ */
+export declare function scanTraces(options: ScanOptions): ScanResult;

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

@@ -0,0 +1,218 @@
+// 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 { microToMilli } from '../../utils/units.js';
+import { getPropertyByPath } from '../helpers.js';
+import { decompressTraceBuffer, parseTraceJson } from '../loader.js';
+/**
+ * Resolves a list of directory paths, glob patterns, or file paths into a deduplicated list of trace files.
+ *
+ * @throws {Error} When a literal target path does not exist.
+ * @throws {Error} When no trace files (.json, .json.gz) are matched across all targets.
+ */
+export function resolveScanTargets(targets) {
+    const resolvedFiles = new Set();
+    for (const target of targets) {
+        const hasGlobWildcards = /[*?[\]]/.test(target);
+        if (hasGlobWildcards) {
+            const globbed = fs.globSync(target);
+            for (const file of globbed) {
+                if (file.endsWith('.json') || file.endsWith('.json.gz')) {
+                    resolvedFiles.add(path.resolve(file));
+                }
+            }
+            continue;
+        }
+        let stat;
+        try {
+            stat = fs.statSync(target);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                throw new Error(`Target path not found: ${target}`);
+            }
+            throw err;
+        }
+        if (stat.isDirectory()) {
+            const dirents = fs.readdirSync(target, { recursive: true, withFileTypes: true });
+            for (const dirent of dirents) {
+                if (dirent.isFile()) {
+                    const name = dirent.name;
+                    if (name.endsWith('.json') || name.endsWith('.json.gz')) {
+                        const dir = dirent.parentPath ?? dirent.path ?? target;
+                        resolvedFiles.add(path.resolve(dir, name));
+                    }
+                }
+            }
+        }
+        else if (stat.isFile()) {
+            if (target.endsWith('.json') || target.endsWith('.json.gz')) {
+                resolvedFiles.add(path.resolve(target));
+            }
+        }
+    }
+    const sorted = Array.from(resolvedFiles).sort();
+    if (sorted.length === 0) {
+        throw new Error(`No trace files (.json, .json.gz) found matching targets: ${targets.join(', ')}`);
+    }
+    return sorted;
+}
+/**
+ * Scans multiple trace files or directories for events matching query criteria.
+ *
+ * Uses fast string pre-filtering before JSON parsing to achieve high scanning throughput
+ * across hundreds of fixtures without running heavyweight DevTools Trace Engine pipelines.
+ *
+ * @throws {Error} When no search filter options are provided.
+ * @throws {Error} When resolveScanTargets fails to match trace files.
+ */
+export function scanTraces(options) {
+    const { targets, names, category, phase, grep, fields, limit = 50 } = options;
+    if (!names?.length && !category && !phase && !grep && !fields?.length) {
+        throw new Error('At least one search filter must be specified (--name, --category, --phase, --grep, or --fields).');
+    }
+    const files = resolveScanTargets(targets);
+    const namesSet = names && names.length > 0 ? new Set(names) : null;
+    // Extract final property identifier from dot-notation path (e.g. 'args.data.id' -> 'id') for substring pre-filtering.
+    const leafFields = fields && fields.length > 0 ? fields.map((f) => f.split('.').pop() ?? f) : null;
+    const matchedFiles = [];
+    let totalEventsMatched = 0;
+    for (const filePath of files) {
+        let rawBuffer;
+        try {
+            rawBuffer = fs.readFileSync(filePath);
+        }
+        catch {
+            continue;
+        }
+        let jsonContent;
+        try {
+            jsonContent = decompressTraceBuffer(rawBuffer, filePath);
+        }
+        catch {
+            continue;
+        }
+        // Fast substring pre-filtering to eliminate non-matching files without JSON.parse overhead.
+        if (grep && !jsonContent.includes(grep)) {
+            continue;
+        }
+        if (names && names.length > 0) {
+            const hasAnyName = names.some((n) => jsonContent.includes(n));
+            if (!hasAnyName) {
+                continue;
+            }
+        }
+        if (category && !jsonContent.includes(category)) {
+            continue;
+        }
+        if (leafFields && leafFields.length > 0) {
+            const hasAllLeaves = leafFields.every((lf) => jsonContent.includes(lf));
+            if (!hasAllLeaves) {
+                continue;
+            }
+        }
+        let rawEvents;
+        try {
+            rawEvents = parseTraceJson(jsonContent);
+        }
+        catch {
+            continue;
+        }
+        let fileMatches = 0;
+        const fileCategories = new Set();
+        let firstEventName;
+        let firstEventTsMs;
+        for (const raw of rawEvents) {
+            if (!raw || typeof raw !== 'object') {
+                continue;
+            }
+            const event = raw;
+            const eventName = event.name ?? '';
+            if (namesSet && !namesSet.has(eventName)) {
+                continue;
+            }
+            const eventCat = event.cat;
+            if (category) {
+                const matchesCategory = Boolean(eventCat && (eventCat === category || eventCat.split(',').includes(category)));
+                if (!matchesCategory) {
+                    continue;
+                }
+            }
+            const eventPh = event.ph;
+            if (phase && eventPh !== phase) {
+                continue;
+            }
+            if (grep) {
+                const matchesGrep = eventName.includes(grep) ||
+                    Boolean(eventCat?.includes(grep)) ||
+                    Boolean(event.args && JSON.stringify(event.args).includes(grep));
+                if (!matchesGrep) {
+                    continue;
+                }
+            }
+            if (fields && fields.length > 0) {
+                let hasAllFields = true;
+                for (const field of fields) {
+                    if (getPropertyByPath(event, field) === undefined) {
+                        hasAllFields = false;
+                        break;
+                    }
+                }
+                if (!hasAllFields) {
+                    continue;
+                }
+            }
+            fileMatches++;
+            if (eventCat) {
+                fileCategories.add(eventCat);
+            }
+            if (firstEventName === undefined) {
+                firstEventName = eventName || '(anonymous)';
+                firstEventTsMs = microToMilli(event.ts ?? 0);
+            }
+        }
+        if (fileMatches > 0) {
+            totalEventsMatched += fileMatches;
+            const relativePath = path.relative(process.cwd(), filePath);
+            matchedFiles.push({
+                file: relativePath,
+                matchCount: fileMatches,
+                categories: Array.from(fileCategories).sort(),
+                firstEventName,
+                firstEventTsMs,
+            });
+        }
+    }
+    // Sort files by match count descending, with secondary alphabetical sort.
+    matchedFiles.sort((a, b) => {
+        if (b.matchCount !== a.matchCount) {
+            return b.matchCount - a.matchCount;
+        }
+        return a.file.localeCompare(b.file);
+    });
+    return {
+        query: {
+            names,
+            category,
+            phase,
+            grep,
+            fields,
+        },
+        totalFilesScanned: files.length,
+        totalFilesMatched: matchedFiles.length,
+        totalEventsMatched,
+        matchedFiles: matchedFiles.slice(0, limit),
+    };
+}

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

@@ -0,0 +1,10 @@
+import { type TimeRange } from '../../utils/filter.js';
+import type { LoadedTrace } from '../loader.js';
+import type { SchedulingResult } from '../types.js';
+export interface ExtractSchedulingOptions {
+    timeRange?: TimeRange;
+}
+/**
+ * Extracts async task and animation frame scheduling, cancellation, and execution metrics.
+ */
+export declare function extractScheduling(loadedTrace: LoadedTrace, options?: ExtractSchedulingOptions): SchedulingResult;

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

@@ -0,0 +1,89 @@
+// 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 async task and animation frame scheduling, cancellation, and execution metrics.
+ */
+export function extractScheduling(loadedTrace, options) {
+    const { parsedTrace, rawEvents } = loadedTrace;
+    const timeRange = options?.timeRange;
+    const animStats = {
+        scheduledCount: 0,
+        canceledCount: 0,
+        executedCount: 0,
+        cancellationRatePct: 0,
+    };
+    const timerStats = {
+        scheduledCount: 0,
+        canceledCount: 0,
+        executedCount: 0,
+        cancellationRatePct: 0,
+    };
+    const mainThread = getMainRendererThread(parsedTrace.data);
+    // biome-ignore lint/suspicious/noExplicitAny: generic event scanning
+    const eventsToScan = mainThread?.entries || rawEvents || [];
+    for (const entry of eventsToScan) {
+        const startMs = microToMilli(entry.ts);
+        const durMs = microToMilli(entry.dur ?? 0);
+        if (!isEventInBounds(startMs, durMs, timeRange)) {
+            continue;
+        }
+        const name = entry.name;
+        if (name === 'RequestAnimationFrame') {
+            animStats.scheduledCount++;
+        }
+        else if (name === 'CancelAnimationFrame') {
+            animStats.canceledCount++;
+        }
+        else if (name === 'FireAnimationFrame') {
+            animStats.executedCount++;
+        }
+        else if (name === 'TimerInstall') {
+            timerStats.scheduledCount++;
+        }
+        else if (name === 'TimerRemove') {
+            timerStats.canceledCount++;
+        }
+        else if (name === 'TimerFire') {
+            timerStats.executedCount++;
+        }
+    }
+    animStats.cancellationRatePct =
+        animStats.scheduledCount > 0
+            ? round((animStats.canceledCount / animStats.scheduledCount) * 100, 1)
+            : 0;
+    timerStats.cancellationRatePct =
+        timerStats.scheduledCount > 0
+            ? round((timerStats.canceledCount / timerStats.scheduledCount) * 100, 1)
+            : 0;
+    const warnings = [];
+    let churnDetected = false;
+    if (animStats.cancellationRatePct >= 70 && animStats.scheduledCount >= 5) {
+        churnDetected = true;
+        warnings.push(`High animation frame cancellation rate (${animStats.cancellationRatePct}%). ${animStats.canceledCount} of ${animStats.scheduledCount} scheduled rAFs were canceled before execution.`);
+    }
+    if (timerStats.cancellationRatePct >= 70 && timerStats.scheduledCount >= 5) {
+        churnDetected = true;
+        warnings.push(`High timer cancellation rate (${timerStats.cancellationRatePct}%). ${timerStats.canceledCount} of ${timerStats.scheduledCount} installed timers were removed before firing.`);
+    }
+    return {
+        timeRange,
+        animationFrames: animStats,
+        timers: timerStats,
+        churnDetected,
+        warnings,
+    };
+}