documentation-hub 5.7.2

package/docs/github-issues/issue-5-body.md

@@ -0,0 +1,173 @@
+## Problem Description
+
+**Type:** Bug (Infinite Re-render Loop)
+**Priority:** High
+**Likelihood:** 60%
+**Impact:** App freeze/crash when theme color parsing fails
+**Timeline:** 1-2 weeks (user enters invalid color value)
+
+ThemeContext calls `setState` inside a `useEffect` error handler, which can trigger an infinite re-render loop when color parsing fails.
+
+### Affected Files
+
+- [`src/contexts/ThemeContext.tsx:203-268`](src/contexts/ThemeContext.tsx#L203-L268) - Custom color application with error handler
+
+###Current Problematic Code
+
+```typescript
+useEffect(() => {
+  const root = window.document.documentElement;
+
+  if (useCustomColors) {
+    try {
+      root.setAttribute('data-custom-colors', 'true');
+
+      const foregroundColor = getContrastTextColor(customBackgroundColor);
+      root.style.setProperty('--custom-primary', hexToHSL(customPrimaryColor));
+      // ... more color applications
+    } catch (error) {
+      log.error('[ThemeContext] Error applying custom colors:', error);
+
+      // ❌ INFINITE LOOP TRAP!
+      setUseCustomColors(false); // Triggers useEffect again!
+      root.removeAttribute('data-custom-colors');
+    }
+  }
+}, [useCustomColors, customPrimaryColor, customBackgroundColor /* deps */]);
+```
+
+## The Infinite Loop Scenario
+
+**Step 1:** User enters invalid color (e.g., "#GGGGGG")
+**Step 2:** useEffect runs, `hexToHSL("#GGGGGG")` throws error
+**Step 3:** Catch block calls `setUseCustomColors(false)` → state change
+**Step 4:** State change triggers useEffect again (dependency changed)
+**Step 5:** If error persists (bad color in localStorage), loop continues
+
+**Result:** React error: "Maximum update depth exceeded"
+
+## Additional Issues
+
+**Problem 2:** Multiple useEffect hooks modify same DOM element
+
+7 separate useEffect hooks all modify `window.document.documentElement`:
+
+- Theme application (light/dark)
+- Accent color
+- Custom colors
+- Density
+- Animations
+- Blur effects
+- Typography
+
+All running simultaneously during initial mount = potential race conditions
+
+**Problem 3:** No validation before applying colors
+
+Colors applied directly without validation:
+
+```typescript
+root.style.setProperty('--custom-primary', hexToHSL(customPrimaryColor));
+```
+
+If `hexToHSL()` throws, entire effect fails and triggers recovery via setState.
+
+## Root Cause
+
+1. **Error Recovery in useEffect:** Calling setState inside effect's error handler creates feedback loop
+2. **No Color Validation:** Invalid colors aren't caught before attempting to apply
+3. **Lack of Error Boundaries:** No fallback mechanism to prevent cascading failures
+4. **Too Many Effects:** 7 separate hooks all modifying the same DOM element
+
+## Evidence
+
+**From Code Comments:**
+
+- Line 232: "Disable custom colors on error to prevent cascading failures"
+  - Confirms failures have occurred
+  - The "fix" (setUseCustomColors) creates new problem
+
+## Proposed Solution
+
+**Solution 1: Validate colors before applying**
+
+```typescript
+// NEW: Color validation utility
+function isValidHexColor(color: string): boolean {
+  return /^#[0-9A-F]{6}$/i.test(color);
+}
+
+// REFACTORED: Validate in state setter, not in effect
+const [customPrimaryColor, setCustomPrimaryColor] = useState<string>(() => {
+  const stored = localStorage.getItem('customPrimaryColor') || '#3b82f6';
+  return isValidHexColor(stored) ? stored : '#3b82f6'; // Validate on load
+});
+
+// Validate in setter
+const updateCustomPrimaryColor = (color: string) => {
+  if (isValidHexColor(color)) {
+    setCustomPrimaryColor(color);
+  } else {
+    log.warn(`Invalid hex color: ${color}, using default`);
+    setCustomPrimaryColor('#3b82f6');
+  }
+};
+
+// Effect no longer needs error recovery
+useEffect(() => {
+  const root = window.document.documentElement;
+
+  if (useCustomColors) {
+    // Safe to apply - already validated
+    const foregroundColor = getContrastTextColor(customBackgroundColor);
+    root.style.setProperty('--custom-primary', hexToHSL(customPrimaryColor));
+  }
+}, [useCustomColors, customPrimaryColor, customBackgroundColor]);
+```
+
+**Solution 2: Consolidate effects**
+
+```typescript
+// Instead of 7 separate useEffect hooks, use one coordinated effect
+useEffect(() => {
+  const root = window.document.documentElement;
+
+  try {
+    applyTheme(root, theme, resolvedTheme);
+    applyAccentColor(root, accentColor, customAccentColor);
+    applyCustomColors(root, useCustomColors, { customPrimaryColor /* ... */ });
+    applyDensity(root, density);
+    applyAnimations(root, animations);
+    applyBlur(root, blur);
+    applyTypography(root, { fontSize, fontFamily /* ... */ });
+  } catch (error) {
+    log.error('[ThemeContext] Failed to apply theme:', error);
+    // DON'T call setState here - just log and use defaults
+  }
+}, [theme, accentColor /* all deps */]);
+```
+
+## Acceptance Criteria
+
+- [ ] No `setState` calls inside useEffect error handlers
+- [ ] All colors validated before applying to DOM
+- [ ] Invalid colors in localStorage don't crash app
+- [ ] No infinite re-render loops on theme errors
+- [ ] Clear error messages when color validation fails
+- [ ] Fallback to default theme on catastrophic failure
+- [ ] All 7 theme aspects apply correctly
+
+## Testing Strategy
+
+1. **Invalid Color Test:** Enter "#ZZZZZZ", verify app doesn't crash, fallback applied
+2. **Corrupted Storage Test:** Set invalid localStorage color, restart app, verify loads with default
+3. **Rapid Change Test:** Change all settings rapidly (10 changes/second), verify no loop warnings
+4. **Error Boundary Test:** Force hexToHSL() to throw, verify boundary catches, app remains usable
+
+## Estimated Effort
+
+**2 hours** (1 hour implementation + 1 hour testing)
+
+## Research Reference
+
+Full analysis: [`GH_Issues/scratchpads/predictive-analysis-2025-10-18.md`](../GH_Issues/scratchpads/predictive-analysis-2025-10-18.md#high-priority-issue-5-theme-context-infinite-loop-on-error)

package/docs/github-issues/issue-6-body.md

@@ -0,0 +1,158 @@
+## Problem Description
+
+**Type:** Enhancement (UX Polish)
+**Priority:** Medium
+**Likelihood:** 40%
+**Impact:** Unprofessional flicker/flash on startup
+**Timeline:** **ALREADY HAPPENING** - visible on every launch
+
+Main window is visible immediately on creation, showing black background before React loads.
+
+### Affected Files
+
+- [`electron/main.ts:365-395`](electron/main.ts#L365-L395) - Window creation without ready-to-show
+
+### Current Implementation
+
+```typescript
+async function createWindow() {
+  mainWindow = new BrowserWindow({
+    width: 1400,
+    height: 900,
+    minWidth: 800,
+    minHeight: 600,
+    frame: false,
+    titleBarStyle: 'hiddenInset',
+    backgroundColor: '#0a0a0a', // Dark gray
+    webPreferences: REQUIRED_SECURITY_SETTINGS,
+    // ❌ NO show: false option!
+  });
+
+  if (isDev) {
+    mainWindow.loadURL('http://localhost:5173'); // Shows immediately!
+  } else {
+    mainWindow.loadFile(join(__dirname, '../index.html'));
+  }
+
+  // ❌ NO ready-to-show event handler!
+}
+```
+
+### Comparison: Comparison Window (Correct Pattern)
+
+Located at `electron/main.ts:657-693`:
+
+```typescript
+const comparisonWindow = new BrowserWindow({
+  // ...
+  show: false, // Hidden initially!
+  backgroundColor: '#ffffff',
+});
+
+comparisonWindow.loadURL(/*...*/);
+
+// Show only when ready!
+comparisonWindow.once('ready-to-show', () => {
+  comparisonWindow.show();
+});
+```
+
+## User Experience Impact
+
+**Current Behavior:**
+
+- 0ms: User clicks app icon
+- 50ms: Electron window appears (black screen)
+- 1500ms: React finally renders UI
+- **User sees:** 1.5 seconds of black screen
+
+**Expected with Fix:**
+
+- 0ms: User clicks app icon
+- 0ms: Window created but hidden
+- 1500ms: All providers initialized, React ready
+- 1500ms: Window shows (smooth fade-in)
+- **User sees:** Nothing until app is fully loaded
+
+## Root Cause
+
+1. `show: false` not set in BrowserWindowOptions
+2. No `ready-to-show` event listener
+3. No loading splash screen
+
+## Proposed Solution
+
+**Option 1: Hide until ready (Recommended)**
+
+```typescript
+async function createWindow() {
+  mainWindow = new BrowserWindow({
+    width: 1400,
+    height: 900,
+    minWidth: 800,
+    minHeight: 600,
+    frame: false,
+    titleBarStyle: 'hiddenInset',
+    backgroundColor: '#0a0a0a',
+    show: false, // Hide initially
+    webPreferences: REQUIRED_SECURITY_SETTINGS,
+  });
+
+  if (isDev) {
+    mainWindow.loadURL('http://localhost:5173');
+  } else {
+    mainWindow.loadFile(join(__dirname, '../index.html'));
+  }
+
+  // Show when content is ready
+  mainWindow.once('ready-to-show', () => {
+    mainWindow?.show();
+
+    // Optional: Fade in effect
+    mainWindow?.setOpacity(0);
+    let opacity = 0;
+    const fadeIn = setInterval(() => {
+      opacity += 0.1;
+      mainWindow?.setOpacity(opacity);
+      if (opacity >= 1) clearInterval(fadeIn);
+    }, 20); // 200ms total fade
+  });
+}
+```
+
+## Acceptance Criteria
+
+- [ ] Window hidden until `ready-to-show` event fires
+- [ ] No black screen visible during startup
+- [ ] Smooth appearance of UI (optional: fade-in effect)
+- [ ] Dev tools open correctly in development mode
+- [ ] Window shows at correct size and position
+- [ ] All window event handlers still work correctly
+
+## Testing Strategy
+
+1. **Cold Start Test:** Restart app 10 times, verify no black screen flicker
+2. **Dev Mode Test:** Run `npm run dev`, verify dev tools open correctly
+3. **Production Test:** Build app, test on fresh install and with existing data
+
+## Estimated Effort
+
+**30 minutes** (15 min implementation + 15 min testing)
+
+## Priority Justification
+
+**Why Medium (not High):**
+
+- Purely cosmetic issue (doesn't affect functionality)
+- Workaround exists (users can wait)
+- Easy fix, low risk
+
+**Why Not Low:**
+
+- Affects every single app launch
+- First impression matters (UX quality)
+- Simple fix with big perceived improvement
+
+## Research Reference
+
+Full analysis: [`GH_Issues/scratchpads/predictive-analysis-2025-10-18.md`](../GH_Issues/scratchpads/predictive-analysis-2025-10-18.md#medium-priority-issue-6-main-window-shows-black-screen-on-startup)

package/docs/github-issues/issue-7-body.md

@@ -0,0 +1,171 @@
+## Problem Description
+
+**Type:** Bug (Timing/Coordination)
+**Priority:** Medium
+**Likelihood:** 50%
+**Impact:** Auto-update delayed by 5-10 seconds in corporate environments
+**Timeline:** **ALREADY HAPPENING** - affects users behind proxies
+
+Background certificate check and auto-updater initialize independently with no coordination, causing TLS failures when updater runs before certificates are validated.
+
+### Affected Files
+
+- [`electron/main.ts:576-607`](electron/main.ts#L576-L607) - Certificate check (runs at 500ms)
+- [`electron/main.ts:1585-1595`](electron/main.ts#L1585-L1595) - Auto-updater (runs at 1000ms)
+
+### Current Implementation
+
+**Certificate Check:**
+
+```typescript
+app.whenReady().then(async () => {
+  await createWindow();
+
+  setImmediate(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 500)); // ❌ Arbitrary delay
+
+    performPreflightCertificateCheck()
+      .then(() => {
+        // ... success handling
+      })
+      .catch((error) => {
+        // ... error handling
+      });
+  });
+});
+```
+
+**Auto-Updater:**
+
+```typescript
+app.whenReady().then(() => {
+  setTimeout(() => {
+    updaterHandler = new AutoUpdaterHandler(); // ❌ Might run before certs validated!
+
+    if (!isDev) {
+      updaterHandler.checkOnStartup(); // Immediately tries to connect
+    }
+  }, 1000); // ❌ Another arbitrary delay
+});
+```
+
+## The Race Condition
+
+**Scenario 1: Certificate check wins (500ms < 1000ms)**
+
+- Result: Works correctly
+
+**Scenario 2: Certificate check is slow (network latency)**
+
+- 500ms: Certificate check starts
+- 1000ms: Auto-updater starts
+- 1001ms: Update check fails with TLS error (certs not ready)
+- 2000ms: Certificate check completes (too late!)
+- Result: Auto-update fails, user doesn't get notified
+
+**Scenario 3: Corporate proxy (high latency)**
+
+- Both checks hang waiting for proxy auth
+- Both timeout
+- Result: Both fail, no updates available
+
+## Impact Analysis
+
+**Affected Users:**
+
+- Corporate environments with Zscaler/proxy
+- Users with slow network connections
+- Users with SSL-intercepting firewalls
+
+Based on extensive proxy configuration code (lines 51-313), this clearly affects a significant portion of users.
+
+**User Experience:**
+
+- Update notification should appear
+- Instead: silence (update check failed)
+- User never knows update is available
+- Continues using old version with bugs
+
+## Root Cause
+
+1. **Independent Initialization:** Two `setTimeout` calls with arbitrary delays (500ms, 1000ms)
+2. **No Synchronization:** Auto-updater doesn't wait for certificate validation
+3. **Race Condition:** Which finishes first is unpredictable (network dependent)
+4. **Silent Failure:** Failed update checks don't retry or notify user
+
+## Proposed Solution
+
+Make certificate validation a prerequisite for updater:
+
+```typescript
+app.whenReady().then(async () => {
+  // STEP 1: Create window first (user sees app immediately)
+  await createWindow();
+
+  // STEP 2: Background initialization (non-blocking for UI)
+  setImmediate(async () => {
+    try {
+      // STEP 2A: Validate certificates (BLOCKING for updater)
+      log.info('[Init] Validating certificates...');
+      await performPreflightCertificateCheck();
+      log.info('[Init] Certificates validated');
+
+      // Notify renderer
+      if (mainWindow && !mainWindow.isDestroyed()) {
+        mainWindow.webContents.send('certificate-check-complete', {
+          success: true,
+          timestamp: new Date().toISOString(),
+        });
+      }
+    } catch (error) {
+      log.error('[Init] Certificate validation failed:', error);
+
+      // Notify renderer of failure
+      if (mainWindow && !mainWindow.isDestroyed()) {
+        mainWindow.webContents.send('certificate-check-complete', {
+          success: false,
+          error: error.message,
+          timestamp: new Date().toISOString(),
+        });
+      }
+    }
+
+    // STEP 2B: Initialize updater (AFTER certificates validated)
+    log.info('[Init] Initializing auto-updater...');
+    updaterHandler = new AutoUpdaterHandler(mainWindow);
+
+    if (!isDev) {
+      setTimeout(() => {
+        log.info('[Init] Checking for updates...');
+        updaterHandler.checkOnStartup();
+      }, 2000); // 2 second delay AFTER certs validated
+    }
+
+    log.info('[Init] Background initialization complete');
+  });
+});
+```
+
+## Acceptance Criteria
+
+- [ ] Auto-updater only initializes AFTER certificate validation completes
+- [ ] No race condition between certificate check and update check
+- [ ] Failed certificate validation delays updater (doesn't crash it)
+- [ ] Update checks succeed in corporate proxy environments
+- [ ] User gets notified of available updates within 5 seconds
+- [ ] Failed update checks retry with exponential backoff
+
+## Testing Strategy
+
+1. **Normal Network Test:** Verify update notification appears within 5 seconds
+2. **Slow Network Test:** Add 3s latency, verify updater waits for certificates
+3. **Corporate Proxy Test:** Test with Zscaler/proxy configuration
+4. **Certificate Failure Test:** Block GitHub certificates, verify updater doesn't crash
+
+## Estimated Effort
+
+**1 hour** (30 min implementation + 30 min testing)
+
+## Research Reference
+
+Full analysis: [`GH_Issues/scratchpads/predictive-analysis-2025-10-18.md`](../GH_Issues/scratchpads/predictive-analysis-2025-10-18.md#medium-priority-issue-7-certificate-check-delays-auto-update)