@hearthlog/module-gallery 0.0.0-stage → 1.0.1

package/src/gallery/backup.ts

@@ -0,0 +1,140 @@
+import { queryDatabase } from '@hearthlog/sdk/data';
+import { requireActiveContext } from '@hearthlog/sdk/runtime';
+import { galleryPhotoCommands, galleryAlbumCommands, galleryAlbumPhotoCommands } from '@hearthlog/sdk/data';
+import { galleryOriginal, stageGalleryOriginal, discardStagedGalleryOriginal, triggerGalleryTransfers } from './file-store.js';
+import { createGalleryArchive, readGalleryArchive, type GalleryBackupManifest, type GalleryBackupPhoto } from './backup-archive.js';
+
+const BLOB_DOWNLOAD_LIMIT = 512 * 1024 * 1024;
+
+interface ArchiveWriter {
+    write(part: Blob): Promise<void>;
+    close(): Promise<void>;
+    abort(): Promise<void>;
+}
+
+interface SaveHandle { createWritable(): Promise<ArchiveWriter> }
+
+function backupName(): string { return `stor-gallery-${new Date().toISOString().slice(0, 10)}.tar`; }
+
+/** Invoked directly from a click so the browser's file picker keeps user activation. */
+export async function exportGalleryBackup(onProgress: (message: string) => void): Promise<number> {
+    const picker = (window as Window & {
+        showSaveFilePicker?: (options: { suggestedName: string; types: Array<{ description: string; accept: Record<string, string[]> }> }) => Promise<SaveHandle>;
+    }).showSaveFilePicker;
+    const handlePromise = picker?.call(window, {
+        suggestedName: backupName(),
+        types: [{ description: 'Gallery backup', accept: { 'application/x-tar': ['.tar'] } }],
+    });
+    const writer = handlePromise ? await (await handlePromise).createWritable() : null;
+    try {
+        const context = await requireActiveContext();
+        const snapshot = await queryDatabase((repositories) => repositories.gallery.exportSnapshot());
+        if (snapshot.photos.length === 0) throw new Error('There are no photos to back up.');
+        const manifest: Omit<GalleryBackupManifest, 'photos'> & { photos: Array<Omit<GalleryBackupPhoto, 'sha256'>> } = {
+            format: 'stor-gallery', version: 1, exportedAt: new Date().toISOString(),
+            photos: snapshot.photos.map((photo) => ({
+                id: photo.id, fileVersionId: photo.file_version_id, filename: photo.filename,
+                contentType: photo.content_type, byteSize: photo.byte_size, width: photo.width,
+                height: photo.height, capturedAt: photo.captured_at, importedAt: photo.imported_at,
+                timelineDay: photo.timeline_day, caption: photo.caption, favorite: Boolean(photo.favorite),
+                cameraMake: photo.camera_make, cameraModel: photo.camera_model,
+                lensModel: photo.lens_model, focalLength: photo.focal_length, fNumber: photo.f_number,
+                exposureTime: photo.exposure_time, iso: photo.iso,
+                latitude: photo.latitude, longitude: photo.longitude,
+            })),
+            albums: snapshot.albums.map((album) => ({
+                id: album.id, title: album.title, description: album.description,
+                coverPhotoId: album.cover_photo_id,
+            })),
+            memberships: snapshot.memberships.map((member) => ({
+                albumId: member.album_id, photoId: member.photo_id, addedAt: member.added_at,
+            })),
+        };
+        const parts: Blob[] = [];
+        let bytes = 0;
+        let completed = 0;
+        for await (const part of createGalleryArchive(manifest, async (photo) => {
+            onProgress(`Backing up ${completed + 1} of ${manifest.photos.length} photos…`);
+            const blob = await galleryOriginal({
+                tenantId: context.tenantId, logId: context.logId,
+                photoId: photo.id, fileVersionId: photo.fileVersionId,
+            }, { cache: false });
+            completed += 1;
+            return blob;
+        })) {
+            if (writer) await writer.write(part);
+            else {
+                bytes += part.size;
+                if (bytes > BLOB_DOWNLOAD_LIMIT) {
+                    throw new Error('This backup is too large for a browser download. Use a browser with Save file support.');
+                }
+                parts.push(part);
+            }
+        }
+        if (writer) await writer.close();
+        else {
+            const url = URL.createObjectURL(new Blob(parts, { type: 'application/x-tar' }));
+            const link = document.createElement('a');
+            link.href = url;
+            link.download = backupName();
+            link.click();
+            window.setTimeout(() => URL.revokeObjectURL(url), 60_000);
+        }
+        return completed;
+    } catch (cause) {
+        await writer?.abort().catch(() => undefined);
+        throw cause;
+    }
+}
+
+/** Validate all bytes first, then append fresh events into the active log. */
+export async function restoreGalleryBackup(file: File, onProgress: (message: string) => void): Promise<{
+    photos: number; albums: number;
+}> {
+    const archive = await readGalleryArchive(file);
+    const { manifest } = archive;
+    if (manifest.photos.length === 0) throw new Error('This backup contains no photos.');
+    for (let index = 0; index < manifest.photos.length; index += 1) {
+        onProgress(`Checking ${index + 1} of ${manifest.photos.length} originals…`);
+        await archive.original(manifest.photos[index]);
+    }
+    const context = await requireActiveContext();
+    const photoIds = new Map(manifest.photos.map((photo) => [photo.id, crypto.randomUUID()]));
+    const albumIds = new Map(manifest.albums.map((album) => [album.id, crypto.randomUUID()]));
+    let restored = 0;
+    try {
+        for (const photo of manifest.photos) {
+            onProgress(`Restoring ${restored + 1} of ${manifest.photos.length} photos…`);
+            const id = photoIds.get(photo.id)!;
+            const fileVersionId = crypto.randomUUID();
+            const scope = { tenantId: context.tenantId, logId: context.logId, photoId: id, fileVersionId };
+            const blob = await archive.original(photo);
+            await stageGalleryOriginal(scope, new File([blob], photo.filename, { type: photo.contentType }));
+            try {
+                const { sha256: _digest, ...metadata } = photo;
+                await galleryPhotoCommands.create({ ...metadata, id, fileVersionId }, { submissionId: crypto.randomUUID() });
+            } catch (cause) {
+                await discardStagedGalleryOriginal(scope);
+                throw cause;
+            }
+            restored += 1;
+        }
+        for (const album of manifest.albums) {
+            await galleryAlbumCommands.create({
+                id: albumIds.get(album.id)!, title: album.title,
+                description: album.description, coverPhotoId: photoIds.get(album.coverPhotoId) ?? '',
+            }, { submissionId: crypto.randomUUID() });
+        }
+        for (const member of manifest.memberships) {
+            await galleryAlbumPhotoCommands.create({
+                id: crypto.randomUUID(), albumId: albumIds.get(member.albumId)!,
+                photoId: photoIds.get(member.photoId)!, addedAt: member.addedAt,
+            }, { submissionId: crypto.randomUUID() });
+        }
+    } catch (cause) {
+        throw new Error(`${restored} photos were restored before the backup stopped. ${cause instanceof Error ? cause.message : 'Restore failed.'}`);
+    } finally {
+        triggerGalleryTransfers();
+    }
+    return { photos: restored, albums: manifest.albums.length };
+}

