@rapidmx/web-client 0.9.0 → 0.11.0

package/apps/shared/appearance/appearanceCache.ts

@@ -0,0 +1,106 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { AppearanceMode, AppearancePreferences, normalizeAppearance } from "@rapidmx/react-shared/appearance/preferencesApi.js";
+import { rangeFromLevels, rangeToLevels } from "./photo.js";
+import type { PhotoRange } from "./theme.js";
+
+export 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 function cacheKeyOf(prefs: AppearancePreferences): string {
+    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: string | number | undefined): number {
+    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(): AppearanceCache | undefined {
+    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: AppearanceCache = {
+            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: AppearancePreferences,
+    css: string,
+    time: number,
+    uid?: string,
+    measured?: { version: string; range: PhotoRange },
+): void {
+    try {
+        const cache: AppearanceCache = { 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(): void {
+    try {
+        localStorage.removeItem(APPEARANCE_CACHE_KEY);
+    } catch {
+        // Nothing to forget.
+    }
+}

package/apps/shared/appearance/appearanceContext.ts

@@ -0,0 +1,77 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { createContext, useContext } from "react";
+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>;
+}
+
+const NOOP_PREFS: AppearancePreferences = { version: 1, mode: "system" };
+
+/** What `useAppearance()` returns outside an `AppearanceProvider` (a component tested alone): the defaults, and changes go nowhere. */
+export const INERT_APPEARANCE: AppearanceApi = {
+    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<AppearanceApi>(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(): AppearanceApi {
+    return useContext(AppearanceContext);
+}

package/apps/shared/appearance/bootScript.ts

@@ -0,0 +1,35 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { APPEARANCE_STYLE_ID } from "./theme.js";
+import { APPEARANCE_CACHE_KEY } from "./appearanceCache.js";
+
+/**
+ * The inline script the page layouts put in `<head>`, after the stylesheets and before the body, so the user's theme is in place before
+ * the first paint. It runs before any of this app's code and must not depend on it, which is why it is a plain ES5 string:
+ *
+ * - it reads the cache `AppearanceProvider` keeps in `localStorage` (`appearanceCache.ts`): finished stylesheet text, the mode, the key
+ * of the preferences they were made from and the time they were last changed (`t`);
+ * - it does nothing when the cache belongs to another account (`<html data-uid>` names the signed-in one, when the page knows it), or
+ * when the server already rendered a stylesheet (`<style data-key data-t>`) for *different* preferences that are at least as new: the
+ * server's copy can be a minute old, so it only wins when it is not older than the browser's;
+ * - otherwise it puts the cached stylesheet in the page (replacing the server's, which for the same preferences lacks the measured
+ * lightness of the background image), or removes the server's when the cache says nothing is chosen, and sets `<html data-theme>` for
+ * an explicit "Light" or "Dark" (removing it for "System", whose stylesheet follows the operating system by media query).
+ *
+ * Any failure (storage blocked, bad JSON) leaves the page as it was.
+ */
+export const APPEARANCE_BOOT_SCRIPT =
+    "(function(){try{" +
+    `var c=JSON.parse(localStorage.getItem("${APPEARANCE_CACHE_KEY}")||"null"),d=document,h=d.documentElement;` +
+    'if(!c||c.v!==1||typeof c.css!=="string"||typeof c.key!=="string")return;' +
+    'var u=h.getAttribute("data-uid");if(u&&c.uid&&u!==c.uid)return;' +
+    `var s=d.getElementById("${APPEARANCE_STYLE_ID}");` +
+    'if(s&&s.getAttribute("data-key")!==c.key&&Number(s.getAttribute("data-t")||0)>=(c.t||0))return;' +
+    "if(c.css){" +
+    `if(!s){s=d.createElement("style");s.id="${APPEARANCE_STYLE_ID}";d.head.appendChild(s)}` +
+    's.setAttribute("data-key",c.key);s.textContent=c.css' +
+    "}else if(s){s.parentNode.removeChild(s)}" +
+    'if(c.mode==="light"||c.mode==="dark")h.setAttribute("data-theme",c.mode);else h.removeAttribute("data-theme")' +
+    "}catch(e){}})();";

package/apps/shared/appearance/color.ts

@@ -0,0 +1,169 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The small amount of colour maths theming needs, with no dependency: parsing and formatting `#rrggbb`, mixing, WCAG relative
+ * luminance and contrast, and deriving a readable text colour or a whole shade scale from one chosen colour. Pure - nothing here
+ * touches the DOM.
+ */
+
+/** A colour as 0-255 red, green and blue. */
+export interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+
+export const BLACK: Rgb = { r: 0, g: 0, b: 0 };
+export const WHITE: Rgb = { r: 255, g: 255, b: 255 };
+
+/** WCAG AA for normal-size text. */
+export const AA_CONTRAST = 4.5;
+
+const HEX_6 = /^#?([0-9a-f]{6})$/i;
+const HEX_3 = /^#?([0-9a-f])([0-9a-f])([0-9a-f])$/i;
+
+/** `#rrggbb` (or, forgivingly, `rrggbb`, `#rgb` and `rgb`, in any case) as a colour; `undefined` for anything else. */
+export function parseHex(input: string): Rgb | undefined {
+    const text = input.trim();
+    let digits: string;
+    const long = HEX_6.exec(text);
+    if (long) {
+        digits = long[1];
+    } else {
+        const short = HEX_3.exec(text);
+        if (!short) {
+            return undefined;
+        }
+        digits = short[1] + short[1] + short[2] + short[2] + short[3] + short[3];
+    }
+    const value = parseInt(digits, 16);
+    return { r: (value >> 16) & 255, g: (value >> 8) & 255, b: value & 255 };
+}
+
+function channel(value: number): number {
+    return Math.min(255, Math.max(0, Math.round(value)));
+}
+
+/** The colour as lower-case `#rrggbb` (channels are rounded and clamped). */
+export function toHex({ r, g, b }: Rgb): string {
+    return "#" + [r, g, b].map((value) => channel(value).toString(16).padStart(2, "0")).join("");
+}
+
+/** The lower-case `#rrggbb` form of a hex colour typed any of the forgiving ways `parseHex()` accepts; `undefined` if it isn't one. */
+export function normalizeHex(input: string): string | undefined {
+    const rgb = parseHex(input);
+    return rgb ? toHex(rgb) : undefined;
+}
+
+/** `true` for a strict `#rrggbb` (what the server stores). */
+export function isHexColor(input: string): boolean {
+    return /^#[0-9a-f]{6}$/i.test(input);
+}
+
+/** The colour `amount` of the way from `from` to `to` (0 is `from`, 1 is `to`), mixed in sRGB. */
+export function mix(from: Rgb, to: Rgb, amount: number): Rgb {
+    const t = Math.min(1, Math.max(0, amount));
+    return { r: from.r + (to.r - from.r) * t, g: from.g + (to.g - from.g) * t, b: from.b + (to.b - from.b) * t };
+}
+
+function linear(value: number): number {
+    const s = value / 255;
+    return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+}
+
+/** WCAG 2 relative luminance: 0 for black, 1 for white. */
+export function relativeLuminance({ r, g, b }: Rgb): number {
+    return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+}
+
+/** The gray (0-255) whose relative luminance is `luminance` - the inverse of `relativeLuminance()` for a gray. */
+export function grayOfLuminance(luminance: number): number {
+    const l = Math.min(1, Math.max(0, luminance));
+    const s = l <= 0.0031308 ? l * 12.92 : 1.055 * Math.pow(l, 1 / 2.4) - 0.055;
+    return channel(s * 255);
+}
+
+/** WCAG 2 contrast ratio between two colours: 1 (identical) to 21 (black on white). Symmetric. */
+export function contrastRatio(a: Rgb, b: Rgb): number {
+    const la = relativeLuminance(a);
+    const lb = relativeLuminance(b);
+    return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+/** The contrast ratio of two `#rrggbb` colours, `undefined` when either doesn't parse. */
+export function contrastOfHex(a: string, b: string): number | undefined {
+    const first = parseHex(a);
+    const second = parseHex(b);
+    return first && second ? contrastRatio(first, second) : undefined;
+}
+
+/** The app's own two text colours, for text that must sit on a colour of unknown lightness. */
+export const DARK_TEXT: Rgb = { r: 0x1c, g: 0x25, b: 0x26 };
+export const LIGHT_TEXT: Rgb = { r: 0xff, g: 0xff, b: 0xff };
+
+/**
+ * The app's dark or light text colour for text on `background`: `prefer` (light by default, as on the primary colour; the accent
+ * colour prefers dark) whenever that reaches AA contrast, else whichever of the two reads better.
+ */
+export function readableOn(background: Rgb, prefer: Rgb = LIGHT_TEXT): Rgb {
+    if (contrastRatio(prefer, background) >= AA_CONTRAST) {
+        return prefer;
+    }
+    return contrastRatio(DARK_TEXT, background) >= contrastRatio(LIGHT_TEXT, background) ? DARK_TEXT : LIGHT_TEXT;
+}
+
+/**
+ * `foreground`, moved toward black or white - whichever the background is further from - just far enough to reach `minimum`
+ * contrast against `background`; unchanged when it already does. Where even black or white can't (a mid-gray background can't reach
+ * 7:1), the best of the two.
+ */
+export function ensureContrast(foreground: Rgb, background: Rgb, minimum: number = AA_CONTRAST): Rgb {
+    if (contrastRatio(foreground, background) >= minimum) {
+        return foreground;
+    }
+    const target = contrastRatio(BLACK, background) >= contrastRatio(WHITE, background) ? BLACK : WHITE;
+    for (let step = 1; step <= 20; step++) {
+        const candidate = mix(foreground, target, step / 20);
+        if (contrastRatio(candidate, background) >= minimum) {
+            return candidate;
+        }
+    }
+    return target;
+}
+
+/** The shades the app's tokens come in, derived from one colour. */
+export interface PrimaryScale {
+    base: string;
+    dark: string;
+    darker: string;
+    darkest: string;
+    light: string;
+    lighter: string;
+    lightest: string;
+    /** Text that reads on `base`: `preferOnBase` (white by default) when that reaches AA contrast, else the better of the app's two. */
+    onBase: string;
+}
+
+/**
+ * The seven-step scale (`base`, three darker shades, three lighter ones) plus the text colour for a button of `base`, from the single
+ * `#rrggbb` a user picked. Shades are mixes with black and white, so the hue stays exactly the one chosen. `undefined` if `hex` isn't
+ * a colour.
+ */
+export function deriveScale(hex: string, preferOnBase: Rgb = LIGHT_TEXT): PrimaryScale | undefined {
+    const base = parseHex(hex);
+    if (!base) {
+        return undefined;
+    }
+    return {
+        base: toHex(base),
+        dark: toHex(mix(base, BLACK, 0.2)),
+        darker: toHex(mix(base, BLACK, 0.4)),
+        darkest: toHex(mix(base, BLACK, 0.55)),
+        light: toHex(mix(base, WHITE, 0.2)),
+        lighter: toHex(mix(base, WHITE, 0.4)),
+        lightest: toHex(mix(base, WHITE, 0.6)),
+        onBase: toHex(readableOn(base, preferOnBase)),
+    };
+}

package/apps/shared/appearance/photo.ts

@@ -0,0 +1,88 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * How light and how dark a background photo is, measured in the browser, so the panels over it are only as opaque as its busiest
+ * places demand (see `panelAlpha()`). Nothing is uploaded: the picture is drawn once at 32 x 32 pixels on a canvas and its lightest and
+ * darkest twentieth are taken.
+ */
+import { grayOfLuminance, Rgb, relativeLuminance } from "./color.js";
+import type { PhotoRange } from "./theme.js";
+
+/** The side, in pixels, of the square the picture is shrunk to for measuring. */
+export const MEASURE_SIZE = 32;
+
+/** Pixels more transparent than this don't count - a transparent PNG margin is whatever is behind it, not the picture. */
+const MIN_ALPHA = 128;
+
+function gray(level: number): Rgb {
+    return { r: level, g: level, b: level };
+}
+
+/**
+ * The 5th and 95th percentile of relative luminance across RGBA pixel data, as the grays that have them - the darkest and lightest
+ * a panel's text may sit over. `undefined` when no pixel is opaque enough to count.
+ */
+export function rangeOfPixels(rgba: ArrayLike<number>): PhotoRange | undefined {
+    const values: number[] = [];
+    for (let i = 0; i + 3 < rgba.length; i += 4) {
+        if (rgba[i + 3] >= MIN_ALPHA) {
+            values.push(relativeLuminance({ r: rgba[i], g: rgba[i + 1], b: rgba[i + 2] }));
+        }
+    }
+    if (values.length === 0) {
+        return undefined;
+    }
+    values.sort((a, b) => a - b);
+    const at = (fraction: number) => values[Math.min(values.length - 1, Math.floor(values.length * fraction))];
+    return { lo: gray(grayOfLuminance(at(0.05))), hi: gray(grayOfLuminance(at(0.95))) };
+}
+
+/**
+ * Loads `url` and measures it. `undefined` where it can't be done - no canvas, the picture doesn't load, or it comes from another
+ * origin without CORS and taints the canvas - in which case the caller assumes the worst.
+ */
+export async function measureImage(url: string): Promise<PhotoRange | undefined> {
+    if (typeof document === "undefined" || typeof Image === "undefined") {
+        return undefined;
+    }
+    try {
+        const image = new Image();
+        image.decoding = "async";
+        const loaded = new Promise<void>((resolve, reject) => {
+            image.onload = () => resolve();
+            image.onerror = () => reject(new Error("The image did not load."));
+        });
+        image.src = url;
+        await loaded;
+        const canvas = document.createElement("canvas");
+        canvas.width = MEASURE_SIZE;
+        canvas.height = MEASURE_SIZE;
+        const context = canvas.getContext("2d", { willReadFrequently: true });
+        if (!context) {
+            return undefined;
+        }
+        context.drawImage(image, 0, 0, MEASURE_SIZE, MEASURE_SIZE);
+        return rangeOfPixels(context.getImageData(0, 0, MEASURE_SIZE, MEASURE_SIZE).data);
+    } catch {
+        return undefined;
+    }
+}
+
+/** A measured range as the two gray levels the cache stores. */
+export function rangeToLevels(range: PhotoRange): [number, number] {
+    return [range.lo.r, range.hi.r];
+}
+
+/** The range for two stored gray levels; `undefined` unless both are numbers from 0 to 255. */
+export function rangeFromLevels(levels: unknown): PhotoRange | undefined {
+    if (
+        !Array.isArray(levels) ||
+        levels.length !== 2 ||
+        !levels.every((level) => typeof level === "number" && Number.isFinite(level) && level >= 0 && level <= 255)
+    ) {
+        return undefined;
+    }
+    return { lo: gray(levels[0]), hi: gray(levels[1]) };
+}

package/apps/shared/appearance/resolvedTheme.ts

@@ -0,0 +1,67 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useSyncExternalStore } from "react";
+
+/** The colour scheme the app is showing right now: what the user chose, or - for "System" - what the operating system prefers. */
+export type ResolvedTheme = "light" | "dark";
+
+/** The media query that says the operating system prefers a dark scheme. */
+export const DARK_SCHEME_QUERY = "(prefers-color-scheme: dark)";
+
+/**
+ * The scheme in effect: an explicit `data-theme="light" | "dark"` on `<html>` (set by `AppearanceProvider` for every choice
+ * including "System", and by a page's own `<html data-theme>`) wins, else the operating system's preference, else `"light"`.
+ * `"light"` where there is no document (server-side rendering).
+ */
+export function readResolvedTheme(): ResolvedTheme {
+    if (typeof document === "undefined") {
+        return "light";
+    }
+    const override = document.documentElement.getAttribute("data-theme");
+    if (override === "light" || override === "dark") {
+        return override;
+    }
+    return typeof window.matchMedia === "function" && window.matchMedia(DARK_SCHEME_QUERY).matches ? "dark" : "light";
+}
+
+/** Calls `onChange` when the operating system's scheme or `<html data-theme>` changes; returns the unsubscribe. */
+function subscribe(onChange: () => void): () => void {
+    const media = typeof window.matchMedia === "function" ? window.matchMedia(DARK_SCHEME_QUERY) : undefined;
+    media?.addEventListener("change", onChange);
+    const observer = new MutationObserver(onChange);
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: ["data-theme"] });
+    return () => {
+        media?.removeEventListener("change", onChange);
+        observer.disconnect();
+    };
+}
+
+/**
+ * `"light"` or `"dark"`: the scheme the app is showing now, kept live - it changes when the user picks another in Settings >
+ * Appearance and, while they follow the system, when the operating system's preference flips. For anything that must match the
+ * app's scheme without reading CSS (a message body rendered in its own document, a canvas, a chart). Needs no provider: it reads
+ * `<html data-theme>` and `matchMedia` itself. Renders `"light"` on the server and for the hydrating render, then the real value.
+ */
+export function useResolvedTheme(): ResolvedTheme {
+    return useSyncExternalStore(subscribe, readResolvedTheme, () => "light");
+}
+
+export { useAppearance } from "./appearanceContext.js";
+export type { AppearanceApi, AppearancePatch } from "./appearanceContext.js";
+
+function subscribeSystem(onChange: () => void): () => void {
+    const media = typeof window.matchMedia === "function" ? window.matchMedia(DARK_SCHEME_QUERY) : undefined;
+    media?.addEventListener("change", onChange);
+    return () => media?.removeEventListener("change", onChange);
+}
+
+function readSystemDark(): boolean {
+    return typeof window.matchMedia === "function" && window.matchMedia(DARK_SCHEME_QUERY).matches;
+}
+
+/** `true` while the operating system prefers a dark scheme - only the media query, never `<html data-theme>` (which `AppearanceProvider` sets from this). */
+export function useSystemPrefersDark(): boolean {
+    return useSyncExternalStore(subscribeSystem, readSystemDark, () => false);
+}