Kordant/tasks/ios-production/09-image-caching.md

09. Image Caching & Lazy Loading

meta: id: ios-production-09 feature: ios-production priority: P2 depends_on: [] tags: [performance, caching, production]

objective:

• Implement efficient image caching and lazy loading to improve app performance and reduce network usage

deliverables:

• URLSession-based image caching
• Lazy loading for lists and grids
• Image optimization pipeline
• Memory and disk cache limits

steps:

1. Implement image caching:
   • Use URLCache with memory (50MB) and disk (100MB) limits
   • Or integrate Kingfisher or Nuke for advanced caching
   • Configure cache expiration (7 days default)
   • Add cache cleanup on low memory warnings
2. Add lazy loading:
   • Use LazyVStack and LazyHGrid for lists
   • Implement pagination for long lists (alerts, exposures)
   • Add prefetching for adjacent items
   • Show placeholder while loading
3. Optimize images:
   • Request appropriate sizes from backend (thumbnail, full)
   • Use WebP or HEIC format where supported
   • Compress images before upload (VoicePrint, document scan)
   • Implement progressive JPEG loading
4. Add loading states:
   • Skeleton placeholders while images load
   • Error state with retry button
   • Fade-in animation when image loads
5. Implement memory management:
   • Clear image cache on memory warning
   • Limit concurrent image downloads (max 5)
   • Cancel downloads for off-screen images
6. Add offline support:
   • Cache images for offline viewing
   • Show cached images when offline
   • Queue uploads for when online

tests:

• Unit: Test cache hit/miss behavior
• Performance: Test scrolling with 1000 images
• Memory: Verify no memory leaks with image loading

acceptance_criteria:

• Images cached with 50MB memory / 100MB disk limits
• Lazy loading on all lists and grids
• Pagination for lists >50 items
• Image placeholders while loading
• Cache cleared on memory warning
• Offline image viewing working
• Progressive loading for large images
• No memory leaks in image loading pipeline
• Smooth 60fps scrolling on image-heavy screens

validation:

• Scroll through alert list → smooth, no stuttering
• Turn on airplane mode → cached images still visible
• Monitor memory → stable during image browsing
• Check cache directory → images stored with correct expiration

notes:

• Kingfisher is the most popular Swift image caching library
• Nuke is lighter and faster for advanced use cases
• Consider using SwiftUI AsyncImage for simple cases
• Always test on physical device, not just simulator