Initial project setup

Add project structure with package.json, source code, tests, documentation, and GitHub workflows.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

docs/TROUBLESHOOTING.md

@@ -0,0 +1,403 @@
+# YT2AI Troubleshooting Guide
+
+## Quick Fixes
+
+### "Bookmarklet doesn't work at all"
+1. **Check installation:** Ensure the bookmark URL starts with `javascript:`
+2. **Check Chrome version:** Must be Chrome 90+ on Android
+3. **Test on YouTube:** Must be on a YouTube video page
+4. **Clear browser cache:** Chrome → Settings → Privacy → Clear browsing data
+
+### "No subtitles found"
+1. **Verify subtitles exist:** Check if YouTube shows CC button
+2. **Language requirement:** Only English auto-generated subtitles supported
+3. **Try different video:** Some videos don't have auto-captions
+4. **Wait and retry:** New videos may need time for caption generation
+
+### "Loading forever" / Timeout
+1. **Check network connection:** Ensure stable internet
+2. **Try different network:** Switch between WiFi and mobile data
+3. **Retry after timeout:** Wait 30 seconds, then try again
+4. **Video length:** Very long videos (2+ hours) may timeout
+
+## Common Issues
+
+### Installation Problems
+
+#### Issue: "Bookmark won't save the JavaScript code"
+**Symptoms:** Bookmark saves but doesn't contain the full JavaScript code
+
+**Solutions:**
+1. **Copy complete code:** Ensure you copy the entire javascript: URL
+2. **Manual typing:** Some browsers truncate paste - try typing "javascript:" first
+3. **Alternative method:** Create bookmark first, then edit URL field
+4. **Check for truncation:** Bookmark URL should be several KB long
+
+**Prevention:**
+- Always verify the bookmark URL starts with `javascript:(function(){`
+- Test bookmark immediately after creating
+
+#### Issue: "Chrome says 'This type of file can harm your computer'"
+**Symptoms:** Chrome blocks bookmark creation with security warning
+
+**Solutions:**
+1. **Enable in Settings:** Chrome → Settings → Privacy and security → Site settings
+2. **Temporary bypass:** Type `chrome://settings/content/unsandboxedPlugins`
+3. **Alternative installation:** Use mobile installation method via QR code
+
+**Note:** This is expected behavior - bookmarklets are active code.
+
+### Execution Problems
+
+#### Issue: "Please navigate to a specific YouTube video page"
+**Symptoms:** Error message when tapping bookmark on YouTube
+
+**Cause:** Bookmarklet requires specific video URL format
+
+**Solutions:**
+1. **Correct URL format:** Must be `/watch?v=` or `/shorts/` format
+2. **Not on homepage:** Navigate to specific video first
+3. **Not on playlist:** Go directly to video, not playlist page
+4. **Valid video ID:** Ensure URL contains valid 11-character video ID
+
+**Valid URLs:**
+- ✅ `https://www.youtube.com/watch?v=dQw4w9WgXcQ`
+- ✅ `https://youtu.be/dQw4w9WgXcQ`
+- ✅ `https://www.youtube.com/shorts/dQw4w9WgXcQ`
+- ❌ `https://www.youtube.com` (homepage)
+- ❌ `https://www.youtube.com/playlist?list=...` (playlist)
+
+#### Issue: "This bookmarklet only works on YouTube pages"
+**Symptoms:** Error when not on YouTube
+
+**Cause:** Safety check prevents execution on non-YouTube sites
+
+**Solution:** Navigate to YouTube.com before using bookmarklet
+
+### Subtitle Extraction Issues
+
+#### Issue: "Video has subtitles but extraction fails"
+**Symptoms:** YouTube shows CC button but bookmarklet finds no subtitles
+
+**Possible Causes:**
+1. **Language mismatch:** Only English auto-generated supported
+2. **Manual captions:** User-uploaded captions not supported  
+3. **API restrictions:** Subtitle service may block certain videos
+4. **Geographic restrictions:** Some content blocked by region
+
+**Solutions:**
+1. **Check caption type:** Ensure "English (auto-generated)" is available
+2. **Try different video:** Test with known working video
+3. **Clear browser data:** Reset any API blocks
+4. **Wait and retry:** API issues often resolve automatically
+
+#### Issue: "CAPTCHA required" 
+**Symptoms:** Modal asking to complete CAPTCHA verification
+
+**Cause:** Subtitle API requires human verification (rate limiting)
+
+**Solutions:**
+1. **Complete CAPTCHA:** Follow the mobile-optimized instructions
+2. **Wait before retry:** 5-10 minutes cooldown period
+3. **Switch networks:** Different IP may avoid rate limiting
+4. **Reduce frequency:** Avoid rapid successive extractions
+
+**Prevention:**
+- Wait at least 30 seconds between extractions
+- Don't test repeatedly on same video
+- Use different videos for testing
+
+### Mobile-Specific Issues
+
+#### Issue: "Touch targets too small"
+**Symptoms:** Difficult to tap close buttons or UI elements
+
+**Cause:** UI scaling issue on high-DPI displays
+
+**Solutions:**
+1. **Browser zoom:** Adjust Chrome zoom to 100%
+2. **System display size:** Check Android display settings
+3. **Update Chrome:** Ensure latest version
+4. **Report issue:** Include device model and screen size
+
+**Temporary workaround:** Use stylus or fingernail for precision
+
+#### Issue: "Overlay doesn't fit screen"
+**Symptoms:** Content cut off or requires scrolling
+
+**Cause:** Responsive design issue with specific device
+
+**Solutions:**
+1. **Rotate device:** Try landscape orientation
+2. **Close other tabs:** Free memory for proper rendering
+3. **Restart browser:** Clear rendering cache
+4. **Check zoom level:** Ensure 100% zoom
+
+**Report needed:** Device model, screen resolution, Chrome version
+
+#### Issue: "Performance is slow"
+**Symptoms:** Long loading times, UI lag, browser unresponsive
+
+**Cause:** Memory pressure or slow network
+
+**Solutions:**
+1. **Close background apps:** Free system memory
+2. **Check available storage:** Ensure 1GB+ free space
+3. **Restart Chrome:** Clear memory leaks
+4. **Switch networks:** Test WiFi vs mobile data
+5. **Update Chrome:** Performance improvements in newer versions
+
+**Performance tips:**
+- Use on newer Android devices (8.0+)
+- Ensure good network connection
+- Close unnecessary browser tabs
+
+### Network and API Issues
+
+#### Issue: "Network timeout" errors
+**Symptoms:** Extraction fails with timeout message after 30 seconds
+
+**Cause:** Slow network or API server overload
+
+**Solutions:**
+1. **Check connection speed:** Test with speed test app
+2. **Switch networks:** Try different WiFi or mobile data
+3. **Retry later:** API servers may be temporarily overloaded
+4. **Shorter videos:** Try with <10 minute videos first
+
+**Network requirements:**
+- Minimum: 1 Mbps download speed
+- Recommended: 5+ Mbps for reliable operation
+
+#### Issue: "API service unavailable"
+**Symptoms:** Error indicating subtitle service is down
+
+**Cause:** External API (downloadyoutubesubtitles.com) temporarily unavailable
+
+**Solutions:**
+1. **Wait and retry:** Usually resolves within 1-2 hours
+2. **Check service status:** Visit downloadyoutubesubtitles.com directly
+3. **Try different videos:** Some videos may still work
+4. **Monitor announcements:** Check GitHub issues for outage reports
+
+**No user action required:** This is a temporary external service issue
+
+## Advanced Troubleshooting
+
+### Debug Mode
+
+#### Enable Debug Logging
+Add `?debug=true` to YouTube URL:
+```
+https://www.youtube.com/watch?v=dQw4w9WgXcQ&debug=true
+```
+
+Then tap bookmarklet to get detailed console logs.
+
+#### Reading Debug Output
+Look for these patterns in browser console:
+- `[YT2AI:INFO]` - Normal operation messages
+- `[YT2AI:WARN]` - Warnings that don't break functionality
+- `[YT2AI:ERROR]` - Errors that prevent operation
+- `[YT2AI:DEBUG]` - Detailed operation information
+
+#### Common Debug Messages
+```
+[YT2AI:INFO] Bookmarklet initialized
+[YT2AI:DEBUG] Environment: mobile=true, android=true
+[YT2AI:DEBUG] Video ID extracted: dQw4w9WgXcQ
+[YT2AI:ERROR] Network timeout after 30000ms
+```
+
+### Chrome Developer Tools (Advanced)
+
+#### Enable Developer Tools on Android
+1. **Enable Developer Options:** Settings → About phone → Tap Build number 7 times
+2. **Enable USB Debugging:** Settings → Developer options → USB debugging
+3. **Connect to computer:** USB cable + Chrome on desktop
+4. **Inspect device:** Chrome → chrome://inspect → Find your device
+
+#### Useful Developer Tools Tabs
+- **Console:** View JavaScript errors and debug messages
+- **Network:** Monitor API requests and responses
+- **Memory:** Check for memory leaks or high usage
+- **Performance:** Profile execution timing
+
+### Memory Investigation
+
+#### Check Memory Usage
+```javascript
+// In console:
+console.log('Memory:', performance.memory);
+console.log('State:', window.__YT2AI__?.stateManager.getState());
+```
+
+#### Memory Warning Signs
+- `usedJSHeapSize` > 50MB
+- Browser becomes unresponsive
+- Other tabs crash or reload
+- Android shows "Chrome is using too much memory"
+
+#### Memory Solutions
+1. **Force cleanup:** Reload YouTube page
+2. **Restart Chrome:** Force close and reopen
+3. **Restart device:** Clear all memory
+4. **Free storage:** Delete unused apps/files
+
+## Error Codes Reference
+
+### YT2AI Error Types
+
+#### E001: Invalid YouTube Context
+- **Message:** "This bookmarklet only works on YouTube pages"
+- **Cause:** Not on youtube.com domain
+- **Solution:** Navigate to YouTube first
+
+#### E002: No Video ID Found
+- **Message:** "Please navigate to a specific YouTube video page"  
+- **Cause:** URL doesn't contain valid video ID
+- **Solution:** Go to specific video page
+
+#### E003: Network Timeout
+- **Message:** "Network timeout after 30000ms"
+- **Cause:** Slow connection or API overload
+- **Solution:** Check network, retry later
+
+#### E004: No Subtitles Available
+- **Message:** "No English auto-generated subtitles found"
+- **Cause:** Video lacks auto-captions
+- **Solution:** Try different video
+
+#### E005: API Service Error
+- **Message:** "Subtitle extraction service temporarily unavailable"
+- **Cause:** External API down
+- **Solution:** Wait and retry
+
+#### E006: CAPTCHA Required
+- **Message:** "Human verification required"
+- **Cause:** Rate limiting triggered
+- **Solution:** Complete CAPTCHA, reduce usage frequency
+
+#### E007: Memory Pressure
+- **Message:** "Insufficient memory to complete operation"
+- **Cause:** Low device memory
+- **Solution:** Close apps, restart browser
+
+## Device-Specific Issues
+
+### Samsung Devices
+
+#### Issue: "Bookmarklet won't execute"
+**Cause:** Samsung Internet interference with Chrome
+
+**Solutions:**
+1. **Set Chrome as default:** Settings → Apps → Default apps → Browser
+2. **Disable Samsung Internet:** If not needed
+3. **Clear app preferences:** Reset default handlers
+
+#### Issue: "UI elements too small"
+**Cause:** Samsung's display scaling
+
+**Solutions:**
+1. **Adjust display size:** Settings → Display → Screen zoom
+2. **Font size:** Settings → Display → Font size and style
+3. **Chrome accessibility:** Chrome → Settings → Accessibility
+
+### Pixel/Nexus Devices
+
+Generally excellent compatibility - report any issues as bugs.
+
+### OnePlus Devices
+
+#### Issue: "Performance lag"
+**Cause:** OxygenOS battery optimization
+
+**Solutions:**
+1. **Battery optimization:** Settings → Battery → Battery optimization → Chrome → Don't optimize
+2. **Background app limits:** Settings → Privacy → Permission manager → Special app access
+
+### Huawei Devices (with Google Services)
+
+#### Issue: "Network connectivity issues"
+**Cause:** Huawei network optimization
+
+**Solutions:**
+1. **Data saver:** Turn off data saver in network settings
+2. **App network permissions:** Ensure Chrome has unrestricted network access
+
+## Reporting Issues
+
+### Before Reporting
+1. **Try troubleshooting steps** above
+2. **Test with debug mode** enabled
+3. **Try different video** to isolate issue
+4. **Check recent similar reports** in GitHub issues
+
+### What to Include
+
+#### Required Information
+- **Device:** Make, model, Android version
+- **Chrome version:** Chrome → Settings → About Chrome
+- **Network type:** WiFi, 4G, 5G, etc.
+- **Video URL:** That reproduces the issue
+- **Error message:** Exact text if any
+- **Steps to reproduce:** Numbered list
+
+#### Helpful Additional Info
+- **Debug console output:** Copy from Developer Tools
+- **Screenshots:** Of error messages or UI issues
+- **Network speed:** From speed test
+- **Multiple devices:** Does issue occur on other devices?
+
+#### Example Report Template
+```
+**Device:** Samsung Galaxy S21, Android 12
+**Chrome Version:** 91.0.4472.120
+**Network:** WiFi, ~50 Mbps
+**Issue:** Overlay appears but extraction never completes
+
+**Steps:**
+1. Navigate to https://www.youtube.com/watch?v=dQw4w9WgXcQ
+2. Tap YT2AI bookmark
+3. See "YT2AI Ready!" message
+4. Loading overlay appears but never finishes
+5. After 30 seconds, no error message appears
+
+**Console Output:**
+[Paste debug console output here]
+
+**Additional Notes:**
+Works fine on different video (tested with jNQXAC9IVRw)
+```
+
+### Where to Report
+
+#### GitHub Issues
+- **Bugs:** Use bug report template
+- **Feature requests:** Use feature request template
+- **Questions:** Use discussion forum
+
+#### Community Support
+- **GitHub Discussions:** General questions and usage help
+- **Reddit:** r/bookmarklets community
+- **Stack Overflow:** Tag with `bookmarklet` and `youtube`
+
+## Prevention Tips
+
+### Best Practices
+1. **Test installation:** Always verify bookmark works after creating
+2. **Use on good network:** WiFi preferred for initial tests
+3. **Start with short videos:** <5 minutes for first tests
+4. **Keep Chrome updated:** Latest version has fewest issues
+5. **Monitor memory:** Close unnecessary tabs during use
+
+### Avoid Common Mistakes
+1. **Don't spam-click:** Wait for completion before retrying
+2. **Don't test on music videos:** Often lack subtitles
+3. **Don't use on very new videos:** Captions take time to generate
+4. **Don't use with VPN:** Can trigger API rate limiting
+5. **Don't use in private browsing:** Some features may not work
+
+---
+
+**Still having issues?** Open a [GitHub issue](https://github.com/yt2ai/yt2ai-bookmarklet/issues) with detailed information.