@rapidmx/web-client 0.30.0 → 0.32.0

package/lib/contacts/contactsApi.ts

@@ -5,8 +5,8 @@
 /** Typed wrappers over `@rapidmx/restapi`'s `/mail/contacts` REST surface — see `mailApi.ts`'s own header
  * comment for the shared ACL/authorization model every wrapper file here follows. */
 
-import { ApiClient, ApiRequestError, apiUrl, withClient, withCsrfHeader } from "../util/api.js";
-import { ListParams, buildQuery } from "../util/apiQuery.js";
+import { ApiClient, apiUrl, withClient, withClientRaw } from "../util/api.js";
+import { ListParams, SETTINGS_LIST_LIMIT, buildQuery } from "../util/apiQuery.js";
 import {
     type EncryptionPreference,
     type KeyConflict,
@@ -83,10 +83,14 @@ export interface Contact {
     rejectedKeys?: RejectedKey[];
 }
 
+/** The order a contacts list is read in: alphabetical, with the `uid` as the tie-breaker so contacts sharing a name keep one fixed order and
+ * a page boundary between them can neither skip nor repeat one. */
+const CONTACT_SORT = JSON.stringify({ displayName: "ASC", uid: "ASC" });
+
 /** Lists a folder's contacts, alphabetically by display name. Never includes soft-deleted contacts — see
  * `listDeletedContacts()` for those. */
 export function listContacts(folderUid: string, params: ListParams = {}, client?: ApiClient): Promise<Contact[]> {
-    return withClient(client, `/mail/contacts?${buildQuery(params, { folderUid, sort: JSON.stringify({ displayName: "ASC" }) })}`);
+    return withClient(client, `/mail/contacts?${buildQuery(params, { folderUid, sort: CONTACT_SORT })}`);
 }
 
 function contactsMatching(contacts: Contact[], address: string): Contact[] {
@@ -195,7 +199,7 @@ export async function fetchSignerKeyState(folderUids: string[], address: string,
 export function listDeletedContacts(folderUid: string, params: ListParams = {}, client?: ApiClient): Promise<Contact[]> {
     return withClient(
         client,
-        `/mail/contacts?${buildQuery(params, { folderUid, deleted: "true", sort: JSON.stringify({ displayName: "ASC" }) })}`,
+        `/mail/contacts?${buildQuery(params, { folderUid, deleted: "true", sort: CONTACT_SORT })}`,
     );
 }
 
@@ -254,7 +258,8 @@ export function setContactFavorite(contact: Contact, favorite: boolean, client?:
 
 /**
  * The URL of a contact's own picture, or `undefined` when they have none. The version is part of it so a replaced picture is fetched again rather than
- * served from the browser's cache.
+ * served from the browser's cache. Only an `<img src>` of the cookie-authenticated web app can load it: under an explicit `ApiClient` use
+ * `useContactPhotoSrc()` instead.
  */
 export function contactPhotoUrl(contact: Pick<Contact, "uid" | "version" | "photoBlobKey">): string | undefined {
     return contact.photoBlobKey ? apiUrl(`/mail/contacts/${encodeURIComponent(contact.uid)}/photo?v=${contact.version}`) : undefined;
@@ -265,19 +270,13 @@ export const CONTACT_PHOTO_TYPES = ["image/jpeg", "image/png", "image/gif", "ima
 export const CONTACT_PHOTO_MAX_BYTES = 1024 * 1024;
 
 /** Sets a contact's own picture from an image file (the file's own bytes go up, not JSON) and returns the updated contact. */
-export async function uploadContactPhoto(uid: string, version: number, file: Blob): Promise<Contact> {
-    const res = await fetch(apiUrl(`/mail/contacts/${encodeURIComponent(uid)}/photo?version=${version}`), {
-        method: "PUT",
-        credentials: "include",
-        headers: withCsrfHeader({ "Content-Type": file.type }, "PUT"),
-        body: file,
-    });
-    const contentType = res.headers.get("content-type") ?? "";
-    const body = contentType.includes("application/json") ? await res.json().catch(() => undefined) : undefined;
-    if (!res.ok) {
-        throw new ApiRequestError((body && (body.message || body.error)) || res.statusText || "Upload failed.", res.status, body?.code);
-    }
-    return body as Contact;
+export function uploadContactPhoto(uid: string, version: number, file: Blob, client?: ApiClient): Promise<Contact> {
+    return withClientRaw(client, `/mail/contacts/${encodeURIComponent(uid)}/photo?version=${version}`, "PUT", file);
+}
+
+/** The bytes of a contact's own picture through an explicit `client` - for one that authenticates with a token, whose `<img>` cannot (see `contactPhotoUrl()`). */
+export function fetchContactPhoto(uid: string, version: number, client: ApiClient): Promise<Blob> {
+    return client.fetchBlob(`/mail/contacts/${encodeURIComponent(uid)}/photo?v=${version}`);
 }
 
 /** Removes a contact's own picture and returns the updated contact. */
@@ -300,7 +299,7 @@ export interface ContactList {
 
 /** Lists a mailbox's contact lists (Outlook-style "Your contact lists"), alphabetically by name. */
 export function listContactLists(mailboxUid: string, params: ListParams = {}, client?: ApiClient): Promise<ContactList[]> {
-    return withClient(client, `/mail/contact-lists?${buildQuery(params, { mailboxUid, sort: JSON.stringify({ name: "ASC" }) })}`);
+    return withClient(client, `/mail/contact-lists?${buildQuery({ limit: SETTINGS_LIST_LIMIT, ...params }, { mailboxUid, sort: JSON.stringify({ name: "ASC", uid: "ASC" }) })}`);
 }
 
 export function createContactList(input: { mailboxUid: string; name: string }, client?: ApiClient): Promise<ContactList> {

package/lib/contacts/gravatar.ts

@@ -3,21 +3,63 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 
-/** The `localStorage` key of the privacy preference: `"off"` stops contact avatars from asking Gravatar for a picture. */
+/** The `localStorage` key of the privacy preference: `"on"` lets contact avatars ask Gravatar for a picture; anything else (including unset or an old `"off"`) does not. */
 export const GRAVATAR_PREFERENCE_KEY = "rapidmx:gravatar";
 
+/** Fired on `window` when this tab changes the preference (the `storage` event covers other tabs). */
+export const GRAVATAR_PREFERENCE_EVENT = "rapidmx:gravatar-changed";
+
 /**
- * Whether avatars may look a person up at Gravatar by the SHA-256 hash of their address (never the address itself). On unless the reader turned
- * it off (`localStorage["rapidmx:gravatar"] = "off"`); a browser without storage keeps the default.
+ * Whether avatars may look a person up at Gravatar by the SHA-256 hash of their address (never the address itself). Off unless the reader turned it on
+ * in Settings > Privacy (`localStorage["rapidmx:gravatar"] = "on"`): it tells gravatar.com the hash and the reader's IP address. A browser without
+ * storage stays off.
  */
 export function gravatarEnabled(): boolean {
     try {
-        return globalThis.localStorage?.getItem(GRAVATAR_PREFERENCE_KEY) !== "off";
+        return globalThis.localStorage.getItem(GRAVATAR_PREFERENCE_KEY) === "on";
     } catch {
-        return true;
+        return false;
     }
 }
 
+/** Turns the Gravatar lookup on or off and tells every subscriber (`subscribeGravatarPreference()`) in this tab. */
+export function setGravatarEnabled(enabled: boolean): void {
+    try {
+        globalThis.localStorage.setItem(GRAVATAR_PREFERENCE_KEY, enabled ? "on" : "off");
+    } catch {
+        // Storage is unavailable: the preference cannot be kept, so it stays off.
+    }
+    globalThis.dispatchEvent(new Event(GRAVATAR_PREFERENCE_EVENT));
+}
+
+/** Calls `listener` whenever the preference changes in this tab or another; returns the unsubscribe function. Shaped for `useSyncExternalStore`. */
+export function subscribeGravatarPreference(listener: () => void): () => void {
+    const onStorage = (event: StorageEvent) => {
+        if (event.key === null || event.key === GRAVATAR_PREFERENCE_KEY) {
+            listener();
+        }
+    };
+    globalThis.addEventListener(GRAVATAR_PREFERENCE_EVENT, listener);
+    globalThis.addEventListener("storage", onStorage);
+    return () => {
+        globalThis.removeEventListener(GRAVATAR_PREFERENCE_EVENT, listener);
+        globalThis.removeEventListener("storage", onStorage);
+    };
+}
+
+/** Gravatar URLs that answered with nothing, so a list that shows the same person again does not ask again for the page's lifetime. */
+const missing = new Set<string>();
+
+/** Remembers that Gravatar has no picture at `url`. */
+export function markGravatarMissing(url: string): void {
+    missing.add(url);
+}
+
+/** Whether Gravatar already answered with no picture at `url`. */
+export function isGravatarMissing(url: string): boolean {
+    return missing.has(url);
+}
+
 const hashes = new Map<string, Promise<string | undefined>>();
 
 /** The lowercase-hex SHA-256 of a trimmed, lowercased `email`, or `undefined` where the browser has no Web Crypto (an insecure page). */

package/lib/contacts/preparePhoto.ts

@@ -0,0 +1,273 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Gets a picture the user chose - a phone's camera photo is typically 2-8 MB, may be HEIC and carries an EXIF orientation - into what the server takes for a
+ * contact's picture (JPEG, PNG, GIF or WebP, at most `CONTACT_PHOTO_MAX_BYTES`, checked by its magic bytes), in the browser, before it is uploaded.
+ */
+import { CONTACT_PHOTO_MAX_BYTES, CONTACT_PHOTO_TYPES } from "./contactsApi.js";
+
+/** The longest side (in pixels) an accepted picture may have and still be sent as it is. */
+export const CONTACT_PHOTO_MAX_SIDE = 1024;
+/** The side (in pixels) of the square picture made from one that has to be changed - an avatar is shown at 72 pixels at most, 512 covers a high-density screen. */
+export const CONTACT_PHOTO_OUTPUT_SIDE = 512;
+/** JPEG qualities tried in turn until the picture fits `CONTACT_PHOTO_MAX_BYTES`. */
+export const CONTACT_PHOTO_QUALITIES = [0.85, 0.75, 0.65, 0.55, 0.45, 0.35];
+
+/** The most pixels (width x height) a picture may have to be decoded: a few kilobytes of PNG can say 30000 x 30000, which takes gigabytes of memory to decode. */
+export const CONTACT_PHOTO_MAX_PIXELS = 16_000_000;
+/** How much of the start of a picture is read to find its size: a JPEG's EXIF segment (up to 64 KB) comes before the size. */
+const HEADER_BYTES = 128 * 1024;
+
+export const CONTACT_PHOTO_UNSUPPORTED_MESSAGE = "This picture's format isn't supported by your browser — choose a JPEG or PNG instead.";
+export const CONTACT_PHOTO_TOO_LARGE_MESSAGE = "This picture could not be made small enough — choose another one.";
+
+/** Why a chosen picture cannot be used (a format the browser cannot decode, such as HEIC, or one that stays too large); its `message` is fit to show the user. */
+export class ContactPhotoError extends Error {
+    constructor(message: string = CONTACT_PHOTO_UNSUPPORTED_MESSAGE) {
+        super(message);
+        this.name = "ContactPhotoError";
+    }
+}
+
+/** How many JPEG segments are read, one small read each, past the start of a picture before giving up on finding its size. */
+const MAX_JPEG_SEGMENTS = 4096;
+
+/** What a JPEG segment starting at `view[0]` (`view` holds its first 9 bytes, fewer at the end of the file) says: how far to its
+ * next segment (`skip`), its size when it is the first frame header ("SOFn"), or `undefined` when there is nothing more to read -
+ * not a marker, the start of the scan, or a cut-off header. */
+function jpegSegment(view: Uint8Array): { skip: number } | { width: number; height: number } | undefined {
+    const be16 = (offset: number) => (view[offset] << 8) | view[offset + 1];
+    if (view.length < 4 || view[0] !== 0xff) {
+        return undefined;
+    }
+    const marker = view[1];
+    if (marker === 0xff) {
+        return { skip: 1 };
+    }
+    if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+        return { skip: 2 };
+    }
+    if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+        return view.length >= 9 ? { width: be16(7), height: be16(5) } : undefined;
+    }
+    return marker === 0xda ? undefined : { skip: 2 + be16(2) };
+}
+
+/** The size of the JPEG `file`, read segment by segment from `offset` (where its start ran out) - an ICC profile or several EXIF/XMP
+ * segments can put the frame header well past the start. */
+async function jpegSizeFrom(file: Blob, offset: number): Promise<{ width: number; height: number } | undefined> {
+    for (let count = 0; count < MAX_JPEG_SEGMENTS && offset < file.size; count++) {
+        const segment = jpegSegment(new Uint8Array(await file.slice(offset, offset + 9).arrayBuffer()));
+        if (!segment) {
+            return undefined;
+        }
+        if ("width" in segment) {
+            return segment;
+        }
+        offset += segment.skip;
+    }
+    return undefined;
+}
+
+/** What the start of a picture says about it: whether it is a JPEG, its size when that can be read from it and, for a JPEG whose
+ * start ran out before its frame header, where to read on from (`resume`). */
+function inspect(head: Uint8Array): { jpeg: boolean; width?: number; height?: number; resume?: number } {
+    const at = (offset: number, text: string) => Array.from(text).every((char, i) => head[offset + i] === char.charCodeAt(0));
+    const be16 = (offset: number) => (head[offset] << 8) | head[offset + 1];
+    const be32 = (offset: number) => be16(offset) * 65536 + be16(offset + 2);
+    const le16 = (offset: number) => head[offset] | (head[offset + 1] << 8);
+    const le24 = (offset: number) => le16(offset) | (head[offset + 2] << 16);
+    const known = (width: number, height: number) => ({ jpeg: false, width, height });
+    if (at(0, "\x89PNG\r\n\x1a\n") && head.length >= 24) {
+        return known(be32(16), be32(20));
+    }
+    if (at(0, "GIF8") && head.length >= 10) {
+        return known(le16(6), le16(8));
+    }
+    if (at(0, "RIFF") && at(8, "WEBP") && head.length >= 30) {
+        if (at(12, "VP8 ")) {
+            return known(le16(26) & 0x3fff, le16(28) & 0x3fff);
+        }
+        if (at(12, "VP8L")) {
+            const bits = (le16(21) | (le16(23) << 16)) >>> 0;
+            return known((bits & 0x3fff) + 1, ((bits >>> 14) & 0x3fff) + 1);
+        }
+        if (at(12, "VP8X")) {
+            return known(le24(24) + 1, le24(27) + 1);
+        }
+        return { jpeg: false };
+    }
+    if (!(head[0] === 0xff && head[1] === 0xd8)) {
+        return { jpeg: false };
+    }
+    // A JPEG is a run of segments (`FF marker`, then a length unless the marker stands alone); the size is in the first frame header, "SOFn".
+    let offset = 2;
+    while (offset + 4 <= head.length) {
+        const segment = jpegSegment(head.subarray(offset, offset + 9));
+        if (!segment) {
+            return { jpeg: true };
+        }
+        if ("width" in segment) {
+            return { jpeg: true, ...segment };
+        }
+        offset += segment.skip;
+    }
+    return { jpeg: true, resume: offset };
+}
+
+interface Decoded {
+    source: CanvasImageSource;
+    width: number;
+    height: number;
+    /** Frees what holds the decoded pixels. */
+    release: () => void;
+}
+
+/** Decodes with the orientation of the photo's EXIF applied, so a phone's sideways-stored picture comes out upright. */
+async function decode(file: Blob): Promise<Decoded> {
+    if (typeof createImageBitmap === "function") {
+        try {
+            const bitmap = await createImageBitmap(file, { imageOrientation: "from-image" });
+            return { source: bitmap, width: bitmap.width, height: bitmap.height, release: () => bitmap.close() };
+        } catch {
+            // Fall through: an `<img>` may still read what this `createImageBitmap()` would not.
+        }
+    }
+    // An `<img>` applies the EXIF orientation itself (`image-orientation: from-image` is the default).
+    const url = URL.createObjectURL(file);
+    try {
+        const image = await new Promise<HTMLImageElement>((resolve, reject) => {
+            const element = new Image();
+            element.onload = () => resolve(element);
+            element.onerror = () => reject(new ContactPhotoError());
+            element.src = url;
+        });
+        return { source: image, width: image.naturalWidth, height: image.naturalHeight, release: () => undefined };
+    } finally {
+        URL.revokeObjectURL(url);
+    }
+}
+
+interface Surface {
+    context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+    encode: (type: string, quality?: number) => Promise<Blob | null>;
+}
+
+function createSurface(side: number): Surface {
+    if (typeof OffscreenCanvas === "function") {
+        const canvas = new OffscreenCanvas(side, side);
+        const context = canvas.getContext("2d");
+        if (!context) {
+            throw new ContactPhotoError();
+        }
+        return { context, encode: (type, quality) => canvas.convertToBlob({ type, quality }) };
+    }
+    const canvas = document.createElement("canvas");
+    canvas.width = side;
+    canvas.height = side;
+    const context = canvas.getContext("2d");
+    if (!context) {
+        throw new ContactPhotoError();
+    }
+    return { context, encode: (type, quality) => new Promise((resolve) => canvas.toBlob(resolve, type, quality)) };
+}
+
+function hasTransparency(context: Surface["context"], side: number): boolean {
+    const { data } = context.getImageData(0, 0, side, side);
+    for (let i = 3; i < data.length; i += 4) {
+        if (data[i] < 255) {
+            return true;
+        }
+    }
+    return false;
+}
+
+function renamed(name: string, extension: "jpg" | "png" | "webp"): string {
+    return `${name.replace(/\.[^./\\]*$/, "") || "photo"}.${extension}`;
+}
+
+/**
+ * The picture to upload for `file`. A picture the server already takes (an accepted type within the byte limit and at most `CONTACT_PHOTO_MAX_SIDE` pixels a
+ * side) is returned as it is - an animated GIF stays animated - unless it is a JPEG, which is always drawn again to drop its EXIF. Anything else (a phone's 6 MB photo, a HEIC, a huge PNG) is decoded with its EXIF orientation applied,
+ * cropped to the centered square - avatars are circular, so the corners are never seen - scaled down to at most `CONTACT_PHOTO_OUTPUT_SIDE` pixels and encoded as a
+ * JPEG (transparent parts on white, quality lowered step by step until it fits), or kept as PNG/WebP when it has transparency and still fits.
+ *
+ * @throws ContactPhotoError when the browser cannot decode it (HEIC, or not a picture at all), it says it has more than `CONTACT_PHOTO_MAX_PIXELS` pixels
+ * (it is not decoded at all then) or it cannot be made small enough.
+ */
+export async function prepareContactPhoto(file: File): Promise<File> {
+    const accepted = CONTACT_PHOTO_TYPES.includes(file.type) && file.size <= CONTACT_PHOTO_MAX_BYTES;
+    let head = inspect(new Uint8Array(await file.slice(0, HEADER_BYTES).arrayBuffer()));
+    if (head.resume !== undefined) {
+        head = { ...head, ...(await jpegSizeFrom(file, head.resume)) };
+    }
+    if (head.jpeg && (!head.width || !head.height)) {
+        // A JPEG whose size is not found within the segments read (or is given as zero, to be redefined by a later marker) could be of any
+        // size, and would reach the decoder unchecked.
+        throw new ContactPhotoError();
+    }
+    if (head.width !== undefined && head.height !== undefined && head.width * head.height > CONTACT_PHOTO_MAX_PIXELS) {
+        throw new ContactPhotoError(CONTACT_PHOTO_TOO_LARGE_MESSAGE);
+    }
+    // A JPEG is always drawn again: its EXIF (the camera, the time, often where it was taken) would otherwise be uploaded and shown to whoever sees the contact.
+    const jpeg = head.jpeg || file.type === "image/jpeg";
+    let decoded: Decoded;
+    try {
+        decoded = await decode(file);
+    } catch (err) {
+        if (accepted && !jpeg) {
+            // It cannot be measured here but the server takes it as it is.
+            return file;
+        }
+        throw err;
+    }
+    try {
+        const { source, width, height } = decoded;
+        // The size could not be read from the file itself (a format with no reader above, or a size past the segments read): what
+        // the decoder made of it is the last check before it is drawn.
+        if (width * height > CONTACT_PHOTO_MAX_PIXELS) {
+            throw new ContactPhotoError(CONTACT_PHOTO_TOO_LARGE_MESSAGE);
+        }
+        if (accepted && !jpeg && Math.max(width, height) <= CONTACT_PHOTO_MAX_SIDE) {
+            return file;
+        }
+        const crop = Math.min(width, height);
+        // Never enlarged: a small picture only gets cropped.
+        const side = Math.min(crop, CONTACT_PHOTO_OUTPUT_SIDE);
+        const { context, encode } = createSurface(side);
+        const draw = () => {
+            context.imageSmoothingQuality = "high";
+            context.drawImage(source, (width - crop) / 2, (height - crop) / 2, crop, crop, 0, 0, side, side);
+        };
+
+        draw();
+        if (["image/png", "image/webp", "image/gif"].includes(file.type) && hasTransparency(context, side)) {
+            const type = file.type === "image/webp" ? "image/webp" : "image/png";
+            const blob = await encode(type);
+            if (blob && blob.size <= CONTACT_PHOTO_MAX_BYTES) {
+                // A browser that cannot encode WebP answers with a PNG instead.
+                const kept = blob.type || type;
+                return new File([blob], renamed(file.name, kept === "image/webp" ? "webp" : "png"), { type: kept });
+            }
+            // Too large to keep the transparency: a JPEG has none, so what showed through becomes white.
+            context.clearRect(0, 0, side, side);
+        }
+        context.fillStyle = "#ffffff";
+        context.fillRect(0, 0, side, side);
+        draw();
+        for (const quality of CONTACT_PHOTO_QUALITIES) {
+            const blob = await encode("image/jpeg", quality);
+            if (!blob) {
+                throw new ContactPhotoError();
+            }
+            if (blob.size <= CONTACT_PHOTO_MAX_BYTES) {
+                return new File([blob], renamed(file.name, "jpg"), { type: "image/jpeg" });
+            }
+        }
+        throw new ContactPhotoError(CONTACT_PHOTO_TOO_LARGE_MESSAGE);
+    } finally {
+        decoded.release();
+    }
+}

package/lib/contacts/useContactPhotoSrc.ts

@@ -0,0 +1,177 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import type { ApiClient } from "../util/api.js";
+import { type Contact, contactPhotoUrl, fetchContactPhoto } from "./contactsApi.js";
+
+/** How many pictures stay loaded (as `blob:` URLs) after nothing shows them any more, so a list scrolled back over does not fetch them all again. */
+const CACHE_LIMIT = 50;
+
+interface Entry {
+    url: string;
+    /** How many mounted avatars show this URL; it is never revoked while that is more than none. */
+    refs: number;
+}
+
+/** Least recently used first (a `Map` iterates in insertion order, and a use moves the entry to the end). */
+const entries = new Map<string, Entry>();
+/** Fetches in flight, and how many avatars are waiting on each (they are all counted as showing the picture the moment it is stored). */
+const pending = new Map<string, { request: Promise<string>; waiters: number }>();
+const clientIds = new WeakMap<ApiClient, number>();
+let nextClientId = 0;
+
+/** One key per picture of one account: the same uid never collides across the clients of a multi-account app, and a replaced picture (new version) is a new key. */
+function keyOf(client: ApiClient, uid: string, version: number): string {
+    let id = clientIds.get(client);
+    if (id === undefined) {
+        id = nextClientId++;
+        clientIds.set(client, id);
+    }
+    return `${id}:${uid}:${version}`;
+}
+
+/** Revokes the pictures beyond the limit that nothing shows, oldest first. */
+function trim(): void {
+    for (const [key, entry] of entries) {
+        if (entries.size <= CACHE_LIMIT) {
+            return;
+        }
+        if (entry.refs === 0) {
+            URL.revokeObjectURL(entry.url);
+            entries.delete(key);
+        }
+    }
+}
+
+/** How many pictures are fetched at once; a list of a hundred contacts must not open a hundred requests together. */
+const MAX_CONCURRENT_FETCHES = 4;
+let fetching = 0;
+const waiting: (() => void)[] = [];
+
+/** Runs `task` once fewer than `MAX_CONCURRENT_FETCHES` others are running, in the order asked. */
+function limited<T>(task: () => Promise<T>): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+        const run = () => {
+            task()
+                .then(resolve, reject)
+                .finally(() => {
+                    // A waiting task takes over the slot; it is only given up when none waits.
+                    const next = waiting.shift();
+                    if (next) {
+                        next();
+                    } else {
+                        fetching--;
+                    }
+                });
+        };
+        if (fetching < MAX_CONCURRENT_FETCHES) {
+            fetching++;
+            run();
+        } else {
+            waiting.push(run);
+        }
+    });
+}
+
+/** The `blob:` URL for `key`, fetched with `load` unless it is cached, and counted as shown until `release()`. Concurrent callers share one fetch. */
+async function acquire(key: string, load: () => Promise<Blob>): Promise<string> {
+    const entry = entries.get(key);
+    if (entry) {
+        entry.refs++;
+        entries.delete(key);
+        entries.set(key, entry);
+        return entry.url;
+    }
+    let shared = pending.get(key);
+    if (!shared) {
+        const created: { request: Promise<string>; waiters: number } = {
+            waiters: 0,
+            request: limited(load)
+                .then((blob) => {
+                    const url = URL.createObjectURL(blob);
+                    // Claimed by everyone waiting from the start: an entry nobody holds yet could be trimmed before its avatar got to it.
+                    entries.set(key, { url, refs: created.waiters });
+                    return url;
+                })
+                .finally(() => pending.delete(key)),
+        };
+        pending.set(key, created);
+        shared = created;
+    }
+    shared.waiters++;
+    return shared.request;
+}
+
+function release(key: string): void {
+    const entry = entries.get(key);
+    if (entry) {
+        entry.refs--;
+    }
+    trim();
+}
+
+/** Forgets every cached picture (and revokes its URL). For a test, or when an account is signed out. */
+export function clearContactPhotoCache(): void {
+    for (const entry of entries.values()) {
+        URL.revokeObjectURL(entry.url);
+    }
+    entries.clear();
+}
+
+/**
+ * What to put in an `<img src>` for a contact's own picture, or `undefined` when they have none, it is still loading or it could not be loaded (the avatar
+ * then shows initials). Without an explicit `client` that is the plain `contactPhotoUrl()`: the browser sends the `jwt` cookie with the request. A
+ * token-authenticated client (the desktop and mobile apps) cannot do that - an `<img>` sends no `Authorization` header - so the picture is fetched through the client
+ * and shown as a `blob:` URL, cached per client, contact and version with a small LRU and revoked once it falls out of it and nothing shows it.
+ */
+export function useContactPhotoSrc(contact: Pick<Contact, "uid" | "version" | "photoBlobKey"> | undefined, client?: ApiClient): string | undefined {
+    return useContactPhoto(contact, client).src;
+}
+
+/**
+ * `useContactPhotoSrc()`, also saying whether a picture that has to be fetched could not be (`failed`: no `src` is coming), and held back until `active` - an avatar
+ * that is not on screen yet has no reason to fetch its picture.
+ */
+export function useContactPhoto(
+    contact: Pick<Contact, "uid" | "version" | "photoBlobKey"> | undefined,
+    client?: ApiClient,
+    active = true,
+): { src: string | undefined; failed: boolean } {
+    const [loaded, setLoaded] = useState<{ key: string; url: string } | undefined>();
+    const [failedKey, setFailedKey] = useState<string | undefined>();
+    const key = active && client && contact?.photoBlobKey ? keyOf(client, contact.uid, contact.version) : undefined;
+    const uid = contact?.uid;
+    const version = contact?.version;
+
+    useEffect(() => {
+        if (!key || !client) {
+            return;
+        }
+        let cancelled = false;
+        let held = false;
+        acquire(key, () => fetchContactPhoto(uid!, version!, client)).then(
+            (url) => {
+                if (cancelled) {
+                    release(key);
+                } else {
+                    held = true;
+                    setLoaded({ key, url });
+                }
+            },
+            () => !cancelled && setFailedKey(key),
+        );
+        return () => {
+            cancelled = true;
+            if (held) {
+                release(key);
+            }
+        };
+    }, [key]);
+
+    if (client) {
+        return { src: key !== undefined && loaded?.key === key ? loaded.url : undefined, failed: key !== undefined && failedKey === key };
+    }
+    return { src: contact && contactPhotoUrl(contact), failed: false };
+}