@rapidmx/web-client 0.10.0 → 0.11.0

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

@@ -0,0 +1,16 @@
+/**
+ * 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 declare const APPEARANCE_BOOT_SCRIPT: string;

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

@@ -0,0 +1,33 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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/dist/apps/shared/appearance/color.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 declare const BLACK: Rgb;
+export declare const WHITE: Rgb;
+/** WCAG AA for normal-size text. */
+export declare const AA_CONTRAST = 4.5;
+/** `#rrggbb` (or, forgivingly, `rrggbb`, `#rgb` and `rgb`, in any case) as a colour; `undefined` for anything else. */
+export declare function parseHex(input: string): Rgb | undefined;
+/** The colour as lower-case `#rrggbb` (channels are rounded and clamped). */
+export declare function toHex({ r, g, b }: Rgb): string;
+/** The lower-case `#rrggbb` form of a hex colour typed any of the forgiving ways `parseHex()` accepts; `undefined` if it isn't one. */
+export declare function normalizeHex(input: string): string | undefined;
+/** `true` for a strict `#rrggbb` (what the server stores). */
+export declare function isHexColor(input: string): boolean;
+/** The colour `amount` of the way from `from` to `to` (0 is `from`, 1 is `to`), mixed in sRGB. */
+export declare function mix(from: Rgb, to: Rgb, amount: number): Rgb;
+/** WCAG 2 relative luminance: 0 for black, 1 for white. */
+export declare function relativeLuminance({ r, g, b }: Rgb): number;
+/** The gray (0-255) whose relative luminance is `luminance` - the inverse of `relativeLuminance()` for a gray. */
+export declare function grayOfLuminance(luminance: number): number;
+/** WCAG 2 contrast ratio between two colours: 1 (identical) to 21 (black on white). Symmetric. */
+export declare function contrastRatio(a: Rgb, b: Rgb): number;
+/** The contrast ratio of two `#rrggbb` colours, `undefined` when either doesn't parse. */
+export declare function contrastOfHex(a: string, b: string): number | undefined;
+/** The app's own two text colours, for text that must sit on a colour of unknown lightness. */
+export declare const DARK_TEXT: Rgb;
+export declare const LIGHT_TEXT: Rgb;
+/**
+ * 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 declare function readableOn(background: Rgb, prefer?: Rgb): Rgb;
+/**
+ * `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 declare function ensureContrast(foreground: Rgb, background: Rgb, minimum?: number): Rgb;
+/** 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 declare function deriveScale(hex: string, preferOnBase?: Rgb): PrimaryScale | undefined;

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

@@ -0,0 +1,132 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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.
+ */
+export const BLACK = { r: 0, g: 0, b: 0 };
+export const WHITE = { 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) {
+    const text = input.trim();
+    let digits;
+    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) {
+    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 }) {
+    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) {
+    const rgb = parseHex(input);
+    return rgb ? toHex(rgb) : undefined;
+}
+/** `true` for a strict `#rrggbb` (what the server stores). */
+export function isHexColor(input) {
+    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, to, amount) {
+    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) {
+    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 }) {
+    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) {
+    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, b) {
+    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, b) {
+    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 = { r: 0x1c, g: 0x25, b: 0x26 };
+export const LIGHT_TEXT = { 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, prefer = LIGHT_TEXT) {
+    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, background, minimum = AA_CONTRAST) {
+    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 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, preferOnBase = LIGHT_TEXT) {
+    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/dist/apps/shared/appearance/photo.d.ts

@@ -0,0 +1,17 @@
+import type { PhotoRange } from "./theme.js";
+/** The side, in pixels, of the square the picture is shrunk to for measuring. */
+export declare const MEASURE_SIZE = 32;
+/**
+ * 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 declare function rangeOfPixels(rgba: ArrayLike<number>): PhotoRange | undefined;
+/**
+ * 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 declare function measureImage(url: string): Promise<PhotoRange | undefined>;
+/** A measured range as the two gray levels the cache stores. */
+export declare function rangeToLevels(range: PhotoRange): [number, number];
+/** The range for two stored gray levels; `undefined` unless both are numbers from 0 to 255. */
+export declare function rangeFromLevels(levels: unknown): PhotoRange | undefined;

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

@@ -0,0 +1,79 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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, relativeLuminance } from "./color.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) {
+    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) {
+    const values = [];
+    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) => 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) {
+    if (typeof document === "undefined" || typeof Image === "undefined") {
+        return undefined;
+    }
+    try {
+        const image = new Image();
+        image.decoding = "async";
+        const loaded = new Promise((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) {
+    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) {
+    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/dist/apps/shared/appearance/resolvedTheme.d.ts

@@ -0,0 +1,21 @@
+/** 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 declare 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 declare function readResolvedTheme(): ResolvedTheme;
+/**
+ * `"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 declare function useResolvedTheme(): ResolvedTheme;
+export { useAppearance } from "./appearanceContext.js";
+export type { AppearanceApi, AppearancePatch } from "./appearanceContext.js";
+/** `true` while the operating system prefers a dark scheme - only the media query, never `<html data-theme>` (which `AppearanceProvider` sets from this). */
+export declare function useSystemPrefersDark(): boolean;

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

@@ -0,0 +1,55 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useSyncExternalStore } from "react";
+/** 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() {
+    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) {
+    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() {
+    return useSyncExternalStore(subscribe, readResolvedTheme, () => "light");
+}
+export { useAppearance } from "./appearanceContext.js";
+function subscribeSystem(onChange) {
+    const media = typeof window.matchMedia === "function" ? window.matchMedia(DARK_SCHEME_QUERY) : undefined;
+    media?.addEventListener("change", onChange);
+    return () => media?.removeEventListener("change", onChange);
+}
+function readSystemDark() {
+    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() {
+    return useSyncExternalStore(subscribeSystem, readSystemDark, () => false);
+}

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

@@ -0,0 +1,111 @@
+/**
+ * Turns a user's `AppearancePreferences` into CSS - pure functions, no DOM (`AppearanceProvider` applies the result).
+ *
+ * **How the theme reaches the app.** The app's colours are custom properties (`--rr-color-*`, mapped to Tailwind's colours in
+ * `app.css`'s `@theme`), with a light set on `:root` and a dark set for `prefers-color-scheme: dark` and `[data-theme="dark"]`. A
+ * deployment's branding stylesheet re-points the same properties. The user's choices are emitted as one more set of those
+ * properties, `!important` and for both schemes (`appearanceCss()`), so precedence is: built-in defaults < the branding stylesheet <
+ * the user. A custom property declared `!important` on `<html>` cannot be beaten by any ordinary rule, however specific - but a
+ * branding stylesheet's own *rules* (say `nav { background: ... }`) are untouched and still decide their element, exactly as they
+ * always did; only the tokens are the user's.
+ *
+ * **Background.** With a background set, `--color-surface` and `--color-surface-alt` (what `bg-surface` and `bg-surface-alt` read)
+ * become the scheme's surface colour at an alpha, so the rail and header are translucent panels over the fixed background layer,
+ * and the content region (`#app-content`) is one such panel itself, its own `bg-surface` children transparent so panels never stack
+ * into an opaque slab; menus, dialogs and pop-ups reset both tokens to the opaque colour again (see `app.css`). The alpha is chosen
+ * so text stays at AA contrast over the photo (`panelAlpha()`).
+ */
+import type { AppearanceBackground, AppearanceColors, AppearancePreferences } from "@rapidmx/react-shared/appearance/preferencesApi.js";
+import { Rgb } from "./color.js";
+import type { ResolvedTheme } from "./resolvedTheme.js";
+/** What each scheme's tokens are without any customisation - `app.css`'s own values. */
+export interface SchemePalette {
+    surface: string;
+    text: string;
+    muted: string;
+}
+export declare const DEFAULT_PALETTE: Record<ResolvedTheme, SchemePalette>;
+/** The colours in effect for a scheme: the user's surface and text where chosen, else the defaults. */
+export interface EffectivePalette {
+    surface: Rgb;
+    text: Rgb;
+    muted: Rgb;
+    /** The user chose a surface. */
+    surfaceChosen: boolean;
+    /** The user chose a text colour, or the default one could not be read on their surface and was replaced. */
+    textAdjusted: boolean;
+}
+export declare function effectivePalette(colors: AppearanceColors | undefined, scheme: ResolvedTheme): EffectivePalette;
+/**
+ * The custom properties a user's colours set for one scheme - only those they changed (and what derives from them): the primary
+ * colour's seven-step scale and the text on it, the accent and its shades, and the surface / text family. Empty when they chose
+ * no colours.
+ */
+export declare function colorVariables(colors: AppearanceColors | undefined, scheme: ResolvedTheme): Record<string, string>;
+/** The lightest and darkest a background can be behind a panel, as colours. */
+export interface PhotoRange {
+    lo: Rgb;
+    hi: Rgb;
+}
+/** What is assumed of a photo nobody has measured: black in one corner and white in another. */
+export declare const WORST_CASE_PHOTO: PhotoRange;
+/** The panels are never more see-through than this ... */
+export declare const PANEL_ALPHA_MIN = 0.5;
+/** ... nor less than this (still a hint of the picture). */
+export declare const PANEL_ALPHA_MAX = 0.96;
+/**
+ * The opacity (0.5 to 0.96) of the surface panels over a background, the lowest for which text and muted text keep AA contrast
+ * against the worst place the picture can be. What is behind a panel is the picture under the dim (`dim` of the surface colour laid
+ * over it); the panel is `alpha` of the surface over that, so the picture's share of what the text sits on is `(1 - alpha) *
+ * (1 - dim)`. A wide-ranging (busy) photo therefore gets more opaque panels than a plain one, and more dim allows less opaque
+ * panels.
+ */
+export declare function panelAlpha(palette: Pick<EffectivePalette, "surface" | "text" | "muted">, dim: number, photo: PhotoRange): number;
+/** What a background shows behind the panels - `undefined` for none: a colour, or an image of unknown or measured lightness. */
+export declare function backgroundPhoto(background: AppearanceBackground | undefined, measured?: PhotoRange): PhotoRange | undefined;
+/** The dim actually laid over the background: a colour has no picture to dim. */
+export declare function effectiveDim(background: AppearanceBackground): number;
+/**
+ * The custom properties for one scheme: the user's colours, plus - when a background is set - the translucent panel colours and the
+ * transparent frame. `measured` is the image's measured lightness range, when known (`photo.ts`).
+ */
+export declare function themeVariables(prefs: AppearancePreferences, scheme: ResolvedTheme, measured?: PhotoRange): Record<string, string>;
+/** The element `appearanceCss()` writes into `<head>`, so an update replaces rather than duplicates it. */
+export declare const APPEARANCE_STYLE_ID = "rr-appearance";
+/** A string as a CSS `url()` argument: quoted, with what could end the string or the declaration escaped. */
+export declare function cssUrl(url: string): string;
+/**
+ * The rules for the background layer, which is two pseudo-elements of `<html>` rather than any markup - so it exists from the
+ * first byte of a server-rendered page (no flash), follows a live preview by rewriting one stylesheet, and needs no component.
+ * `::before` is the picture (or colour): `position: fixed`, behind everything (`z-index: -1` puts it above the page's own canvas
+ * colour and below every in-flow box), its box grown by twice the blur so the blurred edge falls outside the window. `::after` is the
+ * dim: the scheme's surface colour at the chosen opacity. Neither takes a click, and neither prints.
+ */
+export declare function backgroundCss(background: AppearanceBackground | undefined, imageUrl?: string): string;
+export interface AppearanceCssOptions {
+    /** The image's measured lightness range, when known (`photo.ts`); an unmeasured photo is assumed the worst case. */
+    measured?: PhotoRange;
+    /** Where the background image comes from - the server's URL for the stored version, or a `blob:` URL while an upload is in flight. */
+    imageUrl?: string;
+}
+/**
+ * The stylesheet text for the user's preferences, or `""` when they change nothing. Three rules per set of properties so each
+ * scheme is right in every case: the light set for everything except an explicit dark (`data-theme="dark"`) - which also covers
+ * a page with no `data-theme` at all; the dark set for a dark operating system on a page with no `data-theme` yet (before the
+ * provider ran, or a server-rendered page following "System"); and the dark set for an explicit `data-theme="dark"`. All three are
+ * `html:root...` (0,2,1) so the later dark rules win the equal-specificity tie against the light one. Then the background layer
+ * (`backgroundCss()`).
+ */
+export declare function appearanceCss(prefs: AppearancePreferences | undefined, options?: AppearanceCssOptions): string;
+/** A pair of colours that is hard to read, as `ContrastWarning`s describe them. */
+export interface ContrastWarning {
+    id: "text-surface" | "accent-text";
+    ratio: number;
+    message: string;
+}
+/**
+ * The colour pairs the user's choices make hard to read (contrast below 4.5:1, WCAG AA for normal text) in `scheme`: the text on the
+ * surface, and the text on an accent-coloured button. A warning, never a block - it is their app. Nothing for a pair they haven't
+ * touched (the app's own pairs are the app's business).
+ */
+export declare function contrastWarnings(colors: AppearanceColors | undefined, scheme: ResolvedTheme): ContrastWarning[];