soundwave/docs/OFFLINE_QUICK_START.md

# 🚀 Quick Start: Offline Playlists

## For Users

### Download Playlist for Offline Use:
1. Navigate to any playlist
2. Scroll to "Cache for Offline" card
3. Tap **"Make Available Offline"**
4. Wait for download to complete
5. Green checkmark = Ready! 🎉

### Play Offline:
1. Enable airplane mode
2. Open SoundWave
3. Navigate to cached playlist
4. Tap Play - Works instantly! 📱

### Manage Storage:
1. Tap **"Offline"** in sidebar (PWA badge)
2. View all cached playlists
3. Remove individual playlists or clear all
4. See storage usage at a glance

---

## For Developers

### Check if Playlist is Cached:
```typescript
import { offlineStorage } from '../utils/offlineStorage';

const playlist = await offlineStorage.getPlaylist(id);
if (playlist?.offline) {
  console.log('Available offline!');
}
```

### Cache a Playlist:
```typescript
import { usePWA } from '../context/PWAContext';

const { cachePlaylist } = usePWA();
const audioUrls = tracks.map(t => `/api/audio/${t.youtube_id}/download/`);

await cachePlaylist(playlistId, audioUrls);
await offlineStorage.savePlaylist({...playlist, offline: true});
```

### Remove from Cache:
```typescript
const { removePlaylistCache } = usePWA();

await removePlaylistCache(playlistId, audioUrls);
await offlineStorage.removePlaylist(id);
```

---

## New Routes

- `/offline` - Offline storage management page
- All existing routes unchanged

---

## Security ✅

- ✅ Authentication required for all endpoints
- ✅ User isolation enforced (owner-based filtering)
- ✅ No cross-user data access
- ✅ Service Worker respects authentication
- ✅ No route conflicts

---

## Testing

### Online:
```bash
# Navigate to playlist, click "Make Available Offline"
# Check sidebar badge shows "Offline" menu
# Visit /offline to see cached playlists
```

### Offline:
```bash
# Enable airplane mode in browser DevTools
# Navigate to cached playlist
# Verify playback works
# Check offline warning appears for uncached content
```

---

## Browser DevTools Testing

### Service Worker:
```
Application → Service Workers → soundwave-v1 (Active)
```

### Cache Storage:
```
Application → Cache Storage
- soundwave-audio-v1 (audio files)
- soundwave-api-v1 (API responses)
```

### IndexedDB:
```
Application → IndexedDB → soundwave-offline
- playlists (cached metadata)
```

---

## Storage Limits

- **Desktop**: ~50% of available disk space
- **Mobile**: ~50% of available storage
- **Minimum**: 10 MB per origin
- **Typical**: Several GB available

---

## Known Behaviors

1. **Storage is per-browser** - Not synced across devices
2. **Caching requires network** - Must be online to download
3. **Authentication required** - Token must be valid
4. **Browser may evict** - On low storage, browser clears cache
5. **HTTPS required** - Service Workers need secure context

---

## Files Changed

### New:
- `frontend/src/pages/OfflineManagerPage.tsx`
- `docs/OFFLINE_FEATURE_COMPLETE.md`

### Modified:
- `frontend/src/pages/PlaylistDetailPage.tsx`
- `frontend/src/pages/PlaylistsPage.tsx`
- `frontend/src/App.tsx`
- `frontend/src/components/Sidebar.tsx`
- `frontend/public/service-worker.js`

---

## No Breaking Changes

✅ All existing features work as before  
✅ Backward compatible  
✅ Progressive enhancement  
✅ Graceful degradation  

---

Ready to use! 🎉