This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
ADR 0045: ProgressiveImage Shared Component Pattern
Status: proposed Date: 2026-06-06
Context
After the UX Overhaul (spec 006), the app lost progressive image loading. The previous implementation used blurred 512px thumbnails that showed immediately, with sharp 2048px previews swapping in once ready. The redesign replaced this with skeleton placeholders that jump directly to full quality.
At least six pages share this pattern: media grid, media detail, face thumbnails in People, person detail, album covers, and search results. Each needs the same blur→HQ dual-layer behavior with a smooth crossfade transition, prefers-reduced-motion support, and consistent accessibility.
Without a shared component, implementing progressive loading in each page independently would mean:
- Duplicating 30+ lines of template, state, and transition logic across 6+ call sites
- Inconsistent accessibility handling (some pages forgetting
aria-hiddenon the blur layer, missingdecoding="async") - Transition behavior diverging between pages over time
Decision
Extract ProgressiveImage.svelte as a shared Svelte 5 component that encapsulates:
- Blur thumbnail layer: always shown when
thumbnailUrlis provided - HQ preview layer: conditional on
previewReady && previewUrl - Crossfade transition: opacity transition on HQ load
prefers-reduced-motionsupport: disables crossfade, shows HQ instantlyloading="lazy"+decoding="async"on both<img>elementsaria-hidden="true"on the blur layer (decorative)
Props
| Prop | Type | Description |
|---|---|---|
thumbnailUrl |
string | null |
Blurred thumbnail URL (512px) |
previewUrl |
string | null |
Sharp preview URL (2048px) |
previewReady |
boolean |
Whether preview URL is available for display |
alt |
string |
Alt text for the image |
objectFit |
'cover' | 'contain' |
CSS object-fit (default: 'cover') |
class |
string | undefined |
Additional CSS classes |
Behavior
thumbnailUrl present → blur layer visible (always)
previewReady && previewUrl → HQ layer fades in over blur layer
!previewReady → blur layer shown alone (or skeleton if no thumbnail)
prefers-reduced-motion → no crossfade, HQ appears instantly
Alternatives Considered
-
Inline snippets per page: Duplicate 30+ lines across 6+ pages. Drift risk, inconsistent a11y, no single place to fix bugs. Rejected.
-
Wrapper component around
<img>: Only handles single-layer display. Does not support the dual-layer blur+HQ pattern where both layers coexist simultaneously during crossfade. Rejected. -
CSS-only approach (
image-set()or@supports): Cannot gate HQ display on a runtimepreviewStatusstate. No way to trigger crossfade on async readiness. Rejected.
Rationale
- DRY: 6+ call sites need identical logic — component eliminates duplication
- Encapsulation: transition, a11y, and load state managed in one place
- Testable: isolated component with clear props interface, no page-level coupling
- No new dependencies: pure Svelte 5 runes + Tailwind CSS
Constraints
- Svelte 5 runes only (
$state,$props,$derived) - No new runtime libraries
- Component does not manage its own IntersectionObserver — parent controls viewport gating via
previewReadyprop - Must accept arbitrary URL patterns (face thumbnails use different URL structures than media thumbnails)
Consequences
- Progressive loading restored across all image contexts with consistent behavior
- Single place to maintain transition timing, a11y attributes, and load optimization
- Pages only need to provide
thumbnailUrl,previewUrl, andpreviewReady— component handles the rest - Future changes to progressive loading behavior (e.g., adding blur-up filter, LQIP placeholders) happen in one file
- No impact on backend or worker systems — purely a frontend presentation pattern
References
- Spec 013:
specs/013-progressive-image-loading/spec.md - Requirements R1–R5
- Existing blur pattern:
MediaGrid.sveltelines 650–684
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference