From fdeebf178f60f911435d4ef48b08a867b9cbc3bc Mon Sep 17 00:00:00 2001
From: Robert DeLuca <robertdeluca19@gmail.com>
Date: Wed, 11 Feb 2026 12:10:14 -0600
Subject: [PATCH 1/2] =?UTF-8?q?=E2=9A=A1=EF=B8=8F=20Fix=20TDD=20SSE=20perf?=
 =?UTF-8?q?ormance=20by=20splitting=20heavy=20comparison=20data?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Split report-data.json into lightweight SSE data and on-demand heavy fields:

- report-data.json: Only lightweight comparison fields (broadcast via SSE)
- comparison-details.json: Heavy fields like diffClusters, intensityStats,
  boundingBox, regionAnalysis, hotspotAnalysis, confirmedRegions (persisted,
  never broadcast)

Remove redundant groups array from report-data.json — UI already computes
groups client-side via groupComparisons(). Switch to compact JSON serialization.

Add GET /api/comparison/:id endpoint that merges lightweight + heavy data
on-demand. Frontend fetches full details only when viewer opens via new
useComparison hook.

Result: 79% reduction in SSE payload (735 KB → 153 KB per update),
cumulative broadcast drops from ~97 MB to ~20 MB for 135 comparisons.
---
 src/reporter/src/api/client.js                |   9 ++
 .../comparison/fullscreen-viewer.jsx          |   6 +-
 .../views/comparison-detail-view.jsx          |  25 ++-
 .../src/hooks/queries/use-tdd-queries.js      |  10 ++
 src/reporter/src/lib/query-keys.js            |   1 +
 src/server/handlers/tdd-handler.js            | 110 ++++++++++---
 src/server/routers/dashboard.js               |  55 ++++++-
 tests/server/handlers/tdd-handler.test.js     |  63 +++++++-
 tests/server/routers/dashboard.test.js        | 147 ++++++++++++++++++
 9 files changed, 395 insertions(+), 31 deletions(-)

diff --git a/src/reporter/src/api/client.js b/src/reporter/src/api/client.js
index 4995d6e2..b9a99cdf 100644
--- a/src/reporter/src/api/client.js
+++ b/src/reporter/src/api/client.js
@@ -48,6 +48,15 @@ export const tdd = {
     return fetchJson('/api/report-data');
   },
 
+  /**
+   * Get full comparison details (lightweight + heavy fields)
+   * @param {string} id - Comparison ID, signature, or name
+   * @returns {Promise<Object>}
+   */
+  async getComparison(id) {
+    return fetchJson(`/api/comparison/${encodeURIComponent(id)}`);
+  },
+
   /**
    * Accept a single baseline
    * @param {string} id - Comparison ID
diff --git a/src/reporter/src/components/comparison/fullscreen-viewer.jsx b/src/reporter/src/components/comparison/fullscreen-viewer.jsx
index dfe3395b..9bbb3722 100644
--- a/src/reporter/src/components/comparison/fullscreen-viewer.jsx
+++ b/src/reporter/src/components/comparison/fullscreen-viewer.jsx
@@ -540,7 +540,8 @@ function FullscreenViewerInner({
             </button>
 
             {/* Regions toggle - only show if comparison has regions */}
-            {comparison?.confirmedRegions?.length > 0 && (
+            {(comparison?.confirmedRegions?.length > 0 ||
+              comparison?.hasConfirmedRegions) && (
               <button
                 type="button"
                 onClick={() => setShowRegions(!showRegions)}
@@ -825,7 +826,8 @@ function FullscreenViewerInner({
           </button>
 
           {/* Regions toggle - mobile */}
-          {comparison?.confirmedRegions?.length > 0 && (
+          {(comparison?.confirmedRegions?.length > 0 ||
+            comparison?.hasConfirmedRegions) && (
             <button
               type="button"
               onClick={() => setShowRegions(!showRegions)}
diff --git a/src/reporter/src/components/views/comparison-detail-view.jsx b/src/reporter/src/components/views/comparison-detail-view.jsx
index 5c7efeb6..d17d52ae 100644
--- a/src/reporter/src/components/views/comparison-detail-view.jsx
+++ b/src/reporter/src/components/views/comparison-detail-view.jsx
@@ -2,6 +2,7 @@ import { useCallback, useMemo } from 'react';
 import { useLocation, useRoute } from 'wouter';
 import {
   useAcceptBaseline,
+  useComparison,
   useDeleteComparison,
   useRejectBaseline,
   useReportData,
@@ -27,10 +28,10 @@ export default function ComparisonDetailView() {
     [reportData?.comparisons]
   );
 
-  // Find the comparison by ID from route params
+  // Find the lightweight comparison by ID from route params
   // Uses stable IDs (id, signature, or name) - not array indices which change with filters
-  const comparison = useMemo(() => {
-    const targetId = params?.id ? decodeURIComponent(params.id) : null;
+  let lightComparison = useMemo(() => {
+    let targetId = params?.id ? decodeURIComponent(params.id) : null;
     if (!targetId || comparisons.length === 0) {
       return null;
     }
@@ -41,6 +42,24 @@ export default function ComparisonDetailView() {
     );
   }, [params, comparisons]);
 
+  // Fetch full comparison details on-demand (includes heavy fields like diffClusters)
+  let { data: fullComparison } = useComparison(lightComparison?.id);
+
+  // Merge lightweight SSE data with on-demand heavy fields
+  let comparison = useMemo(() => {
+    if (!lightComparison) return null;
+    if (!fullComparison) return lightComparison;
+    return {
+      ...lightComparison,
+      diffClusters: fullComparison.diffClusters,
+      confirmedRegions: fullComparison.confirmedRegions,
+      intensityStats: fullComparison.intensityStats,
+      boundingBox: fullComparison.boundingBox,
+      regionAnalysis: fullComparison.regionAnalysis,
+      hotspotAnalysis: fullComparison.hotspotAnalysis,
+    };
+  }, [lightComparison, fullComparison]);
+
   // Simple navigation - just change the URL using stable IDs
   const handleNavigate = useCallback(
     targetComparison => {
diff --git a/src/reporter/src/hooks/queries/use-tdd-queries.js b/src/reporter/src/hooks/queries/use-tdd-queries.js
index 39324c6b..2f68638c 100644
--- a/src/reporter/src/hooks/queries/use-tdd-queries.js
+++ b/src/reporter/src/hooks/queries/use-tdd-queries.js
@@ -3,6 +3,16 @@ import { tdd } from '../../api/client.js';
 import { queryKeys } from '../../lib/query-keys.js';
 import { SSE_STATE, useReportDataSSE } from '../use-sse.js';
 
+export function useComparison(id, options = {}) {
+  return useQuery({
+    queryKey: queryKeys.comparison(id),
+    queryFn: () => tdd.getComparison(id),
+    enabled: !!id,
+    staleTime: 10_000,
+    ...options,
+  });
+}
+
 export function useReportData(options = {}) {
   // Use SSE for real-time updates
   let { state: sseState } = useReportDataSSE({
diff --git a/src/reporter/src/lib/query-keys.js b/src/reporter/src/lib/query-keys.js
index 2951484a..0afe4c97 100644
--- a/src/reporter/src/lib/query-keys.js
+++ b/src/reporter/src/lib/query-keys.js
@@ -11,6 +11,7 @@ export const queryKeys = {
   // TDD (local)
   tdd: ['tdd'],
   reportData: () => [...queryKeys.tdd, 'report'],
+  comparison: id => [...queryKeys.tdd, 'comparison', id],
 
   // Cloud
   cloud: ['cloud'],
diff --git a/src/server/handlers/tdd-handler.js b/src/server/handlers/tdd-handler.js
index a4017d5b..fe7f1603 100644
--- a/src/server/handlers/tdd-handler.js
+++ b/src/server/handlers/tdd-handler.js
@@ -198,15 +198,53 @@ export const createTddHandler = (
 
   const tddService = new TddService(config, workingDir, setBaseline);
   const reportPath = join(workingDir, '.vizzly', 'report-data.json');
+  const detailsPath = join(workingDir, '.vizzly', 'comparison-details.json');
+
+  /**
+   * Read heavy comparison details from comparison-details.json
+   * Returns a map of comparison ID -> heavy fields
+   */
+  const readComparisonDetails = () => {
+    try {
+      if (!existsSync(detailsPath)) return {};
+      return JSON.parse(readFileSync(detailsPath, 'utf8'));
+    } catch {
+      return {};
+    }
+  };
+
+  /**
+   * Persist heavy fields for a comparison to comparison-details.json
+   * This file is NOT watched by SSE, so writes here don't trigger broadcasts
+   * Skips writing if all heavy fields are empty (passed comparisons)
+   */
+  const updateComparisonDetails = (id, heavyFields) => {
+    let hasData = Object.values(heavyFields).some(
+      v => v != null && (!Array.isArray(v) || v.length > 0)
+    );
+    if (!hasData) return;
+
+    let details = readComparisonDetails();
+    details[id] = heavyFields;
+    writeFileSync(detailsPath, JSON.stringify(details));
+  };
+
+  /**
+   * Remove a comparison's heavy fields from comparison-details.json
+   */
+  const removeComparisonDetails = id => {
+    let details = readComparisonDetails();
+    delete details[id];
+    writeFileSync(detailsPath, JSON.stringify(details));
+  };
 
   const readReportData = () => {
     try {
       if (!existsSync(reportPath)) {
         return {
           timestamp: Date.now(),
-          comparisons: [], // Internal flat list for easy updates
-          groups: [], // Grouped structure for UI
-          summary: { total: 0, groups: 0, passed: 0, failed: 0, errors: 0 },
+          comparisons: [],
+          summary: { total: 0, passed: 0, failed: 0, errors: 0 },
         };
       }
       const data = readFileSync(reportPath, 'utf8');
@@ -216,8 +254,7 @@ export const createTddHandler = (
       return {
         timestamp: Date.now(),
         comparisons: [],
-        groups: [],
-        summary: { total: 0, groups: 0, passed: 0, failed: 0, errors: 0 },
+        summary: { total: 0, passed: 0, failed: 0, errors: 0 },
       };
     }
   };
@@ -254,14 +291,10 @@ export const createTddHandler = (
         });
       }
 
-      // Generate grouped structure from flat comparisons
-      reportData.groups = groupComparisons(reportData.comparisons);
-
-      // Update summary
+      // Update summary (groups computed client-side from comparisons)
       reportData.timestamp = Date.now();
       reportData.summary = {
         total: reportData.comparisons.length,
-        groups: reportData.groups.length,
         passed: reportData.comparisons.filter(
           c =>
             c.status === 'passed' ||
@@ -275,7 +308,7 @@ export const createTddHandler = (
         errors: reportData.comparisons.filter(c => c.status === 'error').length,
       };
 
-      writeFileSync(reportPath, JSON.stringify(reportData, null, 2));
+      writeFileSync(reportPath, JSON.stringify(reportData));
     } catch (error) {
       output.error('Failed to update comparison:', error);
     }
@@ -465,22 +498,46 @@ export const createTddHandler = (
     const vizzlyDir = join(workingDir, '.vizzly');
 
     // Record the comparison for the dashboard
-    // Spread the full comparison to include regionAnalysis, confirmedRegions, hotspotAnalysis, etc.
+    // Only include lightweight fields in report-data.json (broadcast via SSE)
     const newComparison = {
-      ...comparison,
-      originalName: name,
-      // Convert absolute file paths to web-accessible URLs
+      id: comparison.id,
+      name: comparison.name,
+      status: comparison.status,
+      signature: comparison.signature,
       baseline: convertPathToUrl(comparison.baseline, vizzlyDir),
       current: convertPathToUrl(comparison.current, vizzlyDir),
       diff: convertPathToUrl(comparison.diff, vizzlyDir),
-      // Use extracted properties with top-level viewport_width/browser
       properties: extractedProperties,
+      threshold: comparison.threshold,
+      minClusterSize: comparison.minClusterSize,
+      diffPercentage: comparison.diffPercentage,
+      diffCount: comparison.diffCount,
+      reason: comparison.reason,
+      totalPixels: comparison.totalPixels,
+      aaPixelsIgnored: comparison.aaPixelsIgnored,
+      aaPercentage: comparison.aaPercentage,
+      heightDiff: comparison.heightDiff,
+      error: comparison.error,
+      originalName: name,
       timestamp: Date.now(),
+      // Boolean hints so UI can show toggle buttons without fetching heavy data
+      hasDiffClusters: comparison.diffClusters?.length > 0,
+      hasConfirmedRegions: comparison.confirmedRegions?.length > 0,
     };
 
-    // Update comparison in report data file
+    // Update lightweight comparison in report-data.json (triggers SSE broadcast)
     updateComparison(newComparison);
 
+    // Persist heavy fields separately (NOT broadcast via SSE)
+    updateComparisonDetails(comparison.id, {
+      diffClusters: comparison.diffClusters,
+      intensityStats: comparison.intensityStats,
+      boundingBox: comparison.boundingBox,
+      regionAnalysis: comparison.regionAnalysis,
+      hotspotAnalysis: comparison.hotspotAnalysis,
+      confirmedRegions: comparison.confirmedRegions,
+    });
+
     // Log screenshot event for menubar
     // Normalize status to match HTTP response ('failed' -> 'diff')
     let logStatus = comparison.status === 'failed' ? 'diff' : comparison.status;
@@ -759,10 +816,14 @@ export const createTddHandler = (
       const freshReportData = {
         timestamp: Date.now(),
         comparisons: [],
-        groups: [],
-        summary: { total: 0, groups: 0, passed: 0, failed: 0, errors: 0 },
+        summary: { total: 0, passed: 0, failed: 0, errors: 0 },
       };
-      writeFileSync(reportPath, JSON.stringify(freshReportData, null, 2));
+      writeFileSync(reportPath, JSON.stringify(freshReportData));
+
+      // Clear comparison details
+      if (existsSync(detailsPath)) {
+        writeFileSync(detailsPath, JSON.stringify({}));
+      }
 
       output.info(
         `Baselines reset - ${deletedBaselines} baselines deleted, ${deletedCurrents} current screenshots deleted, ${deletedDiffs} diffs deleted`
@@ -843,17 +904,18 @@ export const createTddHandler = (
       output.warn(`Failed to update baseline metadata: ${error.message}`);
     }
 
+    // Remove heavy fields from comparison-details.json
+    removeComparisonDetails(comparisonId);
+
     // Remove comparison from report data
     reportData.comparisons = reportData.comparisons.filter(
       c => c.id !== comparisonId
     );
 
-    // Regenerate groups and summary
-    reportData.groups = groupComparisons(reportData.comparisons);
+    // Regenerate summary (groups computed client-side)
     reportData.timestamp = Date.now();
     reportData.summary = {
       total: reportData.comparisons.length,
-      groups: reportData.groups.length,
       passed: reportData.comparisons.filter(
         c =>
           c.status === 'passed' ||
@@ -866,7 +928,7 @@ export const createTddHandler = (
       errors: reportData.comparisons.filter(c => c.status === 'error').length,
     };
 
-    writeFileSync(reportPath, JSON.stringify(reportData, null, 2));
+    writeFileSync(reportPath, JSON.stringify(reportData));
 
     output.info(`Deleted comparison ${comparisonId} (${comparison.name})`);
     return { success: true, id: comparisonId };
diff --git a/src/server/routers/dashboard.js b/src/server/routers/dashboard.js
index e4f27dc5..7251e495 100644
--- a/src/server/routers/dashboard.js
+++ b/src/server/routers/dashboard.js
@@ -6,7 +6,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import * as output from '../../utils/output.js';
-import { sendHtml, sendSuccess } from '../middleware/response.js';
+import { sendError, sendHtml, sendSuccess } from '../middleware/response.js';
 
 // SPA routes that should serve the dashboard HTML
 const SPA_ROUTES = ['/', '/stats', '/settings', '/projects', '/builds'];
@@ -70,6 +70,59 @@ export function createDashboardRouter(context) {
       }
     }
 
+    // API endpoint for fetching full comparison details (lightweight + heavy fields)
+    let comparisonMatch = pathname.match(/^\/api\/comparison\/(.+)$/);
+    if (comparisonMatch) {
+      let comparisonId = decodeURIComponent(comparisonMatch[1]);
+
+      let reportDataPath = join(workingDir, '.vizzly', 'report-data.json');
+      if (!existsSync(reportDataPath)) {
+        sendError(res, 404, 'No report data found');
+        return true;
+      }
+
+      try {
+        let reportData = JSON.parse(readFileSync(reportDataPath, 'utf8'));
+        let comparison = (reportData.comparisons || []).find(
+          c =>
+            c.id === comparisonId ||
+            c.signature === comparisonId ||
+            c.name === comparisonId
+        );
+
+        if (!comparison) {
+          sendError(res, 404, 'Comparison not found');
+          return true;
+        }
+
+        // Merge with heavy fields from comparison-details.json
+        let detailsPath = join(
+          workingDir,
+          '.vizzly',
+          'comparison-details.json'
+        );
+        if (existsSync(detailsPath)) {
+          try {
+            let details = JSON.parse(readFileSync(detailsPath, 'utf8'));
+            let heavy = details[comparison.id];
+            if (heavy) {
+              comparison = { ...comparison, ...heavy };
+            }
+          } catch {
+            // Details file is optional, continue without heavy fields
+          }
+        }
+
+        sendSuccess(res, comparison);
+      } catch (error) {
+        output.debug('Error reading comparison data:', {
+          error: error.message,
+        });
+        sendError(res, 500, 'Failed to read comparison data');
+      }
+      return true;
+    }
+
     // Serve React SPA for dashboard routes
     if (SPA_ROUTES.includes(pathname) || pathname.startsWith('/comparison/')) {
       const reportDataPath = join(workingDir, '.vizzly', 'report-data.json');
diff --git a/tests/server/handlers/tdd-handler.test.js b/tests/server/handlers/tdd-handler.test.js
index b98bc2fa..388585f1 100644
--- a/tests/server/handlers/tdd-handler.test.js
+++ b/tests/server/handlers/tdd-handler.test.js
@@ -1349,7 +1349,68 @@ describe('server/handlers/tdd-handler', () => {
         );
         assert.ok(reportData.timestamp);
         assert.ok(Array.isArray(reportData.comparisons));
-        assert.ok(Array.isArray(reportData.groups));
+      });
+
+      it('excludes heavy fields from report-data.json and writes them to comparison-details.json', async () => {
+        let deps = createMockDeps({
+          tddServiceOverrides: {
+            compareScreenshot: name => ({
+              id: `comp-${name}`,
+              name,
+              status: 'failed',
+              signature: `${name}|1920|chrome`,
+              baseline: '/baselines/test.png',
+              current: '/current/test.png',
+              diff: '/diffs/test.png',
+              diffPercentage: 5.5,
+              threshold: 0.1,
+              diffClusters: [
+                { x: 10, y: 20, width: 100, height: 50, pixelCount: 500 },
+              ],
+              intensityStats: { mean: 0.3, max: 0.8 },
+              boundingBox: { x: 0, y: 0, width: 1920, height: 1080 },
+              regionAnalysis: { totalRegions: 1 },
+              hotspotAnalysis: { coverage: 0.9 },
+              confirmedRegions: [{ id: 'r1', label: 'header' }],
+            }),
+          },
+        });
+        let handler = createTddHandler({}, '/test', null, null, false, deps);
+
+        await handler.handleScreenshot('build-1', 'test', 'base64data', {});
+
+        // report-data.json should NOT contain heavy fields
+        let reportData = JSON.parse(
+          deps._fileSystem['/test/.vizzly/report-data.json']
+        );
+        let comparison = reportData.comparisons[0];
+        assert.strictEqual(comparison.diffClusters, undefined);
+        assert.strictEqual(comparison.intensityStats, undefined);
+        assert.strictEqual(comparison.boundingBox, undefined);
+        assert.strictEqual(comparison.regionAnalysis, undefined);
+        assert.strictEqual(comparison.hotspotAnalysis, undefined);
+        assert.strictEqual(comparison.confirmedRegions, undefined);
+
+        // But should have boolean hints
+        assert.strictEqual(comparison.hasDiffClusters, true);
+        assert.strictEqual(comparison.hasConfirmedRegions, true);
+
+        // And should still have lightweight fields
+        assert.strictEqual(comparison.diffPercentage, 5.5);
+        assert.strictEqual(comparison.threshold, 0.1);
+        assert.strictEqual(comparison.status, 'failed');
+
+        // comparison-details.json SHOULD contain heavy fields
+        let details = JSON.parse(
+          deps._fileSystem['/test/.vizzly/comparison-details.json']
+        );
+        assert.ok(details['comp-test']);
+        assert.strictEqual(details['comp-test'].diffClusters.length, 1);
+        assert.strictEqual(details['comp-test'].confirmedRegions.length, 1);
+        assert.deepStrictEqual(details['comp-test'].intensityStats, {
+          mean: 0.3,
+          max: 0.8,
+        });
       });
 
       it('updates existing comparison by ID', async () => {
diff --git a/tests/server/routers/dashboard.test.js b/tests/server/routers/dashboard.test.js
index df2fff7f..591a009b 100644
--- a/tests/server/routers/dashboard.test.js
+++ b/tests/server/routers/dashboard.test.js
@@ -157,6 +157,153 @@ describe('server/routers/dashboard', () => {
       });
     });
 
+    describe('GET /api/comparison/:id', () => {
+      it('returns merged comparison data by id', async () => {
+        writeFileSync(
+          join(testDir, '.vizzly', 'report-data.json'),
+          JSON.stringify({
+            comparisons: [
+              {
+                id: 'comp-1',
+                name: 'login-page',
+                signature: 'login-page|1280|chrome',
+                status: 'failed',
+                diffPercentage: 0.5,
+                hasDiffClusters: true,
+              },
+            ],
+          })
+        );
+        writeFileSync(
+          join(testDir, '.vizzly', 'comparison-details.json'),
+          JSON.stringify({
+            'comp-1': {
+              diffClusters: [{ x: 10, y: 20, width: 100, height: 50 }],
+              confirmedRegions: [{ id: 'r1', label: 'header' }],
+              intensityStats: { mean: 0.3 },
+            },
+          })
+        );
+
+        let handler = createDashboardRouter();
+        let req = createMockRequest('GET');
+        let res = createMockResponse();
+
+        await handler(req, res, '/api/comparison/comp-1');
+
+        assert.strictEqual(res.statusCode, 200);
+        let body = res.getParsedBody();
+        assert.strictEqual(body.id, 'comp-1');
+        assert.strictEqual(body.name, 'login-page');
+        assert.strictEqual(body.diffPercentage, 0.5);
+        // Heavy fields merged in
+        assert.strictEqual(body.diffClusters.length, 1);
+        assert.strictEqual(body.confirmedRegions.length, 1);
+        assert.deepStrictEqual(body.intensityStats, { mean: 0.3 });
+      });
+
+      it('returns comparison by signature', async () => {
+        writeFileSync(
+          join(testDir, '.vizzly', 'report-data.json'),
+          JSON.stringify({
+            comparisons: [
+              {
+                id: 'comp-2',
+                name: 'home-page',
+                signature: 'home-page|1920|firefox',
+                status: 'passed',
+              },
+            ],
+          })
+        );
+
+        let handler = createDashboardRouter();
+        let req = createMockRequest('GET');
+        let res = createMockResponse();
+
+        await handler(req, res, '/api/comparison/home-page%7C1920%7Cfirefox');
+
+        assert.strictEqual(res.statusCode, 200);
+        let body = res.getParsedBody();
+        assert.strictEqual(body.id, 'comp-2');
+      });
+
+      it('returns comparison by name', async () => {
+        writeFileSync(
+          join(testDir, '.vizzly', 'report-data.json'),
+          JSON.stringify({
+            comparisons: [
+              { id: 'comp-3', name: 'settings-page', status: 'new' },
+            ],
+          })
+        );
+
+        let handler = createDashboardRouter();
+        let req = createMockRequest('GET');
+        let res = createMockResponse();
+
+        await handler(req, res, '/api/comparison/settings-page');
+
+        assert.strictEqual(res.statusCode, 200);
+        let body = res.getParsedBody();
+        assert.strictEqual(body.id, 'comp-3');
+      });
+
+      it('returns 404 when comparison not found', async () => {
+        writeFileSync(
+          join(testDir, '.vizzly', 'report-data.json'),
+          JSON.stringify({ comparisons: [] })
+        );
+
+        let handler = createDashboardRouter();
+        let req = createMockRequest('GET');
+        let res = createMockResponse();
+
+        await handler(req, res, '/api/comparison/nonexistent');
+
+        assert.strictEqual(res.statusCode, 404);
+      });
+
+      it('returns 404 when no report data exists', async () => {
+        let handler = createDashboardRouter();
+        let req = createMockRequest('GET');
+        let res = createMockResponse();
+
+        // Remove the report-data.json file (doesn't exist by default in test)
+        await handler(req, res, '/api/comparison/any-id');
+
+        assert.strictEqual(res.statusCode, 404);
+      });
+
+      it('returns lightweight data when no details file exists', async () => {
+        writeFileSync(
+          join(testDir, '.vizzly', 'report-data.json'),
+          JSON.stringify({
+            comparisons: [
+              {
+                id: 'comp-4',
+                name: 'dashboard',
+                status: 'passed',
+                hasDiffClusters: false,
+              },
+            ],
+          })
+        );
+
+        let handler = createDashboardRouter();
+        let req = createMockRequest('GET');
+        let res = createMockResponse();
+
+        await handler(req, res, '/api/comparison/comp-4');
+
+        assert.strictEqual(res.statusCode, 200);
+        let body = res.getParsedBody();
+        assert.strictEqual(body.id, 'comp-4');
+        // No heavy fields since no details file
+        assert.strictEqual(body.diffClusters, undefined);
+      });
+    });
+
     describe('SPA Routes', () => {
       it('serves dashboard HTML for / route', async () => {
         let handler = createDashboardRouter();

From e29db8bfc6f90a12aec55f907da9301c8e6a2f1a Mon Sep 17 00:00:00 2001
From: Robert DeLuca <robertdeluca19@gmail.com>
Date: Wed, 11 Feb 2026 12:30:29 -0600
Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=90=9B=20Address=20code=20review=20fe?=
 =?UTF-8?q?edback?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add debug logging to readComparisonDetails for consistency
- Add empty comparison ID validation in /api/comparison/:id
- Add debug logging for details file parse errors in dashboard router
---
 src/server/handlers/tdd-handler.js |  3 ++-
 src/server/routers/dashboard.js    | 10 ++++++++--
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/src/server/handlers/tdd-handler.js b/src/server/handlers/tdd-handler.js
index fe7f1603..863d0e52 100644
--- a/src/server/handlers/tdd-handler.js
+++ b/src/server/handlers/tdd-handler.js
@@ -208,7 +208,8 @@ export const createTddHandler = (
     try {
       if (!existsSync(detailsPath)) return {};
       return JSON.parse(readFileSync(detailsPath, 'utf8'));
-    } catch {
+    } catch (error) {
+      output.debug('Failed to read comparison details:', error);
       return {};
     }
   };
diff --git a/src/server/routers/dashboard.js b/src/server/routers/dashboard.js
index 7251e495..acec69b4 100644
--- a/src/server/routers/dashboard.js
+++ b/src/server/routers/dashboard.js
@@ -74,6 +74,10 @@ export function createDashboardRouter(context) {
     let comparisonMatch = pathname.match(/^\/api\/comparison\/(.+)$/);
     if (comparisonMatch) {
       let comparisonId = decodeURIComponent(comparisonMatch[1]);
+      if (!comparisonId) {
+        sendError(res, 400, 'Comparison ID is required');
+        return true;
+      }
 
       let reportDataPath = join(workingDir, '.vizzly', 'report-data.json');
       if (!existsSync(reportDataPath)) {
@@ -108,8 +112,10 @@ export function createDashboardRouter(context) {
             if (heavy) {
               comparison = { ...comparison, ...heavy };
             }
-          } catch {
-            // Details file is optional, continue without heavy fields
+          } catch (error) {
+            output.debug('Failed to read comparison details:', {
+              error: error.message,
+            });
           }
         }