Cutlery/immich
1
0
Fork 1
mirror of https://github.com/immich-app/immich.git synced 2026-03-09 19:33:43 -04:00
Code Issues Packages Projects Releases Wiki Activity

feat(web): adaptive progressive image loading for photo viewer

Browse Source 
Replace ImageManager with a new AdaptiveImageLoader that progressively
loads images through quality tiers (thumbnail → preview → original).

New components and utilities:
- AdaptiveImage: layered image renderer with thumbhash, thumbnail,
  preview, and original layers with visibility managed by load state
- AdaptiveImageLoader: state machine driving the quality progression
  with per-quality callbacks and error handling
- ImageLayer/Image: low-level image elements with load/error lifecycle
- PreloadManager: preloads adjacent assets for instant navigation
- AlphaBackground/DelayedLoadingSpinner: loading state UI

Zoom is handled via a derived CSS transform applied to the content
wrapper in AdaptiveImage, with the zoom library (zoomTarget: null)
only tracking state without manipulating the DOM directly.

Also adds scaleToCover to container-utils and getAssetUrls to utils.
This commit is contained in:
midzelis 2026-01-15 20:34:21 +00:00
parent aaf34fa7d4
commit 7e2863858d
20 changed files with 1235 additions and 409 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
e2e/src/specs/web/photo-viewer.e2e-spec.ts
View File

