binect-chrome/DOWNLOAD_DETECTION_FIXES.md

# Download Detection Debugging & Fixes

## Summary

I've added comprehensive debugging and a fallback mechanism to help diagnose and work around download detection issues.

## Changes Made

### 1. **Comprehensive Debug Logging**

**Service Worker (src/background/service-worker.ts):**
- All events now log with `[Service Worker]` prefix
- Shows when service worker loads/reloads
- Logs PDF detection callbacks
- Logs message handling from popup

**PDF Detector (src/utils/pdf-detector.ts):**
- All download events logged with `[PDF Detector]` prefix
- Shows download state changes (in_progress → complete)
- Logs download item details (filename, mime, state, url)
- Confirms when PDF is detected vs. ignored

**Popup (src/popup/popup.ts):**
- All PDF loading operations logged with `[Popup]` prefix
- Shows detection priority: tab viewer → background → fallback
- Logs results of each detection method

### 2. **Fallback Mechanism**

**New function: `checkRecentDownloads()` (src/popup/popup.ts:254-298)**
- Directly queries Chrome's downloads API for recent PDFs
- Checks last 20 downloads
- Finds most recent completed PDF
- **Works even if service worker missed the download event**

**PDF Detection Priority:**
1. Current tab (PDF viewer) - NEW
2. Background service worker (download event listener)
3. **Recent downloads fallback** - NEW
4. No PDF detected

This triple-layer approach ensures PDFs are detected even if the service worker is sleeping.

## How to Debug

### Step 1: Reload Extension
```bash
npm run build
```
Then reload at `chrome://extensions/`

### Step 2: Open Consoles

**Service Worker Console:**
1. Go to `chrome://extensions/`
2. Click "service worker" link under BinectChrome
3. **Keep this open while testing**

**Popup Console:**
1. Click the extension icon
2. Right-click inside popup → "Inspect"
3. View console

### Step 3: Download a Test PDF

**Test URL:**
```
https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
```

**Method 1: Direct download**
- Right-click link → "Save link as..."
- Save to Downloads

**Method 2: View in browser**
- Paste URL in address bar
- Let Chrome open it in viewer
- Click extension icon

### Step 4: Check Logs

**Expected Service Worker logs:**
```
[Service Worker] ===== BinectChrome service worker loaded =====
[Service Worker] Initializing PDF detection...
[PDF Detector] Starting PDF detection, registering download listener
[PDF Detector] Listener registered successfully

# When download completes:
[PDF Detector] Download changed: {id: X, state: {...}, stateValue: "complete"}
[PDF Detector] Download complete, searching for item: X
[PDF Detector] Search results: 1 items
[PDF Detector] Download item: {id: X, filename: "dummy.pdf", mime: "application/pdf", ...}
[PDF Detector] PDF detected!
[Service Worker] PDF DETECTED CALLBACK: dummy.pdf
[Service Worker] Badge updated, PDF stored in memory
```

**Expected Popup logs:**
```
[Popup] Loading last PDF...
[Popup] No PDF in current tab, checking background script...
[Service Worker] Message received: getLastPDF
[Service Worker] Returning last PDF: dummy.pdf
[Popup] Background returned PDF: dummy.pdf
```

**If service worker missed it (fallback):**
```
[Popup] Loading last PDF...
[Popup] No PDF in current tab, checking background script...
[Service Worker] Message received: getLastPDF
[Service Worker] Returning last PDF: none
[Popup] Background has no PDF, checking recent downloads as fallback...
[Popup] Checked recent downloads: 15 items
[Popup] Found recent PDF: dummy.pdf
```

## Common Issues & Solutions

### Issue 1: No Service Worker Logs

**Symptom:** Service worker console is empty or shows "Inactive"

**Solution:**
- Click the extension icon (wakes it up)
- Or go to `chrome://serviceworker-internals/` and click "Start"
- Check for registration errors

### Issue 2: Service Worker Not Waking for Downloads

**Symptom:** Download completes but no `[PDF Detector]` logs appear

**This is the main issue with Manifest V3 service workers!**

**Diagnosis:**
1. Open service worker console
2. Download a PDF
3. Watch if service worker console gets new logs

**If no logs:** Service worker didn't wake up for the download event

**Workaround:** The fallback mechanism handles this! When you open the popup, it checks recent downloads directly.

### Issue 3: Badge Not Updating

**Symptom:** PDF downloads but badge stays empty

**Cause:** Service worker detected PDF but couldn't update badge (possibly terminated)

**Solution:** The fallback still works - open popup to see the PDF