package/src/gallery/exif.ts

@@ -0,0 +1,240 @@
+/**
+ * Minimal EXIF reader for Gallery imports. It reads only the capture and
+ * camera fields the Gallery stores, from JPEG, PNG, WebP, and HEIC/HEIF
+ * originals. Malformed or missing metadata yields empty fields, never an error.
+ */
+
+export interface PhotoMetadata {
+    /** `YYYY-MM-DDTHH:mm:ss`, with a UTC offset when the camera recorded one. */
+    capturedAt: string;
+    /** Calendar day of the capture in the camera's local time. */
+    capturedDay: string;
+    cameraMake: string;
+    cameraModel: string;
+    lensModel: string;
+    /** Millimetres. */
+    focalLength: number;
+    fNumber: number;
+    /** Seconds. */
+    exposureTime: number;
+    iso: number;
+    latitude: number | null;
+    longitude: number | null;
+}
+
+export const EMPTY_PHOTO_METADATA: PhotoMetadata = {
+    capturedAt: '', capturedDay: '', cameraMake: '', cameraModel: '', lensModel: '',
+    focalLength: 0, fNumber: 0, exposureTime: 0, iso: 0, latitude: null, longitude: null,
+};
+
+const TAGS = {
+    make: 0x010f,
+    model: 0x0110,
+    dateTime: 0x0132,
+    exifIfd: 0x8769,
+    gpsIfd: 0x8825,
+    exposureTime: 0x829a,
+    fNumber: 0x829d,
+    iso: 0x8827,
+    dateTimeOriginal: 0x9003,
+    dateTimeDigitized: 0x9004,
+    offsetTimeOriginal: 0x9011,
+    focalLength: 0x920a,
+    lensModel: 0xa434,
+    gpsLatitudeRef: 1,
+    gpsLatitude: 2,
+    gpsLongitudeRef: 3,
+    gpsLongitude: 4,
+} as const;
+
+const TYPE_SIZES: Record<number, number> = { 1: 1, 2: 1, 3: 2, 4: 4, 5: 8, 7: 1, 9: 4, 10: 8 };
+
+type TagValue = string | number[];
+
+export function readPhotoMetadata(bytes: Uint8Array): PhotoMetadata {
+    try {
+        const tiff = findTiff(bytes);
+        return tiff === null ? { ...EMPTY_PHOTO_METADATA } : parseTiff(bytes, tiff);
+    } catch {
+        return { ...EMPTY_PHOTO_METADATA };
+    }
+}
+
+function findTiff(bytes: Uint8Array): number | null {
+    if (bytes[0] === 0xff && bytes[1] === 0xd8) return findJpegTiff(bytes);
+    if (ascii(bytes, 1, 'PNG')) return findChunkTiff(bytes, 8, 'eXIf', 'big');
+    if (ascii(bytes, 0, 'RIFF') && ascii(bytes, 8, 'WEBP')) return findChunkTiff(bytes, 12, 'EXIF', 'little');
+    // HEIC/HEIF store an `Exif` item whose payload is `Exif\0\0` + TIFF.
+    const marker = [0x45, 0x78, 0x69, 0x66, 0, 0];
+    for (let index = 0; index + 10 <= bytes.length; index += 1) {
+        if (marker.every((byte, offset) => bytes[index + offset] === byte) && isTiffHeader(bytes, index + 6)) {
+            return index + 6;
+        }
+    }
+    return null;
+}
+
+function findJpegTiff(bytes: Uint8Array): number | null {
+    let offset = 2;
+    while (offset + 4 <= bytes.length && bytes[offset] === 0xff) {
+        const marker = bytes[offset + 1];
+        if (marker === 0xda || marker === 0xd9) return null;
+        const length = (bytes[offset + 2] << 8) | bytes[offset + 3];
+        if (marker === 0xe1 && ascii(bytes, offset + 4, 'Exif\0\0') && isTiffHeader(bytes, offset + 10)) {
+            return offset + 10;
+        }
+        offset += 2 + length;
+    }
+    return null;
+}
+
+function findChunkTiff(bytes: Uint8Array, start: number, type: string, sizeOrder: 'big' | 'little'): number | null {
+    // PNG chunks are length + type + data + CRC; RIFF chunks are type + length + data (+ pad).
+    let offset = start;
+    while (offset + 8 <= bytes.length) {
+        const png = sizeOrder === 'big';
+        const size = png ? readUint32(bytes, offset, false) : readUint32(bytes, offset + 4, true);
+        const chunkType = png ? offset + 4 : offset;
+        const data = offset + 8;
+        if (ascii(bytes, chunkType, type)) {
+            if (isTiffHeader(bytes, data)) return data;
+            if (ascii(bytes, data, 'Exif\0\0') && isTiffHeader(bytes, data + 6)) return data + 6;
+            return null;
+        }
+        offset = data + size + (png ? 4 : size % 2);
+    }
+    return null;
+}
+
+function parseTiff(bytes: Uint8Array, tiff: number): PhotoMetadata {
+    const little = bytes[tiff] === 0x49;
+    const ifd0 = readIfd(bytes, tiff, readUint32(bytes, tiff + 4, little), little);
+    const exifOffset = numberAt(ifd0.get(TAGS.exifIfd));
+    const gpsOffset = numberAt(ifd0.get(TAGS.gpsIfd));
+    const exif = exifOffset ? readIfd(bytes, tiff, exifOffset, little) : new Map<number, TagValue>();
+    const gps = gpsOffset ? readIfd(bytes, tiff, gpsOffset, little) : new Map<number, TagValue>();
+
+    const captured = exifDate(
+        text(exif.get(TAGS.dateTimeOriginal)) || text(exif.get(TAGS.dateTimeDigitized)) || text(ifd0.get(TAGS.dateTime)),
+        text(exif.get(TAGS.offsetTimeOriginal)),
+    );
+    const make = text(ifd0.get(TAGS.make));
+    let model = text(ifd0.get(TAGS.model));
+    // Many cameras repeat the make inside the model ("Canon Canon EOS R6").
+    if (make && model.toLowerCase().startsWith(make.toLowerCase())) model = model.slice(make.length).trim();
+
+    return {
+        capturedAt: captured.at,
+        capturedDay: captured.day,
+        cameraMake: make,
+        cameraModel: model,
+        lensModel: text(exif.get(TAGS.lensModel)),
+        focalLength: rounded(numberAt(exif.get(TAGS.focalLength)), 1),
+        fNumber: rounded(numberAt(exif.get(TAGS.fNumber)), 1),
+        exposureTime: rounded(numberAt(exif.get(TAGS.exposureTime)), 6),
+        iso: Math.round(numberAt(exif.get(TAGS.iso))),
+        latitude: coordinate(gps.get(TAGS.gpsLatitude), text(gps.get(TAGS.gpsLatitudeRef)), 'S', 90),
+        longitude: coordinate(gps.get(TAGS.gpsLongitude), text(gps.get(TAGS.gpsLongitudeRef)), 'W', 180),
+    };
+}
+
+function readIfd(bytes: Uint8Array, tiff: number, offset: number, little: boolean): Map<number, TagValue> {
+    const values = new Map<number, TagValue>();
+    const start = tiff + offset;
+    if (offset <= 0 || start + 2 > bytes.length) return values;
+    const count = readUint16(bytes, start, little);
+    for (let index = 0; index < count; index += 1) {
+        const entry = start + 2 + index * 12;
+        if (entry + 12 > bytes.length) break;
+        const tag = readUint16(bytes, entry, little);
+        const type = readUint16(bytes, entry + 2, little);
+        const items = readUint32(bytes, entry + 4, little);
+        const size = TYPE_SIZES[type];
+        if (!size || items > 1024) continue;
+        const valueOffset = size * items <= 4 ? entry + 8 : tiff + readUint32(bytes, entry + 8, little);
+        if (valueOffset + size * items > bytes.length) continue;
+        values.set(tag, readValue(bytes, valueOffset, type, items, little));
+    }
+    return values;
+}
+
+function readValue(bytes: Uint8Array, offset: number, type: number, items: number, little: boolean): TagValue {
+    if (type === 2) {
+        let value = '';
+        for (let index = 0; index < items && bytes[offset + index] !== 0; index += 1) {
+            value += String.fromCharCode(bytes[offset + index]);
+        }
+        return value.trim();
+    }
+    const values: number[] = [];
+    for (let index = 0; index < items; index += 1) {
+        const at = offset + index * TYPE_SIZES[type];
+        if (type === 1 || type === 7) values.push(bytes[at]);
+        else if (type === 3) values.push(readUint16(bytes, at, little));
+        else if (type === 4) values.push(readUint32(bytes, at, little));
+        else if (type === 9) values.push(readUint32(bytes, at, little) | 0);
+        else {
+            const signed = type === 10;
+            const numerator = signed ? readUint32(bytes, at, little) | 0 : readUint32(bytes, at, little);
+            const denominator = signed ? readUint32(bytes, at + 4, little) | 0 : readUint32(bytes, at + 4, little);
+            values.push(denominator === 0 ? 0 : numerator / denominator);
+        }
+    }
+    return values;
+}
+
+function exifDate(value: string, offset: string): { at: string; day: string } {
+    const match = /^(\d{4}):(\d{2}):(\d{2})[ T](\d{2}):(\d{2}):(\d{2})/.exec(value);
+    if (!match) return { at: '', day: '' };
+    const [, year, month, day, hour, minute, second] = match;
+    const date = new Date(Date.UTC(Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second)));
+    if (Number(year) < 1900 || date.getUTCMonth() !== Number(month) - 1 || date.getUTCDate() !== Number(day)) {
+        return { at: '', day: '' };
+    }
+    const zone = /^[+-]\d{2}:\d{2}$/.test(offset) ? offset : '';
+    return { at: `${year}-${month}-${day}T${hour}:${minute}:${second}${zone}`, day: `${year}-${month}-${day}` };
+}
+
+function coordinate(value: TagValue | undefined, ref: string, negative: string, limit: number): number | null {
+    if (!Array.isArray(value) || value.length === 0) return null;
+    const [degrees = 0, minutes = 0, seconds = 0] = value;
+    const decimal = degrees + minutes / 60 + seconds / 3600;
+    if (!Number.isFinite(decimal) || decimal > limit || (decimal === 0 && !ref)) return null;
+    return rounded(ref.toUpperCase() === negative ? -decimal : decimal, 6);
+}
+
+function text(value: TagValue | undefined): string {
+    return typeof value === 'string' ? value : '';
+}
+
+function numberAt(value: TagValue | undefined): number {
+    return Array.isArray(value) && Number.isFinite(value[0]) ? value[0] : 0;
+}
+
+function rounded(value: number, digits: number): number {
+    const factor = 10 ** digits;
+    return Math.round(value * factor) / factor;
+}
+
+function isTiffHeader(bytes: Uint8Array, offset: number): boolean {
+    return (bytes[offset] === 0x49 && bytes[offset + 1] === 0x49 && bytes[offset + 2] === 0x2a && bytes[offset + 3] === 0)
+        || (bytes[offset] === 0x4d && bytes[offset + 1] === 0x4d && bytes[offset + 2] === 0 && bytes[offset + 3] === 0x2a);
+}
+
+function ascii(bytes: Uint8Array, offset: number, value: string): boolean {
+    for (let index = 0; index < value.length; index += 1) {
+        if (bytes[offset + index] !== value.charCodeAt(index)) return false;
+    }
+    return true;
+}
+
+function readUint16(bytes: Uint8Array, offset: number, little: boolean): number {
+    return little ? bytes[offset] | (bytes[offset + 1] << 8) : (bytes[offset] << 8) | bytes[offset + 1];
+}
+
+function readUint32(bytes: Uint8Array, offset: number, little: boolean): number {
+    const value = little
+        ? bytes[offset] | (bytes[offset + 1] << 8) | (bytes[offset + 2] << 16) | (bytes[offset + 3] << 24)
+        : (bytes[offset] << 24) | (bytes[offset + 1] << 16) | (bytes[offset + 2] << 8) | bytes[offset + 3];
+    return value >>> 0;
+}

package/src/gallery/file-store.ts

@@ -0,0 +1,206 @@
+import { openDB, type DBSchema, type IDBPDatabase } from 'idb';
+import { AccessSessionExpiredError, fetchAccessProtected } from '@hearthlog/sdk/runtime';
+import { requireActiveContext } from '@hearthlog/sdk/runtime';
+import { commandActionsAvailable, commandAvailability } from '@hearthlog/sdk/runtime';
+
+const DB_NAME = 'stor-gallery-files';
+const DB_VERSION = 1;
+const RETRY_MAX_MS = 5 * 60 * 1000;
+
+export interface GalleryFileScope {
+    tenantId: string;
+    logId: string;
+    photoId: string;
+    fileVersionId: string;
+}
+
+interface GalleryBlob {
+    key: string;
+    blob: Blob;
+    size: number;
+    contentType: string;
+}
+
+export interface GalleryUpload extends GalleryFileScope {
+    id: string;
+    blobKey: string;
+    attempts: number;
+    nextAttemptAt: number;
+    lastError: string;
+    state: 'pending' | 'needs_attention';
+}
+
+interface GalleryFileDatabase extends DBSchema {
+    blobs: { key: string; value: GalleryBlob };
+    uploads: { key: string; value: GalleryUpload };
+}
+
+let databasePromise: Promise<IDBPDatabase<GalleryFileDatabase>> | null = null;
+let transferPromise: Promise<void> | null = null;
+
+function database(): Promise<IDBPDatabase<GalleryFileDatabase>> {
+    databasePromise ??= openDB<GalleryFileDatabase>(DB_NAME, DB_VERSION, {
+        upgrade(db) {
+            db.createObjectStore('blobs', { keyPath: 'key' });
+            db.createObjectStore('uploads', { keyPath: 'id' });
+        },
+    });
+    return databasePromise;
+}
+
+function blobKey(scope: Pick<GalleryFileScope, 'tenantId' | 'photoId' | 'fileVersionId'>): string {
+    return `${scope.tenantId}:${scope.photoId}:${scope.fileVersionId}`;
+}
+
+export function galleryFileEndpoint(scope: GalleryFileScope, variant: 'original' | 'thumbnail' | 'display' = 'original'): string {
+    return `/api/gallery-files/v1/logs/${encodeURIComponent(scope.logId)}/photos/${encodeURIComponent(scope.photoId)}/versions/${encodeURIComponent(scope.fileVersionId)}/${variant}`;
+}
+
+/** Save bytes and the retry record in one durable transaction before appending metadata. */
+export async function stageGalleryOriginal(scope: GalleryFileScope, file: File): Promise<void> {
+    const db = await database();
+    const key = blobKey(scope);
+    const tx = db.transaction(['blobs', 'uploads'], 'readwrite');
+    await Promise.all([
+        tx.objectStore('blobs').put({ key, blob: file, size: file.size, contentType: file.type }),
+        tx.objectStore('uploads').put({
+            ...scope, id: key, blobKey: key, attempts: 0, nextAttemptAt: Date.now(),
+            lastError: '', state: 'pending',
+        }),
+    ]);
+    await tx.done;
+    try { await navigator.storage?.persist?.(); } catch { /* Best effort. */ }
+}
+
+/** Only use when the corresponding metadata command definitively failed. */
+export async function discardStagedGalleryOriginal(scope: GalleryFileScope): Promise<void> {
+    const db = await database();
+    const key = blobKey(scope);
+    const tx = db.transaction(['blobs', 'uploads'], 'readwrite');
+    await Promise.all([tx.objectStore('blobs').delete(key), tx.objectStore('uploads').delete(key)]);
+    await tx.done;
+}
+
+export async function galleryUploadState(scope: GalleryFileScope): Promise<GalleryUpload | null> {
+    return (await (await database()).get('uploads', blobKey(scope))) ?? null;
+}
+
+export async function galleryOriginal(scope: GalleryFileScope, options: { cache?: boolean } = {}): Promise<Blob> {
+    const db = await database();
+    const cached = await db.get('blobs', blobKey(scope));
+    if (cached) return cached.blob;
+    const response = await fetchAccessProtected(galleryFileEndpoint(scope));
+    if (!response.ok) {
+        if (response.status === 404) throw new Error('This photo is available when its original is uploaded.');
+        throw new Error('The photo could not be loaded.');
+    }
+    const blob = await response.blob();
+    // A viewed original is cached for offline use. Pending originals are never
+    // evicted; cache budgeting follows in the recovery slice.
+    if (options.cache !== false) {
+        await db.put('blobs', {
+            key: blobKey(scope), blob, size: blob.size,
+            contentType: blob.type || response.headers.get('Content-Type') || 'application/octet-stream',
+        });
+    }
+    return blob;
+}
+
+export async function galleryRendition(scope: GalleryFileScope, variant: 'thumbnail' | 'display'): Promise<Blob> {
+    const db = await database();
+    const key = `${blobKey(scope)}:${variant}`;
+    const cached = await db.get('blobs', key);
+    if (cached) return cached.blob;
+    const localOriginal = await db.get('blobs', blobKey(scope));
+    if (localOriginal) return localOriginal.blob;
+    const response = await fetchAccessProtected(galleryFileEndpoint(scope, variant));
+    if (!response.ok) {
+        if (response.status === 404) throw new Error('This photo is available when its display image is uploaded.');
+        throw new Error('The photo could not be loaded.');
+    }
+    const blob = await response.blob();
+    await db.put('blobs', { key, blob, size: blob.size, contentType: 'image/webp' });
+    return blob;
+}
+
+export async function galleryLocalStorageStats(): Promise<{ files: number; bytes: number; pending: number }> {
+    const db = await database();
+    const context = await requireActiveContext();
+    const blobs = await db.getAll('blobs');
+    const uploads = await db.getAll('uploads');
+    return {
+        files: blobs.filter((blob) => blob.key.startsWith(`${context.tenantId}:`)).length,
+        bytes: blobs.filter((blob) => blob.key.startsWith(`${context.tenantId}:`)).reduce((total, blob) => total + blob.size, 0),
+        pending: uploads.filter((upload) => upload.tenantId === context.tenantId).length,
+    };
+}
+
+async function runGalleryTransfers(): Promise<void> {
+    if (!commandActionsAvailable() || !navigator.onLine) return;
+    const tenantId = (await requireActiveContext()).tenantId;
+    const db = await database();
+    const now = Date.now();
+    const uploads = (await db.getAll('uploads'))
+        .filter((upload) => upload.tenantId === tenantId && upload.state === 'pending' && upload.nextAttemptAt <= now)
+        .sort((a, b) => a.nextAttemptAt - b.nextAttemptAt)
+        .slice(0, 3);
+    for (const upload of uploads) {
+        if (!commandActionsAvailable() || (await requireActiveContext()).tenantId !== tenantId) break;
+        const cached = await db.get('blobs', upload.blobKey);
+        if (!cached) {
+            await db.put('uploads', { ...upload, state: 'needs_attention', lastError: 'The local photo is missing.' });
+            continue;
+        }
+        try {
+            const response = await fetchAccessProtected(galleryFileEndpoint(upload), {
+                method: 'PUT', headers: { 'Content-Type': cached.contentType }, body: cached.blob,
+            });
+            if (!response.ok) {
+                const body: unknown = await response.json().catch(() => null);
+                const code = body && typeof body === 'object' && 'code' in body ? body.code : null;
+                const permanent = [400, 409, 413, 415].includes(response.status);
+                if (permanent) {
+                    await db.put('uploads', {
+                        ...upload, state: 'needs_attention', lastError: String(code ?? 'The upload was rejected.'),
+                    });
+                    continue;
+                }
+                throw new Error(String(code ?? 'The upload could not be completed.'));
+            }
+            await db.delete('uploads', upload.id);
+            window.dispatchEvent(new CustomEvent('stor:gallery-transfer', { detail: upload.photoId }));
+        } catch (cause) {
+            if (cause instanceof AccessSessionExpiredError) break;
+            const attempts = upload.attempts + 1;
+            await db.put('uploads', {
+                ...upload, attempts,
+                nextAttemptAt: Date.now() + Math.min(RETRY_MAX_MS, 1000 * 2 ** Math.min(attempts, 8)),
+                lastError: cause instanceof Error ? cause.message : 'Upload failed',
+            });
+        }
+    }
+    if (uploads.length === 3) window.setTimeout(triggerGalleryTransfers, 0);
+}
+
+export function triggerGalleryTransfers(): void {
+    transferPromise ??= runGalleryTransfers().catch((cause) => {
+        console.error('Gallery transfer failed', cause);
+    }).finally(() => { transferPromise = null; });
+}
+
+export function startGalleryFileCoordinator(): () => void {
+    const trigger = () => triggerGalleryTransfers();
+    const unsubscribe = commandAvailability.subscribe(trigger);
+    window.addEventListener('online', trigger);
+    window.addEventListener('focus', trigger);
+    window.addEventListener('pageshow', trigger);
+    const interval = window.setInterval(trigger, 15_000);
+    trigger();
+    return () => {
+        unsubscribe();
+        window.removeEventListener('online', trigger);
+        window.removeEventListener('focus', trigger);
+        window.removeEventListener('pageshow', trigger);
+        window.clearInterval(interval);
+    };
+}