@rapidmx/web-client 0.9.0 → 0.11.0

package/apps/shared/signing/enrollmentView.ts

@@ -0,0 +1,251 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { EnrollmentResult, SignEnrollmentStage, SignEnrollmentStep } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+import type { SigningEnrollmentInfo } from "./signingInfo.js";
+
+/** Warn about an expiring certificate this many days ahead. */
+export const EXPIRY_WARNING_DAYS = 30;
+
+const DAY_MS = 86_400_000;
+
+/** Epoch ms of a date the server sent, or `undefined` for a missing or unparseable one. */
+export function timeOf(value: string | number | undefined): number | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+    const time = typeof value === "number" ? value : Date.parse(value);
+    return Number.isFinite(time) ? time : undefined;
+}
+
+/** "just now", "20 s ago", "3 min ago", "2 h ago", "4 days ago" - `undefined` when there is no date. A time slightly in the future (clock skew) is "just now". */
+export function relativeTime(value: string | number | undefined, now: number): string | undefined {
+    const time = timeOf(value);
+    if (time === undefined) {
+        return undefined;
+    }
+    const seconds = Math.max(0, Math.floor((now - time) / 1000));
+    if (seconds < 5) {
+        return "just now";
+    }
+    if (seconds < 60) {
+        return `${seconds} s ago`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60) {
+        return `${minutes} min ago`;
+    }
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24) {
+        return `${hours} h ago`;
+    }
+    const days = Math.floor(hours / 24);
+    return `${days} ${days === 1 ? "day" : "days"} ago`;
+}
+
+/** A calendar date in the reader's language ("21 Sep 2027"); the raw text if it is not a date. */
+export function formatDate(value: string | number | undefined): string {
+    const time = timeOf(value);
+    if (time === undefined) {
+        return typeof value === "string" ? value : "";
+    }
+    return new Date(time).toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric" });
+}
+
+/** A date and time for a step's timestamp. */
+export function formatDateTime(value: string | number | undefined): string {
+    const time = timeOf(value);
+    if (time === undefined) {
+        return typeof value === "string" ? value : "";
+    }
+    return new Date(time).toLocaleString(undefined, { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" });
+}
+
+/** A long serial number as `0A1B2C3D...9F8E7D` (the whole value is what gets copied). */
+export function truncateSerial(serial: string, keep = 8): string {
+    return serial.length > keep * 2 + 3 ? `${serial.slice(0, keep)}...${serial.slice(-keep)}` : serial;
+}
+
+export type ExpiryState = "ok" | "soon" | "expired" | "unknown";
+
+/** How long a certificate has left: `soon` inside `EXPIRY_WARNING_DAYS`, `expired` once past. */
+export function expiryOf(notAfter: string | number | undefined, now: number): { state: ExpiryState; daysLeft?: number } {
+    const time = timeOf(notAfter);
+    if (time === undefined) {
+        return { state: "unknown" };
+    }
+    if (time <= now) {
+        return { state: "expired", daysLeft: 0 };
+    }
+    const daysLeft = Math.ceil((time - now) / DAY_MS);
+    return { state: daysLeft <= EXPIRY_WARNING_DAYS ? "soon" : "ok", daysLeft };
+}
+
+/** The order the server's steps normally go in, with the words for a server that names a stage but not the steps. */
+const STAGE_STEPS: { stage: SignEnrollmentStage; label: string }[] = [
+    { stage: "submitted", label: "Request sent to the certificate authority" },
+    { stage: "awaiting-challenge", label: "Verification e-mail from the CA" },
+    { stage: "challenge-answered", label: "Verification answered" },
+    { stage: "validating", label: "CA validates the answer" },
+    { stage: "issuing", label: "Certificate issued and installed" },
+];
+
+/** What each stage means, for the line under the bar. */
+const STAGE_TEXT: Record<SignEnrollmentStage, string> = {
+    submitted: "Request sent - waiting for the certificate authority to answer",
+    "awaiting-challenge": "Waiting for the CA's verification e-mail",
+    "challenge-answered": "Verification answered - waiting for the certificate",
+    validating: "The CA is validating the answer",
+    issuing: "The certificate is being issued",
+    issued: "Issued",
+    failed: "Failed",
+};
+
+/**
+ * The steps to draw: the server's own `stages` when it sent them, else - for a server that only says which `stage` it is at - the usual five
+ * with everything before it done and it active, else none (an older server: the card falls back to a plain sentence).
+ */
+export function stepsOf(result: EnrollmentResult | null | undefined): SignEnrollmentStep[] {
+    if (!result) {
+        return [];
+    }
+    if (result.stages && result.stages.length > 0) {
+        return result.stages;
+    }
+    if (!result.stage) {
+        return [];
+    }
+    const index = STAGE_STEPS.findIndex((step) => step.stage === result.stage);
+    const failed = result.stage === "failed" || result.status === "failed";
+    const issued = result.stage === "issued" || result.status === "issued";
+    // An issued enrollment has done every step; a failed one stopped at an unknown step, so none is claimed done or active.
+    return STAGE_STEPS.map((step, position): SignEnrollmentStep => {
+        if (issued) {
+            return { id: step.stage, label: step.label, state: "done" };
+        }
+        if (failed || index === -1) {
+            return { id: step.stage, label: step.label, state: "pending" };
+        }
+        return { id: step.stage, label: step.label, state: position < index ? "done" : position === index ? "active" : "pending" };
+    });
+}
+
+/** The percentage the bar shows: the server's `progress`, else what the steps say (done steps out of all), else `undefined` - unknown. */
+export function progressOf(result: EnrollmentResult | null | undefined): number | undefined {
+    if (!result) {
+        return undefined;
+    }
+    if (typeof result.progress === "number") {
+        return Math.round(result.progress);
+    }
+    if (result.status === "issued") {
+        return 100;
+    }
+    const steps = stepsOf(result);
+    return steps.length > 0 ? Math.round((steps.filter((step) => step.state === "done").length / steps.length) * 100) : undefined;
+}
+
+/** The step doing the work now, if any. */
+export function activeStepOf(result: EnrollmentResult | null | undefined): SignEnrollmentStep | undefined {
+    return stepsOf(result).find((step) => step.state === "active");
+}
+
+/**
+ * A certificate that is issued but not in the mailbox yet: the server installs it with a job a few minutes after the CA issues it, and says when it
+ * has (`installedAt`). An older server sends neither date, so its issued certificates are never "installing".
+ */
+export function isInstalling(result: EnrollmentResult | null | undefined): boolean {
+    return result?.status === "issued" && !!result.issuedAt && !result.installedAt;
+}
+
+/** What the server says about a CA it could not reach: still pending, to be retried - not a failure. */
+export const CA_UNREACHABLE_TEXT = "The certificate authority could not be reached just now - it will be asked again.";
+
+/** The plain-language line: what the enrollment is waiting for, when it was issued, why it failed. `undefined` when the server said nothing to go on. */
+export function statusLineOf(result: EnrollmentResult | null | undefined): string | undefined {
+    if (!result) {
+        return undefined;
+    }
+    if (result.status === "issued") {
+        if (isInstalling(result)) {
+            return "Issued - installing it on your mailbox (this takes a few minutes)";
+        }
+        return result.notAfter ? `Issued - valid until ${formatDate(result.notAfter)}` : "Issued";
+    }
+    if (result.status === "failed") {
+        return `Failed: ${result.error ?? "the certificate authority did not issue a certificate."}`;
+    }
+    return result.stage ? STAGE_TEXT[result.stage] : undefined;
+}
+
+/** What a pending request says when the server has not said how it issues certificates (an older server): nothing that is only true of one way of issuing them. */
+export const PENDING_FALLBACK_TEXT = "Requested - waiting for the certificate. Use Check status to see where the request is.";
+
+/** A manual deployment: nobody but an administrator can make the certificate. Never "takes effect automatically". */
+export const MANUAL_ISSUE_TEXT = "This server issues signing certificates manually: an administrator has to upload the certificate for your request. Contact your administrator.";
+
+/** The enrollment id the browser kept is one the server does not know any more (another provider after a configuration change, a cancelled request). */
+export const STALE_REQUEST_TEXT = "This request is no longer active - request a new certificate.";
+
+/** How a request is being turned into a certificate: by a public CA on its own, by an administrator, or not known. The enrollment's own `provider` wins over what the deployment says now. */
+export type IssueMode = "automatic" | "manual" | "unknown";
+
+export function issueModeOf(result: EnrollmentResult | null | undefined, info: SigningEnrollmentInfo | null | undefined): IssueMode {
+    const provider = result?.provider;
+    if (provider === "manual" || (!provider && info?.backend === "manual")) {
+        return "manual";
+    }
+    if (provider === "rfc8823" || (!provider && info?.automatic)) {
+        return "automatic";
+    }
+    return "unknown";
+}
+
+function minutes(count: number): string {
+    return `${count} ${count === 1 ? "minute" : "minutes"}`;
+}
+
+/** "Requested from ca.example. The CA sends a verification e-mail to jane@example.com; this usually takes about 5 minutes." - each part only as far as it is known. */
+export function requestedFromText(info: SigningEnrollmentInfo | null | undefined, address: string | undefined): string {
+    const host = info?.ca?.host ? `Requested from ${info.ca.host}.` : "Requested from the certificate authority.";
+    const sentence = `The CA sends a verification e-mail to ${address ?? "this mailbox"}`;
+    const duration = info?.typicalDurationMinutes ? `; this usually takes about ${minutes(info.typicalDurationMinutes)}` : "";
+    return `${host} ${sentence}${duration}.`;
+}
+
+/** What to say before anyone has asked for a certificate: how this deployment will issue it (or that it does not). `undefined` when nothing is known. */
+export function beforeRequestText(info: SigningEnrollmentInfo | null | undefined, address: string | undefined): string | undefined {
+    if (!info || info.backend === "none") {
+        return info ? "This server does not issue signing certificates." : undefined;
+    }
+    if (info.backend === "manual") {
+        return MANUAL_ISSUE_TEXT;
+    }
+    const from = info.ca?.host ?? "a public certificate authority";
+    const duration = info.typicalDurationMinutes ? `, usually within about ${minutes(info.typicalDurationMinutes)}` : "";
+    return `A certificate is issued automatically by ${from}: it sends a verification e-mail to ${address ?? "this mailbox"}${duration}.`;
+}
+
+/** The warning when the CA has been reporting a problem: what it said and when it last worked. `undefined` when it has not. */
+export function healthWarning(info: SigningEnrollmentInfo | null | undefined): string | undefined {
+    const error = info?.health?.lastError;
+    if (!error) {
+        return undefined;
+    }
+    const last = info.health!.lastSuccessAt ? formatDateTime(info.health!.lastSuccessAt) : "never";
+    return `The certificate authority reported a problem: ${error} (last successful contact ${last})`;
+}
+
+/** A pending request is "taking longer than expected" after this long without a change. */
+export const OVERDUE_AFTER_MS = 60 * 60_000;
+
+/** Whether a pending request was made more than an hour ago and nothing has changed in the last hour: say so instead of staying silent. */
+export function isOverdue(result: EnrollmentResult | null | undefined, now: number): boolean {
+    if (result?.status !== "pending") {
+        return false;
+    }
+    const requested = timeOf(result.requestedAt);
+    const changed = timeOf(result.updatedAt) ?? requested;
+    return requested !== undefined && changed !== undefined && now - requested > OVERDUE_AFTER_MS && now - changed > OVERDUE_AFTER_MS;
+}

package/apps/shared/signing/signingInfo.ts

@@ -0,0 +1,58 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { SigningEnrollmentInfo, getSigningEnrollmentInfo } from "@rapidmx/react-shared/crypto/signingProviderApi.js";
+
+// The type and the request both come from react-shared's `signingProviderApi.js` (R6's) - this module only adds the caching, the
+// never-rejects contract and the hook that Settings > Encryption and its card want. Re-exported so the rest of `signing/` and
+// `SigningCertificateCard` keep importing `SigningEnrollmentInfo` from here rather than reaching into react-shared directly.
+export type { SigningEnrollmentInfo };
+
+/** How long an answer is reused: the page asks once when it opens, and again after this if it is opened again. */
+export const SIGNING_INFO_CACHE_MS = 5 * 60_000;
+
+let cached: { at: number; promise: Promise<SigningEnrollmentInfo | null> } | undefined;
+
+/** The deployment's signing-enrollment description, or `null` when it cannot be had (an older server with no such endpoint, offline,
+ * anything) - never rejects. One request at a time, reused for five minutes. */
+export function fetchSigningEnrollmentInfo(now: number = Date.now()): Promise<SigningEnrollmentInfo | null> {
+    if (cached && now - cached.at < SIGNING_INFO_CACHE_MS) {
+        return cached.promise;
+    }
+    const promise = getSigningEnrollmentInfo().catch(() => null);
+    cached = { at: now, promise };
+    // An answer that could not be had is not worth remembering: the next visit asks again.
+    void promise.then((info) => {
+        if (info === null && cached?.promise === promise) {
+            cached = undefined;
+        }
+    });
+    return promise;
+}
+
+/** Forgets the remembered answer: for tests, which share the module. */
+export function resetSigningInfo(): void {
+    cached = undefined;
+}
+
+/** The deployment's description, once it is known: `undefined` while it is being asked for, `null` when there is none. Asks only while `enabled`. */
+export function useSigningEnrollmentInfo(enabled: boolean): SigningEnrollmentInfo | null | undefined {
+    const [info, setInfo] = useState<SigningEnrollmentInfo | null | undefined>(undefined);
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        let cancelled = false;
+        void fetchSigningEnrollmentInfo().then((answer) => {
+            if (!cancelled) {
+                setInfo(answer);
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [enabled]);
+    return info;
+}

package/apps/shared/signing/useNow.ts

@@ -0,0 +1,19 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+
+/** The current time in epoch ms, re-read every `intervalMs` while `enabled` - for "3 min ago" texts and countdowns that keep themselves right. */
+export function useNow(intervalMs: number, enabled = true): number {
+    const [now, setNow] = useState(() => Date.now());
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        setNow(Date.now());
+        const timer = setInterval(() => setNow(Date.now()), intervalMs);
+        return () => clearInterval(timer);
+    }, [intervalMs, enabled]);
+    return now;
+}

package/apps/shared/signing/useSigningEnrollmentWatcher.ts

@@ -0,0 +1,90 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useRef } from "react";
+import type { Mailbox } from "@rapidmx/react-shared/mail/mailApi.js";
+import { getCurrentSignEnrollment } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+import { notify } from "../notifications/store.js";
+import { readStoredSignEnrollment, storeSignEnrollment } from "./enrollmentStorage.js";
+import { EnrollmentSnapshot, onEnrollmentEnded, watchCurrentEnrollment, watchEnrollment } from "./enrollmentTracker.js";
+import { formatDate, isInstalling } from "./enrollmentView.js";
+
+/** Where the pop-up's action leads: the page that shows the certificate. */
+export const SIGNING_SETTINGS_HREF = "/settings/encryption";
+
+/**
+ * Tells the user, wherever they are in the app, when a signing certificate they asked for is issued or has failed. Lives in the persistent app
+ * frame (`AppChrome`): for each mailbox the user owns it follows the enrollment this browser has a stored id for and - for one started on another
+ * device - the one the server names as the mailbox's current enrollment when it is still pending (`GET .../sign-enrollment`; an older server
+ * answers 404 and nothing is followed). Reading, backoff and visibility rules are the tracker's (`enrollmentTracker.ts`), shared with the
+ * Settings > Encryption card, so an enrollment is asked about once. The pop-up is raised once per enrollment (`dedupeKey`) and only for one that
+ * was seen pending - never for a certificate issued long ago.
+ */
+export function useSigningEnrollmentWatcher({ userUid, mailboxes, enabled }: { userUid?: string; mailboxes: Mailbox[]; enabled: boolean }): void {
+    const mailboxesRef = useRef(mailboxes);
+    mailboxesRef.current = mailboxes;
+    // Keyed on the uids of the mailboxes the user owns: a refreshed list of the same mailboxes must not start over.
+    const ownedKey = mailboxes
+        .filter((mailbox) => mailbox.ownerUserUid === userUid)
+        .map((mailbox) => mailbox.uid)
+        .join("|");
+
+    useEffect(() => {
+        if (!enabled || !userUid || !ownedKey) {
+            return;
+        }
+        let cancelled = false;
+        const releases: (() => void)[] = [];
+        for (const mailboxUid of ownedKey.split("|")) {
+            const storedId = readStoredSignEnrollment(mailboxUid);
+            if (storedId) {
+                releases.push(watchEnrollment(mailboxUid, storedId));
+                continue;
+            }
+            // Never throws or rejects: a lookup that cannot be made (an older server, offline, anything) is "nothing is pending", and the frame goes on.
+            void (async () => {
+                try {
+                    const current = await getCurrentSignEnrollment(mailboxUid);
+                    if (!cancelled && current?.status === "pending") {
+                        storeSignEnrollment(mailboxUid, current.enrollmentId);
+                        releases.push(watchCurrentEnrollment(mailboxUid, current));
+                    }
+                } catch {
+                    // Nothing to follow.
+                }
+            })();
+        }
+        const stopListening = onEnrollmentEnded((snapshot) => announce(snapshot, mailboxesRef.current));
+        return () => {
+            cancelled = true;
+            stopListening();
+            releases.forEach((release) => release());
+        };
+    }, [enabled, userUid, ownedKey]);
+}
+
+/** The pop-up for an enrollment that just ended - issued or failed (the tracker announces nothing else, and always with its answer). */
+function announce(snapshot: EnrollmentSnapshot, mailboxes: Mailbox[]): void {
+    const address = mailboxes.find((mailbox) => mailbox.uid === snapshot.mailboxUid)?.primarySmtpAddress;
+    const result = snapshot.result!;
+    if (result.status === "issued") {
+        notify({
+            kind: "success",
+            title: "Digital signature certificate issued",
+            message: isInstalling(result)
+                ? `The certificate for ${address ?? "your mailbox"} is issued and is being installed - mail is signed once it is (a few minutes).`
+                : `${address ? `Mail from ${address}` : "Your mail"} is now signed${result.notAfter ? ` (valid until ${formatDate(result.notAfter)})` : ""}.`,
+            actions: [{ label: "View", href: SIGNING_SETTINGS_HREF }],
+            dedupeKey: `sign-enrollment:${snapshot.enrollmentId}`,
+        });
+    } else {
+        notify({
+            kind: "error",
+            title: "Digital signature certificate could not be issued",
+            message: result.error ?? "The certificate authority did not issue a certificate.",
+            actions: [{ label: result.retryable === false ? "Details" : "Try again", href: SIGNING_SETTINGS_HREF }],
+            dedupeKey: `sign-enrollment:${snapshot.enrollmentId}`,
+        });
+    }
+}

package/apps/shared/styles/app.css

@@ -276,13 +276,111 @@ h5,
 h6 {
     font-family: var(--rr-font-display);
 }
-
-/* The compose editor's quoted original (`composeQuoting.ts`'s blockquote). TipTap keeps the element but not the
- * inline style it was seeded with, and Tailwind's preflight resets the browser's own blockquote indent - without
- * this the quote under a reply reads as if it were part of the new message. */
-.tiptap blockquote {
-    margin: 0;
-    padding-left: 1em;
-    border-left: 2px solid var(--rr-color-border);
-    color: var(--rr-color-text-muted);
-}
+
+/* The compose editor's quoted original (`composeQuoting.ts`'s blockquote). TipTap keeps the element but not the
+ * inline style it was seeded with, and Tailwind's preflight resets the browser's own blockquote indent - without
+ * this the quote under a reply reads as if it were part of the new message. */
+.tiptap blockquote {
+    margin: 0;
+    padding-left: 1em;
+    border-left: 2px solid var(--rr-color-border);
+    color: var(--rr-color-text-muted);
+}
+
+/* A new-mail pop-up (`NewMailToasts.tsx`) eases in from just above its place. Only for readers who have not asked their system
+ * for less motion: with `prefers-reduced-motion: reduce` it simply appears. */
+@media (prefers-reduced-motion: no-preference) {
+    .rr-toast-in {
+        animation: rr-toast-in 0.18s ease-out;
+    }
+}
+@keyframes rr-toast-in {
+    from {
+        opacity: 0;
+        transform: translateY(-0.5rem);
+    }
+    to {
+        opacity: 1;
+        transform: none;
+    }
+}
+
+/* The frame's own background: the page's `surface-alt`, unless the user has chosen a background (`appearance/theme.ts` then sets `--rr-frame-bg`
+ * to `transparent` so the fixed background layer - `html::before`/`html::after` - shows through instead). */
+.rr-frame-bg {
+    background-color: var(--rr-frame-bg, var(--rr-color-surface-alt));
+}
+
+/* With a background set, `--color-surface` and `--color-surface-alt` (what `bg-surface` and `bg-surface-alt` read) are translucent panels
+ * (`appearance/theme.ts`). Anything that must stay readable on its own - menus, dialogs, drawers, list pop-ups and the pop-ups - takes the
+ * opaque colours back for itself and everything inside it, and so does anything that stays put while a page scrolls under it (`.rr-solid`: the
+ * sticky title bar, the branding header, the phone's bottom tab bar), or the text beneath would show through it. Without a background these two declarations change nothing. */
+[role="menu"],
+[role="dialog"],
+[role="listbox"],
+.rr-toast-in,
+.rr-solid,
+[data-branding-header],
+nav[aria-label="Mobile navigation"] {
+    --color-surface: var(--rr-color-surface);
+    --color-surface-alt: var(--rr-color-surface-alt);
+}
+
+/* The slot a branding header or footer's `{USER_MENU}` becomes (`BrandingChrome.tsx`): the account menu's button sits in the line of text
+ * the variable was written in. */
+[data-rr-slot="user-menu"] {
+    display: inline-flex;
+    align-items: center;
+    vertical-align: middle;
+}
+
+/* The Outbox pill's "something is on its way" dot (`OutboxBadge`). Still when the user asks for less motion. */
+@media (prefers-reduced-motion: no-preference) {
+    .rr-sending-dot {
+        animation: rr-sending-dot 1.1s ease-in-out infinite;
+    }
+}
+@keyframes rr-sending-dot {
+    0%,
+    100% {
+        opacity: 0.35;
+        transform: scale(0.8);
+    }
+    50% {
+        opacity: 1;
+        transform: scale(1.15);
+    }
+}
+
+/* The signing-certificate card's progress bar (`SigningCertificateCard`): a soft highlight sweeping across the filled part while a step is active, and
+ * an endless slide for a bar with no number. Both stand still when the user asks for less motion (the indeterminate bar then shows as a faded full bar). */
+.rr-progress-shimmer {
+    position: relative;
+    overflow: hidden;
+}
+@media (prefers-reduced-motion: no-preference) {
+    .rr-progress-shimmer::after {
+        content: "";
+        position: absolute;
+        inset: 0;
+        background: linear-gradient(90deg, transparent, rgb(255 255 255 / 0.45), transparent);
+        transform: translateX(-100%);
+        animation: rr-progress-shimmer 1.6s ease-in-out infinite;
+    }
+    .rr-progress-indeterminate {
+        animation: rr-progress-slide 1.4s ease-in-out infinite;
+    }
+}
+@keyframes rr-progress-shimmer {
+    to {
+        transform: translateX(100%);
+    }
+}
+@keyframes rr-progress-slide {
+    0% {
+        transform: translateX(-100%);
+    }
+    100% {
+        transform: translateX(300%);
+    }
+}

package/apps/www/_layout.tsx

@@ -4,6 +4,7 @@
 ///////////////////////////////////////////////////////////////////////////////
 import React, { PropsWithChildren } from "react";
 import { Branding } from "@rapidmx/react-shared/branding/brandingApi.js";
+import { AppearanceHead, appearanceHtmlAttributes } from "../shared/appearance/AppearanceHead.js";
 import { CUSTOM_STYLESHEET_LINK_ID } from "@rapidmx/react-shared/branding/useBranding.js";
 
 export interface LayoutProps {
@@ -16,15 +17,19 @@ export interface LayoutProps {
      * which doesn't receive props at all - falling back to the stock defaults there is acceptable.
      */
     branding?: Branding;
+    /** The signed-in user's stored appearance preferences (a page prop from the same `fetchProps()`, present only on the www pages and only when the user has any): rendered as a stylesheet in the `<head>` so the very first paint is themed - see `AppearanceHead`. */
+    appearance?: unknown;
+    /** The signed-in user (supplied by the framework), so a cached appearance from another account on this browser is never applied. */
+    userUid?: string;
 }
 
-export default function Layout({ children, branding }: PropsWithChildren<LayoutProps>) {
+export default function Layout({ children, branding, appearance, userUid }: PropsWithChildren<LayoutProps>) {
     const title = branding?.title || branding?.companyName ? `${branding?.title || branding?.companyName}: Mail` : "RapidMX: Mail";
     const iconHref = branding?.iconUrl || branding?.logoUrl || "/images/logo.svg";
     const stylesheetHref = branding?.stylesheetUrl;
 
     return (
-        <html lang="en">
+        <html lang="en" {...appearanceHtmlAttributes(appearance, userUid)}>
             <head>
                 <meta charSet="utf-8" />
                 <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -38,6 +43,7 @@ export default function Layout({ children, branding }: PropsWithChildren<LayoutP
                     href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap"
                 />
                 {stylesheetHref && <link rel="stylesheet" href={stylesheetHref} id={CUSTOM_STYLESHEET_LINK_ID} />}
+                <AppearanceHead appearance={appearance} />
             </head>
             <body>{children}</body>
         </html>

package/apps/www/_routedPage.tsx

@@ -0,0 +1,24 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { ComponentType } from "react";
+import AppRouter, { RoutedPageComponent } from "../shared/navigation/AppRouter.js";
+import { wwwRoutes } from "./_routes.js";
+
+/**
+ * Makes a `www` page the entry of the client-side router: the page's default export is `routedPage("/its/route", Page)`.
+ * `@rapidrest/react` server-renders and hydrates exactly that component, so what it renders - the router, with the persistent
+ * app frame (`AppChrome`) and `Page` inside it - is the whole client tree, and later pages replace `Page` without a page load.
+ * `path` is the page's route template, the same as its entry in `_routes.ts`.
+ *
+ * The result carries the plain `Page` as `.page`, which is what the router shows when it loads this module for a navigation
+ * (rendering the wrapped default export there would nest a second router).
+ */
+export function routedPage<P extends object>(path: string, Page: ComponentType<P>): RoutedPageComponent<P> {
+    function RoutedPage(props: P) {
+        return <AppRouter routes={wwwRoutes} initialPath={path} initialPage={Page} pageProps={props} />;
+    }
+    RoutedPage.page = Page;
+    return RoutedPage;
+}

package/apps/www/_routes.ts

@@ -0,0 +1,36 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { RouteDefinition } from "../shared/navigation/routes.js";
+
+/**
+ * Every `apps/www` page the client-side router can show without a page load (see `apps/shared/navigation/AppRouter.tsx`), in
+ * the order they are matched: literal routes before the parameterized ones that would also match them. Each page loads with a
+ * dynamic `import()`, which is what makes it a chunk of its own - only the page a document was rendered for is in its first
+ * JavaScript. Keep it in step with the files under `apps/www`; a page missing from here still works, it is just reached with a
+ * page load. (The file starts with `_` so `@rapidrest/react` doesn't treat it as a page.)
+ *
+ * The four app-rail pages are `idlePrefetch`ed: downloaded when the browser is idle after the first page has loaded.
+ */
+export const wwwRoutes: readonly RouteDefinition[] = [
+    { path: "/", active: "mail", load: () => import("./index.js"), idlePrefetch: true },
+    { path: "/messages/:uid", active: "mail", load: () => import("./messages/[uid].js") },
+    { path: "/calendar", active: "calendar", load: () => import("./calendar/index.js"), idlePrefetch: true },
+    { path: "/contacts", active: "contacts", load: () => import("./contacts/index.js"), idlePrefetch: true },
+    { path: "/contacts/:uid", active: "contacts", load: () => import("./contacts/[uid].js") },
+    { path: "/tasks", active: "tasks", load: () => import("./tasks/index.js"), idlePrefetch: true },
+    { path: "/settings/appearance", active: "settings", load: () => import("./settings/appearance/index.js") },
+    { path: "/settings/auto-reply", active: "settings", load: () => import("./settings/auto-reply/index.js") },
+    { path: "/settings/encryption", active: "settings", load: () => import("./settings/encryption/index.js") },
+    { path: "/settings/filters", active: "settings", load: () => import("./settings/filters/index.js") },
+    { path: "/settings/filters/new", active: "settings", load: () => import("./settings/filters/new/index.js") },
+    { path: "/settings/filters/:uid", active: "settings", load: () => import("./settings/filters/[uid].js") },
+    { path: "/settings/labels", active: "settings", load: () => import("./settings/labels/index.js") },
+    { path: "/settings/privacy", active: "settings", load: () => import("./settings/privacy/index.js") },
+    { path: "/settings/read-receipts", active: "settings", load: () => import("./settings/read-receipts/index.js") },
+    { path: "/settings/sharing", active: "settings", load: () => import("./settings/sharing/index.js") },
+    { path: "/settings/signatures", active: "settings", load: () => import("./settings/signatures/index.js") },
+    { path: "/settings/signatures/new", active: "settings", load: () => import("./settings/signatures/new/index.js") },
+    { path: "/settings/signatures/:uid", active: "settings", load: () => import("./settings/signatures/[uid].js") },
+];