Add adaptive media variants for weak networks

docs/FRONTEND_INTEGRATION.md

@@ -18,7 +18,7 @@ CORS_ORIGINS=http://192.168.1.12:3000,http://192.168.1.12:5173
 GOOGLE_CALLBACK_URL=http://192.168.1.12:4000/api/v1/auth/google/callback
 ```
 
-With `PUBLIC_BASE_URL` configured, file fields such as `avatar`, `coverImage`, `imageUrls`, `videoUrl`, `hlsUrl`, `audioUrl`, `thumbnailUrl`, `mediaUrl`, and marketplace images are returned as absolute URLs.
+With `PUBLIC_BASE_URL` configured, file fields such as `avatar`, `coverImage`, `imageUrls`, `imageVariants`, `videoUrl`, `hlsUrl`, `audioUrl`, `thumbnailUrl`, `thumbnailVariants`, `mediaUrl`, and marketplace images are returned as absolute URLs.
 
 ## Pagination contract
 
@@ -212,8 +212,10 @@ When `VIDEO_PROCESSING_ENABLED=true` and `ffmpeg` is available on the server:
 - uploaded post/reel videos are converted to optimized `mp4`
 - `+faststart` is applied so playback begins faster on mobile/web
 - uploaded post/reel videos also produce an HLS playlist at `hlsUrl` when `VIDEO_PROCESSING_GENERATE_HLS=true`
+- when `ffprobe` is available, `hlsUrl` points to a master playlist with multiple renditions so HLS players can downgrade quality automatically on weak networks
 - local storage responses serve `mp4`, `m3u8`, `m4s`, and `ts` files with explicit media `Content-Type` headers and `Accept-Ranges: bytes`
 - a thumbnail image is generated automatically if the client does not send `thumbnailUrl`
+- generated thumbnails also expose `thumbnailVariants.lowUrl`, `thumbnailVariants.mediumUrl`, `thumbnailVariants.highUrl`, and `thumbnailVariants.originalUrl`
 
 If `ffmpeg` is not installed or video processing is disabled, uploads still work and the original
 video file is stored as-is.
@@ -222,6 +224,7 @@ Recommended client behavior:
 
 - use `hlsUrl` first when present for adaptive/streaming playback
 - fall back to `videoUrl` for progressive `mp4` playback
+- for poster frames on weak networks, prefer `thumbnailVariants.lowUrl` or `thumbnailVariants.mediumUrl`
 
 ## Audio and image delivery
 
@@ -229,11 +232,15 @@ Managed uploads are stored under stable UUID-based paths, so local storage respo
 
 - images (`jpg`, `jpeg`, `png`, `webp`, `gif`) are served with explicit `Content-Type` and long-lived immutable `Cache-Control`
 - audio (`mp3`, `wav`, `m4a`, `aac`, `ogg`) is served with explicit `Content-Type`, long-lived immutable `Cache-Control`, and `Accept-Ranges: bytes`
+- uploaded post images are normalized into responsive variants and posts now include `imageVariants[]`
 
 Recommended client behavior:
 
 - for audio, stream `audioUrl` directly and allow byte-range playback/resume
-- for images, render `imageUrls` directly and rely on URL-based caching for repeat views
+- `imageUrls` now default to feed-friendly optimized images for backward compatibility
+- on weak networks, prefer `imageVariants[index].lowUrl`
+- on normal networks, use `imageUrls[index]` or `imageVariants[index].mediumUrl`
+- on detail screens or zoom views, use `imageVariants[index].highUrl` or `imageVariants[index].originalUrl`
 
 ## Marketplace split