@rapidmx/web-client 0.33.0 → 0.34.0

package/apps/shared/calendar/calendarReminders.ts

@@ -7,7 +7,7 @@
 
 import type { PushEvent } from "../../../lib/mail/pushClient.js";
 
-/** How long "Snooze" waits before the reminder reappears - or less, if the meeting starts sooner (`snoozeDelayMs()`). */
+/** How long "Snooze" waits before the alarm comes back. */
 export const SNOOZE_MS = 5 * 60_000;
 
 /** The payload restapi's `CalendarReminderJob` publishes (`{ eventUid, title, startDate, location }`) as a `"CalendarEvent"`/`"reminder"` push event. */
@@ -49,17 +49,26 @@ export function joinMeetingUrl(location: string | null | undefined): string | un
     return url.protocol === "http:" || url.protocol === "https:" ? trimmed : undefined;
 }
 
+/** What the alarm's button that opens an event's location URL is called: "Join" for a video meeting (a conferencing service's link, or any link that says
+ * it is one to join), "Open" for any other web address. */
+export function locationActionLabel(url: string): "Join" | "Open" {
+    const { hostname, pathname } = new URL(url);
+    const host = hostname.toLowerCase();
+    const conferencing = /(^|\.)(zoom\.us|zoom\.com|zoomgov\.com|webex\.com|gotomeeting\.com|goto\.com|whereby\.com|bluejeans\.com|chime\.aws|meet\.jit\.si)$/;
+    const known = conferencing.test(host) || host === "meet.google.com" || host === "teams.microsoft.com" || host === "teams.live.com";
+    return known || /\/(join|meet|meeting|room|call)(\/|$)/i.test(pathname) || /^(meet|video|call|conference)\./.test(host) ? "Join" : "Open";
+}
+
+/** Where an alarm's View button leads: the Calendar, with the event (and the occurrence due) open. */
+export function calendarEventHref(eventUid: string, startDate: string): string {
+    return `/calendar?event=${encodeURIComponent(eventUid)}&start=${encodeURIComponent(startDate)}`;
+}
+
 /** The reminder `event` carries, or `undefined` for anything else the shared push connection delivers (mail, folders, appearance, ...). */
 export function calendarReminderOf(event: PushEvent): CalendarReminderNotice | undefined {
     return event.type === "CalendarEvent" && event.action === "reminder" && isReminderNotice(event.data) ? event.data : undefined;
 }
 
