feat: adaptive progressive image loading for photo viewer

[midzelis]

In this screenshot, the load times are artificially slowed down so you can see all the different quality levels slowly stream into the browser. The artificial delays are as follows: 500ms delay before sending first byte, then throttle each photo as follows:
thumbnails=1s, preview=4s, original=10s

Initially, (b/c of 500ms delay) you'll set the thumbhash, then you'll see the thumb for 1s, then you'll see the preview stream in over 4s, and then when you zoom (which auto-loads the original quality) you'll see that stream in as well.

The demo video is repeated a 2nd time. The second time I start to zoom while preview is still loading, and you'll see the original start to load before the preview finishes.

Note, this is also using progressive-jpegs for preview. Non-progressive jpegs/webp files will stream/render from top to bottom.

Additionally, while all these images are loading, if you click next/prev, all of them are canceled, which is new feature too - this keeps the navigation responsive. If you are coming from the timeline, the preview image from the timeline is available immediately, so the delay between timeline and the full screen viewer should be almost imperceptible in most cases.

This video is an EXAGGERATION showing the worst case - very slow links/mobile devices. With preloading, and reusing thumbs from timeline, in practice, you won't see this at all. But, if you are on a slow link, you'll get faster feedback, better experience than staring at a black screen with a spinner like you currently do.

adaptive.mp4

The photo viewer currently loads images by swapping by showing a loading spinner until the 'preview' size image loads. And then on zoom, replacing that single <img> element's src from preview to original. This causes visible flicker between quality levels because the browser shows a blank state while the next resolution loads.

This PR replaces that with a layered progressive loading system. Three <img> elements (thumbnail, preview, original) are always present in the DOM, stacked by z-index. Each layer fades in on top of the previous one as it loads, so there's never a blank flash between quality transitions. A thumbhash canvas sits underneath everything as the initial placeholder.

The end result is - no spinner at all. The 'thumbnail' size image is VERY likely to already have been loaded (if your navigating from the timeline) - so you'll likely instantly see the thumbnail in most cases. However, if you do not (because this is a direct nav) you'll at least see the thumbhash, which is part of the asset response metdata and does not need a url fetch to get the image.

After the thumb is loaded, preview (or fullsize - or original - based on various conditions) image starts to load. If you start to zoom in, the fullsize (or original) image is loaded.

This change is fully transparent compatible. Transparent images (WEBP) have gray background set behind the image. Note - thumbhashes do support a transparent alpha channel, and the thumbhash will be drawn on top of the gray background.

The AdaptiveImageLoader is a state machine that manages cancelation and quality progression between: basic → loading-thumbnail → thumbnail → loading-preview → preview → loading-original → original

The asset viewer preloads and cancels the next/previous images using the same (headless) state-machine.

Because the "image" is now actually 3 layers - zoom-image was modified (upstream) and can now apply to an arbitary element instead of just tags - we now zoom the <AdaptiveImage> root div.

Added lots of e2e tests.

[mertalev]

Is it possible to swap the image bitmaps as they're loaded rather than doing z-levels?

[midzelis]

Is it possible to swap the image bitmaps as they're loaded rather than doing z-levels?

The thumbhash (canvas) actually does get removed after the 'thumbnail' quality image is loaded successfully.

Something similar should be possible when the 'preview' image fully loads on top of the 'thumbnail' - once preview is loaded, thumbnail can be safely removed.

On zoom, same thing - once full/original is fully loaded, the thumbnail can be removed.

In general, we need to have 2 images while the higher quality is loading - so you see the lower quality 'under' the higher quality one. Once loaded, the lower quality one can be removed from DOM.

However, this does add overall complexity. Why are you asking? Is it for performance or memory reasons? For managing the z-index? Or something else?

[mertalev]

Swapping the bitmap is how it's handled in the mobile app, which is generally better for performance (less compositing, lower memory usage, etc.) and handles alpha. It basically needs an API that decouples decoding the image from displaying it. Not a huge deal if there's no good way to do that in web, but it's better if it can.

[github-actions]

Preview environment has been removed.

[michelheusschen]

I gave it another round of testing and no more issues, so all good from me. Thank you for the effort you put into this!

I am thinking your approval somehow block the check job to run lol