🐛 Prevent stale TDD image loads (#230)

## Why this change
In TDD mode, baseline/current/diff images are overwritten in place under
stable `/images/*` URLs.

That means the reporter can receive fresh comparison data while the
browser still shows stale cached image bytes. The result feels like an
SSE issue, but the primary problem is image caching.

## What changed
- Added a reporter utility that appends a version query param to local
`/images/*` URLs.
- Added a report-data normalizer so comparisons always have a timestamp
fallback for cache-busting (`comparison.timestamp ??
reportData.timestamp`).
- Wired cache-busted URLs into comparison image render paths (viewer,
fullscreen queue thumbnails, screenshot list, screenshot display).
- Added no-cache response headers for image responses in the assets
router.
- Added focused unit tests for URL rewriting behavior and report-data
timestamp normalization.

## Test plan
- `node --test tests/server/routers/assets.test.js
tests/reporter/utils/image-url.test.js
tests/reporter/utils/report-data.test.js`
- `npm run build:reporter`

Author: Robdel12

src/reporter/src/api/client.js

@@ -9,6 +9,8 @@
  * - api.auth.*   - Authentication
  */
 
+import { normalizeReportData } from '../utils/report-data.js';
+
 /**
  * Make a JSON API request
  * @param {string} url - Request URL
@@ -45,7 +47,8 @@ export const tdd = {
    * @returns {Promise<Object|null>}
    */
   async getReportData() {
-    return fetchJson('/api/report-data');
+    let data = await fetchJson('/api/report-data');
+    return normalizeReportData(data);
   },
 
   /**

src/reporter/src/components/comparison/comparison-viewer.jsx

@@ -5,6 +5,7 @@ import {
 } from '@vizzly-testing/observatory';
 import { useCallback, useMemo, useState } from 'react';
 import { VIEW_MODES } from '../../utils/constants.js';
+import { withImageVersion } from '../../utils/image-url.js';
 
 /**
  * Comparison Viewer for inline card display
@@ -36,12 +37,20 @@ export default function ComparisonViewer({ comparison, viewMode }) {
     [comparison]
   );
 
-  // Build image URLs - no memoization needed, object creation is cheap
-  const imageUrls = {
-    current: comparison.current,
-    baseline: comparison.baseline,
-    diff: comparison.diff,
-  };
+  // Build image URLs once per comparison update.
+  const imageUrls = useMemo(
+    () => ({
+      current: withImageVersion(comparison.current, comparison.timestamp),
+      baseline: withImageVersion(comparison.baseline, comparison.timestamp),
+      diff: withImageVersion(comparison.diff, comparison.timestamp),
+    }),
+    [
+      comparison.current,
+      comparison.baseline,
+      comparison.diff,
+      comparison.timestamp,
+    ]
+  );
 
   // For new screenshots, just show the current image (no baseline exists yet)
   if (comparison.status === 'new' || comparison.status === 'baseline-created') {
@@ -52,7 +61,7 @@ export default function ComparisonViewer({ comparison, viewMode }) {
             First screenshot - creating new baseline
           </p>
           <img
-            src={comparison.current}
+            src={imageUrls.current}
             alt="New baseline screenshot"
             className="mx-auto max-w-full block"
           />

src/reporter/src/components/comparison/fullscreen-viewer.jsx

@@ -45,6 +45,7 @@ import {
 } from '@vizzly-testing/observatory';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { VIEW_MODES } from '../../utils/constants.js';
+import { withImageVersion } from '../../utils/image-url.js';
 import { ScreenshotDisplay } from './screenshot-display.jsx';
 
 /**
@@ -641,7 +642,10 @@ function FullscreenViewerInner({
                   <QueueItem
                     item={item}
                     isActive={isActive}
-                    thumbnailUrl={item.current || item.baseline}
+                    thumbnailUrl={withImageVersion(
+                      item.current || item.baseline,
+                      item.timestamp
+                    )}
                     onClick={() => onNavigate(item)}
                   />
                 </div>

src/reporter/src/components/comparison/screenshot-display.jsx

@@ -6,6 +6,7 @@ import {
   ToggleMode,
 } from '@vizzly-testing/observatory';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { withImageVersion } from '../../utils/image-url.js';
 
 /**
  * Unified Screenshot Display Component - matches Observatory architecture
@@ -123,14 +124,21 @@ export function ScreenshotDisplay({
     setImageLoadStates(prev => new Map(prev).set(imageKey, 'loaded'));
   }, []);
 
-  // Build image URLs from comparison object - no memoization needed, object creation is cheap
-  const imageUrls = comparison
-    ? {
-        current: comparison.current,
-        baseline: comparison.baseline,
-        diff: comparison.diff,
-      }
-    : {};
+  // Build image URLs once per comparison update.
+  const imageUrls = useMemo(
+    () =>
+      comparison
+        ? {
+            current: withImageVersion(comparison.current, comparison.timestamp),
+            baseline: withImageVersion(
+              comparison.baseline,
+              comparison.timestamp
+            ),
+            diff: withImageVersion(comparison.diff, comparison.timestamp),
+          }
+        : {},
+    [comparison]
+  );
 
   // Create a screenshot-like object for the comparison modes
   const screenshot = useMemo(() => {
@@ -213,7 +221,7 @@ export function ScreenshotDisplay({
             >
               {comparison && (
                 <img
-                  src={comparison.current}
+                  src={imageUrls.current}
                   alt={comparison.name || 'New screenshot'}
                   className="block"
                   onLoad={() => handleImageLoad(`current-${screenshot?.id}`)}

src/reporter/src/components/comparison/screenshot-list.jsx

@@ -7,6 +7,7 @@ import {
   XCircleIcon,
 } from '@heroicons/react/24/outline';
 import { useMemo } from 'react';
+import { withImageVersion } from '../../utils/image-url.js';
 import { Badge, Button } from '../design-system/index.js';
 import SmartImage from '../ui/smart-image.jsx';
 
@@ -238,7 +239,10 @@ function ScreenshotGroupRow({
 }) {
   let { primary, hasChanges, hasNew, maxDiff } = group;
   let needsAction = hasChanges || hasNew;
-  let thumbnailSrc = primary.current || primary.baseline;
+  let thumbnailSrc = withImageVersion(
+    primary.current || primary.baseline,
+    primary.timestamp
+  );
 
   // Generate test ID from primary comparison
   let testId = `screenshot-group-${(primary.id || primary.signature || group.name).replace(/[^a-zA-Z0-9-]/g, '-')}`;

src/reporter/src/providers/sse-provider.jsx

@@ -1,6 +1,10 @@
 import { useQueryClient } from '@tanstack/react-query';
 import { createContext, useEffect, useRef, useState } from 'react';
 import { queryKeys } from '../lib/query-keys.js';
+import {
+  normalizeComparisonUpdate,
+  normalizeReportData,
+} from '../utils/report-data.js';
 
 export let SSE_STATE = {
   CONNECTING: 'connecting',
@@ -57,7 +61,10 @@ export function SSEProvider({ enabled = true, children }) {
       eventSource.addEventListener('reportData', event => {
         try {
           let data = JSON.parse(event.data);
-          queryClient.setQueryData(queryKeys.reportData(), data);
+          queryClient.setQueryData(
+            queryKeys.reportData(),
+            normalizeReportData(data)
+          );
         } catch {
           // Ignore parse errors
         }
@@ -66,9 +73,13 @@ export function SSEProvider({ enabled = true, children }) {
       // Incremental: single comparison added or changed
       eventSource.addEventListener('comparisonUpdate', event => {
         try {
-          let comparison = JSON.parse(event.data);
+          let incomingComparison = JSON.parse(event.data);
           queryClient.setQueryData(queryKeys.reportData(), old => {
             if (!old) return old;
+            let comparison = normalizeComparisonUpdate(
+              incomingComparison,
+              old.timestamp
+            );
             let comparisons = old.comparisons || [];
             let idx = comparisons.findIndex(c => c.id === comparison.id);
             if (idx >= 0) {

src/reporter/src/utils/image-url.js

@@ -0,0 +1,29 @@
+/**
+ * Add a version query param for local image URLs so updated screenshots
+ * are re-fetched when report data changes.
+ *
+ * This is a no-op for non-local URLs.
+ */
+export let LOCAL_IMAGE_PREFIX = '/images/';
+
+export function withImageVersion(url, version) {
+  if (!url || typeof url !== 'string') {
+    return url;
+  }
+
+  // Only rewrite local TDD image paths.
+  if (!url.startsWith(LOCAL_IMAGE_PREFIX)) {
+    return url;
+  }
+
+  if (version === null || version === undefined) {
+    return url;
+  }
+
+  let [path, queryString = ''] = url.split('?');
+  let params = new URLSearchParams(queryString);
+  params.set('v', String(version));
+  let query = params.toString();
+
+  return query ? `${path}?${query}` : path;
+}

src/reporter/src/utils/report-data.js

@@ -0,0 +1,40 @@
+/**
+ * Ensure each comparison has a timestamp for image cache-busting.
+ */
+export function normalizeReportData(reportData) {
+  if (!reportData || !Array.isArray(reportData.comparisons)) {
+    return reportData;
+  }
+
+  let needsNormalization = reportData.comparisons.some(
+    comparison => comparison && comparison.timestamp == null
+  );
+
+  if (!needsNormalization) {
+    return reportData;
+  }
+
+  let fallbackTimestamp = reportData.timestamp ?? Date.now();
+  let comparisons = reportData.comparisons.map(comparison =>
+    normalizeComparisonUpdate(comparison, fallbackTimestamp)
+  );
+
+  return {
+    ...reportData,
+    comparisons,
+  };
+}
+
+/**
+ * Ensure a single comparison includes a timestamp.
+ */
+export function normalizeComparisonUpdate(comparison, fallbackTimestamp) {
+  if (!comparison || comparison.timestamp != null) {
+    return comparison;
+  }
+
+  return {
+    ...comparison,
+    timestamp: fallbackTimestamp ?? Date.now(),
+  };
+}

src/server/routers/assets.js

@@ -84,6 +84,10 @@ export function createAssetsRouter() {
       if (existsSync(fullImagePath)) {
         try {
           const imageData = readFileSync(fullImagePath);
+          // Images are rewritten in place between TDD runs, so disable browser caching.
+          res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate');
+          res.setHeader('Pragma', 'no-cache');
+          res.setHeader('Expires', '0');
           sendFile(res, imageData, 'image/png');
           return true;
         } catch (error) {

tests/reporter/utils/image-url.test.js

@@ -0,0 +1,57 @@
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { withImageVersion } from '../../../src/reporter/src/utils/image-url.js';
+
+describe('reporter/utils/image-url', () => {
+  it('returns original value for non-string urls', () => {
+    assert.strictEqual(withImageVersion(null, 1), null);
+    assert.strictEqual(withImageVersion(undefined, 1), undefined);
+    assert.strictEqual(withImageVersion(42, 1), 42);
+  });
+
+  it('returns original url for non-local images', () => {
+    let url = 'https://cdn.example.com/image.png';
+    assert.strictEqual(withImageVersion(url, 123), url);
+  });
+
+  it('returns original url when version is missing', () => {
+    let url = '/images/current/homepage.png';
+    assert.strictEqual(withImageVersion(url, null), url);
+    assert.strictEqual(withImageVersion(url, undefined), url);
+  });
+
+  it('appends v query param for local image urls', () => {
+    assert.strictEqual(
+      withImageVersion('/images/current/homepage.png', 123),
+      '/images/current/homepage.png?v=123'
+    );
+  });
+
+  it('supports zero as a valid cache-busting version', () => {
+    assert.strictEqual(
+      withImageVersion('/images/current/homepage.png', 0),
+      '/images/current/homepage.png?v=0'
+    );
+  });
+
+  it('appends v query param using ampersand when query already exists', () => {
+    assert.strictEqual(
+      withImageVersion('/images/current/homepage.png?mode=thumb', 456),
+      '/images/current/homepage.png?mode=thumb&v=456'
+    );
+  });
+
+  it('replaces existing v query param instead of duplicating', () => {
+    assert.strictEqual(
+      withImageVersion('/images/current/homepage.png?v=old&mode=thumb', 456),
+      '/images/current/homepage.png?v=456&mode=thumb'
+    );
+  });
+
+  it('encodes non-numeric version values', () => {
+    assert.strictEqual(
+      withImageVersion('/images/current/homepage.png', 'run 1'),
+      '/images/current/homepage.png?v=run+1'
+    );
+  });
+});