-/** How long "Snooze" waits before showing the reminder again: `SNOOZE_MS`, or less if the meeting starts first - never negative (snoozing a
- * reminder for a meeting that has already started shows it again at once rather than waiting a further five minutes). */
-export function snoozeDelayMs(startDate: string, now: number = Date.now()): number {
-    return Math.max(0, Math.min(SNOOZE_MS, new Date(startDate).getTime() - now));
-}
-
 /** The pop-up's message line: when the meeting starts, relative to `now`. */
 export function reminderMessage(startDate: string, now: number = Date.now()): string {
     const time = new Date(startDate).toLocaleTimeString([], { hour: "numeric", minute: "2-digit" });

package/apps/shared/calendar/useCalendarReminders.ts

@@ -2,14 +2,12 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import { useEffect } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { getPushClient } from "../../../lib/mail/pushClient.js";
+import { getNotificationsEnabled } from "../notifications/preferences.js";
+import { playNotificationSound } from "../notifications/sounds.js";
 import { notify } from "../notifications/store.js";
-import { CalendarReminderNotice, calendarReminderOf, joinMeetingUrl, reminderMessage, reminderNotificationId, snoozeDelayMs } from "./calendarReminders.js";
-
-/** Where a reminder's title leads. There is no per-event deep link yet (the calendar opens an event by local state, not a URL - see
- * `apps/www/calendar/index.tsx`'s `openEvent()`), so every reminder opens the calendar itself. */
-export const CALENDAR_HREF = "/calendar";
+import { CalendarReminderNotice, SNOOZE_MS, calendarReminderOf, reminderMessage, reminderNotificationId } from "./calendarReminders.js";
 
 export interface UseCalendarRemindersOptions {
     /** Nothing is shown without a signed-in user. */
@@ -18,76 +16,83 @@ export interface UseCalendarRemindersOptions {
     enabled: boolean;
 }
 
+/** The calendar alarms waiting on the person, as `CalendarAlarmDialog` draws them. */
+export interface CalendarAlarms {
+    /** The alarm on screen: the oldest one not yet answered. `undefined` when there is none. */
+    current?: CalendarReminderNotice;
+    /** How many more are waiting behind `current`. */
+    waiting: number;
+    /** Closes `current` and brings it back after `SNOOZE_MS` (five minutes). */
+    snooze: () => void;
+    /** Closes `current` for good. */
+    dismiss: () => void;
+}
+
 /**
- * Pop-up meeting reminders. restapi's `CalendarReminderJob` fires a `"CalendarEvent"`/`"reminder"` push event (`{ eventUid, title, startDate }`)
- * when an event's `reminderMinutesBeforeStart` comes due, over the same shared push connection Mail already keeps open
- * (`getPushClient()`) - every accessible mailbox's own channel is already subscribed (`useMailLiveUpdates`'s `pushChannelsFor()`, and the
- * event is published to the mailbox channel as well as the folder's own), so this hook only has to listen, never to manage channels of its
- * own. Lives in the persistent app frame (`AppShell`), like `useSigningEnrollmentWatcher`, so a reminder shows wherever the user is signed in -
- * Mail, Calendar, Contacts, Settings.
+ * Calendar alarms. restapi's `CalendarReminderJob` fires a `"CalendarEvent"`/`"reminder"` push event (`{ eventUid, title, startDate, location }`)
+ * when an event's `reminderMinutesBeforeStart` comes due, over the same shared push connection Mail already keeps open (`getPushClient()`) -
+ * every accessible mailbox's own channel is already subscribed (`useMailLiveUpdates`'s `pushChannelsFor()`, and the event is published to the
+ * mailbox channel as well as the folder's own), so this hook only has to listen, never to manage channels of its own. Lives in the persistent
+ * app frame (`AppShell`), like `useSigningEnrollmentWatcher`, so an alarm shows wherever the user is signed in - Mail, Calendar, Contacts, Settings.
+ *
+ * An alarm is a modal (`CalendarAlarmDialog`), with a bell: not a pop-up that goes by itself, since a meeting missed to a toast that timed out
+ * is the failure an alarm exists to prevent. Alarms that arrive together queue, one dialog at a time. **Snooze** closes it and brings it back -
+ * with the bell again - after exactly `SNOOZE_MS`. A snooze is this tab's own `setTimeout`, cleared on unmount or sign-out; like the alarm itself (the
+ * push event is never replayed), it does not survive the tab closing.
  *
- * Each reminder is a sticky pop-up (`notify()`, kind `"calendar"`) with two actions: **Dismiss** closes it and does nothing else. **Snooze**
- * closes it and shows it again - reusing the same notification id, so it replaces rather than stacks - after `SNOOZE_MS` (five minutes), or
- * sooner if the meeting starts first (`snoozeDelayMs()`). A snooze is this tab's own `setTimeout`, cleared on unmount or sign-out; like the
- * reminder itself (the push event is never replayed), it does not survive the tab closing.
+ * With pop-ups turned off (`getNotificationsEnabled()`) no dialog is shown and nothing is heard: the alarm is only recorded in "Recent notifications".
  */
-export function useCalendarReminders({ userUid, enabled }: UseCalendarRemindersOptions): void {
-    useEffect(() => {
-        if (!enabled || !userUid) {
+export function useCalendarReminders({ userUid, enabled }: UseCalendarRemindersOptions): CalendarAlarms {
+    const [queue, setQueue] = useState<CalendarReminderNotice[]>([]);
+    // The queue as of the last render, for the callbacks below to read (a state updater must not start a timer: React may run it twice).
+    const queueRef = useRef(queue);
+    queueRef.current = queue;
+    const timers = useRef(new Set<ReturnType<typeof setTimeout>>());
+
+    const present = useCallback((notice: CalendarReminderNotice) => {
+        if (!getNotificationsEnabled()) {
+            // Off: only the history keeps it.
+            notify({ id: reminderNotificationId(notice.eventUid, notice.startDate), kind: "calendar", title: notice.title, message: reminderMessage(notice.startDate) });
             return;
         }
-        const timers = new Set<ReturnType<typeof setTimeout>>();
+        const id = reminderNotificationId(notice.eventUid, notice.startDate);
+        setQueue((current) => (current.some((queued) => reminderNotificationId(queued.eventUid, queued.startDate) === id) ? current : [...current, notice]));
+        playNotificationSound("calendar");
+    }, []);
 
-        function show(notice: CalendarReminderNotice): void {
-            const joinUrl = joinMeetingUrl(notice.location);
-            notify({
-                id: reminderNotificationId(notice.eventUid, notice.startDate),
-                kind: "calendar",
-                title: notice.title,
-                message: reminderMessage(notice.startDate),
-                // Anyone who can invite you can put any address in an event's location: the button says where it goes.
-                hint: joinUrl ? `Join Meeting opens ${new URL(joinUrl).host}` : undefined,
-                href: CALENDAR_HREF,
-                sticky: true,
-                actions: [
-                    ...(joinUrl
-                        ? [
-                              {
-                                  label: "Join Meeting",
-                                  onClick: () => window.open(joinUrl, "_blank", "noopener,noreferrer"),
-                                  // Joining isn't resolving the reminder - Dismiss/Snooze are still there afterward.
-                                  keepOpen: true,
-                              },
-                          ]
-                        : []),
-                    { label: "Dismiss" },
-                    {
-                        label: "Snooze",
-                        onClick: () => {
-                            const timer = setTimeout(() => {
-                                timers.delete(timer);
-                                show(notice);
-                            }, snoozeDelayMs(notice.startDate));
-                            timers.add(timer);
-                        },
-                    },
-                ],
-            });
+    useEffect(() => {
+        if (!enabled || !userUid) {
+            return;
         }
-
         const offEvent = getPushClient().onEvent((event) => {
             const notice = calendarReminderOf(event);
             if (notice) {
-                show(notice);
+                present(notice);
             }
         });
-
+        const pending = timers.current;
         return () => {
             offEvent();
-            for (const timer of timers) {
+            for (const timer of pending) {
                 clearTimeout(timer);
             }
-            timers.clear();
+            pending.clear();
+            setQueue([]);
         };
-    }, [enabled, userUid]);
+    }, [enabled, userUid, present]);
+
+    const dismiss = useCallback(() => setQueue((current) => current.slice(1)), []);
+    const snooze = useCallback(() => {
+        const first = queueRef.current[0];
+        if (first) {
+            const timer = setTimeout(() => {
+                timers.current.delete(timer);
+                present(first);
+            }, SNOOZE_MS);
+            timers.current.add(timer);
+        }
+        setQueue((current) => current.slice(1));
+    }, [present]);
+
+    return { current: queue[0], waiting: Math.max(0, queue.length - 1), snooze, dismiss };
 }

package/apps/shared/components/calendar/CalendarAlarmDialog.tsx

@@ -0,0 +1,75 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+import Button from "../../../../lib/components/buttons/Button.js";
+import Modal from "../../../../lib/components/overlays/Modal.js";
+import { calendarEventHref, joinMeetingUrl, locationActionLabel, reminderMessage } from "../../calendar/calendarReminders.js";
+import type { CalendarAlarms } from "../../calendar/useCalendarReminders.js";
+import { useNavigate } from "../../navigation/index.js";
+
+export interface CalendarAlarmDialogProps {
+    alarms: CalendarAlarms;
+}
+
+/**
+ * The modal an event's alarm raises (see `useCalendarReminders()`): what is starting and when, where, and three actions. **View** opens the event's card
+ * in the Calendar. **Join** or **Open** - named for what the event's location is, a video meeting or any other web address - opens that address in a new
+ * tab; it is only there when the location is a web address, and says which site it goes to, since anyone who can invite you can put any address in an
+ * event. **Snooze** closes the dialog and brings it back after five minutes. Closing it with the close button or Escape dismisses the alarm.
+ * View and Join/Open also dismiss it: the person has answered it.
+ */
+export default function CalendarAlarmDialog({ alarms }: CalendarAlarmDialogProps) {
+    const navigate = useNavigate();
+    const { current: alarm, waiting, snooze, dismiss } = alarms;
+    if (!alarm) {
+        return null;
+    }
+    const url = joinMeetingUrl(alarm.location);
+    const location = alarm.location?.trim();
+    return (
+        <Modal open onClose={dismiss} title={alarm.title}>
+            <div className="flex flex-col gap-4">
+                <div className="flex flex-col gap-1 text-sm">
+                    <p className="font-semibold">{reminderMessage(alarm.startDate)}</p>
+                    {location && <p className="text-text-muted break-words">{location}</p>}
+                    {waiting > 0 && (
+                        <p className="text-xs text-text-muted">
+                            {waiting} more alarm{waiting === 1 ? "" : "s"} after this one
+                        </p>
+                    )}
+                </div>
+                <div className="flex flex-wrap items-center gap-2">
+                    <Button
+                        type="button"
+                        variant="secondary"
+                        className="!w-auto"
+                        onClick={() => {
+                            navigate(calendarEventHref(alarm.eventUid, alarm.startDate));
+                            dismiss();
+                        }}
+                    >
+                        View
+                    </Button>
+                    {url && (
+                        <Button
+                            type="button"
+                            className="!w-auto"
+                            onClick={() => {
+                                window.open(url, "_blank", "noopener,noreferrer");
+                                dismiss();
+                            }}
+                        >
+                            {locationActionLabel(url)}
+                        </Button>
+                    )}
+                    <Button type="button" variant="secondary" className="!w-auto" onClick={snooze}>
+                        Snooze
+                    </Button>
+                </div>
+                {url && <p className="text-xs text-text-muted">{`${locationActionLabel(url)} opens ${new URL(url).host}`}</p>}
+            </div>
+        </Modal>
+    );
+}

package/apps/shared/components/layout/AppShell.tsx

@@ -50,6 +50,7 @@ import { MailConnectionContext, useMailConnection } from "../../mail/useMailConn
 import { useUnreadTitle } from "../../mail/useUnreadTitle.js";
 import UnlockBridge from "../../mail/outbox/UnlockBridge.js";
 import NotificationCenter from "../../notifications/NotificationCenter.js";
+import CalendarAlarmDialog from "../calendar/CalendarAlarmDialog.js";
 import { useHeaderHeightRef } from "../../notifications/headerOffset.js";
 import NotificationHistoryDialog from "../../notifications/NotificationHistoryDialog.js";
 import { notifySessionExpired, setSignInUrl } from "../../notifications/apiErrors.js";
@@ -210,8 +211,8 @@ export function AppChrome({
     const mail = useMailConnection({ userUid, enabled: inFrame, open: navigate });
     // A signing certificate the user asked for is announced when it is issued (or fails), on whichever page they are - see the hook.
     useSigningEnrollmentWatcher({ userUid, mailboxes: mail.mailboxes, enabled: inFrame });
-    // A meeting reminder pops up on whichever page they are - see the hook.
-    useCalendarReminders({ userUid, enabled: inFrame });
+    // An event's alarm raises a modal (drawn by `CalendarAlarmDialog`, below) on whichever page they are - see the hook.
+    const calendarAlarms = useCalendarReminders({ userUid, enabled: inFrame });
 
     // A refused refresh means the sign-in has ended: open compose windows save what they hold (the access token still works for a while) and the
     // browser goes to sign-in. Not while viewing as another user - the refresh cookie is the admin's own, and refreshing would end the impersonation.
@@ -459,6 +460,7 @@ export function AppChrome({
                         )}
                         {/* The one pop-up stack for the whole app: right under the header row, so it never covers the account menu. */}
                         <NotificationCenter />
+                        <CalendarAlarmDialog alarms={calendarAlarms} />
                         <div
                             id="app-content"
                             tabIndex={-1}

package/apps/shared/components/layout/UserMenu.tsx

@@ -10,6 +10,7 @@ import {
     HiOutlineArrowUturnLeft,
     HiOutlineBell,
     HiOutlineBellAlert,
+    HiOutlineSpeakerWave,
     HiOutlineClock,
     HiOutlineCog6Tooth,
     HiOutlineCommandLine,
@@ -34,7 +35,12 @@ import {
     requestDesktopPermission,
     setDesktopOfferDismissed,
 } from "../../mail/newMailNotifications.js";
-import { getNotificationsEnabled, setNotificationsEnabled } from "../../notifications/preferences.js";
+import {
+    getNotificationSoundsEnabled,
+    getNotificationsEnabled,
+    setNotificationSoundsEnabled,
+    setNotificationsEnabled,
+} from "../../notifications/preferences.js";
 import { dismissAll } from "../../notifications/store.js";
 
 export interface UserMenuProps {
@@ -134,6 +140,7 @@ export default function UserMenu({
     const menuRef = useRef<HTMLDivElement>(null);
     const [detectedAdmin, setDetectedAdmin] = useState(false);
     const [popups, setPopups] = useState(true);
+    const [sounds, setSounds] = useState(true);
     const [permission, setPermission] = useState<DesktopPermission>("unsupported");
     const [profile, setProfile] = useState<Profile | undefined>(undefined);
     // Whether the profile lookup has answered, with a profile or without: the fallback names are only worth asking for after that.
@@ -230,10 +237,16 @@ export default function UserMenu({
     useEffect(() => {
         if (open && showNotificationSettings) {
             setPopups(getNotificationsEnabled());
+            setSounds(getNotificationSoundsEnabled());
             setPermission(desktopPermission());
         }
     }, [open, showNotificationSettings]);
 
+    function toggleSounds() {
+        setNotificationSoundsEnabled(!sounds);
+        setSounds(!sounds);
+    }
+
     function togglePopups() {
         setNotificationsEnabled(!popups);
         setPopups(!popups);
@@ -386,6 +399,21 @@ export default function UserMenu({
                             <span className="text-xs font-semibold text-text-muted">{popups ? "On" : "Off"}</span>
                         </button>
                     )}
+                    {showNotificationSettings && (
+                        <button
+                            role="menuitemcheckbox"
+                            aria-checked={sounds}
+                            type="button"
+                            onClick={toggleSounds}
+                            className="flex w-full items-center justify-between gap-2 px-3.5 py-2 text-left text-sm text-text hover:bg-surface-alt"
+                        >
+                            <span className="flex items-center gap-2">
+                                <HiOutlineSpeakerWave size={16} aria-hidden="true" className="shrink-0 text-text-muted" />
+                                Notification sounds
+                            </span>
+                            <span className="text-xs font-semibold text-text-muted">{sounds ? "On" : "Off"}</span>
+                        </button>
+                    )}
                     {showNotificationSettings && permission === "default" && (
                         <button
                             role="menuitem"

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";
@@ -28,7 +29,7 @@ import { getPushClient } from "../../../lib/mail/pushClient.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";
@@ -538,6 +539,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);

package/dist/apps/shared/calendar/calendarReminders.d.ts

@@ -1,7 +1,7 @@
 /** Pure helpers behind `useCalendarReminders.ts` - kept apart from the hook so the push-payload parsing, the snooze
  * arithmetic and the pop-up's wording are each testable without a React tree or a socket. */
 import type { PushEvent } from "../../../lib/mail/pushClient.js";
-/** How long "Snooze" waits before the reminder reappears - or less, if the meeting starts sooner (`snoozeDelayMs()`). */
+/** How long "Snooze" waits before the alarm comes back. */
 export declare const SNOOZE_MS: number;
 /** The payload restapi's `CalendarReminderJob` publishes (`{ eventUid, title, startDate, location }`) as a `"CalendarEvent"`/`"reminder"` push event. */
 export interface CalendarReminderNotice {
@@ -17,11 +17,13 @@ export interface CalendarReminderNotice {
  * else (a room name, an address, free-text instructions are all real, common `location` values this must not
  * treat as a link). Trimmed first, so incidental whitespace never hides a real link. */
 export declare function joinMeetingUrl(location: string | null | undefined): string | undefined;
+/** What the alarm's button that opens an event's location URL is called: "Join" for a video meeting (a conferencing service's link, or any link that says
+ * it is one to join), "Open" for any other web address. */
+export declare function locationActionLabel(url: string): "Join" | "Open";
+/** Where an alarm's View button leads: the Calendar, with the event (and the occurrence due) open. */
+export declare function calendarEventHref(eventUid: string, startDate: string): string;
 /** The reminder `event` carries, or `undefined` for anything else the shared push connection delivers (mail, folders, appearance, ...). */
 export declare function calendarReminderOf(event: PushEvent): CalendarReminderNotice | undefined;
-/** How long "Snooze" waits before showing the reminder again: `SNOOZE_MS`, or less if the meeting starts first - never negative (snoozing a
- * reminder for a meeting that has already started shows it again at once rather than waiting a further five minutes). */
-export declare function snoozeDelayMs(startDate: string, now?: number): number;
 /** The pop-up's message line: when the meeting starts, relative to `now`. */
 export declare function reminderMessage(startDate: string, now?: number): string;
 /** The one notification id a reminder, and every "Snooze" of it, reuses - so snoozing replaces the same pop-up rather than stacking a new one. */