@ -1,14 +1,13 @@
import { AssetMediaResponseDto, LoginResponseDto } from '@immich/sdk';
import { Page, expect, test } from '@playwright/test';
import { expect, test } from '@playwright/test';
import type { Socket } from 'socket.io-client';
import { utils } from 'src/utils';
function imageLocator(page: Page) {
return page.getByAltText('Image taken').locator('visible=true');
}
test.describe('Photo Viewer', () => {
let admin: LoginResponseDto;
let asset: AssetMediaResponseDto;
let rawAsset: AssetMediaResponseDto;
let websocket: Socket;
test.beforeAll(async () => {
utils.initSdk();
@ -16,6 +15,11 @@ test.describe('Photo Viewer', () => {
admin = await utils.adminSetup();
asset = await utils.createAsset(admin.accessToken);
rawAsset = await utils.createAsset(admin.accessToken, { assetData: { filename: 'test.arw' } });
websocket = await utils.connectWebsocket(admin.accessToken);
});
test.afterAll(() => {
utils.disconnectWebsocket(websocket);
});
test.beforeEach(async ({ context, page }) => {
@ -26,31 +30,51 @@ test.describe('Photo Viewer', () => {
test('loads original photo when zoomed', async ({ page }) => {
await page.goto(`/photos/${asset.id}`);
await expect.poll(async () => await imageLocator(page).getAttribute('src')).toContain('thumbnail');
const box = await imageLocator(page).boundingBox();
expect(box).toBeTruthy();
const { x, y, width, height } = box!;
await page.mouse.move(x + width / 2, y + height / 2);
const preview = page.getByTestId('preview').filter({ visible: true });
await expect(preview).toHaveAttribute('src', /.+/);
const originalResponse = page.waitForResponse((response) => response.url().includes('/original'));
const { width, height } = page.viewportSize()!;
await page.mouse.move(width / 2, height / 2);
await page.mouse.wheel(0, -1);
await expect.poll(async () => await imageLocator(page).getAttribute('src')).toContain('original');
await originalResponse;
const original = page.getByTestId('original').filter({ visible: true });
await expect(original).toHaveAttribute('src', /original/);
});
test('loads fullsize image when zoomed and original is web-incompatible', async ({ page }) => {
await page.goto(`/photos/${rawAsset.id}`);
await expect.poll(async () => await imageLocator(page).getAttribute('src')).toContain('thumbnail');
const box = await imageLocator(page).boundingBox();
expect(box).toBeTruthy();
const { x, y, width, height } = box!;
await page.mouse.move(x + width / 2, y + height / 2);
const preview = page.getByTestId('preview').filter({ visible: true });
await expect(preview).toHaveAttribute('src', /.+/);
const fullsizeResponse = page.waitForResponse((response) => response.url().includes('fullsize'));
const { width, height } = page.viewportSize()!;
await page.mouse.move(width / 2, height / 2);
await page.mouse.wheel(0, -1);
await expect.poll(async () => await imageLocator(page).getAttribute('src')).toContain('fullsize');
await fullsizeResponse;
const original = page.getByTestId('original').filter({ visible: true });
await expect(original).toHaveAttribute('src', /fullsize/);
});
test('reloads photo when checksum changes', async ({ page }) => {
await page.goto(`/photos/${asset.id}`);
await expect.poll(async () => await imageLocator(page).getAttribute('src')).toContain('thumbnail');
const initialSrc = await imageLocator(page).getAttribute('src');
const preview = page.getByTestId('preview').filter({ visible: true });
await expect(preview).toHaveAttribute('src', /.+/);
const initialSrc = await preview.getAttribute('src');
const websocketEvent = utils.waitForWebsocketEvent({ event: 'assetUpdate', id: asset.id });
await utils.replaceAsset(admin.accessToken, asset.id);
await expect.poll(async () => await imageLocator(page).getAttribute('src')).not.toBe(initialSrc);
await websocketEvent;
await expect(preview).not.toHaveAttribute('src', initialSrc!);
});
});

6
e2e/src/ui/specs/asset-viewer/broken-asset.e2e-spec.ts
View File

@ -64,7 +64,9 @@ test.describe('broken-asset responsiveness', () => {
test('broken asset in main viewer shows icon and uses text-base', async ({ context, page }) => {
await context.route(
(url) => url.pathname.includes(`/api/assets/${fixture.primaryAsset.id}/thumbnail`),
(url) =>
url.pathname.includes(`/api/assets/${fixture.primaryAsset.id}/thumbnail`) ||
url.pathname.includes(`/api/assets/${fixture.primaryAsset.id}/original`),
async (route) => {
return route.fulfill({ status: 404 });
},
@ -73,7 +75,7 @@ test.describe('broken-asset responsiveness', () => {
await page.goto(`/photos/${fixture.primaryAsset.id}`);
await page.waitForSelector('#immich-asset-viewer');
const viewerBrokenAsset = page.locator('#immich-asset-viewer #broken-asset [data-broken-asset]');
const viewerBrokenAsset = page.locator('[data-viewer-content] [data-broken-asset]').first();
await expect(viewerBrokenAsset).toBeVisible();
await expect(viewerBrokenAsset.locator('svg')).toBeVisible();

25
web/src/lib/actions/image-loader.svelte.ts Normal file
View File

@ -0,0 +1,25 @@
import { cancelImageUrl } from '$lib/utils/sw-messaging';
export function loadImage(src: string, onLoad: () => void, onError: () => void, onStart?: () => void) {
let destroyed = false;
const handleLoad = () => !destroyed && onLoad();
const handleError = () => !destroyed && onError();
const img = document.createElement('img');
img.addEventListener('load', handleLoad);
img.addEventListener('error', handleError);
onStart?.();
img.src = src;
return () => {
destroyed = true;
img.removeEventListener('load', handleLoad);
img.removeEventListener('error', handleError);
cancelImageUrl(src);
img.remove();
};
}
export type LoadImageFunction = typeof loadImage;

6
web/src/lib/actions/zoom-image.ts
View File

@ -2,7 +2,11 @@ import { assetViewerManager } from '$lib/managers/asset-viewer-manager.svelte';
import { createZoomImageWheel } from '@zoom-image/core';
export const zoomImageAction = (node: HTMLElement, options?: { disabled?: boolean }) => {
const zoomInstance = createZoomImageWheel(node, { maxZoom: 10, initialState: assetViewerManager.zoomState });
const zoomInstance = createZoomImageWheel(node, {
maxZoom: 10,
initialState: assetViewerManager.zoomState,
zoomTarget: null,
});
const unsubscribes = [
assetViewerManager.on({ ZoomChange: (state) => zoomInstance.setState(state) }),

224
web/src/lib/components/AdaptiveImage.svelte Normal file
View File

@ -0,0 +1,224 @@
<script lang="ts">
import { thumbhash } from '$lib/actions/thumbhash';
import AlphaBackground from '$lib/components/AlphaBackground.svelte';
import BrokenAsset from '$lib/components/assets/broken-asset.svelte';
import DelayedLoadingSpinner from '$lib/components/DelayedLoadingSpinner.svelte';
import ImageLayer from '$lib/components/ImageLayer.svelte';
import { assetViewerManager } from '$lib/managers/asset-viewer-manager.svelte';
import { getAssetUrls } from '$lib/utils';
import { AdaptiveImageLoader, type QualityList } from '$lib/utils/adaptive-image-loader.svelte';
import { scaleToCover, scaleToFit } from '$lib/utils/container-utils';
import { getAltText } from '$lib/utils/thumbnail-util';
import { toTimelineAsset } from '$lib/utils/timeline-util';
import type { AssetResponseDto, SharedLinkResponseDto } from '@immich/sdk';
import { untrack, type Snippet } from 'svelte';
type Props = {
asset: AssetResponseDto;
sharedLink?: SharedLinkResponseDto;
objectFit?: 'contain' | 'cover';
container: {
width: number;
height: number;
};
onUrlChange?: (url: string) => void;
onImageReady?: () => void;
onError?: () => void;
ref?: HTMLDivElement;
imgRef?: HTMLImageElement;
backdrop?: Snippet;
overlays?: Snippet;
};
let {
ref = $bindable(),
// eslint-disable-next-line no-useless-assignment
imgRef = $bindable(),
asset,
sharedLink,
objectFit = 'contain',
container,
onUrlChange,
onImageReady,
onError,
backdrop,
overlays,
}: Props = $props();
const afterThumbnail = (loader: AdaptiveImageLoader) => {
if (assetViewerManager.zoom > 1) {
loader.trigger('original');
} else {
loader.trigger('preview');
}
};
const buildQualityList = () => {
const assetUrls = getAssetUrls(asset, sharedLink);
const qualityList: QualityList = [
{
quality: 'thumbnail',
url: assetUrls.thumbnail,
onAfterLoad: afterThumbnail,
onAfterError: afterThumbnail,
},
{
quality: 'preview',
url: assetUrls.preview,
onAfterError: (loader) => loader.trigger('original'),
},
{ quality: 'original', url: assetUrls.original },
];
return qualityList;
};
const loaderKey = $derived(`${asset.id}:${asset.thumbhash}:${sharedLink?.id}`);
const adaptiveImageLoader = $derived.by(() => {
void loaderKey;
return untrack(
() =>
new AdaptiveImageLoader(buildQualityList(), {
onImageReady,
onError,
onUrlChange,
}),
);
});
$effect.pre(() => {
const loader = adaptiveImageLoader;
untrack(() => assetViewerManager.resetZoomState());
return () => loader.destroy();
});
const imageDimensions = $derived.by(() => {
const { width, height } = asset;
if (width && width > 0 && height && height > 0) {
return { width, height };
}
return { width: 1, height: 1 };
});
const { width, height, left, top } = $derived.by(() => {
const scaleFn = objectFit === 'cover' ? scaleToCover : scaleToFit;
const { width, height } = scaleFn(imageDimensions, container);
return {
width: width + 'px',
height: height + 'px',
left: (container.width - width) / 2 + 'px',
top: (container.height - height) / 2 + 'px',
};
});
const { status } = $derived(adaptiveImageLoader);
const alt = $derived(status.urls.preview ? $getAltText(toTimelineAsset(asset)) : '');
const show = $derived.by(() => {
const { quality, started, hasError, urls } = status;
return {
alphaBackground: !hasError && started,
spinner: !asset.thumbhash && !started,
brokenAsset: hasError,
thumbhash: quality.thumbnail !== 'success' && quality.preview !== 'success' && quality.original !== 'success',
thumbnail: quality.thumbnail !== 'error' && quality.preview !== 'success' && quality.original !== 'success',
preview: quality.preview !== 'error' && quality.original !== 'success',
original: quality.original !== 'error' && urls.original !== undefined,
};
});
$effect(() => {
if (assetViewerManager.zoom > 1 && status.quality.original !== 'success') {
untrack(() => void adaptiveImageLoader.trigger('original'));
}
});
let thumbnailElement = $state<HTMLImageElement>();
let previewElement = $state<HTMLImageElement>();
let originalElement = $state<HTMLImageElement>();
$effect(() => {
const quality = status.quality;
imgRef =
(quality.original === 'success' ? originalElement : undefined) ??
(quality.preview === 'success' ? previewElement : undefined) ??
(quality.thumbnail === 'success' ? thumbnailElement : undefined);
});
const zoomTransform = $derived.by(() => {
const { currentZoom, currentPositionX, currentPositionY } = assetViewerManager.zoomState;
if (currentZoom === 1 && currentPositionX === 0 && currentPositionY === 0) {
return undefined;
}
return `translate(${currentPositionX}px, ${currentPositionY}px) scale(${currentZoom})`;
});
</script>
<div class="relative h-full w-full overflow-hidden will-change-transform" bind:this={ref}>
{@render backdrop?.()}
<div
class="absolute inset-0"
style:transform={zoomTransform}
style:transform-origin={zoomTransform ? '0 0' : undefined}
>
<div class="absolute" style:left style:top style:width style:height>
{#if show.alphaBackground}
<AlphaBackground />
{/if}
{#if show.thumbhash}
{#if asset.thumbhash}
<!-- Thumbhash / spinner layer -->
<canvas use:thumbhash={{ base64ThumbHash: asset.thumbhash }} class="h-full w-full absolute"></canvas>
{:else if show.spinner}
<DelayedLoadingSpinner />
{/if}
{/if}
{#if show.thumbnail}
<ImageLayer
{adaptiveImageLoader}
{width}
{height}
quality="thumbnail"
src={status.urls.thumbnail}
alt=""
role="presentation"
bind:ref={thumbnailElement}
/>
{/if}
{#if show.brokenAsset}
<BrokenAsset class="text-xl h-full w-full absolute" />
{/if}
{#if show.preview}
<ImageLayer
{adaptiveImageLoader}
{alt}
{width}
{height}
{overlays}
quality="preview"
src={status.urls.preview}
bind:ref={previewElement}
/>
{/if}
{#if show.original}
<ImageLayer
{adaptiveImageLoader}
{alt}
{width}
{height}
{overlays}
quality="original"
src={status.urls.original}
bind:ref={originalElement}
/>
{/if}
</div>
</div>
</div>

11
web/src/lib/components/AlphaBackground.svelte Normal file
View File

@ -0,0 +1,11 @@
<script lang="ts">
import type { ClassValue } from 'svelte/elements';
interface Props {
class?: ClassValue;
}
let { class: className = '' }: Props = $props();
</script>
<div class="absolute h-full w-full bg-gray-300 dark:bg-gray-700 {className}"></div>

20
web/src/lib/components/DelayedLoadingSpinner.svelte Normal file
View File

@ -0,0 +1,20 @@
<script lang="ts">
import { LoadingSpinner } from '@immich/ui';
</script>
<div class="delayed-spinner absolute flex h-full items-center justify-center">
<LoadingSpinner />
</div>
<style>
@keyframes delayedVisibility {
to {
visibility: visible;
}
}
.delayed-spinner {
visibility: hidden;
animation: 0s linear 0.4s forwards delayedVisibility;
}
</style>

47
web/src/lib/components/ImageLayer.svelte Normal file
View File

@ -0,0 +1,47 @@
<script lang="ts">
import Image from '$lib/components/Image.svelte';
import type { AdaptiveImageLoader, ImageQuality } from '$lib/utils/adaptive-image-loader.svelte';
import type { Snippet } from 'svelte';
type Props = {
adaptiveImageLoader: AdaptiveImageLoader;
quality: ImageQuality;
src: string | undefined;
alt?: string;
role?: string;
ref?: HTMLImageElement;
width: string;
height: string;
overlays?: Snippet;
};
let {
adaptiveImageLoader,
quality,
src,
alt = '',
role,
ref = $bindable(),
width,
height,
overlays,
}: Props = $props();
</script>
{#key adaptiveImageLoader}
<div class="absolute top-0" style:width style:height>
<Image
{src}
onStart={() => adaptiveImageLoader.onStart(quality)}
onLoad={() => adaptiveImageLoader.onLoad(quality)}
onError={() => adaptiveImageLoader.onError(quality)}
bind:ref
class="h-full w-full bg-transparent"
{alt}
{role}
draggable={false}
data-testid={quality}
/>
{@render overlays?.()}
</div>
{/key}

104
web/src/lib/components/asset-viewer/PreloadManager.svelte.ts Normal file
View File

@ -0,0 +1,104 @@
import { loadImage } from '$lib/actions/image-loader.svelte';
import { getAssetUrls } from '$lib/utils';
import { AdaptiveImageLoader, type QualityList } from '$lib/utils/adaptive-image-loader.svelte';
import type { AssetResponseDto, SharedLinkResponseDto } from '@immich/sdk';
type AssetCursor = {
current: AssetResponseDto;
nextAsset?: AssetResponseDto;
previousAsset?: AssetResponseDto;
};
export class PreloadManager {
private nextPreloader: AdaptiveImageLoader | undefined;
private previousPreloader: AdaptiveImageLoader | undefined;
private startPreloader(
asset: AssetResponseDto | undefined,
sharedlink: SharedLinkResponseDto | undefined,
): AdaptiveImageLoader | undefined {
if (!asset) {
return;
}
const urls = getAssetUrls(asset, sharedlink);
const afterThumbnail = (loader: AdaptiveImageLoader) => loader.trigger('preview');
const qualityList: QualityList = [
{
quality: 'thumbnail',
url: urls.thumbnail,
onAfterLoad: afterThumbnail,
onAfterError: afterThumbnail,
},
{
quality: 'preview',
url: urls.preview,
onAfterError: (loader) => loader.trigger('original'),
},
{ quality: 'original', url: urls.original },
];
const loader = new AdaptiveImageLoader(qualityList, undefined, loadImage);
loader.start();
return loader;
}
private destroyPreviousPreloader() {
this.previousPreloader?.destroy();
this.previousPreloader = undefined;
}
private destroyNextPreloader() {
this.nextPreloader?.destroy();
this.nextPreloader = undefined;
}
cancelBeforeNavigation(direction: 'previous' | 'next') {
switch (direction) {
case 'next': {
this.destroyPreviousPreloader();
break;
}
case 'previous': {
this.destroyNextPreloader();
break;
}
}
}
updateAfterNavigation(oldCursor: AssetCursor, newCursor: AssetCursor, sharedlink: SharedLinkResponseDto | undefined) {
const movedForward = newCursor.current.id === oldCursor.nextAsset?.id;
const movedBackward = newCursor.current.id === oldCursor.previousAsset?.id;
if (!movedBackward) {
this.destroyPreviousPreloader();
}
if (!movedForward) {
this.destroyNextPreloader();
}
if (movedForward) {
this.nextPreloader = this.startPreloader(newCursor.nextAsset, sharedlink);
} else if (movedBackward) {
this.previousPreloader = this.startPreloader(newCursor.previousAsset, sharedlink);
} else {
this.previousPreloader = this.startPreloader(newCursor.previousAsset, sharedlink);
this.nextPreloader = this.startPreloader(newCursor.nextAsset, sharedlink);
}
}
initializePreloads(cursor: AssetCursor, sharedlink: SharedLinkResponseDto | undefined) {
if (cursor.nextAsset) {
this.nextPreloader = this.startPreloader(cursor.nextAsset, sharedlink);
}
if (cursor.previousAsset) {
this.previousPreloader = this.startPreloader(cursor.previousAsset, sharedlink);
}
}
destroy() {
this.destroyNextPreloader();
this.destroyPreviousPreloader();
}
}
export const preloadManager = new PreloadManager();

181
web/src/lib/components/asset-viewer/asset-viewer.svelte
View File

@ -5,15 +5,16 @@
import NextAssetAction from '$lib/components/asset-viewer/actions/next-asset-action.svelte';
import PreviousAssetAction from '$lib/components/asset-viewer/actions/previous-asset-action.svelte';
import AssetViewerNavBar from '$lib/components/asset-viewer/asset-viewer-nav-bar.svelte';
import { preloadManager } from '$lib/components/asset-viewer/PreloadManager.svelte';
import { AssetAction, ProjectionType } from '$lib/constants';
import { activityManager } from '$lib/managers/activity-manager.svelte';
import { assetViewerManager } from '$lib/managers/asset-viewer-manager.svelte';
import { authManager } from '$lib/managers/auth-manager.svelte';
import { editManager, EditToolType } from '$lib/managers/edit/edit-manager.svelte';
import { eventManager } from '$lib/managers/event-manager.svelte';
import { imageManager } from '$lib/managers/ImageManager.svelte';
import { getAssetActions } from '$lib/services/asset.service';
import { assetViewingStore } from '$lib/stores/asset-viewing.store';
import { isFaceEditMode } from '$lib/stores/face-edit.svelte';
import { ocrManager } from '$lib/stores/ocr.svelte';
import { alwaysLoadOriginalVideo } from '$lib/stores/preferences.store';
import { SlideshowNavigation, SlideshowState, slideshowStore } from '$lib/stores/slideshow.store';
@ -36,6 +37,7 @@
} from '@immich/sdk';
import { CommandPaletteDefaultProvider } from '@immich/ui';
import { onDestroy, onMount, untrack } from 'svelte';
import type { SwipeCustomEvent } from 'svelte-gestures';
import { t } from 'svelte-i18n';
import { fly } from 'svelte/transition';
import Thumbnail from '../assets/thumbnail/thumbnail.svelte';
@ -92,20 +94,19 @@
stopProgress: stopSlideshowProgress,
slideshowNavigation,
slideshowState,
slideshowTransition,
slideshowRepeat,
} = slideshowStore;
const stackThumbnailSize = 60;
const stackSelectedThumbnailSize = 65;
const asset = $derived(cursor.current);
let previewStackedAsset: AssetResponseDto | undefined = $state();
let stack: StackResponseDto | null = $state(null);
const asset = $derived(previewStackedAsset ?? cursor.current);
const nextAsset = $derived(cursor.nextAsset);
const previousAsset = $derived(cursor.previousAsset);
let sharedLink = getSharedLink();
let previewStackedAsset: AssetResponseDto | undefined = $state();
let fullscreenElement = $state<Element>();
let unsubscribes: (() => void)[] = [];
let stack: StackResponseDto | null = $state(null);
let playOriginalVideo = $state($alwaysLoadOriginalVideo);
let slideshowStartAssetId = $state<string>();
@ -115,7 +116,7 @@
};
const refreshStack = async () => {
if (authManager.isSharedLink) {
if (authManager.isSharedLink || !withStacked) {
return;
}
@ -126,51 +127,50 @@
if (!stack?.assets.some(({ id }) => id === asset.id)) {
stack = null;
}
untrack(() => {
imageManager.preload(stack?.assets[1]);
});
};
const handleFavorite = async () => {
if (album && album.isActivityEnabled) {
try {
await activityManager.toggleLike();
} catch (error) {
handleError(error, $t('errors.unable_to_change_favorite'));
}
if (!album || !album.isActivityEnabled) {
return;
}
try {
await activityManager.toggleLike();
} catch (error) {
handleError(error, $t('errors.unable_to_change_favorite'));
}
};
onMount(() => {
syncAssetViewerOpenClass(true);
unsubscribes.push(
slideshowState.subscribe((value) => {
if (value === SlideshowState.PlaySlideshow) {
slideshowHistory.reset();
slideshowHistory.queue(toTimelineAsset(asset));
handlePromiseError(handlePlaySlideshow());
} else if (value === SlideshowState.StopSlideshow) {
handlePromiseError(handleStopSlideshow());
}
}),
slideshowNavigation.subscribe((value) => {
if (value === SlideshowNavigation.Shuffle) {
slideshowHistory.reset();
slideshowHistory.queue(toTimelineAsset(asset));
}
}),
);
const slideshowStateUnsubscribe = slideshowState.subscribe((value) => {
if (value === SlideshowState.PlaySlideshow) {
slideshowHistory.reset();
slideshowHistory.queue(toTimelineAsset(asset));
handlePromiseError(handlePlaySlideshow());
} else if (value === SlideshowState.StopSlideshow) {
handlePromiseError(handleStopSlideshow());
}
});
const slideshowNavigationUnsubscribe = slideshowNavigation.subscribe((value) => {
if (value === SlideshowNavigation.Shuffle) {
slideshowHistory.reset();
slideshowHistory.queue(toTimelineAsset(asset));
}
});
return () => {
slideshowStateUnsubscribe();
slideshowNavigationUnsubscribe();
};
});
onDestroy(() => {
for (const unsubscribe of unsubscribes) {
unsubscribe();
}
activityManager.reset();
assetViewerManager.closeEditor();
syncAssetViewerOpenClass(false);
preloadManager.destroy();
});
const closeViewer = () => {
@ -187,8 +187,7 @@
};
const tracker = new InvocationTracker();
const navigateAsset = (order?: 'previous' | 'next', e?: Event) => {
const navigateAsset = (order?: 'previous' | 'next') => {
if (!order) {
if ($slideshowState === SlideshowState.PlaySlideshow) {
order = $slideshowNavigation === SlideshowNavigation.AscendingOrder ? 'previous' : 'next';
@ -197,16 +196,19 @@
}
}
e?.stopPropagation();
imageManager.cancel(asset);
preloadManager.cancelBeforeNavigation(order);
if (tracker.isActive()) {
return;
}
void tracker.invoke(async () => {
const isShuffle =
$slideshowState === SlideshowState.PlaySlideshow && $slideshowNavigation === SlideshowNavigation.Shuffle;
let hasNext: boolean;
if ($slideshowState === SlideshowState.PlaySlideshow && $slideshowNavigation === SlideshowNavigation.Shuffle) {
if (isShuffle) {
hasNext = order === 'previous' ? slideshowHistory.previous() : slideshowHistory.next();
if (!hasNext) {
const asset = await onRandom?.();
@ -220,17 +222,22 @@
order === 'previous' ? await navigateToAsset(cursor.previousAsset) : await navigateToAsset(cursor.nextAsset);
}
if ($slideshowState === SlideshowState.PlaySlideshow) {
if (hasNext) {
$restartSlideshowProgress = true;
} else if ($slideshowRepeat && slideshowStartAssetId) {
// Loop back to starting asset
await setAssetId(slideshowStartAssetId);
$restartSlideshowProgress = true;
} else {
await handleStopSlideshow();
}
if ($slideshowState !== SlideshowState.PlaySlideshow) {
return;
}
if (hasNext) {
$restartSlideshowProgress = true;
return;
}
if ($slideshowRepeat && slideshowStartAssetId) {
await setAssetId(slideshowStartAssetId);
$restartSlideshowProgress = true;
return;
}
await handleStopSlideshow();
}, $t('error_while_navigating'));
};
@ -274,12 +281,14 @@
}
};
const handleStackedAssetMouseEvent = (isMouseOver: boolean, asset: AssetResponseDto) => {
previewStackedAsset = isMouseOver ? asset : undefined;
const handleStackedAssetMouseEvent = (isMouseOver: boolean, stackedAsset: AssetResponseDto) => {
previewStackedAsset = isMouseOver ? stackedAsset : undefined;
};
const handlePreAction = (action: Action) => {
preAction?.(action);
};
const handleAction = async (action: Action) => {
switch (action.type) {
case AssetAction.DELETE:
@ -352,17 +361,31 @@
await ocrManager.getAssetOcr(asset.id);
}
};
$effect(() => {
// eslint-disable-next-line @typescript-eslint/no-unused-expressions
asset;
untrack(() => handlePromiseError(refresh()));
imageManager.preload(cursor.nextAsset);
imageManager.preload(cursor.previousAsset);
});
let lastCursor = $state<AssetCursor>();
$effect(() => {
if (cursor.current.id === lastCursor?.current.id) {
return;
}
if (lastCursor) {
preloadManager.updateAfterNavigation(lastCursor, cursor, sharedLink);
}
if (!lastCursor) {
preloadManager.initializePreloads(cursor, sharedLink);
}
lastCursor = cursor;
});
const viewerKind = $derived.by(() => {
if (previewStackedAsset) {
return previewStackedAsset.type === AssetTypeEnum.Image ? 'StackPhotoViewer' : 'StackVideoViewer';
return previewStackedAsset.type === AssetTypeEnum.Image ? 'PhotoViewer' : 'StackVideoViewer';
}
if (asset.type === AssetTypeEnum.Video) {
return 'VideoViewer';
@ -403,6 +426,24 @@
assetViewerManager.isShowDetailPanel &&
!assetViewerManager.isShowEditor,
);
const onSwipe = (event: SwipeCustomEvent) => {
if (assetViewerManager.zoom > 1) {
return;
}
if (ocrManager.showOverlay) {
return;
}
if (event.detail.direction === 'left') {
navigateAsset('next');
}
if (event.detail.direction === 'right') {
navigateAsset('previous');
}
};
</script>
<CommandPaletteDefaultProvider name={$t('assets')} actions={[Tag]} />
@ -448,23 +489,15 @@
</div>
{/if}
{#if $slideshowState === SlideshowState.None && showNavigation && !assetViewerManager.isShowEditor && previousAsset}
{#if $slideshowState === SlideshowState.None && showNavigation && !assetViewerManager.isShowEditor && !isFaceEditMode.value && previousAsset}
<div class="my-auto col-span-1 col-start-1 row-span-full row-start-1 justify-self-start">
<PreviousAssetAction onPreviousAsset={() => navigateAsset('previous')} />
</div>
{/if}
<!-- Asset Viewer -->
<div class="z-[-1] relative col-start-1 col-span-4 row-start-1 row-span-full">
{#if viewerKind === 'StackPhotoViewer'}
<PhotoViewer
cursor={{ ...cursor, current: previewStackedAsset! }}
onPreviousAsset={() => navigateAsset('previous')}
onNextAsset={() => navigateAsset('next')}
haveFadeTransition={false}
{sharedLink}
/>
{:else if viewerKind === 'StackVideoViewer'}
<div data-viewer-content class="z-[-1] relative col-start-1 col-span-4 row-start-1 row-span-full">
{#if viewerKind === 'StackVideoViewer'}
<VideoViewer
asset={previewStackedAsset!}
cacheKey={previewStackedAsset!.thumbhash}
@ -494,13 +527,7 @@
{:else if viewerKind === 'CropArea'}
<CropArea {asset} />
{:else if viewerKind === 'PhotoViewer'}
<PhotoViewer
{cursor}
onPreviousAsset={() => navigateAsset('previous')}
onNextAsset={() => navigateAsset('next')}
{sharedLink}
haveFadeTransition={$slideshowState !== SlideshowState.None && $slideshowTransition}
/>
<PhotoViewer cursor={{ ...cursor, current: asset }} {sharedLink} {onSwipe} />
{:else if viewerKind === 'VideoViewer'}
<VideoViewer
{asset}
@ -535,7 +562,7 @@
{/if}
</div>
{#if $slideshowState === SlideshowState.None && showNavigation && !assetViewerManager.isShowEditor && nextAsset}
{#if $slideshowState === SlideshowState.None && showNavigation && !assetViewerManager.isShowEditor && !isFaceEditMode.value && nextAsset}
<div class="my-auto col-span-1 col-start-4 row-span-full row-start-1 justify-self-end">
<NextAssetAction onNextAsset={() => navigateAsset('next')} />
</div>

37
web/src/lib/components/asset-viewer/face-editor/face-editor.svelte
View File

@ -3,7 +3,7 @@
import { assetViewingStore } from '$lib/stores/asset-viewing.store';
import { isFaceEditMode } from '$lib/stores/face-edit.svelte';
import { getPeopleThumbnailUrl } from '$lib/utils';
import { getContentMetrics, getNaturalSize } from '$lib/utils/container-utils';
import { getNaturalSize, scaleToFit } from '$lib/utils/container-utils';
import { handleError } from '$lib/utils/handle-error';
import { createFace, getAllPeople, type PersonResponseDto } from '@immich/sdk';
import { Button, Input, modalManager, toastManager } from '@immich/ui';
@ -81,15 +81,20 @@
await getPeople();
});
$effect(() => {
const metrics = getContentMetrics(htmlElement);
const imageBoundingBox = {
top: metrics.offsetY,
left: metrics.offsetX,
width: metrics.contentWidth,
height: metrics.contentHeight,
const imageContentMetrics = $derived.by(() => {
const natural = getNaturalSize(htmlElement);
const container = { width: containerWidth, height: containerHeight };
const { width: contentWidth, height: contentHeight } = scaleToFit(natural, container);
return {
contentWidth,
contentHeight,
offsetX: (containerWidth - contentWidth) / 2,
offsetY: (containerHeight - contentHeight) / 2,
};
});
$effect(() => {
const { offsetX, offsetY } = imageContentMetrics;
if (!canvas) {
return;
@ -105,8 +110,8 @@
}
faceRect.set({
top: imageBoundingBox.top + 200,
left: imageBoundingBox.left + 200,
top: offsetY + 200,
left: offsetX + 200,
});
faceRect.setCoords();
@ -214,13 +219,13 @@
}
const { left, top, width, height } = faceRect.getBoundingRect();
const metrics = getContentMetrics(htmlElement);
const { offsetX, offsetY, contentWidth, contentHeight } = imageContentMetrics;
const natural = getNaturalSize(htmlElement);
const scaleX = natural.width / metrics.contentWidth;
const scaleY = natural.height / metrics.contentHeight;
const imageX = (left - metrics.offsetX) * scaleX;
const imageY = (top - metrics.offsetY) * scaleY;
const scaleX = natural.width / contentWidth;
const scaleY = natural.height / contentHeight;
const imageX = (left - offsetX) * scaleX;
const imageY = (top - offsetY) * scaleY;
return {
imageWidth: natural.width,

224
web/src/lib/components/asset-viewer/photo-viewer.svelte
View File

@ -1,66 +1,56 @@
<script lang="ts">
import { shortcuts } from '$lib/actions/shortcut';
import { thumbhash } from '$lib/actions/thumbhash';
import { zoomImageAction } from '$lib/actions/zoom-image';
import AdaptiveImage from '$lib/components/AdaptiveImage.svelte';
import FaceEditor from '$lib/components/asset-viewer/face-editor/face-editor.svelte';
import OcrBoundingBox from '$lib/components/asset-viewer/ocr-bounding-box.svelte';
import BrokenAsset from '$lib/components/assets/broken-asset.svelte';
import AssetViewerEvents from '$lib/components/AssetViewerEvents.svelte';
import { assetViewerFadeDuration } from '$lib/constants';
import { assetViewerManager } from '$lib/managers/asset-viewer-manager.svelte';
import { castManager } from '$lib/managers/cast-manager.svelte';
import { imageManager } from '$lib/managers/ImageManager.svelte';
import { isFaceEditMode } from '$lib/stores/face-edit.svelte';
import { ocrManager } from '$lib/stores/ocr.svelte';
import { boundingBoxesArray, type Faces } from '$lib/stores/people.store';
import { SlideshowLook, SlideshowState, slideshowLookCssMapping, slideshowStore } from '$lib/stores/slideshow.store';
import { getAssetUrl, targetImageSize as getTargetImageSize, handlePromiseError } from '$lib/utils';
import { SlideshowLook, SlideshowState, slideshowStore } from '$lib/stores/slideshow.store';
import { handlePromiseError } from '$lib/utils';
import { canCopyImageToClipboard, copyImageToClipboard } from '$lib/utils/asset-utils';
import { type ContentMetrics, getContentMetrics } from '$lib/utils/container-utils';
import { getNaturalSize, scaleToFit, type ContentMetrics } from '$lib/utils/container-utils';
import { handleError } from '$lib/utils/handle-error';
import { getOcrBoundingBoxes } from '$lib/utils/ocr-utils';
import { getBoundingBox } from '$lib/utils/people-utils';
import { getAltText } from '$lib/utils/thumbnail-util';
import { toTimelineAsset } from '$lib/utils/timeline-util';
import { AssetMediaSize, type SharedLinkResponseDto } from '@immich/sdk';
import { LoadingSpinner, toastManager } from '@immich/ui';
import { type SharedLinkResponseDto } from '@immich/sdk';
import { toastManager } from '@immich/ui';
import { onDestroy, untrack } from 'svelte';
import { useSwipe, type SwipeCustomEvent } from 'svelte-gestures';
import { t } from 'svelte-i18n';
import { fade } from 'svelte/transition';
import type { AssetCursor } from './asset-viewer.svelte';
interface Props {
cursor: AssetCursor;
element?: HTMLDivElement | undefined;
haveFadeTransition?: boolean;
sharedLink?: SharedLinkResponseDto | undefined;
onPreviousAsset?: (() => void) | null;
onNextAsset?: (() => void) | null;
element?: HTMLDivElement;
sharedLink?: SharedLinkResponseDto;
onReady?: () => void;
onError?: () => void;
onSwipe?: (event: SwipeCustomEvent) => void;
}
let {
cursor,
element = $bindable(),
haveFadeTransition = true,
sharedLink = undefined,
onPreviousAsset = null,
onNextAsset = null,
}: Props = $props();
let { cursor, element = $bindable(), sharedLink, onReady, onError, onSwipe }: Props = $props();
const { slideshowState, slideshowLook } = slideshowStore;
const asset = $derived(cursor.current);
let imageLoaded: boolean = $state(false);
let originalImageLoaded: boolean = $state(false);
let imageError: boolean = $state(false);
let visibleImageReady: boolean = $state(false);
let loader = $state<HTMLImageElement>();
let previousAssetId: string | undefined;
$effect.pre(() => {
void asset.id;
const id = asset.id;
if (id === previousAssetId) {
return;
}
previousAssetId = id;
untrack(() => {
assetViewerManager.resetZoomState();
visibleImageReady = false;
$boundingBoxesArray = [];
});
});
@ -69,25 +59,30 @@
$boundingBoxesArray = [];
});
let containerWidth = $state(0);
let containerHeight = $state(0);
const container = $derived({
width: containerWidth,
height: containerHeight,
});
const overlayMetrics = $derived.by((): ContentMetrics => {
if (!assetViewerManager.imgRef || !visibleImageReady) {
return { contentWidth: 0, contentHeight: 0, offsetX: 0, offsetY: 0 };
}
const { contentWidth, contentHeight, offsetX, offsetY } = getContentMetrics(assetViewerManager.imgRef);
const { currentZoom, currentPositionX, currentPositionY } = assetViewerManager.zoomState;
const natural = getNaturalSize(assetViewerManager.imgRef);
const scaled = scaleToFit(natural, container);
return {
contentWidth: contentWidth * currentZoom,
contentHeight: contentHeight * currentZoom,
offsetX: offsetX * currentZoom + currentPositionX,
offsetY: offsetY * currentZoom + currentPositionY,
contentWidth: scaled.width,
contentHeight: scaled.height,
offsetX: 0,
offsetY: 0,
};
});
let ocrBoxes = $derived(ocrManager.showOverlay ? getOcrBoundingBoxes(ocrManager.data, overlayMetrics) : []);
let isOcrActive = $derived(ocrManager.showOverlay);
const ocrBoxes = $derived(ocrManager.showOverlay ? getOcrBoundingBoxes(ocrManager.data, overlayMetrics) : []);
const onCopy = async () => {
if (!canCopyImageToClipboard() || !assetViewerManager.imgRef) {
@ -124,29 +119,15 @@
handlePromiseError(onCopy());
};
const onSwipe = (event: SwipeCustomEvent) => {
if (assetViewerManager.zoom > 1) {
return;
}
let currentPreviewUrl = $state<string>();
if (ocrManager.showOverlay) {
return;
}
if (onNextAsset && event.detail.direction === 'left') {
onNextAsset();
}
if (onPreviousAsset && event.detail.direction === 'right') {
onPreviousAsset();
}
const onUrlChange = (url: string) => {
currentPreviewUrl = url;
};
const targetImageSize = $derived(getTargetImageSize(asset, originalImageLoaded || assetViewerManager.zoom > 1));
$effect(() => {
if (imageLoaderUrl) {
void cast(imageLoaderUrl);
if (currentPreviewUrl) {
void cast(currentPreviewUrl);
}
});
@ -164,38 +145,10 @@
}
};
const onload = () => {
imageLoaded = true;
originalImageLoaded = targetImageSize === AssetMediaSize.Fullsize || targetImageSize === 'original';
};
const onerror = () => {
imageError = imageLoaded = true;
};
onDestroy(() => imageManager.cancel(asset, targetImageSize));
let imageLoaderUrl = $derived(
getAssetUrl({ asset, sharedLink, forceOriginal: originalImageLoaded || assetViewerManager.zoom > 1 }),
const blurredSlideshow = $derived(
$slideshowState !== SlideshowState.None && $slideshowLook === SlideshowLook.BlurredBackground && !!asset.thumbhash,
);
let containerWidth = $state(0);
let containerHeight = $state(0);
let lastUrl: string | undefined;
$effect(() => {
if (lastUrl && lastUrl !== imageLoaderUrl) {
untrack(() => {
imageLoaded = false;
originalImageLoaded = false;
imageError = false;
visibleImageReady = false;
});
}
lastUrl = imageLoaderUrl;
});
const faceToNameMap = $derived.by(() => {
// eslint-disable-next-line svelte/prefer-svelte-reactivity
const map = new Map<Faces, string>();
@ -215,9 +168,16 @@
return;
}
const natural = getNaturalSize(assetViewerManager.imgRef);
const scaled = scaleToFit(natural, container);
const { currentZoom, currentPositionX, currentPositionY } = assetViewerManager.zoomState;
const contentOffsetX = (container.width - scaled.width) / 2;
const contentOffsetY = (container.height - scaled.height) / 2;
const containerRect = element.getBoundingClientRect();
const mouseX = event.clientX - containerRect.left;
const mouseY = event.clientY - containerRect.top;
const mouseX = (event.clientX - containerRect.left - contentOffsetX * currentZoom - currentPositionX) / currentZoom;
const mouseY = (event.clientY - containerRect.top - contentOffsetY * currentZoom - currentPositionY) / currentZoom;
const faceBoxes = getBoundingBox(faces, overlayMetrics);
@ -243,12 +203,7 @@
{ shortcut: { key: 'c', meta: true }, onShortcut: onCopyShortcut, preventDefault: false },
]}
/>
{#if imageError}
<div id="broken-asset" class="h-full w-full">
<BrokenAsset class="text-xl h-full w-full" />
</div>
{/if}
<img bind:this={loader} style="display:none" src={imageLoaderUrl} alt="" aria-hidden="true" {onload} {onerror} />
<div
bind:this={element}
class="relative h-full w-full select-none"
@ -258,36 +213,34 @@
ondblclick={onZoom}
onmousemove={handleImageMouseMove}
onmouseleave={handleImageMouseLeave}
use:zoomImageAction={{ disabled: isFaceEditMode.value || ocrManager.showOverlay }}
{...useSwipe((event) => onSwipe?.(event))}
>
{#if !imageLoaded}
<div id="spinner" class="flex h-full items-center justify-center">
<LoadingSpinner />
</div>
{:else if !imageError}
<div
use:zoomImageAction={{ disabled: isOcrActive }}
{...useSwipe(onSwipe)}
class="h-full w-full"
transition:fade={{ duration: haveFadeTransition ? assetViewerFadeDuration : 0 }}
>
{#if $slideshowState !== SlideshowState.None && $slideshowLook === SlideshowLook.BlurredBackground}
<img
src={imageLoaderUrl}
alt=""
class="-z-1 absolute top-0 start-0 object-cover h-full w-full blur-lg"
draggable="false"
/>
<AdaptiveImage
{asset}
{sharedLink}
{container}
objectFit={$slideshowState !== SlideshowState.None && $slideshowLook === SlideshowLook.Cover ? 'cover' : 'contain'}
{onUrlChange}
onImageReady={() => {
visibleImageReady = true;
onReady?.();
}}
onError={() => {
onError?.();
onReady?.();
}}
bind:imgRef={assetViewerManager.imgRef}
>
{#snippet backdrop()}
{#if blurredSlideshow}
<canvas
use:thumbhash={{ base64ThumbHash: asset.thumbhash! }}
class="absolute top-0 left-0 inset-s-0 h-dvh w-dvw"
></canvas>
{/if}
<img
bind:this={assetViewerManager.imgRef}
src={imageLoaderUrl}
onload={() => (visibleImageReady = true)}
alt={$getAltText(toTimelineAsset(asset))}
class="h-full w-full {$slideshowState === SlideshowState.None
? 'object-contain'
: slideshowLookCssMapping[$slideshowLook]}"
draggable="false"
/>
{/snippet}
{#snippet overlays()}
{#each getBoundingBox($boundingBoxesArray, overlayMetrics) as boundingbox, index (boundingbox.id)}
<div
class="absolute border-solid border-white border-3 rounded-lg"
@ -307,23 +260,10 @@
{#each ocrBoxes as ocrBox (ocrBox.id)}
<OcrBoundingBox {ocrBox} />
{/each}
</div>
{/snippet}
</AdaptiveImage>
{#if isFaceEditMode.value}
<FaceEditor htmlElement={assetViewerManager.imgRef} {containerWidth} {containerHeight} assetId={asset.id} />
{/if}
{#if isFaceEditMode.value && assetViewerManager.imgRef}
<FaceEditor htmlElement={assetViewerManager.imgRef} {containerWidth} {containerHeight} assetId={asset.id} />
{/if}
</div>
<style>
@keyframes delayedVisibility {
to {
visibility: visible;
}
}
#broken-asset,
#spinner {
visibility: hidden;
animation: 0s linear 0.4s forwards delayedVisibility;
}
</style>

18
web/src/lib/components/memory-page/memory-photo-viewer.svelte
View File

@ -4,7 +4,7 @@
import { getAssetMediaUrl } from '$lib/utils';
import { getAltText } from '$lib/utils/thumbnail-util';
import { AssetMediaSize } from '@immich/sdk';
import { LoadingSpinner } from '@immich/ui';
import DelayedLoadingSpinner from '$lib/components/DelayedLoadingSpinner.svelte';
import { onMount } from 'svelte';
import { fade } from 'svelte/transition';
@ -44,9 +44,7 @@
{/if}
{#if !imageLoaded}
<div id="spinner" class="flex h-full items-center justify-center">
<LoadingSpinner />
</div>
<DelayedLoadingSpinner />
{:else if imageLoaded}
<div transition:fade={{ duration: assetViewerFadeDuration }} class="h-full w-full">
<img
@ -57,15 +55,3 @@
/>
</div>
{/if}
<style>
@keyframes delayedVisibility {
to {
visibility: visible;
}
}
#spinner {
visibility: hidden;
animation: 0s linear 0.4s forwards delayedVisibility;
}
</style>

99
web/src/lib/managers/ImageManager.spec.ts
View File

@ -1,99 +0,0 @@
import { imageManager } from '$lib/managers/ImageManager.svelte';
import { getAssetMediaUrl } from '$lib/utils';
import { cancelImageUrl } from '$lib/utils/sw-messaging';
import { AssetMediaSize } from '@immich/sdk';
import { assetFactory } from '@test-data/factories/asset-factory';
vi.mock('$lib/utils/sw-messaging', () => ({
cancelImageUrl: vi.fn(),
}));
vi.mock('$lib/utils', () => ({
getAssetMediaUrl: vi.fn(),
}));
describe('ImageManager', () => {
beforeEach(() => {
vi.clearAllMocks();
});
describe('preload', () => {
it('creates an Image with the correct URL', () => {
vi.mocked(getAssetMediaUrl).mockReturnValue('/api/assets/123/media');
const asset = assetFactory.build();
imageManager.preload(asset);
expect(getAssetMediaUrl).toHaveBeenCalledWith({
id: asset.id,
size: AssetMediaSize.Preview,
cacheKey: asset.thumbhash,
});
});
it('does nothing for undefined asset', () => {
imageManager.preload(undefined);
expect(getAssetMediaUrl).not.toHaveBeenCalled();
});
it('does nothing when getAssetMediaUrl returns falsy', () => {
vi.mocked(getAssetMediaUrl).mockReturnValue('');
const asset = assetFactory.build();
imageManager.preload(asset);
expect(getAssetMediaUrl).toHaveBeenCalled();
});
it('uses the specified size', () => {
vi.mocked(getAssetMediaUrl).mockReturnValue('/api/assets/123/media');
const asset = assetFactory.build();
imageManager.preload(asset, AssetMediaSize.Thumbnail);
expect(getAssetMediaUrl).toHaveBeenCalledWith({
id: asset.id,
size: AssetMediaSize.Thumbnail,
cacheKey: asset.thumbhash,
});
});
});
describe('cancel', () => {
it('calls cancelImageUrl with the correct URL', () => {
vi.mocked(getAssetMediaUrl).mockReturnValue('/api/assets/123/media');
const asset = assetFactory.build();
imageManager.cancel(asset, AssetMediaSize.Preview);
expect(cancelImageUrl).toHaveBeenCalledWith('/api/assets/123/media');
});
it('does nothing for undefined asset', () => {
imageManager.cancel(undefined);
expect(getAssetMediaUrl).not.toHaveBeenCalled();
expect(cancelImageUrl).not.toHaveBeenCalled();
});
it('cancels all sizes when size is "all"', () => {
vi.mocked(getAssetMediaUrl).mockImplementation(({ size }) => `/api/assets/123/${size}`);
const asset = assetFactory.build();
imageManager.cancel(asset, 'all');
expect(getAssetMediaUrl).toHaveBeenCalledTimes(Object.values(AssetMediaSize).length);
for (const size of Object.values(AssetMediaSize)) {
expect(cancelImageUrl).toHaveBeenCalledWith(`/api/assets/123/${size}`);
}
});
it('does not call cancelImageUrl when URL is falsy', () => {
vi.mocked(getAssetMediaUrl).mockReturnValue('');
const asset = assetFactory.build();
imageManager.cancel(asset, AssetMediaSize.Preview);
expect(cancelImageUrl).not.toHaveBeenCalled();
});
});
});

37
web/src/lib/managers/ImageManager.svelte.ts
View File

@ -1,37 +0,0 @@
import { getAssetMediaUrl } from '$lib/utils';
import { cancelImageUrl } from '$lib/utils/sw-messaging';
import { AssetMediaSize, type AssetResponseDto } from '@immich/sdk';
type AllAssetMediaSize = AssetMediaSize | 'all';
class ImageManager {
preload(asset: AssetResponseDto | undefined, size: AssetMediaSize = AssetMediaSize.Preview) {
if (!asset) {
return;
}
const url = getAssetMediaUrl({ id: asset.id, size, cacheKey: asset.thumbhash });
if (!url) {
return;
}
const img = new Image();
img.src = url;
}
cancel(asset: AssetResponseDto | undefined, size: AllAssetMediaSize = AssetMediaSize.Preview) {
if (!asset) {
return;
}
const sizes = size === 'all' ? Object.values(AssetMediaSize) : [size];
for (const size of sizes) {
const url = getAssetMediaUrl({ id: asset.id, size, cacheKey: asset.thumbhash });
if (url) {
cancelImageUrl(url);
}
}
}
}
export const imageManager = new ImageManager();

8
web/src/lib/utils.ts
View File

@ -186,6 +186,14 @@ export const getAssetUrl = ({
return getAssetMediaUrl({ id, size, cacheKey });
};
export function getAssetUrls(asset: AssetResponseDto, sharedLink?: SharedLinkResponseDto) {
return {
thumbnail: getAssetMediaUrl({ id: asset.id, cacheKey: asset.thumbhash, size: AssetMediaSize.Thumbnail }),
preview: getAssetUrl({ asset, sharedLink })!,
original: getAssetUrl({ asset, sharedLink, forceOriginal: true })!,
};
}
const forceUseOriginal = (asset: AssetResponseDto) => {
return asset.type === AssetTypeEnum.Image && asset.duration && !asset.duration.includes('0:00:00.000');
};

304
web/src/lib/utils/adaptive-image-loader.spec.ts Normal file
View File

@ -0,0 +1,304 @@
import { AdaptiveImageLoader, type QualityList } from '$lib/utils/adaptive-image-loader.svelte';
import { cancelImageUrl } from '$lib/utils/sw-messaging';
vi.mock('$lib/utils/sw-messaging', () => ({
cancelImageUrl: vi.fn(),
}));
function createQualityList(overrides?: {
onAfterLoad?: Record<string, (loader: AdaptiveImageLoader) => void>;
onAfterError?: Record<string, (loader: AdaptiveImageLoader) => void>;
}): QualityList {
return [
{
quality: 'thumbnail',
url: '/thumbnail.jpg',
onAfterLoad: overrides?.onAfterLoad?.thumbnail,
onAfterError: overrides?.onAfterError?.thumbnail,
},
{
quality: 'preview',
url: '/preview.jpg',
onAfterLoad: overrides?.onAfterLoad?.preview,
onAfterError: overrides?.onAfterError?.preview,
},
{
quality: 'original',
url: '/original.jpg',
onAfterLoad: overrides?.onAfterLoad?.original,
onAfterError: overrides?.onAfterError?.original,
},
];
}
describe('AdaptiveImageLoader', () => {
beforeEach(() => {
vi.clearAllMocks();
});
describe('constructor', () => {
it('initializes with thumbnail URL set', () => {
const loader = new AdaptiveImageLoader(createQualityList());
expect(loader.status.urls.thumbnail).toBe('/thumbnail.jpg');
expect(loader.status.urls.preview).toBeUndefined();
expect(loader.status.urls.original).toBeUndefined();
});
it('initializes all qualities as unloaded', () => {
const loader = new AdaptiveImageLoader(createQualityList());
expect(loader.status.quality.thumbnail).toBe('unloaded');
expect(loader.status.quality.preview).toBe('unloaded');
expect(loader.status.quality.original).toBe('unloaded');
});
});
describe('onStart', () => {
it('sets started to true', () => {
const loader = new AdaptiveImageLoader(createQualityList());
expect(loader.status.started).toBe(false);
loader.onStart('thumbnail');
expect(loader.status.started).toBe(true);
});
it('is a no-op after destroy', () => {
const loader = new AdaptiveImageLoader(createQualityList());
loader.destroy();
loader.onStart('thumbnail');
expect(loader.status.started).toBe(false);
});
});
describe('onLoad', () => {
it('sets quality to success and calls callbacks', () => {
const onUrlChange = vi.fn();
const onImageReady = vi.fn();
const loader = new AdaptiveImageLoader(createQualityList(), { onUrlChange, onImageReady });
loader.onLoad('thumbnail');
expect(loader.status.quality.thumbnail).toBe('success');
expect(onUrlChange).toHaveBeenCalledWith('/thumbnail.jpg');
expect(onImageReady).toHaveBeenCalledOnce();
});
it('calls onAfterLoad callback', () => {
const onAfterLoad = vi.fn();
const qualityList = createQualityList({ onAfterLoad: { thumbnail: onAfterLoad } });
const loader = new AdaptiveImageLoader(qualityList);
loader.onLoad('thumbnail');
expect(onAfterLoad).toHaveBeenCalledWith(loader);
});
it('ignores load if URL is not set', () => {
const onImageReady = vi.fn();
const loader = new AdaptiveImageLoader(createQualityList(), { onImageReady });
loader.onLoad('preview');
expect(loader.status.quality.preview).toBe('unloaded');
expect(onImageReady).not.toHaveBeenCalled();
});
it('ignores load if a higher quality is already loaded', () => {
const onUrlChange = vi.fn();
const loader = new AdaptiveImageLoader(createQualityList(), { onUrlChange });
loader.onLoad('thumbnail');
loader.trigger('preview');
loader.onLoad('preview');
onUrlChange.mockClear();
loader.onLoad('thumbnail');
expect(onUrlChange).not.toHaveBeenCalled();
});
it('is a no-op after destroy', () => {
const onImageReady = vi.fn();
const loader = new AdaptiveImageLoader(createQualityList(), { onImageReady });
loader.destroy();
loader.onLoad('thumbnail');
expect(onImageReady).not.toHaveBeenCalled();
});
});
describe('onError', () => {
it('sets quality to error and clears URL', () => {
const onError = vi.fn();
const loader = new AdaptiveImageLoader(createQualityList(), { onError });
loader.onError('thumbnail');
expect(loader.status.quality.thumbnail).toBe('error');
expect(loader.status.urls.thumbnail).toBeUndefined();
expect(loader.status.hasError).toBe(true);
expect(onError).toHaveBeenCalledOnce();
});
it('calls onAfterError callback', () => {
const onAfterError = vi.fn();
const qualityList = createQualityList({ onAfterError: { thumbnail: onAfterError } });
const loader = new AdaptiveImageLoader(qualityList);
loader.onError('thumbnail');
expect(onAfterError).toHaveBeenCalledWith(loader);
});
it('is a no-op after destroy', () => {
const onError = vi.fn();
const loader = new AdaptiveImageLoader(createQualityList(), { onError });
loader.destroy();
loader.onError('thumbnail');
expect(onError).not.toHaveBeenCalled();
});
});
describe('trigger', () => {
it('sets the URL for the quality', () => {
const loader = new AdaptiveImageLoader(createQualityList());
loader.trigger('preview');
expect(loader.status.urls.preview).toBe('/preview.jpg');
});
it('returns true if URL is already set', () => {
const loader = new AdaptiveImageLoader(createQualityList());
expect(loader.trigger('thumbnail')).toBe(true);
});
it('returns false when triggering a new quality', () => {
const loader = new AdaptiveImageLoader(createQualityList());
expect(loader.trigger('preview')).toBe(false);
});
it('clears hasError when triggering', () => {
const loader = new AdaptiveImageLoader(createQualityList());
loader.onError('thumbnail');
expect(loader.status.hasError).toBe(true);
loader.trigger('preview');
expect(loader.status.hasError).toBe(false);
});
it('calls imageLoader when provided', () => {
const imageLoader = vi.fn(() => vi.fn());
const loader = new AdaptiveImageLoader(createQualityList(), undefined, imageLoader);
loader.trigger('preview');
expect(imageLoader).toHaveBeenCalledWith(
'/preview.jpg',
expect.any(Function),
expect.any(Function),
expect.any(Function),
);
});
it('returns false after destroy', () => {
const loader = new AdaptiveImageLoader(createQualityList());
loader.destroy();
expect(loader.trigger('preview')).toBe(false);
});
it('calls onAfterError if URL is empty', () => {
const onAfterError = vi.fn();
const qualityList = createQualityList({ onAfterError: { preview: onAfterError } });
(qualityList[1] as { url: string }).url = '';
const loader = new AdaptiveImageLoader(qualityList);
expect(loader.trigger('preview')).toBe(false);
expect(onAfterError).toHaveBeenCalledWith(loader);
});
});
describe('start', () => {
it('throws if no imageLoader is provided', () => {
const loader = new AdaptiveImageLoader(createQualityList());
expect(() => loader.start()).toThrow('Start requires imageLoader to be specified');
});
it('calls imageLoader with thumbnail URL', () => {
const imageLoader = vi.fn(() => vi.fn());
const loader = new AdaptiveImageLoader(createQualityList(), undefined, imageLoader);
loader.start();
expect(imageLoader).toHaveBeenCalledWith(
'/thumbnail.jpg',
expect.any(Function),
expect.any(Function),
expect.any(Function),
);
});
});
describe('destroy', () => {
it('cancels all image URLs when no imageLoader', () => {
const loader = new AdaptiveImageLoader(createQualityList());
loader.destroy();
expect(cancelImageUrl).toHaveBeenCalledWith('/thumbnail.jpg');
expect(cancelImageUrl).toHaveBeenCalledWith('/preview.jpg');
expect(cancelImageUrl).toHaveBeenCalledWith('/original.jpg');
});
it('calls destroy functions when imageLoader is provided', () => {
const destroyFn = vi.fn();
const imageLoader = vi.fn(() => destroyFn);
const loader = new AdaptiveImageLoader(createQualityList(), undefined, imageLoader);
loader.start();
loader.destroy();
expect(destroyFn).toHaveBeenCalledOnce();
expect(cancelImageUrl).not.toHaveBeenCalled();
});
});
describe('progressive loading flow', () => {
it('thumbnail load triggers preview via onAfterLoad', () => {
const triggerSpy = vi.fn();
const qualityList = createQualityList({
onAfterLoad: {
thumbnail: (loader) => {
triggerSpy();
loader.trigger('preview');
},
},
});
const loader = new AdaptiveImageLoader(qualityList);
loader.onLoad('thumbnail');
expect(triggerSpy).toHaveBeenCalledOnce();
expect(loader.status.urls.preview).toBe('/preview.jpg');
});
it('thumbnail error triggers preview via onAfterError', () => {
const qualityList = createQualityList({
onAfterError: {
thumbnail: (loader) => loader.trigger('preview'),
},
});
const loader = new AdaptiveImageLoader(qualityList);
loader.onError('thumbnail');
expect(loader.status.urls.preview).toBe('/preview.jpg');
});
});
});

164
web/src/lib/utils/adaptive-image-loader.svelte.ts Normal file
View File

@ -0,0 +1,164 @@
import type { LoadImageFunction } from '$lib/actions/image-loader.svelte';
import { cancelImageUrl } from '$lib/utils/sw-messaging';
export type ImageQuality = 'thumbnail' | 'preview' | 'original';
export type ImageStatus = 'unloaded' | 'success' | 'error';
export type ImageLoaderStatus = {
urls: Record<ImageQuality, string | undefined>;
quality: Record<ImageQuality, ImageStatus>;
started: boolean;
hasError: boolean;
};
type ImageLoaderCallbacks = {
onUrlChange?: (url: string) => void;
onImageReady?: () => void;
onError?: () => void;
};
export type QualityConfig = {
url: string;
quality: ImageQuality;
onAfterLoad?: (loader: AdaptiveImageLoader) => void;
onAfterError?: (loader: AdaptiveImageLoader) => void;
};
export type QualityList = [
QualityConfig & { quality: 'thumbnail' },
QualityConfig & { quality: 'preview' },
QualityConfig & { quality: 'original' },
];
export class AdaptiveImageLoader {
private destroyFunctions: (() => void)[] = [];
private qualityConfigs: Record<ImageQuality, QualityConfig>;
private highestLoadedQualityIndex = -1;
private destroyed = false;
status = $state<ImageLoaderStatus>({
started: false,
hasError: false,
urls: { thumbnail: undefined, preview: undefined, original: undefined },
quality: { thumbnail: 'unloaded', preview: 'unloaded', original: 'unloaded' },
});
constructor(
private readonly qualityList: QualityList,
private readonly callbacks?: ImageLoaderCallbacks,
private readonly imageLoader?: LoadImageFunction,
) {
this.qualityConfigs = {
thumbnail: qualityList[0],
preview: qualityList[1],
original: qualityList[2],
};
this.status.urls.thumbnail = qualityList[0].url;
}
start() {
if (!this.imageLoader) {
throw new Error('Start requires imageLoader to be specified');
}
this.destroyFunctions.push(
this.imageLoader(
this.qualityList[0].url,
() => this.onLoad('thumbnail'),
() => this.onError('thumbnail'),
() => this.onStart('thumbnail'),
),
);
}
onStart(_: ImageQuality) {
if (this.destroyed) {
return;
}
this.status.started = true;
}
onLoad(quality: ImageQuality) {
if (this.destroyed) {
return;
}
const config = this.qualityConfigs[quality];
if (!this.status.urls[quality]) {
return;
}
const index = this.qualityList.indexOf(config);
if (index <= this.highestLoadedQualityIndex) {
return;
}
this.highestLoadedQualityIndex = index;
this.status.quality[quality] = 'success';
this.callbacks?.onUrlChange?.(this.qualityConfigs[quality].url);
this.callbacks?.onImageReady?.();
config.onAfterLoad?.(this);
}
onError(quality: ImageQuality) {
if (this.destroyed) {
return;
}
const config = this.qualityConfigs[quality];
this.status.hasError = true;
this.status.quality[quality] = 'error';
this.status.urls[quality] = undefined;
this.callbacks?.onError?.();
config.onAfterError?.(this);
}
trigger(quality: ImageQuality) {
if (this.destroyed) {
return false;
}
const url = this.qualityConfigs[quality].url;
if (!url) {
this.qualityConfigs[quality].onAfterError?.(this);
return false;
}
if (this.status.urls[quality]) {
return true;
}
this.status.hasError = false;
this.status.urls[quality] = url;
if (this.imageLoader) {
this.destroyFunctions.push(
this.imageLoader(
url,
() => this.onLoad(quality),
() => this.onError(quality),
() => this.onStart(quality),
),
);
}
return false;
}
destroy() {
this.destroyed = true;
if (this.imageLoader) {
for (const destroy of this.destroyFunctions) {
destroy();
}
return;
}
for (const config of Object.values(this.qualityConfigs)) {
cancelImageUrl(config.url);
}
}
}

13
web/src/lib/utils/container-utils.ts
View File

@ -5,6 +5,19 @@ export interface ContentMetrics {
offsetY: number;
}
export const scaleToCover = (
dimensions: { width: number; height: number },
container: { width: number; height: number },
): { width: number; height: number } => {
const scaleX = container.width / dimensions.width;
const scaleY = container.height / dimensions.height;
const scale = Math.max(scaleX, scaleY);
return {
width: dimensions.width * scale,
height: dimensions.height * scale,
};
};
export const scaleToFit = (
dimensions: { width: number; height: number },
container: { width: number; height: number },

54
web/src/lib/utils/layout-utils.spec.ts Normal file
View File

@ -0,0 +1,54 @@
import { scaleToFit } from '$lib/utils/container-utils';
describe('scaleToFit', () => {
const tests = [
{
name: 'landscape image in square container',
dimensions: { width: 2000, height: 1000 },
container: { width: 500, height: 500 },
expected: { width: 500, height: 250 },
},
{
name: 'portrait image in square container',
dimensions: { width: 1000, height: 2000 },
container: { width: 500, height: 500 },
expected: { width: 250, height: 500 },
},
{
name: 'square image in square container',
dimensions: { width: 1000, height: 1000 },
container: { width: 500, height: 500 },
expected: { width: 500, height: 500 },
},
{
name: 'landscape image in landscape container',
dimensions: { width: 1600, height: 900 },
container: { width: 800, height: 600 },
expected: { width: 800, height: 450 },
},
{
name: 'portrait image in portrait container',
dimensions: { width: 900, height: 1600 },
container: { width: 600, height: 800 },
expected: { width: 450, height: 800 },
},
{
name: 'image matches container exactly',
dimensions: { width: 500, height: 300 },
container: { width: 500, height: 300 },
expected: { width: 500, height: 300 },
},
{
name: 'image smaller than container scales up',
dimensions: { width: 100, height: 50 },
container: { width: 400, height: 400 },
expected: { width: 400, height: 200 },
},
];
for (const { name, dimensions, container, expected } of tests) {
it(`should handle ${name}`, () => {
expect(scaleToFit(dimensions, container)).toEqual(expected);
});
}
});