fix: improve profile diff performance, UX, and error handling

- Use Map lookup instead of linear scan for self durations
- Clarify before/after order in help text
- Add --threshold flag to configure regression sensitivity (default 5%)
- Show clear error messages when export files can't be read
- Show actual threshold value in "no changes" message
- Fix constant naming convention (DEFAULT_THRESHOLD_PCT)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: piotrski

packages/agent-react-devtools/src/cli.ts

@@ -53,7 +53,7 @@ Profiling:
   profile timeline [--limit N]  Commit timeline
   profile commit <N | #N> [--limit N]  Detail for specific commit
   profile export <file>               Export as React DevTools JSON
-  profile diff <a.json> <b.json> [--limit N]  Compare two exports`;
+  profile diff <before.json> <after.json> [--limit N] [--threshold N]  Compare two exports`;
 }
 
 function parseArgs(argv: string[]): {
@@ -131,14 +131,27 @@ async function main(): Promise<void> {
       const fileA = command[2];
       const fileB = command[3];
       if (!fileA || !fileB) {
-        console.error('Usage: devtools profile diff <before.json> <after.json> [--limit N]');
+        console.error('Usage: devtools profile diff <before.json> <after.json> [--limit N] [--threshold N]');
         process.exit(1);
       }
       const { loadExportFile, diffProfiles } = await import('./profile-diff.js');
-      const before = loadExportFile(resolve(fileA));
-      const after = loadExportFile(resolve(fileB));
-      const diff = diffProfiles(before, after);
+      let before: ReturnType<typeof loadExportFile>;
+      let after: ReturnType<typeof loadExportFile>;
+      try {
+        before = loadExportFile(resolve(fileA));
+      } catch (e) {
+        console.error(`Error reading ${fileA}: ${(e as Error).message}`);
+        process.exit(1);
+      }
+      try {
+        after = loadExportFile(resolve(fileB));
+      } catch (e) {
+        console.error(`Error reading ${fileB}: ${(e as Error).message}`);
+        process.exit(1);
+      }
       const limit = parseNumericFlag(flags, 'limit');
+      const threshold = parseNumericFlag(flags, 'threshold');
+      const diff = diffProfiles(before, after, threshold);
       console.log(formatProfileDiff(diff, limit));
       return;
     }

packages/agent-react-devtools/src/formatters.ts

@@ -374,7 +374,7 @@ export function formatProfileDiff(diff: ProfileDiffResult, limit?: number): stri
 
   if (diff.regressed.length === 0 && diff.improved.length === 0 && diff.added.length === 0 && diff.removed.length === 0) {
     lines.push('');
-    lines.push('No significant changes (all within 5% threshold)');
+    lines.push(`No significant changes (all within ${s.thresholdPct}% threshold)`);
   }
 
   return lines.join('\n');

packages/agent-react-devtools/src/profile-diff.ts

@@ -29,6 +29,7 @@ export interface ProfileDiffResult {
     totalCommitsAfter: number;
     totalDurationBefore: number;
     totalDurationAfter: number;
+    thresholdPct: number;
   };
 }
 
@@ -57,6 +58,8 @@ export function extractStats(data: ProfilingDataExport): Map<string, ComponentSt
 
   for (const root of data.dataForRoots) {
     for (const commit of root.commitData) {
+      const selfMap = new Map(commit.fiberSelfDurations);
+
       for (const [id, duration] of commit.fiberActualDurations) {
         const name = nameMap.get(id);
         if (!name) continue;
@@ -70,10 +73,9 @@ export function extractStats(data: ProfilingDataExport): Map<string, ComponentSt
         entry.count++;
         if (duration > entry.maxActual) entry.maxActual = duration;
 
-        // Find matching self duration
-        const selfEntry = commit.fiberSelfDurations.find(([sid]) => sid === id);
-        if (selfEntry) {
-          entry.totalSelf += selfEntry[1];
+        const selfDuration = selfMap.get(id);
+        if (selfDuration !== undefined) {
+          entry.totalSelf += selfDuration;
         }
       }
     }
@@ -111,11 +113,12 @@ function getTotalCommits(data: ProfilingDataExport): number {
   return total;
 }
 
-const THRESHOLD_PCT = 5;
+const DEFAULT_THRESHOLD_PCT = 5;
 
 export function diffProfiles(
   before: ProfilingDataExport,
   after: ProfilingDataExport,
+  thresholdPct = DEFAULT_THRESHOLD_PCT,
 ): ProfileDiffResult {
   const statsBefore = extractStats(before);
   const statsAfter = extractStats(after);
@@ -168,9 +171,9 @@ export function diffProfiles(
         renderCountDelta: a.renderCount - b.renderCount,
       };
 
-      if (pct !== null && pct > THRESHOLD_PCT) {
+      if (pct !== null && pct > thresholdPct) {
         regressed.push(entry);
-      } else if (pct !== null && pct < -THRESHOLD_PCT) {
+      } else if (pct !== null && pct < -thresholdPct) {
         improved.push(entry);
       }
       // within threshold = unchanged, skip
@@ -193,6 +196,7 @@ export function diffProfiles(
       totalCommitsAfter: getTotalCommits(after),
       totalDurationBefore: getTotalDuration(before),
       totalDurationAfter: getTotalDuration(after),
+      thresholdPct,
     },
   };
 }