@rapidmx/web-client 0.10.0 → 0.12.0

package/dist/apps/shared/appearance/AppearanceProvider.js

@@ -0,0 +1,390 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { DEFAULT_BACKGROUND, appearanceBackgroundUrl, deleteAppearanceBackground, diffAppearance, getAppearance, isDefaultAppearance, normalizeAppearance, parseAppearanceEvent, saveAppearance, uploadAppearanceBackground, } from "@rapidmx/react-shared/appearance/preferencesApi.js";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { getPushClient } from "@rapidmx/react-shared/mail/pushClient.js";
+import { AppearanceContext } from "./appearanceContext.js";
+import { cacheKeyOf, readAppearanceCache, timeOf, writeAppearanceCache } from "./appearanceCache.js";
+import { measureImage, rangeFromLevels } from "./photo.js";
+import { useSystemPrefersDark } from "./resolvedTheme.js";
+import { APPEARANCE_STYLE_ID, appearanceCss } from "./theme.js";
+/** How long a change waits for a further one before it is saved - a slider being dragged is one save, not sixty. */
+export const APPEARANCE_SAVE_DELAY_MS = 400;
+/** The `imageVersion` the preview of a just-chosen file has until the server names the stored one. */
+const LOCAL_VERSION = "local";
+const DEFAULTS = { version: 1, mode: "system" };
+const useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+/** `prefs` with `patch` merged in, normalised (so an out-of-range number or bad colour can't get through). See `AppearancePatch`. */
+export function mergeAppearance(prefs, patch) {
+    const next = { version: 1, mode: patch.mode ?? prefs.mode };
+    const colors = { ...prefs.colors };
+    for (const [key, value] of Object.entries(patch.colors ?? {})) {
+        if (value === null || value === undefined) {
+            delete colors[key];
+        }
+        else {
+            colors[key] = value;
+        }
+    }
+    if (Object.keys(colors).length > 0) {
+        next.colors = colors;
+    }
+    if (patch.background !== null) {
+        const background = patch.background ? { ...(prefs.background ?? DEFAULT_BACKGROUND), ...patch.background } : prefs.background;
+        if (background) {
+            next.background = background;
+        }
+    }
+    if (prefs.updatedAt !== undefined) {
+        next.updatedAt = prefs.updatedAt;
+    }
+    return normalizeAppearance(next);
+}
+function toInput(prefs) {
+    const { updatedAt: _updatedAt, ...input } = prefs;
+    return input;
+}
+/** Whether two preference objects say the same thing, ignoring the server's timestamp. */
+function sameContent(a, b) {
+    return JSON.stringify(a && toInput(a)) === JSON.stringify(b && toInput(b));
+}
+function messageOf(err, fallback) {
+    return err instanceof ApiRequestError && err.message ? err.message : fallback;
+}
+/**
+ * Owns the user's appearance for the whole app: keeps the theme applied to the page and everything Settings > Appearance needs.
+ *
+ * - **Applies it.** One `<style id="rr-appearance">` in `<head>` (`appearanceCss()`) holds the user's colour tokens and the background
+ * layer, and `<html data-theme>` says which scheme is showing - the chosen one, or for "System" the operating system's, live.
+ * - **Instantly.** `setPrefs()`, `uploadBackground()`, `removeBackground()` and `reset()` change the page in the same frame; the save
+ * happens after (`APPEARANCE_SAVE_DELAY_MS` of quiet, coalesced), sending only what changed - the server merges - and a failed one
+ * rolls back to what the server has and sets `error`.
+ * - **No flash.** It starts from the server's `initial` preferences, or the browser's newer cached copy (which the inline boot script has
+ * already put in place before anything painted), and then asks the server what is true now.
+ * - **Stays current.** Another tab or device's change arrives as a push event and is applied unless this tab has changes of its own
+ * still in flight.
+ */
+export default function AppearanceProvider({ userUid, initial, lookUp = true, children }) {
+    const initialPrefs = useMemo(() => normalizeAppearance(initial), [initial]);
+    const [prefs, setPrefsState] = useState(initialPrefs);
+    // The server (or the user) has spoken: until then the page shows whatever the boot script applied from the cache.
+    const [authoritative, setAuthoritative] = useState(initialPrefs !== undefined);
+    const [local, setLocal] = useState(undefined);
+    const [measured, setMeasured] = useState(() => {
+        // Read here, not in an effect, so the first stylesheet the provider writes already has the measured panel opacity the boot script used.
+        const cache = typeof window === "undefined" ? undefined : readAppearanceCache();
+        const range = rangeFromLevels(cache?.measured?.levels);
+        return cache?.measured && range ? { version: cache.measured.version, range } : undefined;
+    });
+    const [saving, setSaving] = useState(false);
+    const [error, setError] = useState(null);
+    const systemDark = useSystemPrefersDark();
+    const prefsRef = useRef(prefs);
+    prefsRef.current = prefs;
+    /** What the server last acknowledged - what a failed save rolls back to, and what a save is a difference from. */
+    const serverRef = useRef(initialPrefs);
+    /** When this tab last changed the preferences itself (milliseconds), for the cache's time - see `appearanceCache.ts`. */
+    const changedAtRef = useRef(0);
+    const pendingRef = useRef(undefined);
+    const timerRef = useRef(undefined);
+    const flightRef = useRef(undefined);
+    const localRef = useRef(local);
+    localRef.current = local;
+    const resolved = (prefs?.mode ?? "system") === "system" ? (systemDark ? "dark" : "light") : prefs?.mode;
+    const apply = useCallback((next) => {
+        prefsRef.current = next;
+        setPrefsState(next);
+        setAuthoritative(true);
+    }, []);
+    /** `apply()` for a change the user made here: it is newer than anything the server has said so far. */
+    const applyLocal = useCallback((next) => {
+        changedAtRef.current = Date.now();
+        apply(next);
+    }, [apply]);
+    /** Puts the server's last acknowledged preferences back and says why. */
+    const rollback = useCallback((err, fallback) => {
+        pendingRef.current = undefined;
+        apply(serverRef.current);
+        setError(messageOf(err, fallback));
+    }, [apply]);
+    /** Saves whatever is pending, and whatever arrives while that is in flight, one request at a time. */
+    const flush = useCallback(() => {
+        clearTimeout(timerRef.current);
+        timerRef.current = undefined;
+        if (flightRef.current) {
+            return flightRef.current;
+        }
+        if (!pendingRef.current) {
+            return Promise.resolve();
+        }
+        const flight = (async () => {
+            try {
+                while (pendingRef.current) {
+                    const toSave = pendingRef.current;
+                    pendingRef.current = undefined;
+                    // Only what differs from what the server has: it merges, and refuses a body that names the image or a kind it can't yet show.
+                    const update = diffAppearance(serverRef.current, toInput(toSave));
+                    if (!update) {
+                        continue;
+                    }
+                    const stored = await saveAppearance(update);
+                    serverRef.current = stored;
+                    if (!pendingRef.current && prefsRef.current) {
+                        // Nothing newer waiting: take the server's timestamp (the values are the ones sent).
+                        apply({ ...prefsRef.current, updatedAt: stored.updatedAt });
+                    }
+                }
+            }
+            catch (err) {
+                rollback(err, "Your appearance could not be saved. It has been put back.");
+            }
+            finally {
+                flightRef.current = undefined;
+                setSaving(pendingRef.current !== undefined);
+            }
+        })();
+        flightRef.current = flight;
+        return flight;
+    }, [apply, rollback]);
+    /** Queues `next` to be saved after a quiet moment. */
+    const scheduleSave = useCallback((next) => {
+        pendingRef.current = next;
+        setSaving(true);
+        clearTimeout(timerRef.current);
+        timerRef.current = setTimeout(() => void flush(), APPEARANCE_SAVE_DELAY_MS);
+    }, [flush]);
+    // A change still waiting when the provider goes away (the page is closing) is sent now rather than lost.
+    useEffect(() => {
+        function flushWhenHidden() {
+            if (document.visibilityState === "hidden") {
+                void flush();
+            }
+        }
+        document.addEventListener("visibilitychange", flushWhenHidden);
+        return () => {
+            document.removeEventListener("visibilitychange", flushWhenHidden);
+            void flush();
+        };
+    }, [flush]);
+    const setPrefs = useCallback((patch) => {
+        setError(null);
+        const next = mergeAppearance(prefsRef.current ?? DEFAULTS, patch);
+        applyLocal(next);
+        scheduleSave(next);
+    }, [applyLocal, scheduleSave]);
+    const releaseLocal = useCallback(() => {
+        if (localRef.current) {
+            URL.revokeObjectURL(localRef.current);
+            localRef.current = undefined;
+        }
+        setLocal(undefined);
+    }, []);
+    const uploadBackground = useCallback(async (file) => {
+        setError(null);
+        releaseLocal();
+        const url = URL.createObjectURL(file);
+        localRef.current = url;
+        setLocal(url);
+        applyLocal(mergeAppearance(prefsRef.current ?? DEFAULTS, { background: { kind: "image", imageVersion: LOCAL_VERSION } }));
+        try {
+            // Whatever was changed a moment ago is stored first, so its (older) save can't land after the picture.
+            await flush();
+            const stored = await uploadAppearanceBackground(file);
+            if (stored.background?.imageVersion === undefined) {
+                throw new ApiRequestError("The server did not keep the image.", 502);
+            }
+            serverRef.current = stored;
+            const version = String(stored.background.imageVersion);
+            const merged = mergeAppearance(prefsRef.current ?? DEFAULTS, {
+                background: { kind: "image", imageVersion: stored.background.imageVersion },
+            });
+            apply({ ...merged, updatedAt: stored.updatedAt });
+            if (!sameContent(merged, stored)) {
+                // The user moved a slider while the image was uploading: the server has the older values.
+                scheduleSave(merged);
+            }
+            // The local preview stays until the stored image has loaded, so swapping to it doesn't blink.
+            const preload = new Image();
+            const swap = () => {
+                setMeasured((current) => (current?.version === LOCAL_VERSION ? { ...current, version } : current));
+                if (localRef.current === url) {
+                    releaseLocal();
+                }
+            };
+            preload.onload = swap;
+            preload.onerror = swap;
+            preload.src = appearanceBackgroundUrl(version);
+        }
+        catch (err) {
+            releaseLocal();
+            rollback(err, "That image could not be uploaded.");
+        }
+    }, [apply, applyLocal, flush, releaseLocal, rollback, scheduleSave]);
+    const removeBackground = useCallback(async () => {
+        setError(null);
+        const next = mergeAppearance(prefsRef.current ?? DEFAULTS, { background: { kind: "none", imageVersion: undefined } });
+        applyLocal(next);
+        releaseLocal();
+        try {
+            await flush();
+            serverRef.current = (await deleteAppearanceBackground()) ?? serverRef.current;
+            scheduleSave(next);
+        }
+        catch (err) {
+            rollback(err, "The background could not be removed.");
+        }
+    }, [applyLocal, flush, releaseLocal, rollback, scheduleSave]);
+    const reset = useCallback(async () => {
+        setError(null);
+        const hadImage = prefsRef.current?.background?.imageVersion !== undefined;
+        applyLocal(DEFAULTS);
+        releaseLocal();
+        pendingRef.current = undefined;
+        try {
+            await flush();
+            if (hadImage) {
+                serverRef.current = (await deleteAppearanceBackground()) ?? serverRef.current;
+            }
+            const update = diffAppearance(serverRef.current, toInput(DEFAULTS));
+            if (update) {
+                serverRef.current = await saveAppearance(update);
+            }
+        }
+        catch (err) {
+            rollback(err, "Your appearance could not be reset.");
+        }
+    }, [applyLocal, flush, releaseLocal, rollback]);
+    // The page's copy can be a minute old (the server caches a rendered page), and this browser may have changed the preferences since: the
+    // browser's own copy, when it is newer, is what to show - before the first paint, so nothing flips.
+    useIsomorphicLayoutEffect(() => {
+        if (initialPrefs === undefined) {
+            return;
+        }
+        const cache = readAppearanceCache();
+        if (cache && (!cache.uid || cache.uid === userUid) && cache.t > timeOf(initialPrefs.updatedAt)) {
+            apply(cache.prefs);
+        }
+        // Once, for the page as it was rendered.
+    }, []);
+    // Without the page's copy, the cache is what to show until the server answers; then the server's answer is, unless the user changed something
+    // meanwhile. With it, the server is asked too, to correct a page that was cached.
+    useEffect(() => {
+        if (!userUid) {
+            return;
+        }
+        if (initialPrefs === undefined) {
+            const cache = readAppearanceCache();
+            if (cache && (!cache.uid || cache.uid === userUid)) {
+                setPrefsState((current) => current ?? cache.prefs);
+            }
+        }
+        if (!lookUp) {
+            return;
+        }
+        let cancelled = false;
+        getAppearance().then((stored) => {
+            if (cancelled || pendingRef.current || flightRef.current || timerRef.current) {
+                return;
+            }
+            serverRef.current = stored;
+            if (!sameContent(stored, prefsRef.current)) {
+                apply(stored);
+            }
+        }, () => undefined);
+        return () => {
+            cancelled = true;
+        };
+    }, [initialPrefs, userUid, lookUp, apply]);
+    // Another tab or device changed it.
+    useEffect(() => {
+        if (!userUid) {
+            return;
+        }
+        return getPushClient().onEvent((event) => {
+            const pushed = parseAppearanceEvent(event);
+            if (pushed === undefined) {
+                return;
+            }
+            // Our own change still travelling (or its echo, which says what is already on screen) must not undo what is on screen.
+            if (pendingRef.current || flightRef.current || timerRef.current || sameContent(pushed ?? undefined, prefsRef.current)) {
+                return;
+            }
+            serverRef.current = pushed ?? undefined;
+            apply(pushed ?? undefined);
+        });
+    }, [userUid, apply]);
+    const version = prefs?.background?.imageVersion;
+    const imageUrl = local ?? (version === undefined || version === LOCAL_VERSION ? undefined : appearanceBackgroundUrl(version));
+    const measureKey = local ? LOCAL_VERSION : version === undefined ? undefined : String(version);
+    const isImage = prefs?.background?.kind === "image";
+    // Measure the picture (once per image) so the panels over it are only as opaque as it needs.
+    useEffect(() => {
+        if (!isImage || !imageUrl || !measureKey || measured?.version === measureKey) {
+            return;
+        }
+        let cancelled = false;
+        void measureImage(imageUrl).then((range) => {
+            if (!cancelled && range) {
+                setMeasured({ version: measureKey, range });
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [isImage, imageUrl, measureKey, measured?.version]);
+    const range = measured && measured.version === measureKey ? measured.range : undefined;
+    // Apply: the stylesheet, then the scheme.
+    useIsomorphicLayoutEffect(() => {
+        if (!authoritative && !prefs) {
+            // Nothing known yet: leave what the boot script applied from the cache.
+            return;
+        }
+        const css = appearanceCss(prefs, { measured: range, imageUrl });
+        let element = document.getElementById(APPEARANCE_STYLE_ID);
+        if (!css) {
+            element?.remove();
+        }
+        else {
+            if (!element) {
+                element = document.createElement("style");
+                element.id = APPEARANCE_STYLE_ID;
+                document.head.appendChild(element);
+            }
+            element.textContent = css;
+            element.setAttribute("data-key", cacheKeyOf(prefs));
+        }
+        // What the next page load starts from: never a blob: preview, and "nothing chosen" is remembered too (an empty stylesheet), so a page
+        // cached by the server from before a reset doesn't bring the old background back.
+        if (!local) {
+            writeAppearanceCache(prefs ?? DEFAULTS, css, Math.max(timeOf(prefs?.updatedAt), changedAtRef.current), userUid, range && measureKey ? { version: measureKey, range } : undefined);
+        }
+    }, [authoritative, prefs, range, imageUrl, local, userUid, measureKey]);
+    useIsomorphicLayoutEffect(() => {
+        document.documentElement.setAttribute("data-theme", resolved);
+    }, [resolved]);
+    // A blob: URL that outlives the provider leaks the picture's memory.
+    useEffect(() => () => {
+        if (localRef.current) {
+            URL.revokeObjectURL(localRef.current);
+        }
+    }, []);
+    const value = useMemo(() => ({
+        prefs: prefs ?? DEFAULTS,
+        resolved,
+        backgroundUrl: imageUrl,
+        measured: range,
+        isDefault: isDefaultAppearance(prefs),
+        saving,
+        error,
+        clearError: () => setError(null),
+        setPrefs,
+        uploadBackground,
+        removeBackground,
+        reset,
+    }), [prefs, resolved, imageUrl, range, saving, error, setPrefs, uploadBackground, removeBackground, reset]);
+    return _jsx(AppearanceContext.Provider, { value: value, children: children });
+}

package/dist/apps/shared/appearance/ColorField.d.ts

@@ -0,0 +1,22 @@
+import React from "react";
+export interface ColorFieldProps {
+    /** Unique in the page: the ids of the two inputs derive from it. */
+    id: string;
+    label: string;
+    /** One line under the label saying what the colour is used for. */
+    description: string;
+    /** The colour the user chose, `#rrggbb`; `undefined` while they haven't. */
+    value: string | undefined;
+    /** What shows while unset: the colour the app has now. */
+    current: string;
+    /** Called with a new `#rrggbb` as the person picks or types one - on every change, so the app follows a drag on the picker. */
+    onChange: (hex: string) => void;
+    /** Called for "Reset": back to the app's own colour. Absent for a field with nothing to reset to. */
+    onReset?: () => void;
+}
+/**
+ * A colour to choose: the browser's colour picker beside a hex field (`#rrggbb`, and the short `#rgb` and a missing `#` are understood),
+ * and a "Reset" that goes back to the app's own colour. A full `#rrggbb` is applied as it is typed, a short one when the field is left, and
+ * something that isn't a colour changes nothing - the field says so and goes back to the current colour when it is left.
+ */
+export default function ColorField({ id, label, description, value, current, onChange, onReset }: ColorFieldProps): React.JSX.Element;

package/dist/apps/shared/appearance/ColorField.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useState } from "react";
+import { isHexColor, normalizeHex } from "./color.js";
+/**
+ * A colour to choose: the browser's colour picker beside a hex field (`#rrggbb`, and the short `#rgb` and a missing `#` are understood),
+ * and a "Reset" that goes back to the app's own colour. A full `#rrggbb` is applied as it is typed, a short one when the field is left, and
+ * something that isn't a colour changes nothing - the field says so and goes back to the current colour when it is left.
+ */
+export default function ColorField({ id, label, description, value, current, onChange, onReset }) {
+    // What is being typed, while it is: `null` shows the colour itself (after a pick, or once the field is left).
+    const [draft, setDraft] = useState(null);
+    const shown = value ?? current;
+    const invalid = draft !== null && normalizeHex(draft) === undefined;
+    return (_jsxs("div", { className: "flex flex-wrap items-center gap-x-3 gap-y-1", children: [_jsxs("div", { className: "min-w-0 flex-1 basis-40", children: [_jsx("label", { htmlFor: `${id}-hex`, className: "block text-sm font-semibold text-text", children: label }), _jsx("p", { id: `${id}-description`, className: "text-xs text-text-muted", children: description })] }), _jsx("input", { type: "color", "aria-label": `${label} picker`, value: shown, onChange: (event) => {
+                    setDraft(null);
+                    // A colour input only ever holds a `#rrggbb` (the browser sanitises anything else to black).
+                    onChange(normalizeHex(event.target.value));
+                }, className: "h-9 w-12 shrink-0 cursor-pointer rounded-sm border border-border bg-surface p-0.5" }), _jsx("div", { className: "w-28 shrink-0", children: _jsx("input", { id: `${id}-hex`, type: "text", inputMode: "text", autoComplete: "off", spellCheck: false, maxLength: 7, value: draft ?? shown, "aria-invalid": invalid || undefined, "aria-describedby": invalid ? `${id}-error ${id}-description` : `${id}-description`, onChange: (event) => {
+                        setDraft(event.target.value);
+                        // Only a complete `#rrggbb` (the hash is optional) is applied while typing: `#1a2` on the way to `#1a2b3c` would flash `#11aa22`.
+                        const typed = event.target.value.trim();
+                        if (isHexColor(typed.startsWith("#") ? typed : "#" + typed)) {
+                            onChange(normalizeHex(typed));
+                        }
+                    }, onBlur: () => {
+                        // Leaving the field applies a short form (`#abc`) that was typed, and drops anything that isn't a colour.
+                        const hex = draft === null ? undefined : normalizeHex(draft);
+                        if (hex && hex !== shown) {
+                            onChange(hex);
+                        }
+                        setDraft(null);
+                    }, className: "w-full rounded-sm border border-border bg-surface px-2 py-1.5 font-mono text-sm text-text" }) }), onReset && (_jsx("button", { type: "button", onClick: () => {
+                    setDraft(null);
+                    onReset();
+                }, disabled: value === undefined, "aria-label": `Reset ${label.toLowerCase()} to the default`, className: "shrink-0 rounded-sm px-2 py-1.5 text-sm font-semibold text-accent-dark hover:not-disabled:underline disabled:cursor-not-allowed disabled:opacity-50", children: "Reset" })), invalid && (_jsx("p", { id: `${id}-error`, role: "alert", className: "basis-full text-xs text-danger", children: "Use a colour like #1a2b3c." }))] }));
+}

package/dist/apps/shared/appearance/appearanceCache.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The last appearance this browser applied, kept in `localStorage` so a page load (or a page the server didn't send the preferences
+ * to) paints with the user's theme from the first frame instead of flashing the default. It holds the finished stylesheet text, so
+ * the tiny inline script in `<head>` (`APPEARANCE_BOOT_SCRIPT`) applies it without any of this app's code having loaded.
+ *
+ * **Which copy wins.** The server renders a page's preferences into it, but the server caches a rendered page for up to a minute, so
+ * that copy can be *older* than what this browser last applied (a change made a few seconds ago). Each copy therefore carries a time -
+ * the server's `updatedAt`, or for an edit this browser has made and not yet heard back about, the moment it was made - and the newer
+ * one is applied (`t`). After a reset the cache keeps an empty stylesheet ("nothing chosen") rather than being removed, for the same
+ * reason: it is newer than the stale page's idea of a background. Every access is in try/catch: storage can be blocked, full or
+ * absent (private windows, server-side rendering).
+ */
+import { AppearanceMode, AppearancePreferences } from "@rapidmx/react-shared/appearance/preferencesApi.js";
+import type { PhotoRange } from "./theme.js";
+export declare const APPEARANCE_CACHE_KEY = "rapidmx-appearance";
+export interface AppearanceCache {
+    v: 1;
+    /** Whose it is - so a browser shared by two accounts never shows one the other's background. Absent when the page didn't know. */
+    uid?: string;
+    /** `cacheKeyOf(prefs)`: what the stylesheet was made from. */
+    key: string;
+    /** When these preferences were last changed, in milliseconds - see this module's doc comment. */
+    t: number;
+    mode: AppearanceMode;
+    prefs: AppearancePreferences;
+    /** The finished stylesheet text; empty when the preferences change nothing. */
+    css: string;
+    /** The measured lightness of the image, as two gray levels, with the image version they belong to. */
+    measured?: {
+        version: string;
+        levels: [number, number];
+    };
+}
+/** What identifies a set of preferences (the server-rendered stylesheet carries the same in `data-key`): their normalised JSON, whose key order is always the same. */
+export declare function cacheKeyOf(prefs: AppearancePreferences): string;
+/** A server `updatedAt` (an ISO date or milliseconds, both opaque to the rest of the client) as milliseconds; `0` for none or one that isn't a date. */
+export declare function timeOf(updatedAt: string | number | undefined): number;
+/** The stored cache, or `undefined` when there is none, it can't be read, or it isn't well formed. */
+export declare function readAppearanceCache(): AppearanceCache | undefined;
+export declare function writeAppearanceCache(prefs: AppearancePreferences, css: string, time: number, uid?: string, measured?: {
+    version: string;
+    range: PhotoRange;
+}): void;
+/** Forgets the cache - on sign-out, so the next person to sign in on this browser starts from their own. */
+export declare function clearAppearanceCache(): void;

package/dist/apps/shared/appearance/appearanceCache.js

@@ -0,0 +1,80 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The last appearance this browser applied, kept in `localStorage` so a page load (or a page the server didn't send the preferences
+ * to) paints with the user's theme from the first frame instead of flashing the default. It holds the finished stylesheet text, so
+ * the tiny inline script in `<head>` (`APPEARANCE_BOOT_SCRIPT`) applies it without any of this app's code having loaded.
+ *
+ * **Which copy wins.** The server renders a page's preferences into it, but the server caches a rendered page for up to a minute, so
+ * that copy can be *older* than what this browser last applied (a change made a few seconds ago). Each copy therefore carries a time -
+ * the server's `updatedAt`, or for an edit this browser has made and not yet heard back about, the moment it was made - and the newer
+ * one is applied (`t`). After a reset the cache keeps an empty stylesheet ("nothing chosen") rather than being removed, for the same
+ * reason: it is newer than the stale page's idea of a background. Every access is in try/catch: storage can be blocked, full or
+ * absent (private windows, server-side rendering).
+ */
+import { normalizeAppearance } from "@rapidmx/react-shared/appearance/preferencesApi.js";
+import { rangeFromLevels, rangeToLevels } from "./photo.js";
+export const APPEARANCE_CACHE_KEY = "rapidmx-appearance";
+/** What identifies a set of preferences (the server-rendered stylesheet carries the same in `data-key`): their normalised JSON, whose key order is always the same. */
+export function cacheKeyOf(prefs) {
+    return JSON.stringify(normalizeAppearance(prefs) ?? prefs);
+}
+/** A server `updatedAt` (an ISO date or milliseconds, both opaque to the rest of the client) as milliseconds; `0` for none or one that isn't a date. */
+export function timeOf(updatedAt) {
+    const time = typeof updatedAt === "number" ? updatedAt : updatedAt === undefined ? 0 : Date.parse(updatedAt);
+    return Number.isFinite(time) ? time : 0;
+}
+/** The stored cache, or `undefined` when there is none, it can't be read, or it isn't well formed. */
+export function readAppearanceCache() {
+    try {
+        const raw = JSON.parse(localStorage.getItem(APPEARANCE_CACHE_KEY) ?? "null");
+        const prefs = normalizeAppearance(raw?.prefs);
+        if (raw?.v !== 1 || !prefs || typeof raw.css !== "string") {
+            return undefined;
+        }
+        const cache = {
+            v: 1,
+            key: cacheKeyOf(prefs),
+            t: typeof raw.t === "number" && Number.isFinite(raw.t) ? raw.t : 0,
+            mode: prefs.mode,
+            prefs,
+            css: raw.css,
+        };
+        if (typeof raw.uid === "string") {
+            cache.uid = raw.uid;
+        }
+        if (typeof raw.measured?.version === "string" && rangeFromLevels(raw.measured.levels)) {
+            cache.measured = { version: raw.measured.version, levels: raw.measured.levels };
+        }
+        return cache;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeAppearanceCache(prefs, css, time, uid, measured) {
+    try {
+        const cache = { v: 1, key: cacheKeyOf(prefs), t: time, mode: prefs.mode, prefs, css };
+        if (uid) {
+            cache.uid = uid;
+        }
+        if (measured) {
+            cache.measured = { version: measured.version, levels: rangeToLevels(measured.range) };
+        }
+        localStorage.setItem(APPEARANCE_CACHE_KEY, JSON.stringify(cache));
+    }
+    catch {
+        // Storage is unavailable or full: the theme still applies, it just isn't remembered.
+    }
+}
+/** Forgets the cache - on sign-out, so the next person to sign in on this browser starts from their own. */
+export function clearAppearanceCache() {
+    try {
+        localStorage.removeItem(APPEARANCE_CACHE_KEY);
+    }
+    catch {
+        // Nothing to forget.
+    }
+}

package/dist/apps/shared/appearance/appearanceContext.d.ts

@@ -0,0 +1,45 @@
+import type { AppearanceBackground, AppearanceMode, AppearancePreferences, ColorKey } from "@rapidmx/react-shared/appearance/preferencesApi.js";
+import type { ResolvedTheme } from "./resolvedTheme.js";
+import type { PhotoRange } from "./theme.js";
+/**
+ * A change to the preferences, merged into what is there: `mode` replaces; each `colors` entry replaces that colour, and `null` clears
+ * it (back to the app's own); `background` merges into the current one (or a fresh one); `background: null` removes it.
+ */
+export interface AppearancePatch {
+    mode?: AppearanceMode;
+    colors?: Partial<Record<ColorKey, string | null>>;
+    background?: Partial<AppearanceBackground> | null;
+}
+export interface AppearanceApi {
+    /** What is showing now - the user's choices including one still being saved. Never `undefined`: a user who chose nothing has the defaults. */
+    prefs: AppearancePreferences;
+    /** The scheme showing: the chosen mode, or for "System" the operating system's. */
+    resolved: ResolvedTheme;
+    /** Where the background image is loaded from - the stored image's URL, or a local preview while it uploads. */
+    backgroundUrl: string | undefined;
+    /** The background image's measured lightness, once known (until then the panels assume the worst case). */
+    measured: PhotoRange | undefined;
+    /** Nothing customised - `Reset all` has nothing to do. */
+    isDefault: boolean;
+    /** A save is in flight or waiting for the next quiet moment. */
+    saving: boolean;
+    /** Why the last save failed, in words for the user; `null` after a success or `clearError()`. The change it belonged to was rolled back. */
+    error: string | null;
+    clearError: () => void;
+    /** Applies the change at once and saves it in the background; a failed save rolls back to what the server has and sets `error`. */
+    setPrefs: (patch: AppearancePatch) => void;
+    /** Shows `file` as the background at once (already checked with `validateBackgroundFile()`) while it uploads; rolls back on failure. */
+    uploadBackground: (file: Blob) => Promise<void>;
+    /** Removes the background image (and returns to no background). */
+    removeBackground: () => Promise<void>;
+    /** Back to the defaults: system scheme, the app's colours, no background. */
+    reset: () => Promise<void>;
+}
+/** What `useAppearance()` returns outside an `AppearanceProvider` (a component tested alone): the defaults, and changes go nowhere. */
+export declare const INERT_APPEARANCE: AppearanceApi;
+export declare const AppearanceContext: import("react").Context<AppearanceApi>;
+/**
+ * The user's appearance preferences and how to change them: `{ prefs, setPrefs, ... }` (see `AppearanceApi`). Changes apply to the
+ * whole app the instant they are made and are saved in the background. Outside an `AppearanceProvider` it is inert.
+ */
+export declare function useAppearance(): AppearanceApi;

package/dist/apps/shared/appearance/appearanceContext.js

@@ -0,0 +1,29 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { createContext, useContext } from "react";
+const NOOP_PREFS = { version: 1, mode: "system" };
+/** What `useAppearance()` returns outside an `AppearanceProvider` (a component tested alone): the defaults, and changes go nowhere. */
+export const INERT_APPEARANCE = {
+    prefs: NOOP_PREFS,
+    resolved: "light",
+    backgroundUrl: undefined,
+    measured: undefined,
+    isDefault: true,
+    saving: false,
+    error: null,
+    clearError: () => undefined,
+    setPrefs: () => undefined,
+    uploadBackground: () => Promise.resolve(),
+    removeBackground: () => Promise.resolve(),
+    reset: () => Promise.resolve(),
+};
+export const AppearanceContext = createContext(INERT_APPEARANCE);
+/**
+ * The user's appearance preferences and how to change them: `{ prefs, setPrefs, ... }` (see `AppearanceApi`). Changes apply to the
+ * whole app the instant they are made and are saved in the background. Outside an `AppearanceProvider` it is inert.
+ */
+export function useAppearance() {
+    return useContext(AppearanceContext);
+}