✨ Add region sync for local TDD auto-approval (#191)

## Summary

Enables local TDD mode to use user-defined regions from the cloud
dashboard for auto-approving visual diffs. This brings feature parity
with the cloud product's region-based filtering.

**Phase 1 - CLI & API:**
- Add `POST /api/sdk/screenshots/regions` endpoint in cloud API
- Add `vizzly regions:sync` command with `--include-candidates` flag
- Auto-sync regions during baseline download when API token is
configured
- Store region data in `.vizzly/regions.json`

**Phase 2 - TDD Server & UI:**
- Add `POST /api/regions/sync` endpoint for UI-triggered sync
- Add 2D bounding box intersection calculation for region coverage
- Auto-approve comparisons when 80%+ of diffs fall within confirmed
regions
- Add "Sync Regions" button in Settings view
- Add region overlay visualization in fullscreen viewer (press `G` to
toggle)
- Extract `HotSpotOverlay` component to Observatory for sharing with
cloud

## How it works

1. Users confirm dynamic regions (timestamps, avatars, etc.) in the
cloud dashboard
2. CLI syncs these regions via `vizzly regions:sync` or Settings UI
3. During local comparisons, if 80%+ of diff clusters intersect
confirmed regions → auto-pass as "region-filtered"
4. Same behavior as cloud product, same 80% threshold

## Test plan

- [ ] Run `vizzly regions:sync` with valid API token - regions saved to
`.vizzly/regions.json`
- [ ] Start TDD server, open Settings, click "Sync Regions" - success
toast
- [ ] Create a diff that falls within a confirmed region - auto-passes
as "region-filtered"
- [ ] Open fullscreen viewer, press `G` - green region boxes appear on
screenshot
- [ ] Run `npm test` - all tests pass

Author: Robdel12

.github/workflows/sdk-e2e.yml

@@ -269,7 +269,7 @@ jobs:
         id: playwright-cache
         with:
           path: ~/.cache/ms-playwright
-          key: playwright-${{ steps.playwright-version.outputs.version }}-chromium
+          key: playwright-${{ steps.playwright-version.outputs.version }}-ember-chromium-v2
 
       - name: Install Playwright browsers
         if: steps.playwright-cache.outputs.cache-hit != 'true'

package-lock.json

@@ -119,7 +119,7 @@
     "@tanstack/react-query": "^5.90.11",
     "@types/node": "^25.0.2",
     "@vitejs/plugin-react": "^5.0.3",
-    "@vizzly-testing/observatory": "^0.3.0",
+    "@vizzly-testing/observatory": "^0.3.3",
     "autoprefixer": "^10.4.21",
     "babel-plugin-transform-remove-console": "^6.9.4",
     "postcss": "^8.5.6",

package.json

@@ -19,6 +19,7 @@ import {
   DocumentMagnifyingGlassIcon,
   InformationCircleIcon,
   ListBulletIcon,
+  MapPinIcon,
 } from '@heroicons/react/24/outline';
 import {
   ApprovalButtonGroup,
@@ -101,6 +102,7 @@ function FullscreenViewerInner({
   let [showInspector, setShowInspector] = useState(false);
   let [queueFilter, setQueueFilter] = useState('needs-review');
   let [_showBaseline, setShowBaseline] = useState(true);
+  let [showRegions, setShowRegions] = useState(false);
 
   let { zoom, setZoom } = useZoom('fit');
   let { isActive: isReviewMode } = useReviewMode();
@@ -111,7 +113,7 @@ function FullscreenViewerInner({
   // Toggle inspector (closes other panels)
   let toggleInspector = useCallback(() => {
     setShowInspector(prev => !prev);
-  }, []);
+  }, [setShowInspector]);
 
   // Transform comparisons for queue display
   // Map CLI status to Observatory result format
@@ -291,7 +293,7 @@ function FullscreenViewerInner({
     setViewMode(current =>
       current === VIEW_MODES.OVERLAY ? VIEW_MODES.TOGGLE : VIEW_MODES.OVERLAY
     );
-  }, []);
+  }, [setViewMode]);
 
   // Toggle handler for 'd' - toggles diff overlay or baseline/current
   let handleDiffToggle = useCallback(() => {
@@ -300,7 +302,7 @@ function FullscreenViewerInner({
     } else {
       setShowDiffOverlay(prev => !prev);
     }
-  }, [viewMode]);
+  }, [viewMode, setShowBaseline, setShowDiffOverlay]);
 
   // Review mode shortcuts
   let reviewModeShortcuts = useMemo(
@@ -320,6 +322,7 @@ function FullscreenViewerInner({
       onReject,
       cycleViewMode,
       handleDiffToggle,
+      setViewMode,
     ]
   );
 
@@ -352,12 +355,25 @@ function FullscreenViewerInner({
             toggleInspector();
           }
           break;
+        case 'g':
+          if (!e.metaKey && !e.ctrlKey) {
+            e.preventDefault();
+            setShowRegions(prev => !prev);
+          }
+          break;
       }
     };
 
     window.addEventListener('keydown', handleKeyDown);
     return () => window.removeEventListener('keydown', handleKeyDown);
-  }, [canNavigate, handlePrevious, handleNext, onClose, toggleInspector]);
+  }, [
+    canNavigate,
+    handlePrevious,
+    handleNext,
+    onClose,
+    toggleInspector,
+    setShowRegions,
+  ]);
 
   // Scroll active queue item into view
   useEffect(() => {
@@ -381,7 +397,7 @@ function FullscreenViewerInner({
         behavior: 'smooth',
       });
     }
-  }, []);
+  }, [activeQueueItemRef.current]);
 
   if (!comparison) {
     return (
@@ -523,6 +539,20 @@ function FullscreenViewerInner({
               <ListBulletIcon className="w-5 h-5 pointer-events-none" />
             </button>
 
+            {/* Regions toggle - only show if comparison has regions */}
+            {comparison?.confirmedRegions?.length > 0 && (
+              <button
+                type="button"
+                onClick={() => setShowRegions(!showRegions)}
+                className={`p-2 rounded-md transition-colors ${showRegions ? 'bg-emerald-500/15 text-emerald-400' : 'text-slate-400 hover:text-white hover:bg-slate-800/60'}`}
+                title="Show Regions (G)"
+                aria-label="Toggle regions"
+                data-testid="toggle-regions-btn"
+              >
+                <MapPinIcon className="w-5 h-5 pointer-events-none" />
+              </button>
+            )}
+
             <button
               type="button"
               onClick={toggleInspector}
@@ -661,6 +691,7 @@ function FullscreenViewerInner({
             onOnionSkinChange={setOnionSkinPosition}
             zoom={zoom}
             disableLoadingOverlay={true}
+            showRegions={showRegions}
             className="w-full h-full"
           />
         </main>
@@ -793,6 +824,19 @@ function FullscreenViewerInner({
             <InformationCircleIcon className="w-5 h-5 pointer-events-none" />
           </button>
 
+          {/* Regions toggle - mobile */}
+          {comparison?.confirmedRegions?.length > 0 && (
+            <button
+              type="button"
+              onClick={() => setShowRegions(!showRegions)}
+              className={`flex items-center justify-center p-2.5 rounded-lg transition-colors ${showRegions ? 'bg-emerald-500/15 text-emerald-400' : 'text-slate-400 hover:text-white hover:bg-slate-800/60 active:bg-slate-700/60'}`}
+              aria-label="Toggle regions"
+              data-testid="mobile-toggle-regions-btn"
+            >
+              <MapPinIcon className="w-5 h-5 pointer-events-none" />
+            </button>
+          )}
+
           {canDelete && onDelete && (
             <button
               type="button"

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

@@ -1,5 +1,6 @@
 import { ExclamationTriangleIcon } from '@heroicons/react/24/outline';
 import {
+  HotSpotOverlay,
   OnionSkinMode,
   OverlayMode,
   ToggleView,
@@ -23,6 +24,8 @@ export function ScreenshotDisplay({
   // Zoom support
   zoom = 'fit',
   className = '',
+  // Region overlay
+  showRegions = false,
 }) {
   const [imageErrors, setImageErrors] = useState(new Set());
   const [imageLoadStates, setImageLoadStates] = useState(new Map());
@@ -305,6 +308,19 @@ export function ScreenshotDisplay({
                 onDiffToggle={onDiffToggle}
               />
             )}
+
+            {/* Region overlay - shows confirmed regions (green boxes) */}
+            {showRegions && comparison?.confirmedRegions?.length > 0 && (
+              <HotSpotOverlay
+                confirmed={comparison.confirmedRegions}
+                candidates={[]}
+                imageWidth={naturalImageSize.width}
+                imageHeight={naturalImageSize.height}
+                showConfirmed={true}
+                showCandidates={false}
+                disabled={true}
+              />
+            )}
           </div>
         </div>
 

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

@@ -55,15 +55,18 @@ function IconDropdown({
       onChange(val);
       setIsOpen(false);
     },
-    [onChange]
+    [onChange, setIsOpen]
   );
 
   // Close on outside click
-  let handleBlur = useCallback(e => {
-    if (!dropdownRef.current?.contains(e.relatedTarget)) {
-      setIsOpen(false);
-    }
-  }, []);
+  let handleBlur = useCallback(
+    e => {
+      if (!dropdownRef.current?.contains(e.relatedTarget)) {
+        setIsOpen(false);
+      }
+    },
+    [dropdownRef.current?.contains, setIsOpen]
+  );
 
   return (
     // biome-ignore lint/a11y/noStaticElementInteractions: dropdown container needs blur handler

src/reporter/src/components/dashboard/dashboard-filters.jsx

@@ -162,7 +162,7 @@ export default function ComparisonsView() {
         },
       });
     },
-    [acceptMutation, addToast]
+    [acceptMutation, addToast, setLoadingStates]
   );
 
   // Reject a single comparison
@@ -179,7 +179,7 @@ export default function ComparisonsView() {
         },
       });
     },
-    [rejectMutation, addToast]
+    [rejectMutation, addToast, setLoadingStates]
   );
 
   let handleAcceptAll = useCallback(async () => {