### Issue 4: PDF Shows in Popup But Disappears

**Symptom:** PDF shows up, but after a few minutes it's gone

**Cause:** Service worker memory is ephemeral - when it terminates, `lastDetectedPDF` is lost

**Solution:** The fallback mechanism re-fetches from recent downloads each time popup opens

## Testing Checklist

- [ ] Build extension: `npm run build`
- [ ] Reload extension at `chrome://extensions/`
- [ ] Open service worker console
- [ ] Download test PDF (right-click → Save link as)
- [ ] Check service worker logs for detection
- [ ] Check if badge shows "1"
- [ ] Open popup - should show PDF
- [ ] Wait 2 minutes (service worker sleeps)
- [ ] Download another PDF
- [ ] Open popup - should show PDF (even if service worker missed it)
- [ ] Open PDF in browser tab (view, don't download)
- [ ] Open popup - should detect tab viewer

## Known Limitations

### 1. Service Worker Lifecycle (Manifest V3)
Service workers shut down after 30 seconds of inactivity. This is by design in Manifest V3.

**Impact:**
- Download event listener may not fire if service worker is sleeping
- Badge may not update immediately after download
- `lastDetectedPDF` is lost when service worker terminates

**Mitigation:**
- Fallback mechanism checks recent downloads
- Works reliably despite service worker sleep
- Badge updates when popup opens

### 2. File URLs
Chrome extensions can't access `file://` URLs by default.

**Impact:** If PDF is downloaded and opened from disk, can't re-fetch for upload

**Solution:** Use the original download URL (which we store)

### 3. Authenticated Downloads
Some PDFs require authentication cookies.

**Impact:** Re-fetching PDF may fail if session expired

**Solution:** `fetchPDFBytes()` uses `credentials: 'include'` to send cookies

## Advanced Debugging

### Manual Download Check
Run in Service Worker console:
```javascript
chrome.downloads.search({ limit: 10, orderBy: ['-startTime'] }, (items) => {
  console.log('Recent downloads:');
  items.forEach(item => {
    const isPDF = item.filename.toLowerCase().endsWith('.pdf') ||
                  item.mime === 'application/pdf';
    console.log(`  ${item.filename} - PDF: ${isPDF} - State: ${item.state}`);
  });
});
```

### Test Download Listener
Run in Service Worker console:
```javascript
chrome.downloads.download({
  url: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf',
  filename: 'test-download.pdf'
}, (downloadId) => {
  console.log('Started download:', downloadId);
});
```

Watch for `[PDF Detector]` logs.

### Check Permissions
Run in Service Worker console:
```javascript
chrome.permissions.contains({ permissions: ['downloads'] }, (result) => {
  console.log('Has downloads permission:', result);
});
```

## Recommended Testing Flow

**For Development:**
1. Use PDF viewer detection (open PDF in tab)
2. This bypasses download detection entirely
3. Most reliable for testing API integration

**For Download Detection Testing:**
1. Open both service worker and popup consoles
2. Download a PDF
3. Watch logs in real-time
4. Verify fallback works even if service worker missed it

## Next Steps

**If download detection is still unreliable:**

### Option A: Accept Viewer Detection as Primary
- PDF viewer detection works reliably
- Download detection becomes secondary
- Users can open PDFs in browser instead of downloading

### Option B: Persist Detected PDFs
- Store detected PDFs in `chrome.storage` instead of memory
- Survives service worker restarts
- Requires storage cleanup logic

### Option C: Poll Downloads Periodically
- Set up an alarm to check recent downloads every minute
- More resource intensive
- Very reliable

## Files Changed

1. `src/background/service-worker.ts` - Added debug logging
2. `src/utils/pdf-detector.ts` - Added debug logging
3. `src/popup/popup.ts` - Added debug logging and fallback mechanism
4. `DEBUG_DOWNLOAD_DETECTION.md` - Comprehensive debugging guide
5. `DOWNLOAD_DETECTION_FIXES.md` - This file

## Support

If download detection still doesn't work:
1. Follow `DEBUG_DOWNLOAD_DETECTION.md`
2. Export console logs from both service worker and popup
3. Include Chrome version: `chrome://version/`
4. Report to bernd.worsch@binect.de

## Workaround

**The PDF viewer detection is fully functional and reliable!**

Instead of relying on download detection:
1. Open PDFs in Chrome (paste URL in address bar)
2. Click extension icon
3. PDF is detected from current tab
4. Send to Binect

This approach:
- ✅ Always works
- ✅ No service worker timing issues
- ✅ Better user experience (no downloads folder clutter)
- ✅ Easier to test API integration