@rapidmx/web-client 0.33.0 → 0.35.0

package/apps/shared/components/mail/compose/quotedBody.ts

@@ -2,7 +2,7 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import { apiUrl } from "../../../../../lib/util/api.js";
+import { type ApiClient, apiUrl } from "../../../../../lib/util/api.js";
 import { Message, Recipient, attachmentContentUrl, getMessageRawContent, listAttachments } from "../../../../../lib/mail/mailApi.js";
 import type { QuotedBody } from "../../../../../lib/mail/compose/composeQuoting.js";
 import { MAX_QUOTED_IMAGE_BYTES, QuotedImageReference, embedQuotedImages } from "../../../../../lib/mail/compose/quotedImages.js";
@@ -44,9 +44,9 @@ const contentCache = new Map<string, { at: number; promise: Promise<string | und
 /**
  * The server's sanitized HTML body of a message (`GET /mail/messages/:id/content`), or `undefined` when it has none (a
  * `text/plain` message is answered with its preview instead) or the request failed or timed out. Never rejects. Remembered
- * for `QUOTE_CACHE_MS` - except a failure, which is asked again the next time.
+ * for `QUOTE_CACHE_MS` - except a failure, which is asked again the next time. Through `client` when given, else the cookie request.
  */
-function fetchContentHtml(uid: string): Promise<string | undefined> {
+function fetchContentHtml(uid: string, client?: ApiClient): Promise<string | undefined> {
     const cached = contentCache.get(uid);
     if (cached && Date.now() - cached.at < QUOTE_CACHE_MS) {
         return cached.promise;
@@ -55,6 +55,10 @@ function fetchContentHtml(uid: string): Promise<string | undefined> {
     const timer = setTimeout(() => controller.abort(), QUOTE_FETCH_TIMEOUT_MS);
     const promise = (async (): Promise<string | undefined> => {
         try {
+            if (client) {
+                const blob = await client.fetchBlob(`/mail/messages/${encodeURIComponent(uid)}/content`, { signal: controller.signal });
+                return blob.type.toLowerCase().includes("text/html") ? await blob.text() : undefined;
+            }
             const res = await fetch(apiUrl(`/mail/messages/${encodeURIComponent(uid)}/content`), { credentials: "include", signal: controller.signal });
             return res.ok && (res.headers.get("content-type") ?? "").includes("text/html") ? await res.text() : undefined;
         } catch {
@@ -92,9 +96,9 @@ function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
  * keyboard reaches a Reply/Reply All/Forward button - so the request is usually already answered when it is clicked.
  * Nothing to fetch for an encrypted message (`loadOriginalMessage()` never asks the server for one's body).
  */
-export function prefetchOriginalMessage(message: Message): void {
+export function prefetchOriginalMessage(message: Message, client?: ApiClient): void {
     if (!message.encrypted) {
-        void fetchContentHtml(message.uid);
+        void fetchContentHtml(message.uid, client);
     }
 }
 
@@ -116,18 +120,28 @@ function headerRecipients(value: string | undefined, type: "to" | "cc"): Recipie
 
 /** The `data:` URI of the picture a quoted image of `message` stands for - one of the message's own attachments, fetched with the session -
  * or `undefined` when there is none, it is not a raster image, it is too large or it could not be had. Never rejects. */
-function serverImageResolver(message: Message): (reference: QuotedImageReference, signal?: AbortSignal) => Promise<string | undefined> {
+function serverImageResolver(
+    message: Message,
+    client?: ApiClient,
+): (reference: QuotedImageReference, signal?: AbortSignal) => Promise<string | undefined> {
     let attachments: Promise<Awaited<ReturnType<typeof listAttachments>>> | undefined;
     return async (reference, signal) => {
         try {
-            attachments ??= listAttachments(message.folderUid, message.uid);
+            attachments ??= listAttachments(message.folderUid, message.uid, client);
             const attachment = findInlineAttachment(await attachments, reference);
             const type = attachment?.mimeType.split(";")[0].trim().toLowerCase();
             if (!attachment || !type || !EMBEDDED_IMAGE_TYPES.test(type) || attachment.sizeBytes > MAX_QUOTED_IMAGE_BYTES) {
                 return undefined;
             }
-            const res = await fetch(attachmentContentUrl(attachment.uid), { credentials: "include", signal });
-            const bytes = res.ok ? new Uint8Array(await res.arrayBuffer()) : undefined;
+            let bytes: Uint8Array | undefined;
+            if (client) {
+                // A failed response rejects here, which the catch below turns into no picture - as an `!res.ok` answer always was.
+                const blob = await client.fetchBlob(`/mail/attachments/${encodeURIComponent(attachment.uid)}/content`, { signal });
+                bytes = new Uint8Array(await blob.arrayBuffer());
+            } else {
+                const res = await fetch(attachmentContentUrl(attachment.uid), { credentials: "include", signal });
+                bytes = res.ok ? new Uint8Array(await res.arrayBuffer()) : undefined;
+            }
             return bytes && bytes.length <= MAX_QUOTED_IMAGE_BYTES ? toDataUri(type, bytes) : undefined;
         } catch {
             return undefined;
@@ -176,6 +190,7 @@ export async function loadOriginalMessage(
     message: Message,
     security: MessageSecurityResult | null,
     options: { recipients?: boolean } = {},
+    client?: ApiClient,
 ): Promise<OriginalMessage> {
     const recovered: QuotedBody | undefined =
         security?.text !== undefined ? { text: security.text } : security?.html !== undefined ? { html: security.html } : undefined;
@@ -193,7 +208,7 @@ export async function loadOriginalMessage(
     if (!recovered) {
         // Never rejects; nothing (a plain-text message, a failure, a timeout) leaves the raw message below as the other way
         // to the body.
-        const html = await fetchContentHtml(message.uid);
+        const html = await fetchContentHtml(message.uid, client);
         if (html !== undefined) {
             result.body = { html };
         } else {
@@ -202,7 +217,7 @@ export async function loadOriginalMessage(
     }
     try {
         if (needsRaw) {
-            const entity = parseMimeEntity(await withTimeout(getMessageRawContent(message.uid), QUOTE_FETCH_TIMEOUT_MS));
+            const entity = parseMimeEntity(await withTimeout(getMessageRawContent(message.uid, client), QUOTE_FETCH_TIMEOUT_MS));
             if (!recovered && result.body.html === undefined) {
                 const body = extractDisplayBody(entity);
                 result.body = body.html !== undefined ? { html: body.html } : body.text !== undefined ? { text: body.text } : {};
@@ -217,7 +232,7 @@ export async function loadOriginalMessage(
         // message's own recipients.
     }
     if (result.body.html !== undefined) {
-        const resolver = recovered ? partImageResolver(security?.attachments ?? []) : serverImageResolver(message);
+        const resolver = recovered ? partImageResolver(security?.attachments ?? []) : serverImageResolver(message, client);
         const html = result.body.html;
         // Bounded like the body's own request: a picture that has not arrived by then is cancelled and left out of the quote, not waited for -
         // the ones that have arrived stay.

package/apps/shared/components/mail/reading/MessageBody.tsx

@@ -9,6 +9,7 @@ import type { MimeAttachment } from "../../../../../lib/crypto/mime.js";
 import Alert from "../../../../../lib/components/feedback/Alert.js";
 import Button from "../../../../../lib/components/buttons/Button.js";
 import Skeleton from "../../../../../lib/components/feedback/Skeleton.js";
+import { useApiClient } from "../../../../../lib/util/apiClientContext.js";
 import { useResolvedTheme } from "../../../appearance/resolvedTheme.js";
 import { BodyContent, attachmentSource, cachedBodyContent, fetchBodyContent, makeCidResolver } from "./bodyContent.js";
 import { prepareBodyHtml } from "./bodyHtml.js";
@@ -78,6 +79,8 @@ export default function MessageBody({ messageUid, messageVersion, title, content
     });
     const [attempt, setAttempt] = useState(0);
     const supplied = content !== undefined;
+    // The explicit ApiClient this body is rendered under, if any - undefined for the cookie-based web app.
+    const client = useApiClient();
 
     useEffect(() => {
         if (supplied) {
@@ -95,7 +98,7 @@ export default function MessageBody({ messageUid, messageVersion, title, content
         if (!revalidating) {
             setRemote({ status: "loading" });
         }
-        fetchBodyContent(messageUid, messageVersion, controller.signal).then(
+        fetchBodyContent(messageUid, messageVersion, controller.signal, client).then(
             (loaded) => setRemote({ status: "ready", content: loaded, uid: messageUid }),
             (err) => {
                 if (!controller.signal.aborted && !revalidating) {

package/apps/shared/components/mail/reading/bodyContent.ts

@@ -2,7 +2,7 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import { ApiRequestError, apiUrl } from "../../../../../lib/util/api.js";
+import { ApiRequestError, type ApiClient, apiUrl } from "../../../../../lib/util/api.js";
 import { Attachment, attachmentContentUrl } from "../../../../../lib/mail/mailApi.js";
 import type { MimeAttachment } from "../../../../../lib/crypto/mime.js";
 import { bytesToBase64, findInlineAttachment, toDataUri } from "../../../../../lib/mail/inlineImages.js";
@@ -31,28 +31,38 @@ export function cachedBodyContent(uid: string, version: number): BodyContent | u
 /**
  * The message's body from the server's `GET /mail/messages/:id/content`: the HTML the server sanitized when it ingested the message
  * (`sanitizedHtmlBlobKey`), or - for a message with none - the plain-text preview. A request that fails throws an `ApiRequestError`.
- * Successful answers are remembered per uid and version.
+ * Successful answers are remembered per uid and version. With an explicit `client` the request goes through it (its origin and token) instead of
+ * the `jwt` cookie; without one it is the cookie request it always was.
  */
-export async function fetchBodyContent(uid: string, version: number, signal?: AbortSignal): Promise<BodyContent> {
+export async function fetchBodyContent(uid: string, version: number, signal?: AbortSignal, client?: ApiClient): Promise<BodyContent> {
     const cached = cachedBodyContent(uid, version);
     if (cached) {
         return cached;
     }
-    // Says what it can show, as a document request would: the server answers with the sanitized HTML, or its plain-text fallback.
-    const res = await fetch(apiUrl(`/mail/messages/${encodeURIComponent(uid)}/content`), {
-        credentials: "include",
-        headers: { Accept: ACCEPT },
-        signal,
-    });
-    if (!res.ok) {
-        const contentType = res.headers.get("content-type") ?? "";
-        const body = contentType.includes("application/json") ? await res.json().catch(() => undefined) : undefined;
-        throw new ApiRequestError((body && (body.message || body.error)) || res.statusText || "Could not load this message.", res.status, body?.code, body);
+    const path = `/mail/messages/${encodeURIComponent(uid)}/content`;
+    let text: string;
+    let contentType: string;
+    if (client) {
+        // `fetchBlob()` rejects with the same `ApiRequestError` a failed response gives, and its blob carries the response's own type.
+        const blob = await client.fetchBlob(path, { headers: { Accept: ACCEPT }, signal });
+        text = await blob.text();
+        contentType = blob.type;
+    } else {
+        // Says what it can show, as a document request would: the server answers with the sanitized HTML, or its plain-text fallback.
+        const res = await fetch(apiUrl(path), {
+            credentials: "include",
+            headers: { Accept: ACCEPT },
+            signal,
+        });
+        if (!res.ok) {
+            const resType = res.headers.get("content-type") ?? "";
+            const body = resType.includes("application/json") ? await res.json().catch(() => undefined) : undefined;
+            throw new ApiRequestError((body && (body.message || body.error)) || res.statusText || "Could not load this message.", res.status, body?.code, body);
+        }
+        text = await res.text();
+        contentType = res.headers.get("content-type") ?? "";
     }
-    const text = await res.text();
-    const content: BodyContent = (res.headers.get("content-type") ?? "").toLowerCase().includes("text/html")
-        ? { kind: "html", html: text }
-        : { kind: "text", text };
+    const content: BodyContent = contentType.toLowerCase().includes("text/html") ? { kind: "html", html: text } : { kind: "text", text };
     if (cache.size >= CACHE_LIMIT) {
         cache.delete(cache.keys().next().value as string);
     }

package/apps/shared/components/mail/reading/conversationPrint.ts

@@ -40,15 +40,16 @@ export async function olderConversationMessages(message: Message, client?: ApiCl
 
 /**
  * One earlier message of a conversation as it prints: the body the reading pane would show. An encrypted one is decrypted here when this device has
- * its mailbox's keys unlocked; when it can't be, it prints a line saying so rather than the ciphertext.
+ * its mailbox's keys unlocked; when it can't be, it prints a line saying so rather than the ciphertext. `client` is the explicit `ApiClient` every
+ * request goes through when given (see `useApiClient()`); without one they are the cookie requests they always were.
  */
-export async function printableOlderMessage(message: Message): Promise<PrintableMessage> {
-    const attachments = await listAttachments(message.folderUid, message.uid).catch(() => []);
+export async function printableOlderMessage(message: Message, client?: ApiClient): Promise<PrintableMessage> {
+    const attachments = await listAttachments(message.folderUid, message.uid, client).catch(() => []);
     if (message.encrypted) {
         const unlocked = getUnlockedKeys(message.mailboxUid);
         if (unlocked) {
             const { evaluateMessageSecurity } = await import("../../../../../lib/crypto/messageSecurity.js");
-            const security = await evaluateMessageSecurity(await getMessageRawContent(message.uid), unlocked);
+            const security = await evaluateMessageSecurity(await getMessageRawContent(message.uid, client), unlocked);
             const content =
                 security.text !== undefined ? ({ kind: "text", text: security.text } as const) : security.html !== undefined ? ({ kind: "html", html: security.html } as const) : undefined;
             if (content) {
@@ -70,7 +71,8 @@ export async function printableOlderMessage(message: Message): Promise<Printable
     return {
         subject: message.subject || "(no subject)",
         headers: printHeaders(message, formatMailAddress(message.from)),
-        content: await fetchBodyContent(message.uid, message.version),
+        // Without a client this is exactly the cookie request it always was.
+        content: await (client ? fetchBodyContent(message.uid, message.version, undefined, client) : fetchBodyContent(message.uid, message.version)),
         attachments,
     };
 }

package/apps/shared/live/useFolderLiveUpdates.ts

@@ -0,0 +1,59 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useRef } from "react";
+import { getPushClient, type PushEvent } from "../../../lib/mail/pushClient.js";
+
+/** An item a push event says was created, changed or deleted: its uid, and whether it is gone. */
+export interface FolderItemChange {
+    uid: string;
+    deleted: boolean;
+}
+
+/**
+ * The item a push event says was created, changed or deleted, when the event's `type` - the published model class name (`ContactMongo`,
+ * `TaskSQL`, ...) - matches `model`, or `undefined` for anything else the shared push connection delivers. Only the uid is taken: the payload
+ * is whatever every subscriber of the folder may see (a private calendar event's busy block), so a page fetches the item again by its uid.
+ */
+export function changedItemOf(event: PushEvent, model: RegExp): FolderItemChange | undefined {
+    if (!model.test(event.type) || (event.action !== "create" && event.action !== "update" && event.action !== "delete")) {
+        return undefined;
+    }
+    const data = event.data as { uid?: unknown } | null | undefined;
+    return typeof data?.uid === "string" ? { uid: data.uid, deleted: event.action === "delete" } : undefined;
+}
+
+/**
+ * Keeps a page's folders live: while the page is mounted the tab's push connection is subscribed to `folderUids` (under the page's own
+ * `group` - see `PushClient.setChannels()`; Mail's connection subscribes to mail folders only, so nothing else asks for a calendar,
+ * contacts or tasks folder), and `onChange` is called with every item `parse` recognizes - created, changed or deleted anywhere: another
+ * tab, a phone over ActiveSync, the server itself. `onChange` may change between renders; the latest is called.
+ */
+export function useFolderLiveUpdates(
+    group: string,
+    folderUids: readonly string[],
+    parse: (event: PushEvent) => FolderItemChange | undefined,
+    onChange: (change: FolderItemChange) => void,
+): void {
+    const key = [...new Set(folderUids)].sort().join(",");
+    useEffect(() => {
+        const client = getPushClient();
+        client.setChannels(key ? key.split(",") : [], group);
+        client.start();
+        return () => client.setChannels([], group);
+    }, [group, key]);
+
+    const latest = useRef({ parse, onChange });
+    latest.current = { parse, onChange };
+    useEffect(
+        () =>
+            getPushClient().onEvent((event) => {
+                const change = latest.current.parse(event);
+                if (change) {
+                    latest.current.onChange(change);
+                }
+            }),
+        [],
+    );
+}

package/apps/shared/mail/outbox/sendOutcomes.ts

@@ -64,9 +64,7 @@ async function openFailedDraft(event: SendEvent, client: ApiClient | undefined):
             });
             return;
         }
-        // loadOriginalMessage() (quotedBody.ts) does not yet accept an explicit ApiClient itself - out of scope here (that module is not one of
-        // this task's files); it still falls back to the default global session even under an ApiClientContext.Provider.
-        const original = await loadOriginalMessage(moved, null);
+        const original = await loadOriginalMessage(moved, null, {}, client);
         const attachments = await listAttachments(moved.folderUid, moved.uid, client).catch(() => []);
         const byType = (type: "to" | "cc" | "bcc") => moved.recipients.filter((recipient) => recipient.type === type).map(formatRecipient).join(", ");
         openComposeFromOutside({

package/apps/shared/notifications/preferences.ts

@@ -34,3 +34,30 @@ export function setNotificationsEnabled(enabled: boolean): void {
         // Storage blocked or full: the choice lasts until the page is reloaded, no longer.
     }
 }
+
+/**
+ * `localStorage` key of the switch for the sounds that go with notifications (a chime for new mail, a bell for a calendar alarm, a buzz for an
+ * error). Absent means on; `"off"` means the user turned them off. Independent of the pop-ups themselves.
+ */
+export const NOTIFICATION_SOUNDS_KEY = "rapidmx-notification-sounds";
+
+/** Whether notification sounds are on (the default). */
+export function getNotificationSoundsEnabled(): boolean {
+    try {
+        return localStorage.getItem(NOTIFICATION_SOUNDS_KEY) !== "off";
+    } catch {
+        return true;
+    }
+}
+
+export function setNotificationSoundsEnabled(enabled: boolean): void {
+    try {
+        if (enabled) {
+            localStorage.removeItem(NOTIFICATION_SOUNDS_KEY);
+        } else {
+            localStorage.setItem(NOTIFICATION_SOUNDS_KEY, "off");
+        }
+    } catch {
+        // Storage blocked or full: the choice lasts until the page is reloaded, no longer.
+    }
+}

package/apps/shared/notifications/sounds.ts

@@ -0,0 +1,135 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { getNotificationSoundsEnabled } from "./preferences.js";
+
+/**
+ * The sounds that go with the app's notifications: a chime for new mail, a bell for a calendar alarm and a low double buzz for an error. They are
+ * made with the Web Audio API as they are played - no audio files to download, cache or ship - so they work offline and cost nothing until used.
+ *
+ * Browsers only let a page make sound after the person has interacted with it; until then the audio context stays suspended and a sound is silently
+ * skipped (it is resumed, and plays from then on, as soon as the page has had a click or a key press). A sound is never an error: whatever
+ * goes wrong with the audio is swallowed. The same sound is not played twice within `MIN_GAP_MS`, so a burst of notifications is one sound, not a clatter.
+ */
+export type NotificationSound = "mail" | "calendar" | "error";
+
+/** The shortest time between two plays of the same sound. */
+export const MIN_GAP_MS = 750;
+
+interface Tone {
+    /** Pitch in Hz at the start. */
+    frequency: number;
+    /** Pitch in Hz at the end, when it slides. */
+    endFrequency?: number;
+    /** Seconds after the sound starts. */
+    start: number;
+    /** Seconds it takes to die away. */
+    duration: number;
+    type: OscillatorType;
+    /** Peak loudness, 0 to 1. */
+    gain: number;
+}
+
+/** A soft two-note rising chime. */
+const CHIME: Tone[] = [
+    { frequency: 1046.5, start: 0, duration: 0.5, type: "sine", gain: 0.16 },
+    { frequency: 1568, start: 0.14, duration: 0.8, type: "sine", gain: 0.14 },
+];
+
+/** A struck bell, twice: a fundamental with the inharmonic partials of a bell, each dying away slowly. */
+const BELL: Tone[] = [0, 0.75].flatMap((start) =>
+    [
+        { ratio: 1, gain: 0.16, duration: 1.4 },
+        { ratio: 2.76, gain: 0.08, duration: 1.0 },
+        { ratio: 5.4, gain: 0.04, duration: 0.7 },
+        { ratio: 8.93, gain: 0.02, duration: 0.4 },
+    ].map<Tone>((partial) => ({ frequency: 880 * partial.ratio, start, duration: partial.duration, type: "sine", gain: partial.gain })),
+);
+
+/** Two short falling buzzes - nothing like the other two. */
+const ERROR: Tone[] = [
+    { frequency: 300, endFrequency: 190, start: 0, duration: 0.2, type: "sawtooth", gain: 0.09 },
+    { frequency: 300, endFrequency: 190, start: 0.26, duration: 0.2, type: "sawtooth", gain: 0.09 },
+];
+
+const SOUNDS: Record<NotificationSound, Tone[]> = { mail: CHIME, calendar: BELL, error: ERROR };
+
+let context: AudioContext | undefined;
+const lastPlayed: Partial<Record<NotificationSound, number>> = {};
+
+function audioContext(): AudioContext | undefined {
+    if (context) {
+        return context;
+    }
+    const Ctor: typeof AudioContext | undefined =
+        typeof window === "undefined" ? undefined : (window.AudioContext ?? (window as unknown as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext);
+    if (!Ctor) {
+        return undefined;
+    }
+    try {
+        context = new Ctor();
+    } catch {
+        return undefined;
+    }
+    return context;
+}
+
+function playTone(audio: AudioContext, tone: Tone): void {
+    const begin = audio.currentTime + tone.start;
+    const end = begin + tone.duration;
+    const oscillator = audio.createOscillator();
+    const volume = audio.createGain();
+    oscillator.type = tone.type;
+    oscillator.frequency.setValueAtTime(tone.frequency, begin);
+    if (tone.endFrequency !== undefined) {
+        oscillator.frequency.exponentialRampToValueAtTime(tone.endFrequency, end);
+    }
+    // A short attack so it doesn't click, then an exponential die-away.
+    volume.gain.setValueAtTime(0.0001, begin);
+    volume.gain.exponentialRampToValueAtTime(tone.gain, begin + 0.01);
+    volume.gain.exponentialRampToValueAtTime(0.0001, end);
+    oscillator.connect(volume);
+    volume.connect(audio.destination);
+    oscillator.start(begin);
+    oscillator.stop(end + 0.05);
+}
+
+/** Plays `sound`, unless the person turned notification sounds off, the same sound just played, or the browser won't make sound yet. Never throws. */
+export function playNotificationSound(sound: NotificationSound, now: number = Date.now()): void {
+    if (!getNotificationSoundsEnabled()) {
+        return;
+    }
+    const last = lastPlayed[sound];
+    if (last !== undefined && now - last < MIN_GAP_MS) {
+        return;
+    }
+    try {
+        const audio = audioContext();
+        if (!audio) {
+            return;
+        }
+        lastPlayed[sound] = now;
+        const play = (): void => {
+            for (const tone of SOUNDS[sound]) {
+                playTone(audio, tone);
+            }
+        };
+        if (audio.state === "suspended") {
+            // Allowed once the page has been interacted with; until then this is refused and the sound is skipped.
+            void audio.resume().then(play, () => undefined);
+        } else {
+            play();
+        }
+    } catch {
+        // Audio is a nicety: a failure to make a sound never reaches the notification.
+    }
+}
+
+/** Forgets the audio context and what was played when - for tests. */
+export function resetNotificationSounds(): void {
+    context = undefined;
+    for (const key of Object.keys(lastPlayed) as NotificationSound[]) {
+        delete lastPlayed[key];
+    }
+}

package/apps/shared/notifications/store.ts

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import { getNotificationsEnabled } from "./preferences.js";
+import { playNotificationSound } from "./sounds.js";
 
 /**
  * The app's one notification store: every pop-up - new mail, a failed send, an API error, an expired session - goes through
@@ -390,6 +391,14 @@ export function notify(input: NotifyInput): string {
         emit();
         return id;
     }
+    // What is shown is heard: a chime for new mail, a bell for a calendar notice, a buzz for an error.
+    if (entry.kind === "mail") {
+        playNotificationSound("mail");
+    } else if (entry.kind === "calendar") {
+        playNotificationSound("calendar");
+    } else if (entry.kind === "error") {
+        playNotificationSound("error");
+    }
     const room = visibleCount() < MAX_VISIBLE;
     entries.push(entry);
     if (room) {

package/apps/www/calendar/index.tsx

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import { pageTitle } from "../../shared/navigation/pageTitle.js";
+import { useLocation, useNavigate } from "../../shared/navigation/index.js";
 import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { DndContext, DragEndEvent, MouseSensor, TouchSensor, useSensor, useSensors } from "@dnd-kit/core";
 import { HiOutlineBars3, HiOutlinePlus } from "react-icons/hi2";
@@ -24,11 +25,11 @@ import { ApiRequestError } from "../../../lib/util/api.js";
 import { useApiClient } from "../../../lib/util/apiClientContext.js";
 import useIsMobile from "../../../lib/util/useIsMobile.js";
 import { CalendarEvent, getCalendarEvent, listCalendarEvents } from "../../../lib/calendar/calendarApi.js";
-import { getPushClient } from "../../../lib/mail/pushClient.js";
+import { useFolderLiveUpdates } from "../../shared/live/useFolderLiveUpdates.js";
 import { moveOccurrence, resizeOccurrenceEnd } from "../../../lib/calendar/calendarMutations.js";
 import { resolveDragAction } from "../../../lib/calendar/calendarDragIds.js";
 import { createFolder } from "../../../lib/mail/mailApi.js";
-import { CalendarOccurrence, expandAllOccurrences } from "../../../lib/calendar/recurrence.js";
+import { CalendarOccurrence, expandAllOccurrences, expandOccurrences } from "../../../lib/calendar/recurrence.js";
 import { useDayKey } from "../../../lib/calendar/useDayKey.js";
 import { allOccurrences, initialMatchIndex, occurrencesInRange, searchOccurrences, searchTerms, stepSequenceIndex } from "../../../lib/calendar/eventSearch.js";
 import Drawer from "../../../lib/components/overlays/Drawer.js";
@@ -62,6 +63,9 @@ import { notifyApiError } from "../../shared/notifications/apiErrors.js";
 import { bookingSettingsHref } from "../../shared/calendar/bookingPlugin.js";
 import { changedEventOf } from "../../shared/calendar/calendarLiveUpdates.js";
 
+/** The push client channel group (`PushClient.setChannels()`) the page's calendars are subscribed under. */
+const CALENDAR_CHANNEL_GROUP = "calendar";
+
 /** The furthest instants a `Date` can hold: the List's "range" reaches both. */
 const MAX_DATE_MS = 8.64e15;
 
@@ -301,36 +305,35 @@ function CalendarContent({ userUid, bookingHref }: { userUid?: string; bookingHr
     // fetch changes nothing: the next load shows the event as it is.
     const checkedFolderUidsRef = useRef(checkedFolderUids);
     checkedFolderUidsRef.current = checkedFolderUids;
-    useEffect(
-        () =>
-            getPushClient().onEvent((event) => {
-                const change = changedEventOf(event);
-                if (!change) {
-                    return;
-                }
-                const { uid } = change;
-                if (change.deleted) {
-                    setEvents((previous) => previous.filter((existing) => existing.uid !== uid));
-                    return;
-                }
-                void getCalendarEvent(uid, client).then(
-                    (fresh) => {
-                        if (checkedFolderUidsRef.current.has(fresh.folderUid)) {
-                            setEvents((previous) =>
-                                previous.some((existing) => existing.uid === fresh.uid)
-                                    ? previous.map((existing) => (existing.uid === fresh.uid ? fresh : existing))
-                                    : [...previous, fresh],
-                            );
-                        }
-                    },
-                    (err: unknown) => {
-                        if (err instanceof ApiRequestError && err.status === 404) {
-                            setEvents((previous) => previous.filter((existing) => existing.uid !== uid));
-                        }
-                    },
-                );
-            }),
-        [client],
+    // Those events are published on the calendar's own channel, so the page subscribes to every calendar it lists - checked or not, so checking
+    // one needs no new subscription - while it is open.
+    useFolderLiveUpdates(
+        CALENDAR_CHANNEL_GROUP,
+        calendarFolders.map((f) => f.uid),
+        changedEventOf,
+        (change) => {
+            const { uid } = change;
+            if (change.deleted) {
+                setEvents((previous) => previous.filter((existing) => existing.uid !== uid));
+                return;
+            }
+            void getCalendarEvent(uid, client).then(
+                (fresh) => {
+                    if (checkedFolderUidsRef.current.has(fresh.folderUid)) {
+                        setEvents((previous) =>
+                            previous.some((existing) => existing.uid === fresh.uid)
+                                ? previous.map((existing) => (existing.uid === fresh.uid ? fresh : existing))
+                                : [...previous, fresh],
+                        );
+                    }
+                },
+                (err: unknown) => {
+                    if (err instanceof ApiRequestError && err.status === 404) {
+                        setEvents((previous) => previous.filter((existing) => existing.uid !== uid));
+                    }
+                },
+            );
+        },
     );
 
     // Search: `searchText` is the box, `query` what it held once typing paused (or Enter was pressed) and is what is searched for. A search covers every
@@ -538,6 +541,35 @@ function CalendarContent({ userUid, bookingHref }: { userUid?: string; bookingHr
         setModal(null);
     }
 
+    // `?event=<uid>&start=<iso>` opens that event's card on the day it is on - where a calendar alarm's View button leads. `start` names which occurrence
+    // of a recurring event. Read from the page's own location, so it also works from the Calendar itself (a shallow navigation), and then taken off the
+    // address so a reload doesn't open it again.
+    const { search: locationSearch } = useLocation();
+    const navigateTo = useNavigate();
+    const openedFromAddressRef = useRef("");
+    useEffect(() => {
+        const params = new URLSearchParams(locationSearch);
+        const eventUid = params.get("event");
+        const wanted = `${eventUid}|${params.get("start")}`;
+        if (!eventUid || openedFromAddressRef.current === wanted) {
+            return;
+        }
+        openedFromAddressRef.current = wanted;
+        const requestedStart = new Date(params.get("start") ?? "");
+        navigateTo("/calendar", { replace: true });
+        getCalendarEvent(eventUid, client)
+            .then((event) => {
+                const from = isNaN(requestedStart.getTime()) ? new Date(event.startDate) : requestedStart;
+                const candidates = expandOccurrences(event, new Date(from.getTime() - 86_400_000), new Date(from.getTime() + 86_400_000));
+                const match = candidates.find((occurrence) => new Date(occurrence.startDate).getTime() === from.getTime()) ?? candidates[0];
+                if (match) {
+                    setViewDate(occurrenceDay(match));
+                    openEvent(match);
+                }
+            })
+            .catch((err) => notifyApiError(err, "Couldn't open the event"));
+    }, [locationSearch]);
+
     // Keyboard shortcuts - the toolbar's own actions. (A dialog open - the event editor - silences them.)
     useShortcut(SHORTCUTS.calendar.create, () => openNewEvent(), { enabled: !!mailboxUid && !!folderUid });
     useShortcut(SHORTCUTS.calendar.today, goToday);