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

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:

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:

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:

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