# Execution Plan: Fix SSR Violations and SvelteKit Best Practices

## Outcome Name
FixEventSourceSSRAndBestPractices

## Problem Analysis

### Primary Issue
`ReferenceError: EventSource is not defined` at `/home/moze/Sources/insta-recipe/src/routes/+page.svelte:299:66`

### Root Cause
The code is accessing `EventSource` during server-side rendering (SSR), but `EventSource` is a browser-only Web API that doesn't exist in Node.js. Additionally, comprehensive codebase analysis revealed multiple SSR violations and SvelteKit anti-patterns.

### Affected Files - Critical
1. **[src/routes/+page.svelte](src/routes/+page.svelte)** - EventSource accessed at L299, L82 without browser guards
2. **[src/routes/share/+page.svelte](src/routes/share/+page.svelte#L22-L25)** - `$effect` with side effects (calls `process()` function)
3. **[src/routes/share/components/LlmHealthIndicator.svelte](src/routes/share/components/LlmHealthIndicator.svelte#L36-L39)** - `$effect` with `setInterval` (no browser guard)

### Affected Files - Already Compliant (Good Examples)
1. **[src/lib/client/PushNotificationManager.ts](src/lib/client/PushNotificationManager.ts)** ✅
   - Properly uses `browser` from `$app/environment` (L10)
   - Guards `localStorage` access (L296, L300)
   - Guards `window.atob` access (L318)
   - Guards `navigator.serviceWorker` access (L111)

2. **[src/lib/client/ServiceWorkerMessageHandler.ts](src/lib/client/ServiceWorkerMessageHandler.ts)** ✅
   - All browser APIs properly used in client-only context
   - Not imported/used in SSR contexts

### SvelteKit Best Practices (from llms-full.txt documentation)

#### 1. Browser API Access
**Pattern:** Import `browser` from `$app/environment` and guard all browser-only APIs
```js
import { browser } from '$app/environment';

if (browser) {
  // Browser-only code
}
```

**Browser-only APIs to guard:**
- `window.*`
- `document.*`
- `localStorage`, `sessionStorage`
- `navigator.*`
- `EventSource`, `WebSocket`
- `location.*`

#### 2. Lifecycle Hooks
**Pattern:** `onMount` only runs in browser (built-in SSR guard)
```js
import { onMount } from 'svelte';

onMount(() => {
  // Automatically browser-only
  // Still good practice to add explicit browser check for clarity
});
```

#### 3. Runes and Reactivity
**`$effect` gotcha:** Effects run during SSR AND hydration. Must guard browser APIs!
```js
$effect(() => {
  if (!browser) return;
  // Browser-only reactive code
});
```

**`$derived` gotcha:** Computed values run during SSR. Keep them pure!
```js
// ✅ GOOD - pure computation
let doubled = $derived(count * 2);

// ❌ BAD - side effects in derived
let value = $derived(localStorage.getItem('key')); // SSR crash!
```

#### 4. State Initialization
**Pattern:** Initialize with SSR-safe defaults, update in `onMount`
```js
let data = $state<Data | null>(null);

onMount(() => {
  // Load browser-only data
  data = JSON.parse(localStorage.getItem('key') || 'null');
});
```

#### 5. Static Constants
**Gotcha:** Accessing static properties of browser APIs causes SSR errors
```js
// ❌ BAD - EventSource.OPEN doesn't exist in Node
if (eventSource?.readyState === EventSource.OPEN)

// ✅ GOOD - Use numeric constants or guard
if (browser && eventSource?.readyState === EventSource.OPEN)
// OR
if (eventSource?.readyState === 1) // EventSource.OPEN = 1
```

### Codebase Analysis Results

#### ✅ Already Properly Guarded
- `PushNotificationManager.ts` - Excellent example of SSR-safe patterns
- `ServiceWorkerMessageHandler.ts` - Client-only, properly scoped
- All API routes in `src/routes/api/**` - Server-only contexts
- Service worker (`service-worker.ts`) - Runs in worker context only

#### ⚠️ Needs Fixing

**High Priority (Breaking SSR):**
1. **+page.svelte (Queue Dashboard)**
   - L299: `eventSource?.readyState === EventSource.OPEN` - No browser guard
   - L82: `eventSource?.readyState === EventSource.CLOSED` - No browser guard
   - L67: `new EventSource()` - Inside `onMount` but needs explicit guard
   - Missing `browser` import

2. **LlmHealthIndicator.svelte**
   - L36-39: `$effect` with `setInterval` - No browser guard
   - Should use `onMount` instead for timer setup

**Medium Priority (Anti-patterns):**
3. **share/+page.svelte**
   - L22-25: `$effect` calling `process()` with side effects
   - Should use `onMount` with conditional logic instead
   - `$effect` is meant for synchronization, not side effects

#### 📋 Not Issues (Clarifications)
- `setTimeout` in components (L81 in +page.svelte, L53 in share/+page.svelte) - ✅ OK because inside `onMount` or event handlers
- `goto` from `$app/navigation` - ✅ SSR-safe (SvelteKit handles this)
- `$page` store from `$app/stores` - ✅ SSR-safe (available in both contexts)
- Server-side code (`lib/server/**`) using browser automation - ✅ OK (different context, uses Puppeteer)

## Stories

## Stories

### Story 1: Fix EventSource SSR in Queue Dashboard
**As a** developer  
**I want** to guard all EventSource usage from SSR execution  
**So that** the application doesn't crash with "EventSource is not defined"

**Acceptance Criteria:**
- Import `browser` from `$app/environment`
- Guard `EventSource` constructor in `startSSEConnection()`
- Replace `EventSource.OPEN` constant with numeric value `1` or add browser guard
- Replace `EventSource.CLOSED` constant with numeric value `2` or add browser guard
- Connection status works correctly after hydration
- No SSR errors in server logs

**Technical Details:**

**Lines to fix:**
- L2: Add `import { browser } from '$app/environment';`
- L67-68: Add browser guard before creating EventSource
- L82: Change `EventSource.CLOSED` to `2` or guard with `browser`
- L299: Change `EventSource.OPEN` to `1` or guard with `browser`

**Implementation:**
```typescript
import { browser } from '$app/environment';

function startSSEConnection() {
  if (!browser) return; // ✅ Guard
  
  try {
    eventSource = new EventSource('/api/queue/stream');
    // ... rest
  }
}

// In reconnection logic (L82):
if (browser && eventSource?.readyState === 2) { // CLOSED = 2
  startSSEConnection();
}

// In template (L299):
<div class="w-2 h-2 rounded-full {browser && eventSource?.readyState === 1 ? 'bg-green-400' : 'bg-red-400'}"></div>
```

**Files:**
- [src/routes/+page.svelte](src/routes/+page.svelte)

---

### Story 2: Fix $effect Anti-pattern in Share Page
**As a** developer  
**I want** to replace `$effect` side effects with `onMount` pattern  
**So that** the code follows SvelteKit best practices

**Acceptance Criteria:**
- Replace `$effect` with `onMount` for auto-processing shared URLs
- No side effects in reactive expressions
- Auto-processing still works when URL is shared
- No unnecessary re-triggering

**Technical Details:**

According to SvelteKit documentation, `$effect` should be used for synchronization, not side effects like API calls. Use `onMount` instead.

**Current problematic code (L22-25):**
```typescript
$effect(() => {
  if (targetUrl && status === 'idle') {
    process();
  }
});
```

**Fixed code:**
```typescript
let hasProcessed = $state(false);

onMount(() => {
  if (targetUrl && !hasProcessed) {
    hasProcessed = true;
    process();
  }
});
```

**Files:**
- [src/routes/share/+page.svelte](src/routes/share/+page.svelte)

**SvelteKit Pattern Reference:**
> Use `$effect` for synchronizing derived state, DOM manipulation, or reactive cleanup.
> Use `onMount` for initialization, API calls, and browser-only setup.

---

### Story 3: Fix setInterval SSR in LLM Health Indicator
**As a** developer  
**I want** to guard `setInterval` from SSR execution  
**So that** the component doesn't break during server rendering

**Acceptance Criteria:**
- Add browser guard to `$effect` containing `setInterval`
- Health polling only runs in browser
- Component renders safely during SSR
- Cleanup still works correctly

**Technical Details:**

**Current code (L36-39):**
```typescript
$effect(() => {
  checkHealth(); // Initial check
  const interval = setInterval(checkHealth, pollInterval);
  return () => clearInterval(interval);
});
```

**Fixed code:**
```typescript
$effect(() => {
  if (!browser) return; // ✅ SSR guard
  
  checkHealth(); // Initial check
  const interval = setInterval(checkHealth, pollInterval);
  return () => clearInterval(interval);
});
```

**Better alternative - use onMount:**
```typescript
onMount(() => {
  checkHealth(); // Initial check
  const interval = setInterval(checkHealth, pollInterval);
  return () => clearInterval(interval);
});
```

**Files:**
- [src/routes/share/components/LlmHealthIndicator.svelte](src/routes/share/components/LlmHealthIndicator.svelte)

---

### Story 4: Add SSR Best Practices Documentation
**As a** developer  
**I want** documentation on SSR best practices for this project  
**So that** future development avoids these issues

**Acceptance Criteria:**
- Create or update developer documentation
- Include examples from the codebase
- Reference SvelteKit official documentation
- Add inline comments explaining SSR guards

**Technical Details:**

Create documentation covering:
1. Browser API detection with `$app/environment`
2. Lifecycle hook usage (`onMount` vs `$effect`)
3. Common gotchas (static constants, timers, storage APIs)
4. Good examples from our codebase (PushNotificationManager)

**Files to create/update:**
- `docs/SVELTEKIT_SSR_GUIDE.md` (new)
- Add inline comments to fixed files

---

### Story 5: Comprehensive SSR Audit and Testing
**As a** developer  
**I want** to verify no other SSR violations exist  
**So that** the application is fully SSR-safe

**Acceptance Criteria:**
- Manual SSR test: `npm run build && npm run preview`
- Check server logs for any SSR errors
- Test all routes with JavaScript disabled (progressive enhancement)
- Verify hydration works correctly
- No console warnings about hydration mismatches

**Technical Details:**

**Testing checklist:**
- [ ] Build production bundle: `npm run build`
- [ ] Preview production: `npm run preview`
- [ ] Navigate to all routes
- [ ] Check server console for errors
- [ ] Verify SSE connection works
- [ ] Test push notification UI
- [ ] Test queue dashboard
- [ ] Test share page with/without URL params

**Search patterns to verify:**
```bash
# Find any unguarded browser API usage
grep -r "window\." src/routes --include="*.svelte"
grep -r "document\." src/routes --include="*.svelte"
grep -r "localStorage" src/routes --include="*.svelte"
grep -r "navigator\." src/routes --include="*.svelte"
```

**Known safe patterns:**
- API routes (`src/routes/api/**`) - server-only
- Client libraries (`src/lib/client/**`) - properly guarded
- Event handlers (`onclick`, `onsubmit`) - run client-side
- `onMount` callbacks - run client-side

## Implementation Plan

### Phase 1: Critical Fixes (Blocks Production)
**Priority:** URGENT - Fixes SSR crashes

1. **Story 1** - Fix EventSource in Queue Dashboard
   - Add `browser` import
   - Guard EventSource creation
   - Fix static constant references
   - Test SSR rendering

2. **Story 3** - Fix setInterval in LLM Health Indicator  
   - Add browser guard to $effect OR convert to onMount
   - Test component SSR

**Estimated Time:** 30 minutes  
**Testing:** Build and preview, check server logs

---

### Phase 2: Best Practices (Improves Code Quality)
**Priority:** HIGH - Fixes anti-patterns

3. **Story 2** - Fix $effect anti-pattern in Share Page
   - Replace $effect with onMount
   - Add processed flag to prevent re-runs
   - Test auto-processing behavior

**Estimated Time:** 20 minutes  
**Testing:** Test share target flow

---

### Phase 3: Validation & Documentation (Prevents Future Issues)
**Priority:** MEDIUM - Long-term maintainability

4. **Story 5** - Comprehensive SSR Audit
   - Run production build
   - Test all routes
   - Verify no SSR errors

5. **Story 4** - Documentation
   - Create SSR best practices guide
   - Add inline comments
   - Document patterns from PushNotificationManager

**Estimated Time:** 1 hour  
**Testing:** Full regression test

---

### Total Estimated Time
- Critical fixes: 30 min
- Best practices: 20 min  
- Validation & docs: 1 hour
- **Total: ~2 hours**

## Technical Specifications

### SvelteKit Runes Reference

#### `$state` - Reactive State
```typescript
let count = $state(0); // Simple state
let obj = $state({ name: 'Alice' }); // Deep reactive proxy
```
- ✅ SSR-safe for primitive values
- ⚠️ Don't initialize with browser APIs

#### `$derived` - Computed Values
```typescript
let doubled = $derived(count * 2);
```
- ✅ Runs during SSR
- ⚠️ Must be pure (no side effects)
- ❌ Don't access browser APIs

#### `$effect` - Reactive Side Effects
```typescript
$effect(() => {
  // Runs during SSR AND hydration
  console.log('count changed:', count);
});
```
- ⚠️ Runs in both SSR and browser
- ✅ Use for synchronization
- ❌ Not for initialization or API calls
- **Must guard browser APIs**

#### `onMount` - Browser-Only Lifecycle
```typescript
onMount(() => {
  // Only runs in browser
  return () => {
    // Cleanup
  };
});
```
- ✅ Only runs in browser
- ✅ Use for initialization
- ✅ Use for browser API access

### Browser API Constants

Some browser APIs expose static constants that don't exist during SSR:

**EventSource:**
- `EventSource.CONNECTING = 0`
- `EventSource.OPEN = 1`
- `EventSource.CLOSED = 2`

**Solutions:**
```typescript
// ❌ BAD - Crashes SSR
if (es.readyState === EventSource.OPEN)

// ✅ GOOD - Use numeric value
if (es.readyState === 1)

// ✅ GOOD - Guard access
if (browser && es.readyState === EventSource.OPEN)
```

**WebSocket:** Similar issue with `WebSocket.OPEN`, etc.

### Dependencies
- `$app/environment` - Built-in SvelteKit module
- No new package dependencies required

### Files to Modify

**Critical (Phase 1):**
1. `src/routes/+page.svelte` - Queue dashboard
2. `src/routes/share/components/LlmHealthIndicator.svelte` - Health indicator

**Best Practices (Phase 2):**
3. `src/routes/share/+page.svelte` - Share page

**Documentation (Phase 3):**
4. `docs/SVELTEKIT_SSR_GUIDE.md` - New file

### Code Patterns Summary

#### Pattern 1: Browser API in Component State
```svelte
<script lang="ts">
  import { browser } from '$app/environment';
  import { onMount } from 'svelte';
  
  let eventSource = $state<EventSource | null>(null);
  
  onMount(() => {
    if (browser) {
      eventSource = new EventSource('/api/stream');
    }
    
    return () => {
      eventSource?.close();
    };
  });
</script>

<!-- Use numeric constants or guard in template -->
<div>Status: {eventSource?.readyState === 1 ? 'Connected' : 'Disconnected'}</div>
```

#### Pattern 2: Timers and Intervals
```svelte
<script lang="ts">
  import { onMount } from 'svelte';
  
  onMount(() => {
    const interval = setInterval(() => {
      // Polling logic
    }, 1000);
    
    return () => clearInterval(interval);
  });
</script>
```

#### Pattern 3: Auto-Processing on Mount
```svelte
<script lang="ts">
  import { onMount } from 'svelte';
  
  let hasProcessed = $state(false);
  let data = $derived(computeData());
  
  onMount(() => {
    if (shouldProcess && !hasProcessed) {
      hasProcessed = true;
      process();
    }
  });
</script>
```

## Risk Assessment

### High Priority Risks
- **SSR/Hydration mismatch**: If guards are inconsistent between server and client
  - **Mitigation**: Use numeric constants; avoid conditional rendering based on `browser`
  - **Testing**: Check for hydration warnings in console

### Medium Priority Risks
- **Regression in auto-processing**: Share page might not auto-process URLs
  - **Mitigation**: Thorough testing of share target flow
  - **Testing**: Test with Instagram share and manual URL input

- **Connection status flicker**: Status indicator might show wrong state briefly
  - **Mitigation**: Initialize with sensible defaults
  - **Testing**: Watch for visual flicker on page load

### Low Priority Risks
- **Performance**: Minimal, browser checks are fast
- **Breaking changes**: Unlikely, only fixing internal implementation

## Testing Strategy

### Unit Testing
- Not applicable - these are integration-level fixes
- Existing tests should continue to pass

### Integration Testing  
**Manual testing required:**

1. **SSR Testing:**
   ```bash
   npm run build
   npm run preview
   # Check server console for errors
   # Navigate to all pages
   ```

2. **EventSource Connection:**
   - Open queue dashboard
   - Check browser DevTools → Network → EventSource
   - Verify "Live updates" status indicator
   - Add queue item and verify real-time update

3. **Share Page:**
   - Navigate to `/share`
   - Manually enter URL → should work
   - Share from Instagram → should auto-process
   - Check no duplicate processing

4. **LLM Health:**
   - Check health indicator appears
   - Verify polling happens (check Network tab)
   - No SSR errors in console

### Edge Cases
- **Server restart** while client connected → Reconnection works
- **Network disconnection** → Graceful degradation
- **JavaScript disabled** → Progressive enhancement (no errors)
- **Multiple tabs** open → Each maintains own connection

### Hydration Testing
- Disable JavaScript after SSR
- Enable JavaScript and check hydration
- Look for console warnings:
  - "Hydration failed"
  - "The server response doesn't match the client content"

### Browser Compatibility
- Modern browsers with EventSource support
- Browsers without EventSource → Should show disconnected status (no crash)

## Success Metrics

### Must Have (Phase 1)
1. ✅ No `EventSource is not defined` errors
2. ✅ No `setInterval is not defined` errors  
3. ✅ Production build succeeds
4. ✅ SSR renders without errors
5. ✅ Live updates work in browser

### Should Have (Phase 2)
6. ✅ No `$effect` anti-patterns
7. ✅ No hydration warnings
8. ✅ Share page auto-processing works

### Nice to Have (Phase 3)
9. ✅ SSR best practices documentation
10. ✅ Inline comments explaining patterns
11. ✅ All routes tested and verified

## Anti-Patterns to Avoid

### ❌ Don't Do This

```typescript
// 1. Browser API in $derived
let data = $derived(localStorage.getItem('key')); // SSR crash!

// 2. Side effects in $effect without guard
$effect(() => {
  fetch('/api/data'); // Runs during SSR!
});

// 3. Static constants without guard
if (ws.readyState === WebSocket.OPEN) // SSR crash!

// 4. Initialization in $effect
$effect(() => {
  // Use onMount instead
  initialize();
});
```

### ✅ Do This Instead

```typescript
// 1. Load in onMount
let data = $state<string | null>(null);
onMount(() => {
  data = localStorage.getItem('key');
});

// 2. Guard browser APIs in $effect
$effect(() => {
  if (!browser) return;
  fetch('/api/data');
});

// 3. Use numeric constants or guard
if (ws.readyState === 1) // WebSocket.OPEN = 1
// OR
if (browser && ws.readyState === WebSocket.OPEN)

// 4. Initialize in onMount
onMount(() => {
  initialize();
});
```

## References

### Official Documentation
- [SvelteKit SSR](https://svelte.dev/llms-full.txt) - From llms-full.txt
- [Svelte Runes](https://svelte.dev/llms-full.txt) - $state, $derived, $effect
- [SvelteKit $app modules](https://svelte.dev/llms-full.txt) - $app/environment, $app/stores

### Our Codebase Examples
- **Good:** [PushNotificationManager.ts](src/lib/client/PushNotificationManager.ts) - Excellent SSR-safe patterns
- **Good:** [ServiceWorkerMessageHandler.ts](src/lib/client/ServiceWorkerMessageHandler.ts) - Client-only scope
- **Fix:** [+page.svelte](src/routes/+page.svelte) - EventSource needs guards
- **Fix:** [LlmHealthIndicator.svelte](src/routes/share/components/LlmHealthIndicator.svelte) - setInterval needs guard
- **Improve:** [share/+page.svelte](src/routes/share/+page.svelte) - $effect anti-pattern

### Web APIs
- [EventSource MDN](https://developer.mozilla.org/en-US/docs/Web/API/EventSource)
- [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events)

## Appendix: Complete Code Changes

### A. +page.svelte (Queue Dashboard)

**Before:**
```svelte
<script lang="ts">
  import { page } from '$app/stores';
  import { onMount, onDestroy } from 'svelte';
  
  // ... state declarations
  
  onMount(async () => {
    await loadQueueItems();
    startSSEConnection();
  });
  
  function startSSEConnection() {
    try {
      eventSource = new EventSource('/api/queue/stream');
      // ...
      eventSource.addEventListener('error', (event) => {
        // ...
        setTimeout(() => {
          if (eventSource?.readyState === EventSource.CLOSED) {
            startSSEConnection();
          }
        }, 5000);
      });
    }
  }
</script>

<!-- Template -->
<div class="w-2 h-2 rounded-full {eventSource?.readyState === EventSource.OPEN ? 'bg-green-400' : 'bg-red-400'}"></div>
```

**After:**
```svelte
<script lang="ts">
  import { page } from '$app/stores';
  import { browser } from '$app/environment';
  import { onMount, onDestroy } from 'svelte';
  
  // ... state declarations
  
  onMount(async () => {
    await loadQueueItems();
    if (browser) {
      startSSEConnection();
    }
  });
  
  function startSSEConnection() {
    if (!browser) return;
    
    try {
      eventSource = new EventSource('/api/queue/stream');
      // ...
      eventSource.addEventListener('error', (event) => {
        // ...
        setTimeout(() => {
          if (eventSource?.readyState === 2) { // CLOSED = 2
            startSSEConnection();
          }
        }, 5000);
      });
    }
  }
</script>

<!-- Template -->
<div class="w-2 h-2 rounded-full {browser && eventSource?.readyState === 1 ? 'bg-green-400' : 'bg-red-400'}"></div>
```

### B. LlmHealthIndicator.svelte

**Before:**
```svelte
<script lang="ts">
  // ...
  
  $effect(() => {
    checkHealth();
    const interval = setInterval(checkHealth, pollInterval);
    return () => clearInterval(interval);
  });
</script>
```

**After (Option 1 - Guard $effect):**
```svelte
<script lang="ts">
  import { browser } from '$app/environment';
  
  // ...
  
  $effect(() => {
    if (!browser) return;
    
    checkHealth();
    const interval = setInterval(checkHealth, pollInterval);
    return () => clearInterval(interval);
  });
</script>
```

**After (Option 2 - Use onMount - RECOMMENDED):**
```svelte
<script lang="ts">
  import { onMount } from 'svelte';
  
  // ...
  
  onMount(() => {
    checkHealth();
    const interval = setInterval(checkHealth, pollInterval);
    return () => clearInterval(interval);
  });
</script>
```

### C. share/+page.svelte

**Before:**
```svelte
<script lang="ts">
  // ...
  let targetUrl = $derived(sharedUrl || extractUrl(sharedText));
  
  $effect(() => {
    if (targetUrl && status === 'idle') {
      process();
    }
  });
</script>
```

**After:**
```svelte
<script lang="ts">
  import { onMount } from 'svelte';
  
  // ...
  let targetUrl = $derived(sharedUrl || extractUrl(sharedText));
  let hasAutoProcessed = $state(false);
  
  onMount(() => {
    if (targetUrl && status === 'idle' && !hasAutoProcessed) {
      hasAutoProcessed = true;
      process();
    }
  });
</script>
```

---

**Plan Complete - Ready for Implementation**