feat: add offline mode foundation with auto-download liked tracks (#610)

* feat: add offline mode foundation with auto-download liked tracks

- add storage.ts with Cache API + IndexedDB for offline audio storage
- add GET /audio/{file_id}/url endpoint returning direct R2 URLs for caching
- add auto_download_liked preference (stored in localStorage, device-specific)
- add settings toggle that bulk-downloads all liked tracks when enabled
- auto-download new tracks when liking (if preference enabled)
- Player component checks for cached audio before streaming
- fix TLFM reauth notice to show correct message

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

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

* fix: require auth for audio URL endpoint

adds authentication to GET /audio/{file_id}/url to prevent
unauthenticated enumeration of audio URLs.

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

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

* fix: improve IndexedDB robustness

- close database connections after each operation (fixes connection leak)
- deduplicate concurrent downloads using in-flight promise map
- verify cache entry exists in isDownloaded() and clean up stale metadata

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

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

---------

Co-authored-by: Claude Opus 4.5 <[e-mail]>

backend/src/backend/api/audio.py

···
 """audio streaming endpoint."""
 
 import logfire
-from fastapi import APIRouter, HTTPException
+from fastapi import APIRouter, Depends, HTTPException
 from fastapi.responses import RedirectResponse
+from pydantic import BaseModel
 from sqlalchemy import func, select
 
+from backend._internal import Session, require_auth
 from backend.models import Track
 from backend.storage import storage
 from backend.utilities.database import db_session
 
 router = APIRouter(prefix="/audio", tags=["audio"])
+
+
+class AudioUrlResponse(BaseModel):
+    """response containing direct R2 URL for offline caching."""
+
+    url: str
+    file_id: str
+    file_type: str | None
 
 
 @router.get("/{file_id}")
···
     if not url:
         raise HTTPException(status_code=404, detail="audio file not found")
     return RedirectResponse(url=url)
+
+
[e-mail]("/{file_id}/url")
+async def get_audio_url(
+    file_id: str,
+    session: Session = Depends(require_auth),
+) -> AudioUrlResponse:
+    """return direct R2 URL for offline caching.
+
+    unlike the streaming endpoint which returns a 307 redirect,
+    this returns the URL as JSON so the frontend can fetch and
+    cache the audio directly via the Cache API.
+
+    used for offline mode - frontend fetches from R2 and stores locally.
+    """
+    async with db_session() as db:
+        result = await db.execute(
+            select(Track.r2_url, Track.file_type)
+            .where(Track.file_id == file_id)
+            .order_by(Track.r2_url.is_not(None).desc(), Track.created_at.desc())
+            .limit(1)
+        )
+        track_data = result.first()
+
+        if not track_data:
+            raise HTTPException(status_code=404, detail="audio file not found")
+
+        r2_url, file_type = track_data
+
+    # if we have a cached r2_url, return it
+    if r2_url and r2_url.startswith("http"):
+        return AudioUrlResponse(url=r2_url, file_id=file_id, file_type=file_type)
+
+    # otherwise, resolve it
+    url = await storage.get_url(file_id, file_type="audio", extension=file_type)
+    if not url:
+        raise HTTPException(status_code=404, detail="audio file not found")
+
+    return AudioUrlResponse(url=url, file_id=file_id, file_type=file_type)

backend/tests/api/test_audio.py

···
 from httpx import ASGITransport, AsyncClient
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from backend._internal import Session, require_auth
 from backend.main import app
 from backend.models import Artist, Track
+
+
[e-mail]
+def mock_session() -> Session:
+    """create a mock session for authenticated endpoints."""
+    return Session(
+        session_id="test-session-id",
+        did="did:plc:testuser123",
+        handle="testuser.bsky.social",
+        oauth_session={
+            "access_token": "test-access-token",
+            "refresh_token": "test-refresh-token",
+            "dpop_key": {},
+        },
+    )
 
 
 @pytest.fixture
···
 
     assert response.status_code == 404
     assert response.json()["detail"] == "audio file not found"
+
+
+# tests for /audio/{file_id}/url endpoint (offline caching, requires auth)
+
+
+async def test_get_audio_url_with_cached_url(
+    test_app: FastAPI, test_track_with_r2_url: Track, mock_session: Session
+):
+    """test that /url endpoint returns cached r2_url as JSON."""
+    mock_storage = MagicMock()
+    mock_storage.get_url = AsyncMock()
+
+    test_app.dependency_overrides[require_auth] = lambda: mock_session
+
+    try:
+        with patch("backend.api.audio.storage", mock_storage):
+            async with AsyncClient(
+                transport=ASGITransport(app=test_app), base_url="http://test"
+            ) as client:
+                response = await client.get(
+                    f"/audio/{test_track_with_r2_url.file_id}/url"
+                )
+
+        assert response.status_code == 200
+        data = response.json()
+        assert data["url"] == test_track_with_r2_url.r2_url
+        assert data["file_id"] == test_track_with_r2_url.file_id
+        assert data["file_type"] == test_track_with_r2_url.file_type
+        # should NOT call get_url when r2_url is cached
+        mock_storage.get_url.assert_not_called()
+    finally:
+        test_app.dependency_overrides.pop(require_auth, None)
+
+
+async def test_get_audio_url_without_cached_url(
+    test_app: FastAPI, test_track_without_r2_url: Track, mock_session: Session
+):
+    """test that /url endpoint calls storage.get_url when r2_url is None."""
+    expected_url = "https://cdn.example.com/audio/test456.flac"
+
+    mock_storage = MagicMock()
+    mock_storage.get_url = AsyncMock(return_value=expected_url)
+
+    test_app.dependency_overrides[require_auth] = lambda: mock_session
+
+    try:
+        with patch("backend.api.audio.storage", mock_storage):
+            async with AsyncClient(
+                transport=ASGITransport(app=test_app), base_url="http://test"
+            ) as client:
+                response = await client.get(
+                    f"/audio/{test_track_without_r2_url.file_id}/url"
+                )
+
+        assert response.status_code == 200
+        data = response.json()
+        assert data["url"] == expected_url
+        assert data["file_id"] == test_track_without_r2_url.file_id
+        assert data["file_type"] == test_track_without_r2_url.file_type
+
+        mock_storage.get_url.assert_called_once_with(
+            test_track_without_r2_url.file_id,
+            file_type="audio",
+            extension=test_track_without_r2_url.file_type,
+        )
+    finally:
+        test_app.dependency_overrides.pop(require_auth, None)
+
+
+async def test_get_audio_url_not_found(test_app: FastAPI, mock_session: Session):
+    """test that /url endpoint returns 404 for nonexistent track."""
+    test_app.dependency_overrides[require_auth] = lambda: mock_session
+
+    try:
+        async with AsyncClient(
+            transport=ASGITransport(app=test_app), base_url="http://test"
+        ) as client:
+            response = await client.get("/audio/nonexistent/url")
+
+        assert response.status_code == 404
+        assert response.json()["detail"] == "audio file not found"
+    finally:
+        test_app.dependency_overrides.pop(require_auth, None)
+
+
+async def test_get_audio_url_storage_returns_none(
+    test_app: FastAPI, test_track_without_r2_url: Track, mock_session: Session
+):
+    """test that /url endpoint returns 404 when storage.get_url returns None."""
+    mock_storage = MagicMock()
+    mock_storage.get_url = AsyncMock(return_value=None)
+
+    test_app.dependency_overrides[require_auth] = lambda: mock_session
+
+    try:
+        with patch("backend.api.audio.storage", mock_storage):
+            async with AsyncClient(
+                transport=ASGITransport(app=test_app), base_url="http://test"
+            ) as client:
+                response = await client.get(
+                    f"/audio/{test_track_without_r2_url.file_id}/url"
+                )
+
+        assert response.status_code == 404
+        assert response.json()["detail"] == "audio file not found"
+    finally:
+        test_app.dependency_overrides.pop(require_auth, None)
+
+
+async def test_get_audio_url_requires_auth(test_app: FastAPI):
+    """test that /url endpoint returns 401 without authentication."""
+    # ensure no auth override
+    test_app.dependency_overrides.pop(require_auth, None)
+
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.get("/audio/somefile/url")
+
+    assert response.status_code == 401

frontend/src/lib/components/AddToMenu.svelte

···
 		trackTitle: string;
 		trackUri?: string;
 		trackCid?: string;
+		fileId?: string;
 		initialLiked?: boolean;
 		disabled?: boolean;
 		disabledReason?: string;
···
 		trackTitle,
 		trackUri,
 		trackCid,
+		fileId,
 		initialLiked = false,
 		disabled = false,
 		disabledReason,
···
 
 		try {
 			const success = liked
-				? await likeTrack(trackId)
+				? await likeTrack(trackId, fileId)
 				: await unlikeTrack(trackId);
 
 			if (!success) {

frontend/src/lib/components/LikeButton.svelte

···
 	interface Props {
 		trackId: number;
 		trackTitle: string;
+		fileId?: string;
 		initialLiked?: boolean;
 		disabled?: boolean;
 		disabledReason?: string;
 		onLikeChange?: (_liked: boolean) => void;
 	}
 
-	let { trackId, trackTitle, initialLiked = false, disabled = false, disabledReason, onLikeChange }: Props = $props();
+	let { trackId, trackTitle, fileId, initialLiked = false, disabled = false, disabledReason, onLikeChange }: Props = $props();
 
 	let liked = $state(initialLiked);
 	let loading = $state(false);
···
 
 		try {
 			const success = liked
-				? await likeTrack(trackId)
+				? await likeTrack(trackId, fileId)
 				: await unlikeTrack(trackId);
 
 			if (!success) {

frontend/src/lib/components/TrackActionsMenu.svelte

···
 		trackTitle: string;
 		trackUri?: string;
 		trackCid?: string;
+		fileId?: string;
 		initialLiked: boolean;
 		shareUrl: string;
 		onQueue: () => void;
···
 		trackTitle,
 		trackUri,
 		trackCid,
+		fileId,
 		initialLiked,
 		shareUrl,
 		onQueue,
···
 
 		try {
 			const success = liked
-				? await likeTrack(trackId)
+				? await likeTrack(trackId, fileId)
 				: await unlikeTrack(trackId);
 
 			if (!success) {

frontend/src/lib/components/TrackItem.svelte

···
 					trackTitle={track.title}
 					trackUri={track.atproto_record_uri}
 					trackCid={track.atproto_record_cid}
+					fileId={track.file_id}
 					initialLiked={track.is_liked || false}
 					disabled={!track.atproto_record_uri}
 					disabledReason={!track.atproto_record_uri ? "track's record is unavailable" : undefined}
···
 				trackTitle={track.title}
 				trackUri={track.atproto_record_uri}
 				trackCid={track.atproto_record_cid}
+				fileId={track.file_id}
 				initialLiked={track.is_liked || false}
 				shareUrl={shareUrl}
 				onQueue={handleQueue}
···
 		background: var(--bg-tertiary);
 		border-color: var(--accent);
 		color: var(--accent);
+	}
+
+	.action-button:disabled {
+		opacity: 0.6;
+		cursor: not-allowed;
 	}
 
 	.action-button svg {

frontend/src/lib/components/player/Player.svelte

···
 	import { moderation } from '$lib/moderation.svelte';
 	import { preferences } from '$lib/preferences.svelte';
 	import { API_URL } from '$lib/config';
+	import { getCachedAudioUrl } from '$lib/storage';
 	import { onMount } from 'svelte';
 	import { page } from '$app/stores';
 	import TrackInfo from './TrackInfo.svelte';
···
 		);
 	});
 
+	// get audio source URL - checks local cache first, falls back to network
+	async function getAudioSource(file_id: string): Promise<string> {
+		try {
+			const cachedUrl = await getCachedAudioUrl(file_id);
+			if (cachedUrl) {
+				return cachedUrl;
+			}
+		} catch (err) {
+			console.error('failed to check audio cache:', err);
+		}
+		return `${API_URL}/audio/${file_id}`;
+	}
+
+	// track blob URLs we've created so we can revoke them
+	let currentBlobUrl: string | null = null;
+
+	function cleanupBlobUrl() {
+		if (currentBlobUrl) {
+			URL.revokeObjectURL(currentBlobUrl);
+			currentBlobUrl = null;
+		}
+	}
+
 	// handle track changes - load new audio when track changes
 	let previousTrackId = $state<number | null>(null);
 	let isLoadingTrack = $state(false);
···
 
 		// only load new track if it actually changed
 		if (player.currentTrack.id !== previousTrackId) {
-			previousTrackId = player.currentTrack.id;
+			const trackToLoad = player.currentTrack;
+			previousTrackId = trackToLoad.id;
 			player.resetPlayCount();
 			isLoadingTrack = true;
 
-			player.audioElement.src = `${API_URL}/audio/${player.currentTrack.file_id}`;
-			player.audioElement.load();
+			// cleanup previous blob URL before loading new track
+			cleanupBlobUrl();
 
-			// wait for audio to be ready before allowing playback
-			player.audioElement.addEventListener('loadeddata', () => {
-				isLoadingTrack = false;
-			}, { once: true });
+			// async: get audio source (cached or network)
+			getAudioSource(trackToLoad.file_id).then((src) => {
+				// check if track is still current (user may have changed tracks during await)
+				if (player.currentTrack?.id !== trackToLoad.id || !player.audioElement) {
+					// track changed, cleanup if we created a blob URL
+					if (src.startsWith('blob:')) {
+						URL.revokeObjectURL(src);
+					}
+					return;
+				}
+
+				// track if this is a blob URL so we can revoke it later
+				if (src.startsWith('blob:')) {
+					currentBlobUrl = src;
+				}
+
+				player.audioElement.src = src;
+				player.audioElement.load();
+
+				// wait for audio to be ready before allowing playback
+				player.audioElement.addEventListener(
+					'loadeddata',
+					() => {
+						isLoadingTrack = false;
+					},
+					{ once: true }
+				);
+			});
 		}
 	});
 

frontend/src/lib/preferences.svelte.ts

···
 	show_liked_on_profile: boolean;
 	support_url: string | null;
 	ui_settings: UiSettings;
+	auto_download_liked: boolean;
 }
 
 const DEFAULT_PREFERENCES: Preferences = {
···
 	show_sensitive_artwork: false,
 	show_liked_on_profile: false,
 	support_url: null,
-	ui_settings: {}
+	ui_settings: {},
+	auto_download_liked: false
 };
 
 class PreferencesManager {
···
 		return this.data?.ui_settings ?? DEFAULT_PREFERENCES.ui_settings;
 	}
 
+	get autoDownloadLiked(): boolean {
+		return this.data?.auto_download_liked ?? DEFAULT_PREFERENCES.auto_download_liked;
+	}
+
+	setAutoDownloadLiked(enabled: boolean): void {
+		if (browser) {
+			localStorage.setItem('autoDownloadLiked', enabled ? '1' : '0');
+		}
+		if (this.data) {
+			this.data = { ...this.data, auto_download_liked: enabled };
+		}
+	}
+
 	setTheme(theme: Theme): void {
 		if (browser) {
 			localStorage.setItem('theme', theme);
···
 			});
 			if (response.ok) {
 				const data = await response.json();
+				// auto_download_liked is stored locally since it's device-specific
+				const storedAutoDownload = localStorage.getItem('autoDownloadLiked') === '1';
 				this.data = {
 					accent_color: data.accent_color ?? null,
 					auto_advance: data.auto_advance ?? DEFAULT_PREFERENCES.auto_advance,
···
 					show_sensitive_artwork: data.show_sensitive_artwork ?? DEFAULT_PREFERENCES.show_sensitive_artwork,
 					show_liked_on_profile: data.show_liked_on_profile ?? DEFAULT_PREFERENCES.show_liked_on_profile,
 					support_url: data.support_url ?? DEFAULT_PREFERENCES.support_url,
-					ui_settings: data.ui_settings ?? DEFAULT_PREFERENCES.ui_settings
+					ui_settings: data.ui_settings ?? DEFAULT_PREFERENCES.ui_settings,
+					auto_download_liked: storedAutoDownload
 				};
 			} else {
-				this.data = { ...DEFAULT_PREFERENCES, theme: currentTheme };
+				const storedAutoDownload = localStorage.getItem('autoDownloadLiked') === '1';
+				this.data = { ...DEFAULT_PREFERENCES, theme: currentTheme, auto_download_liked: storedAutoDownload };
 			}
 			// apply theme after fetching
 			if (browser) {

frontend/src/lib/storage.ts

···
+/**
+ * offline storage layer for plyr.fm
+ *
+ * uses Cache API for audio bytes (large binary files, quota-managed)
+ * uses IndexedDB for download metadata (queryable, persistent)
+ *
+ * this module bypasses the service worker entirely - we fetch directly
+ * from R2 and store in Cache API from the main thread. this avoids
+ * iOS PWA issues with service worker + redirects + range requests.
+ */
+
+/* eslint-disable no-undef */
+
+import { API_URL } from './config';
+
+// cache name for audio files
+const AUDIO_CACHE_NAME = 'plyr-audio-v1';
+
+// IndexedDB config
+const DB_NAME = 'plyr-offline';
+const DB_VERSION = 1;
+const DOWNLOADS_STORE = 'downloads';
+
+// in-flight downloads (prevents duplicate concurrent downloads)
+const activeDownloads = new Map<string, Promise<void>>();
+
+export interface DownloadRecord {
+	file_id: string;
+	size: number;
+	downloaded_at: number;
+	file_type: string | null;
+}
+
+// IndexedDB helpers
+
+function openDatabase(): Promise<IDBDatabase> {
+	return new Promise((resolve, reject) => {
+		const request = indexedDB.open(DB_NAME, DB_VERSION);
+
+		request.onerror = () => reject(request.error);
+		request.onsuccess = () => resolve(request.result);
+
+		request.onupgradeneeded = (event) => {
+			const db = (event.target as IDBOpenDBRequest).result;
+
+			if (!db.objectStoreNames.contains(DOWNLOADS_STORE)) {
+				const store = db.createObjectStore(DOWNLOADS_STORE, { keyPath: 'file_id' });
+				store.createIndex('downloaded_at', 'downloaded_at', { unique: false });
+			}
+		};
+	});
+}
+
+/**
+ * run a transaction against IndexedDB, properly closing the connection after
+ */
+async function withDatabase<T>(
+	mode: IDBTransactionMode,
+	operation: (store: IDBObjectStore) => IDBRequest<T>
+): Promise<T> {
+	const db = await openDatabase();
+	try {
+		return await new Promise<T>((resolve, reject) => {
+			const tx = db.transaction(DOWNLOADS_STORE, mode);
+			const store = tx.objectStore(DOWNLOADS_STORE);
+			const request = operation(store);
+
+			request.onerror = () => reject(request.error);
+			request.onsuccess = () => resolve(request.result);
+		});
+	} finally {
+		db.close();
+	}
+}
+
+async function getDownloadRecord(file_id: string): Promise<DownloadRecord | null> {
+	const result = await withDatabase('readonly', (store) => store.get(file_id));
+	return result || null;
+}
+
+async function setDownloadRecord(record: DownloadRecord): Promise<void> {
+	await withDatabase('readwrite', (store) => store.put(record));
+}
+
+async function deleteDownloadRecord(file_id: string): Promise<void> {
+	await withDatabase('readwrite', (store) => store.delete(file_id));
+}
+
+/**
+ * get all download records from IndexedDB
+ */
+export async function getAllDownloads(): Promise<DownloadRecord[]> {
+	return withDatabase('readonly', (store) => store.getAll());
+}
+
+// Cache API helpers
+
+/**
+ * get the cache key for an audio file
+ * Cache API requires http/https URLs, so we use a fake but valid URL
+ */
+function getCacheKey(file_id: string): string {
+	return `https://plyr.fm/_offline/${file_id}`;
+}
+
+/**
+ * check if audio is cached locally
+ * verifies both metadata (IndexedDB) and actual audio (Cache API) exist
+ */
+export async function isDownloaded(file_id: string): Promise<boolean> {
+	const record = await getDownloadRecord(file_id);
+	if (!record) return false;
+
+	// also verify the cache entry exists (handles edge case where cache was
+	// cleared but IndexedDB wasn't)
+	try {
+		const cache = await caches.open(AUDIO_CACHE_NAME);
+		const cached = await cache.match(getCacheKey(file_id));
+		if (!cached) {
+			// cache is gone but metadata exists - clean up the stale record
+			await deleteDownloadRecord(file_id);
+			return false;
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * get cached audio as a blob URL for playback
+ * returns null if not cached
+ */
+export async function getCachedAudioUrl(file_id: string): Promise<string | null> {
+	try {
+		const cache = await caches.open(AUDIO_CACHE_NAME);
+		const response = await cache.match(getCacheKey(file_id));
+
+		if (!response) {
+			return null;
+		}
+
+		const blob = await response.blob();
+		return URL.createObjectURL(blob);
+	} catch (error) {
+		console.error('failed to get cached audio:', error);
+		return null;
+	}
+}
+
+/**
+ * download audio file and cache it locally
+ *
+ * 1. fetch presigned URL from backend
+ * 2. fetch audio from R2 directly
+ * 3. store in Cache API
+ * 4. record in IndexedDB
+ *
+ * if a download for this file_id is already in progress, returns
+ * the existing promise (prevents duplicate downloads from concurrent calls)
+ */
+export async function downloadAudio(
+	file_id: string,
+	onProgress?: (loaded: number, total: number) => void
+): Promise<void> {
+	// if already downloading this file, return existing promise
+	const existing = activeDownloads.get(file_id);
+	if (existing) return existing;
+
+	const downloadPromise = (async () => {
+		try {
+			await performDownload(file_id, onProgress);
+		} finally {
+			activeDownloads.delete(file_id);
+		}
+	})();
+
+	activeDownloads.set(file_id, downloadPromise);
+	return downloadPromise;
+}
+
+async function performDownload(
+	file_id: string,
+	onProgress?: (loaded: number, total: number) => void
+): Promise<void> {
+	// 1. get presigned URL from backend
+	const urlResponse = await fetch(`${API_URL}/audio/${file_id}/url`, {
+		credentials: 'include'
+	});
+
+	if (!urlResponse.ok) {
+		throw new Error(`failed to get audio URL: ${urlResponse.status}`);
+	}
+
+	const { url, file_type } = await urlResponse.json();
+
+	// 2. fetch audio from R2
+	const audioResponse = await fetch(url);
+
+	if (!audioResponse.ok) {
+		throw new Error(`failed to fetch audio: ${audioResponse.status}`);
+	}
+
+	// get total size for progress tracking
+	const contentLength = audioResponse.headers.get('content-length');
+	const total = contentLength ? parseInt(contentLength, 10) : 0;
+
+	// read the response as a blob, tracking progress if callback provided
+	let blob: Blob;
+
+	if (onProgress && audioResponse.body && total > 0) {
+		const reader = audioResponse.body.getReader();
+		const chunks: BlobPart[] = [];
+		let loaded = 0;
+
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+
+			chunks.push(value);
+			loaded += value.length;
+			onProgress(loaded, total);
+		}
+
+		blob = new Blob(chunks, {
+			type: audioResponse.headers.get('content-type') || 'audio/mpeg'
+		});
+	} else {
+		blob = await audioResponse.blob();
+	}
+
+	// 3. store in Cache API
+	const cache = await caches.open(AUDIO_CACHE_NAME);
+	const cacheResponse = new Response(blob, {
+		headers: {
+			'content-type': blob.type,
+			'content-length': blob.size.toString()
+		}
+	});
+	await cache.put(getCacheKey(file_id), cacheResponse);
+
+	// 4. record in IndexedDB
+	await setDownloadRecord({
+		file_id,
+		size: blob.size,
+		downloaded_at: Date.now(),
+		file_type
+	});
+}
+
+/**
+ * remove downloaded audio from cache and IndexedDB
+ */
+export async function removeDownload(file_id: string): Promise<void> {
+	// remove from Cache API
+	const cache = await caches.open(AUDIO_CACHE_NAME);
+	await cache.delete(getCacheKey(file_id));
+
+	// remove from IndexedDB
+	await deleteDownloadRecord(file_id);
+}
+
+/**
+ * get storage usage estimate
+ * returns bytes used and quota
+ */
+export async function getStorageUsage(): Promise<{ used: number; quota: number }> {
+	if ('storage' in navigator && 'estimate' in navigator.storage) {
+		const estimate = await navigator.storage.estimate();
+		return {
+			used: estimate.usage || 0,
+			quota: estimate.quota || 0
+		};
+	}
+
+	// fallback: sum up our download records
+	const downloads = await getAllDownloads();
+	const used = downloads.reduce((sum, d) => sum + d.size, 0);
+
+	return { used, quota: 0 };
+}
+
+/**
+ * clear all downloaded audio
+ */
+export async function clearAllDownloads(): Promise<void> {
+	// clear Cache API
+	await caches.delete(AUDIO_CACHE_NAME);
+
+	// clear IndexedDB
+	await withDatabase('readwrite', (store) => store.clear());
+}
+
+/**
+ * download all liked tracks that aren't already cached
+ * returns the number of tracks that were downloaded
+ */
+export async function downloadAllLikedTracks(): Promise<number> {
+	// fetch liked tracks from API
+	const response = await fetch(`${API_URL}/tracks/liked`, {
+		credentials: 'include'
+	});
+
+	if (!response.ok) {
+		throw new Error(`failed to fetch liked tracks: ${response.status}`);
+	}
+
+	const data = await response.json();
+	const tracks = data.tracks as { file_id: string }[];
+
+	let downloadedCount = 0;
+
+	// download each track that isn't already cached
+	for (const track of tracks) {
+		try {
+			const alreadyDownloaded = await isDownloaded(track.file_id);
+			if (!alreadyDownloaded) {
+				await downloadAudio(track.file_id);
+				downloadedCount++;
+			}
+		} catch (err) {
+			console.error(`failed to download track ${track.file_id}:`, err);
+			// continue with other tracks
+		}
+	}
+
+	return downloadedCount;
+}

frontend/src/lib/tracks.svelte.ts

···
 import { API_URL } from './config';
 import type { Track } from './types';
+import { preferences } from './preferences.svelte';
+import { downloadAudio, isDownloaded } from './storage';
 
 interface TracksApiResponse {
 	tracks: Track[];
···
 export const tracksCache = new TracksCache();
 
 // like/unlike track functions
-export async function likeTrack(trackId: number): Promise<boolean> {
+export async function likeTrack(trackId: number, fileId?: string): Promise<boolean> {
 	try {
 		const response = await fetch(`${API_URL}/tracks/${trackId}/like`, {
 			method: 'POST',
···
 
 		// invalidate cache so next fetch gets updated like status
 		tracksCache.invalidate();
+
+		// auto-download if preference is enabled and file_id provided
+		if (fileId && preferences.autoDownloadLiked) {
+			try {
+				const alreadyDownloaded = await isDownloaded(fileId);
+				if (!alreadyDownloaded) {
+					// download in background, don't await
+					downloadAudio(fileId).catch((err) => {
+						console.error('auto-download failed:', err);
+					});
+				}
+			} catch (err) {
+				console.error('failed to check/download:', err);
+			}
+		}
 
 		return true;
 	} catch (e) {

frontend/src/routes/+layout.ts

···
 	show_sensitive_artwork: false,
 	show_liked_on_profile: false,
 	support_url: null,
-	ui_settings: {}
+	ui_settings: {},
+	auto_download_liked: false
 };
 
 export async function load({ fetch, data }: LoadEvent): Promise<LayoutData> {
···
 				});
 				if (prefsResponse.ok) {
 					const prefsData = await prefsResponse.json();
+					// auto_download_liked is stored locally, not on server
+					const storedAutoDownload = typeof localStorage !== 'undefined'
+						? localStorage.getItem('autoDownloadLiked') === '1'
+						: false;
 					preferences = {
 						accent_color: prefsData.accent_color ?? null,
 						auto_advance: prefsData.auto_advance ?? true,
···
 						show_sensitive_artwork: prefsData.show_sensitive_artwork ?? false,
 						show_liked_on_profile: prefsData.show_liked_on_profile ?? false,
 						support_url: prefsData.support_url ?? null,
-						ui_settings: prefsData.ui_settings ?? {}
+						ui_settings: prefsData.ui_settings ?? {},
+						auto_download_liked: storedAutoDownload
 					};
 				}
 			} catch (e) {

frontend/src/routes/settings/+page.svelte

···
 	let backgroundImageUrl = $derived(preferences.uiSettings.background_image_url ?? '');
 	let backgroundTile = $derived(preferences.uiSettings.background_tile ?? false);
 	let usePlayingArtwork = $derived(preferences.uiSettings.use_playing_artwork_as_background ?? false);
+	let autoDownloadLiked = $derived(preferences.autoDownloadLiked);
 	// developer token state
 	let creatingToken = $state(false);
 	let developerToken = $state<string | null>(null);
···
 		queue.setAutoAdvance(value);
 		localStorage.setItem('autoAdvance', value ? '1' : '0');
 		await preferences.update({ auto_advance: value });
+	}
+
+	function handleAutoDownloadToggle(enabled: boolean) {
+		preferences.setAutoDownloadLiked(enabled);
+
+		if (enabled) {
+			// start downloading existing liked tracks in background (non-blocking)
+			toast.success('downloading liked tracks in background...');
+			import('$lib/storage').then(({ downloadAllLikedTracks }) => {
+				downloadAllLikedTracks().then((count) => {
+					if (count > 0) {
+						toast.success(`downloaded ${count} track${count === 1 ? '' : 's'} for offline`);
+					} else {
+						toast.success('all liked tracks already downloaded');
+					}
+				}).catch((err) => {
+					console.error('failed to download liked tracks:', err);
+					toast.error('failed to download some tracks');
+				});
+			});
+		} else {
+			toast.success('auto-download disabled');
+		}
 	}
 
 	// preferences
···
 						<span class="toggle-slider"></span>
 					</label>
 				</div>
+
+				<div class="setting-row">
+					<div class="setting-info">
+						<h3>auto-download liked</h3>
+						<p>automatically download tracks for offline playback when you like them</p>
+					</div>
+					<label class="toggle-switch">
+						<input
+							type="checkbox"
+							checked={autoDownloadLiked}
+							onchange={(e) => handleAutoDownloadToggle((e.target as HTMLInputElement).checked)}
+						/>
+						<span class="toggle-slider"></span>
+					</label>
+				</div>
 			</div>
 		</section>
 
···
 							<circle cx="12" cy="12" r="10" />
 							<path d="M12 16v-4M12 8h.01" />
 						</svg>
-						<span>toggle on to connect teal.fm scrobbling</span>
+						<span>authorization expired — disable and re-enable to reconnect</span>
 					</div>
 				{/if}
 			</div>