feat: add pagination and infinite scroll to tracks list (#554)

* feat: add pagination and infinite scroll to tracks list

backend:
- add cursor-based pagination to /tracks/ endpoint
- use created_at timestamp as cursor for stable pagination
- return next_cursor and has_more fields in response
- default page size of 50, max 100

frontend:
- update TracksCache to support fetchMore() for pagination
- persist pagination state (nextCursor, hasMore) to localStorage
- implement infinite scroll on homepage using IntersectionObserver
- add scroll sentinel element with loading indicator
- trigger fetch 200px before reaching bottom for smooth UX

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

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

* fix: address PR feedback

- move default page size to settings.app.default_page_size
- raise 400 error on invalid cursor format instead of ignoring
- use walrus operator for has_more logic

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

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

---------

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

backend/src/backend/api/tracks/listing.py

···
 """Read-only track listing endpoints."""
 
 import asyncio
+from datetime import datetime
 from typing import Annotated
 
 import logfire
-from fastapi import Depends
+from fastapi import Depends, HTTPException
 from pydantic import BaseModel
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
···
 
 from backend._internal import Session as AuthSession
 from backend._internal import get_optional_session, require_auth
+from backend.config import settings
 from backend.models import (
     Artist,
     Tag,
···
 from .router import router
 
 
+class TracksListResponse(BaseModel):
+    """Response for paginated track listing."""
+
+    tracks: list[TrackResponse]
+    next_cursor: str | None = None
+    has_more: bool = False
+
+
 @router.get("/")
 async def list_tracks(
     db: Annotated[AsyncSession, Depends(get_db)],
     artist_did: str | None = None,
     filter_hidden_tags: bool | None = None,
+    cursor: str | None = None,
+    limit: int | None = None,
     session: AuthSession | None = Depends(get_optional_session),
-) -> dict:
-    """List all tracks, optionally filtered by artist DID.
+) -> TracksListResponse:
+    """List tracks with cursor-based pagination.
 
     Args:
         artist_did: Filter to tracks by this artist only.
···
               don't filter on artist pages)
             - True: always filter hidden tags
             - False: never filter hidden tags
+        cursor: ISO timestamp cursor from previous response's next_cursor.
+            Pass this to get the next page of results.
+        limit: Maximum number of tracks to return (default from settings, max 100).
     """
+    # use settings default if not provided, clamp to reasonable bounds
+    if limit is None:
+        limit = settings.app.default_page_size
+    limit = max(1, min(limit, 100))
     from atproto_identity.did.resolver import AsyncDidResolver
 
     # get authenticated user's liked tracks and preferences
···
         )
         stmt = stmt.where(Track.id.not_in(hidden_track_ids_subq))
 
-    stmt = stmt.order_by(Track.created_at.desc())
+    # apply cursor-based pagination (tracks older than cursor timestamp)
+    if cursor:
+        try:
+            cursor_time = datetime.fromisoformat(cursor)
+            stmt = stmt.where(Track.created_at < cursor_time)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail="invalid cursor format") from e
+
+    # order by created_at desc and fetch one extra to check if there's more
+    stmt = stmt.order_by(Track.created_at.desc()).limit(limit + 1)
     result = await db.execute(stmt)
-    tracks = result.scalars().all()
+    tracks = list(result.scalars().all())
+
+    # check if there are more results and trim to requested limit
+    if has_more := len(tracks) > limit:
+        tracks = tracks[:limit]
+
+    # generate next cursor from the last track's created_at
+    next_cursor = tracks[-1].created_at.isoformat() if has_more and tracks else None
 
     # batch fetch like, comment counts, copyright info, and tags for all tracks
     track_ids = [track.id for track in tracks]
···
         ]
     )
 
-    return {"tracks": track_responses}
+    return TracksListResponse(
+        tracks=list(track_responses),
+        next_cursor=next_cursor,
+        has_more=has_more,
+    )
 
 
 @router.get("/me")

backend/src/backend/config.py

···
         default="plyr",
         description="Prefix used for browser BroadcastChannel identifiers",
     )
+    default_page_size: int = Field(
+        default=50,
+        description="Default page size for paginated endpoints",
+    )
 
 
 class FrontendSettings(AppSettingsSection):

frontend/src/lib/tracks.svelte.ts

···
 import { API_URL } from './config';
 import type { Track } from './types';
 
+interface TracksApiResponse {
+	tracks: Track[];
+	next_cursor: string | null;
+	has_more: boolean;
+}
+
+interface CachedTracksData {
+	tracks: Track[];
+	nextCursor: string | null;
+	hasMore: boolean;
+}
+
 // load cached tracks from localStorage (no time check - trust invalidate() calls)
-function loadCachedTracks(): Track[] {
-	if (typeof window === 'undefined') return [];
+function loadCachedTracks(): CachedTracksData {
+	if (typeof window === 'undefined') {
+		return { tracks: [], nextCursor: null, hasMore: true };
+	}
 	try {
 		const cached = localStorage.getItem('tracks_cache');
 		if (cached) {
-			const { tracks } = JSON.parse(cached);
+			const data = JSON.parse(cached);
 			// check if cache has the new is_liked field, if not invalidate
-			if (tracks && tracks.length > 0 && !('is_liked' in tracks[0])) {
+			if (data.tracks && data.tracks.length > 0 && !('is_liked' in data.tracks[0])) {
 				localStorage.removeItem('tracks_cache');
-				return [];
+				return { tracks: [], nextCursor: null, hasMore: true };
 			}
-			return tracks;
+			return {
+				tracks: data.tracks || [],
+				nextCursor: data.nextCursor ?? null,
+				hasMore: data.hasMore ?? true
+			};
 		}
 	} catch (e) {
 		console.warn('failed to load cached tracks:', e);
 	}
-	return [];
+	return { tracks: [], nextCursor: null, hasMore: true };
 }
 
 // global tracks cache using Svelte 5 runes
 class TracksCache {
-	tracks = $state<Track[]>(loadCachedTracks());
+	tracks = $state<Track[]>(loadCachedTracks().tracks);
 	loading = $state(false);
+	loadingMore = $state(false);
+	nextCursor = $state<string | null>(loadCachedTracks().nextCursor);
+	hasMore = $state(loadCachedTracks().hasMore);
+
+	private persistToStorage(): void {
+		if (typeof window !== 'undefined') {
+			try {
+				localStorage.setItem(
+					'tracks_cache',
+					JSON.stringify({
+						tracks: this.tracks,
+						nextCursor: this.nextCursor,
+						hasMore: this.hasMore
+					})
+				);
+			} catch (e) {
+				console.warn('failed to cache tracks:', e);
+			}
+		}
+	}
 
 	async fetch(force = false): Promise<void> {
 		// always fetch in background to check for updates
···
 			const response = await fetch(`${API_URL}/tracks/`, {
 				credentials: 'include'
 			});
-			const data = await response.json();
+			const data: TracksApiResponse = await response.json();
 			this.tracks = data.tracks;
+			this.nextCursor = data.next_cursor;
+			this.hasMore = data.has_more;
 
-			// persist to localStorage
-			if (typeof window !== 'undefined') {
-				try {
-					localStorage.setItem('tracks_cache', JSON.stringify({
-						tracks: this.tracks
-					}));
-				} catch (e) {
-					console.warn('failed to cache tracks:', e);
-				}
-			}
+			this.persistToStorage();
 		} catch (e) {
 			console.error('failed to fetch tracks:', e);
 		} finally {
···
 		}
 	}
 
+	async fetchMore(): Promise<void> {
+		// don't fetch if already loading or no more results
+		if (this.loadingMore || this.loading || !this.hasMore || !this.nextCursor) {
+			return;
+		}
+
+		this.loadingMore = true;
+		try {
+			const url = new URL(`${API_URL}/tracks/`);
+			url.searchParams.set('cursor', this.nextCursor);
+
+			const response = await fetch(url.toString(), {
+				credentials: 'include'
+			});
+			const data: TracksApiResponse = await response.json();
+
+			// append new tracks to existing list
+			this.tracks = [...this.tracks, ...data.tracks];
+			this.nextCursor = data.next_cursor;
+			this.hasMore = data.has_more;
+
+			this.persistToStorage();
+		} catch (e) {
+			console.error('failed to fetch more tracks:', e);
+		} finally {
+			this.loadingMore = false;
+		}
+	}
+
 	invalidate(): void {
-		// clear cache - next fetch will get fresh data
+		// clear cache and reset pagination state - next fetch will get fresh data
 		if (typeof window !== 'undefined') {
 			localStorage.removeItem('tracks_cache');
 		}
+		this.nextCursor = null;
+		this.hasMore = true;
 	}
 }
 

frontend/src/routes/+page.svelte

···
 	// use cached tracks
 	let tracks = $derived(tracksCache.tracks);
 	let loadingTracks = $derived(tracksCache.loading);
+	let loadingMore = $derived(tracksCache.loadingMore);
+	let hasMore = $derived(tracksCache.hasMore);
 	let hasTracks = $derived(tracks.length > 0);
 	let initialLoad = $state(true);
 
···
 	// track which track ID we've already auto-played to prevent infinite loops
 	let autoPlayedTrackId = $state<string | null>(null);
 
+	// infinite scroll sentinel element
+	let sentinelElement = $state<HTMLDivElement | null>(null);
+
 	onMount(async () => {
 		// fetch tracks from cache (will use cached data if recent)
 		await tracksCache.fetch();
 		initialLoad = false;
 	});
 
+	// set up IntersectionObserver for infinite scroll
+	$effect(() => {
+		if (!sentinelElement) return;
+
+		const observer = new IntersectionObserver(
+			(entries) => {
+				const entry = entries[0];
+				if (entry.isIntersecting && hasMore && !loadingMore && !loadingTracks) {
+					tracksCache.fetchMore();
+				}
+			},
+			{
+				rootMargin: '200px' // trigger 200px before reaching the end
+			}
+		);
+
+		observer.observe(sentinelElement);
+
+		return () => {
+			observer.disconnect();
+		};
+	});
+
 	// reactive effect to auto-play track from URL query param
 	$effect(() => {
 		const trackId = $page.url.searchParams.get('track');
···
 					/>
 				{/each}
 			</div>
+			<!-- infinite scroll sentinel -->
+			{#if hasMore}
+				<div bind:this={sentinelElement} class="scroll-sentinel">
+					{#if loadingMore}
+						<WaveLoading size="sm" message="loading more..." />
+					{/if}
+				</div>
+			{/if}
 		{/if}
 	</section>
 </main>
···
 		display: flex;
 		flex-direction: column;
 		gap: 0.5rem;
+	}
+
+	.scroll-sentinel {
+		display: flex;
+		justify-content: center;
+		padding: 2rem 0;
+		min-height: 60px;
 	}
 
 	@media (max-width: 768px) {