Feature/protocol handlers

* Added account selection for protocol links when multiple connected accounts are available, including mailto: links
* Added support for handling mailto: links in an already-open PWA/session instead of always opening a new tab
* Added webcal: protocol handling for calendar links
* Added account selection for webcal: links when multiple calendar-capable accounts are connected
* Added an import-or-subscribe choice for detected webcal calendars
* Added protocol handler settings for registering mail and calendar handlers and choosing the open mode
* Added service worker/session coordination for passing protocol requests between browser/PWA contexts
* Added tests and translations for the new protocol handler flows

app/[locale]/calendar/page.tsx

@@ -15,6 +15,7 @@ import { useAuthStore, redirectToLogin } from "@/stores/auth-store";
 import { useEmailStore } from "@/stores/email-store";
 import { useSettingsStore } from "@/stores/settings-store";
 import { useIdentityStore } from "@/stores/identity-store";
+import { useAccountStore } from "@/stores/account-store";
 import { toast } from "@/stores/toast-store";
 import { useIsMobile } from "@/hooks/use-media-query";
 import { Button } from "@/components/ui/button";
@@ -37,6 +38,7 @@ import { useRefreshGesture } from "@/hooks/use-refresh-gesture";
 import { downloadEventICS } from "@/lib/calendar-ics-export";
 import { ICalImportModal } from "@/components/calendar/ical-import-modal";
 import { ICalSubscriptionModal } from "@/components/calendar/ical-subscription-modal";
+import { ProtocolAccountPicker } from "@/components/protocol/protocol-account-picker";
 import { RecurrenceScopeDialog, type RecurrenceEditScope } from "@/components/calendar/recurrence-scope-dialog";
 import { NavigationRail } from "@/components/layout/navigation-rail";
 import { SidebarAppsModal } from "@/components/layout/sidebar-apps-modal";
@@ -56,6 +58,8 @@ import { CreateCalendarModal } from "@/components/calendar/create-calendar-modal
 import { getUserParticipantId } from "@/lib/calendar-participants";
 import { generateBirthdayEvents, createBirthdayCalendar, BIRTHDAY_CALENDAR_ID } from "@/lib/birthday-calendar";
 import { debug } from "@/lib/debug";
+import { consumePendingWebcal, hasPendingWebcal, subscribeToPendingWebcal } from "@/lib/protocol-handlers/session";
+import type { ParsedWebcal } from "@/lib/protocol-handlers/webcal";
 
 type PendingScopeAction =
   | { type: "edit"; event: CalendarEvent; updates: Partial<CalendarEvent>; sendScheduling?: boolean }
@@ -68,9 +72,10 @@ function isRecurringEvent(event: CalendarEvent): boolean {
 export default function CalendarPage() {
   const router = useRouter();
   const t = useTranslations("calendar");
+  const tWebcalAction = useTranslations("calendar.webcal_action");
   const isMobile = useIsMobile();
   const { showAppsModal, inlineApp, loadedApps, handleManageApps, handleInlineApp, closeInlineApp, closeAppsModal } = useSidebarApps();
-  const { client, isAuthenticated, logout, checkAuth, isLoading: authLoading } = useAuthStore();
+  const { client, isAuthenticated, logout, checkAuth, switchAccount, activeAccountId, isLoading: authLoading } = useAuthStore();
   const [initialCheckDone, setInitialCheckDone] = useState(() => useAuthStore.getState().isAuthenticated && !!useAuthStore.getState().client);
   const { quota, isPushConnected } = useEmailStore();
   const {
@@ -96,6 +101,10 @@ export default function CalendarPage() {
   const [showEventModal, setShowEventModal] = useState(false);
   const [showImportModal, setShowImportModal] = useState(false);
   const [showSubscriptionModal, setShowSubscriptionModal] = useState(false);
+  const [pendingSubscription, setPendingSubscription] = useState<{ url: string; name: string } | null>(null);
+  const [showWebcalActionChoice, setShowWebcalActionChoice] = useState(false);
+  const [pendingWebcalAccountChoice, setPendingWebcalAccountChoice] = useState<ParsedWebcal | null>(null);
+  const [isProtocolAccountSwitching, setIsProtocolAccountSwitching] = useState(false);
   const [editingSubscription, setEditingSubscription] = useState<string | null>(null);
   const [sharingCalendarId, setSharingCalendarId] = useState<string | null>(null);
   const [defaultCalendarIdForCreate, setDefaultCalendarIdForCreate] = useState<string | undefined>(undefined);
@@ -156,10 +165,10 @@ export default function CalendarPage() {
     if (initialCheckDone && !isAuthenticated && !authLoading) {
       try { sessionStorage.setItem('redirect_after_login', window.location.pathname); } catch { /* ignore */ }
       redirectToLogin();
-    } else if (client && !supportsCalendar) {
+    } else if (client && !supportsCalendar && !pendingWebcalAccountChoice && !isProtocolAccountSwitching && !pendingSubscription && !showWebcalActionChoice && !hasPendingWebcal()) {
       router.push("/");
     }
-  }, [initialCheckDone, isAuthenticated, authLoading, client, supportsCalendar, router]);
+  }, [initialCheckDone, isAuthenticated, authLoading, client, supportsCalendar, pendingWebcalAccountChoice, isProtocolAccountSwitching, pendingSubscription, showWebcalActionChoice, router]);
 
   useEffect(() => {
     if (error) {
@@ -167,6 +176,84 @@ export default function CalendarPage() {
     }
   }, [error]);
 
+  const getWebcalProtocolAccounts = useCallback(() => {
+    const connectedClients = useAuthStore.getState().getAllConnectedClients();
+    return useAccountStore.getState().accounts.filter((account) => {
+      if (!account.isConnected) return false;
+      return connectedClients.get(account.id)?.supportsCalendars() === true;
+    });
+  }, []);
+
+  const openWebcalForAccount = useCallback(async (pending: ParsedWebcal, accountId: string) => {
+    setIsProtocolAccountSwitching(true);
+    try {
+      if (useAuthStore.getState().activeAccountId !== accountId) {
+        await switchAccount(accountId);
+      }
+      setPendingWebcalAccountChoice(null);
+      setPendingSubscription({
+        url: pending.subscriptionUrl,
+        name: pending.suggestedName,
+      });
+      setShowWebcalActionChoice(true);
+    } finally {
+      setIsProtocolAccountSwitching(false);
+    }
+  }, [switchAccount]);
+
+  const handleWebcalProtocolRequest = useCallback((pending: ParsedWebcal) => {
+    const protocolAccounts = getWebcalProtocolAccounts();
+    if (protocolAccounts.length > 1) {
+      setPendingWebcalAccountChoice(pending);
+      return;
+    }
+
+    if (protocolAccounts.length === 0 && !supportsCalendar) {
+      return;
+    }
+
+    const accountId = protocolAccounts[0]?.id ?? activeAccountId;
+    if (accountId) {
+      void openWebcalForAccount(pending, accountId);
+      return;
+    }
+
+    setPendingSubscription({
+      url: pending.subscriptionUrl,
+      name: pending.suggestedName,
+    });
+    setShowWebcalActionChoice(true);
+  }, [activeAccountId, getWebcalProtocolAccounts, openWebcalForAccount, supportsCalendar]);
+
+  const closeWebcalActionChoice = useCallback(() => {
+    setShowWebcalActionChoice(false);
+    setPendingSubscription(null);
+  }, []);
+
+  const handleImportWebcal = useCallback(() => {
+    setShowWebcalActionChoice(false);
+    setShowImportModal(true);
+  }, []);
+
+  const handleSubscribeWebcal = useCallback(() => {
+    setShowWebcalActionChoice(false);
+    setShowSubscriptionModal(true);
+  }, []);
+
+  useEffect(() => {
+    if (!isAuthenticated || !client) return;
+
+    const openPendingWebcal = () => {
+      const pending = consumePendingWebcal();
+      if (!pending) return;
+
+      handleWebcalProtocolRequest(pending);
+    };
+
+    openPendingWebcal();
+    return subscribeToPendingWebcal(openPendingWebcal);
+  }, [isAuthenticated, client, handleWebcalProtocolRequest]);
+
   useEffect(() => {
     if (client && !hasFetched.current) {
       hasFetched.current = true;
@@ -955,7 +1042,54 @@ export default function CalendarPage() {
     });
   }, [events, selectedCalendarIds, visibleEvents]);
 
-  if (!isAuthenticated || !supportsCalendar) return null;
+  const renderWebcalAccountPicker = () => pendingWebcalAccountChoice ? (
+    <ProtocolAccountPicker
+      kind="webcal"
+      operation={pendingWebcalAccountChoice}
+      accounts={getWebcalProtocolAccounts()}
+      activeAccountId={activeAccountId}
+      isSwitching={isProtocolAccountSwitching}
+      onSelect={(accountId) => void openWebcalForAccount(pendingWebcalAccountChoice, accountId)}
+      onCancel={() => setPendingWebcalAccountChoice(null)}
+    />
+  ) : null;
+
+  const renderWebcalActionChoice = () => showWebcalActionChoice && pendingSubscription ? (
+    <div className="fixed inset-0 z-50 flex items-center justify-center">
+      <div className="absolute inset-0 bg-black/50 backdrop-blur-[1px]" onClick={closeWebcalActionChoice} aria-hidden="true" />
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-label={tWebcalAction("title")}
+        className="relative bg-background border border-border rounded-lg shadow-xl w-full max-w-md mx-4 animate-in zoom-in-95 duration-200"
+      >
+        <div className="px-6 py-4 border-b border-border">
+          <h2 className="text-lg font-semibold">{tWebcalAction("title")}</h2>
+          <p className="text-sm text-muted-foreground mt-1">{tWebcalAction("description", { name: pendingSubscription.name })}</p>
+        </div>
+        <div className="px-6 py-4 space-y-3">
+          <Button variant="outline" className="w-full justify-start h-auto py-3" onClick={handleImportWebcal}>
+            <span className="text-left">
+              <span className="block font-medium">{tWebcalAction("import_title")}</span>
+              <span className="block text-xs text-muted-foreground mt-0.5">{tWebcalAction("import_description")}</span>
+            </span>
+          </Button>
+          <Button variant="outline" className="w-full justify-start h-auto py-3" onClick={handleSubscribeWebcal}>
+            <span className="text-left">
+              <span className="block font-medium">{tWebcalAction("subscribe_title")}</span>
+              <span className="block text-xs text-muted-foreground mt-0.5">{tWebcalAction("subscribe_description")}</span>
+            </span>
+          </Button>
+        </div>
+        <div className="flex items-center justify-end gap-2 px-6 py-4 border-t border-border">
+          <Button variant="ghost" onClick={closeWebcalActionChoice}>{tWebcalAction("cancel")}</Button>
+        </div>
+      </div>
+    </div>
+  ) : null;
+
+  if (!isAuthenticated) return null;
+  if (!supportsCalendar) return renderWebcalAccountPicker();
 
   const renderView = () => {
     if (isLoading && calendars.length === 0) {
@@ -1378,14 +1512,23 @@ export default function CalendarPage() {
         <ICalImportModal
           calendars={calendars}
           client={client}
-          onClose={() => setShowImportModal(false)}
+          initialUrl={pendingSubscription?.url}
+          onClose={() => {
+            setShowImportModal(false);
+            setPendingSubscription(null);
+          }}
         />
       )}
 
       {showSubscriptionModal && client && (
         <ICalSubscriptionModal
           client={client}
-          onClose={() => setShowSubscriptionModal(false)}
+          initialUrl={pendingSubscription?.url}
+          initialName={pendingSubscription?.name}
+          onClose={() => {
+            setShowSubscriptionModal(false);
+            setPendingSubscription(null);
+          }}
         />
       )}
 
@@ -1402,6 +1545,8 @@ export default function CalendarPage() {
       })()}
 
       <SidebarAppsModal isOpen={showAppsModal} onClose={closeAppsModal} />
+      {renderWebcalAccountPicker()}
+      {renderWebcalActionChoice()}
       <RecurrenceScopeDialog
         isOpen={!!pendingScopeAction}
         actionType={pendingScopeAction?.type || "edit"}

app/[locale]/layout.tsx

@@ -5,6 +5,7 @@ import { CalendarAlertProvider } from "@/components/providers/calendar-alert-pro
 import { EmbeddedBridgeProvider } from "@/components/providers/embedded-bridge-provider";
 import { RateLimitToastProvider } from "@/components/providers/rate-limit-toast-provider";
 import { TourProvider } from "@/components/tour/tour-provider";
+import { ProtocolLaunchHandlerProvider } from "@/components/protocol/protocol-launch-handler-provider";
 import { locales } from "@/i18n/routing";
 
 export default async function LocaleLayout({
@@ -32,7 +33,9 @@ export default async function LocaleLayout({
           <RateLimitToastProvider>
             <EmbeddedBridgeProvider>
               <TourProvider>
-                {children}
+                <ProtocolLaunchHandlerProvider>
+                  {children}
+                </ProtocolLaunchHandlerProvider>
               </TourProvider>
             </EmbeddedBridgeProvider>
           </RateLimitToastProvider>

app/[locale]/page.tsx

@@ -8,6 +8,7 @@ import { EmailList } from "@/components/email/email-list";
 import { EmailViewer } from "@/components/email/email-viewer";
 import { EmailComposer } from "@/components/email/email-composer";
 import type { ComposerDraftData } from "@/components/email/email-composer";
+import { ProtocolAccountPicker } from "@/components/protocol/protocol-account-picker";
 import { ThreadConversationView } from "@/components/email/thread-conversation-view";
 import { MobileHeader } from "@/components/layout/mobile-header";
 import { ThreadGroup, Email, isUnifiedMailboxId, UNIFIED_ROLE_BY_ID } from "@/lib/jmap/types";
@@ -60,6 +61,9 @@ import { Button } from "@/components/ui/button";
 import { useConfig } from "@/hooks/use-config";
 import { usePluginStore } from "@/stores/plugin-store";
 import { useThemeStore } from "@/stores/theme-store";
+import { consumePendingMailto, subscribeToPendingMailto } from "@/lib/protocol-handlers/session";
+import type { ParsedMailto } from "@/lib/protocol-handlers/mailto";
+import { plainTextToComposerBody } from "@/lib/email-composer-utils";
 import { appLifecycleHooks, uiHooks, routerHooks, toastHooks, emailHooks } from "@/lib/plugin-hooks";
 import { emailToReadView } from "@/lib/plugin-projection";
 
@@ -74,6 +78,7 @@ export default function Home() {
   const [composerDraftText, setComposerDraftText] = useState("");
   const [pendingDraft, setPendingDraft] = useState<ComposerDraftData | null>(null);
   const [composerSessionId, setComposerSessionId] = useState(0);
+  const suppressComposerStateSaveSessionRef = useRef<number | null>(null);
   const { dialogProps: confirmDialogProps, confirm: confirmDialog } = useConfirmDialog();
   const { dialogProps: promptDialogProps, prompt: promptDialog } = usePromptDialog();
   const { showAppsModal, inlineApp, loadedApps, handleManageApps, handleInlineApp, closeInlineApp, closeAppsModal } = useSidebarApps();
@@ -89,8 +94,10 @@ export default function Home() {
   const [isLoadingConversation, setIsLoadingConversation] = useState(false);
   const [rateLimitSecondsLeft, setRateLimitSecondsLeft] = useState<number | null>(null);
   const [previewAttachment, setPreviewAttachment] = useState<{ blobId: string; name: string; type?: string } | null>(null);
+  const [pendingMailtoAccountChoice, setPendingMailtoAccountChoice] = useState<ParsedMailto | null>(null);
+  const [isProtocolAccountSwitching, setIsProtocolAccountSwitching] = useState(false);
   const markAsReadTimeoutRef = useRef<NodeJS.Timeout | null>(null);
-  const { isAuthenticated, client, logout, checkAuth, isLoading: authLoading, connectionLost, isRateLimited, rateLimitUntil } = useAuthStore();
+  const { isAuthenticated, client, logout, checkAuth, switchAccount, activeAccountId, isLoading: authLoading, connectionLost, isRateLimited, rateLimitUntil } = useAuthStore();
   const { identities } = useIdentityStore();
   useIdentitySync();
   const trustedSendersAddressBook = useSettingsStore((state) => state.trustedSendersAddressBook);
@@ -308,6 +315,13 @@ export default function Home() {
     [],
   );
 
+  const getMailtoProtocolAccounts = useCallback(() => {
+    const connectedClients = useAuthStore.getState().getAllConnectedClients();
+    return useAccountStore.getState().accounts.filter((account) =>
+      account.isConnected && connectedClients.has(account.id)
+    );
+  }, []);
+
   // Browser back / forward integration. The restore handler reads the
   // latest values from a ref so we don't have to recreate the callback on
   // every render (and so the popstate listener is never stale).
@@ -651,6 +665,74 @@ export default function Home() {
     }
   }, [initialCheckDone, isAuthenticated, authLoading]);
 
+  const openMailtoDraft = useCallback((pending: ParsedMailto) => {
+    const body = useSettingsStore.getState().plainTextMode
+      ? pending.body
+      : plainTextToComposerBody(pending.body);
+
+    if (showComposer) {
+      suppressComposerStateSaveSessionRef.current = composerSessionId;
+    }
+    setComposerSessionId((id) => id + 1);
+    setPendingDraft({
+      to: pending.to.join(", "),
+      cc: pending.cc.join(", "),
+      bcc: pending.bcc.join(", "),
+      subject: pending.subject,
+      body,
+      showCc: pending.cc.length > 0,
+      showBcc: pending.bcc.length > 0,
+      selectedIdentityId: null,
+      subAddressTag: "",
+      mode: "compose",
+      draftId: null,
+    });
+    setComposerMode("compose");
+    setShowComposer(true);
+    if (isMobile) setActiveView("viewer");
+  }, [composerSessionId, isMobile, setActiveView, showComposer]);
+
+  const openMailtoForAccount = useCallback(async (pending: ParsedMailto, accountId: string) => {
+    setIsProtocolAccountSwitching(true);
+    try {
+      if (useAuthStore.getState().activeAccountId !== accountId) {
+        await switchAccount(accountId);
+      }
+      setPendingMailtoAccountChoice(null);
+      openMailtoDraft(pending);
+    } finally {
+      setIsProtocolAccountSwitching(false);
+    }
+  }, [openMailtoDraft, switchAccount]);
+
+  const handleMailtoProtocolRequest = useCallback((pending: ParsedMailto) => {
+    const protocolAccounts = getMailtoProtocolAccounts();
+    if (protocolAccounts.length > 1) {
+      setPendingMailtoAccountChoice(pending);
+      return;
+    }
+
+    const accountId = protocolAccounts[0]?.id ?? activeAccountId;
+    if (accountId) {
+      void openMailtoForAccount(pending, accountId);
+      return;
+    }
+
+    openMailtoDraft(pending);
+  }, [activeAccountId, getMailtoProtocolAccounts, openMailtoDraft, openMailtoForAccount]);
+
+  useEffect(() => {
+    if (!isAuthenticated || !client) return;
+
+    const openPendingMailto = () => {
+      const pending = consumePendingMailto();
+      if (pending) handleMailtoProtocolRequest(pending);
+    };
+
+    openPendingMailto();
+    return subscribeToPendingMailto(openPendingMailto);
+  }, [isAuthenticated, client, handleMailtoProtocolRequest]);
+
   // Fallback fetch for paths that didn't go through login()'s prefetch
   // (notably checkAuth on page refresh). The prefetch in auth-store/login()
   // populates mailboxes before this effect first runs, so on the post-login
@@ -2373,7 +2455,13 @@ export default function Home() {
                   } : undefined)}
                   initialDraftText={composerDraftText}
                   initialData={pendingDraft}
-                  onSaveState={(data) => setPendingDraft(data)}
+                  onSaveState={(data) => {
+                    if (suppressComposerStateSaveSessionRef.current === composerSessionId) {
+                      suppressComposerStateSaveSessionRef.current = null;
+                      return;
+                    }
+                    setPendingDraft(data);
+                  }}
                   onSend={async (data) => {
                     await handleEmailSend(data);
                     setPendingDraft(null);
@@ -2528,6 +2616,17 @@ export default function Home() {
         <div className="sr-only" aria-live="polite" aria-atomic="true" id="sr-status" />
 
         <SidebarAppsModal isOpen={showAppsModal} onClose={closeAppsModal} />
+        {pendingMailtoAccountChoice && (
+          <ProtocolAccountPicker
+            kind="mailto"
+            operation={pendingMailtoAccountChoice}
+            accounts={getMailtoProtocolAccounts()}
+            activeAccountId={activeAccountId}
+            isSwitching={isProtocolAccountSwitching}
+            onSelect={(accountId) => void openMailtoForAccount(pendingMailtoAccountChoice, accountId)}
+            onCancel={() => setPendingMailtoAccountChoice(null)}
+          />
+        )}
         <ConfirmDialog {...confirmDialogProps} />
         <PromptDialog {...promptDialogProps} />
         <TotpReauthDialog />

app/[locale]/settings/page.tsx

@@ -26,6 +26,7 @@ import {
   Bell,
   Puzzle,
   LayoutGrid,
+  Link as LinkIcon,
   BookOpen,
   PenLine,
   EyeOff,
@@ -63,6 +64,7 @@ import { SidebarAppsSettings } from '@/components/settings/sidebar-apps-settings
 import { NotificationSettings } from '@/components/settings/notification-settings';
 import { ThemesSettings } from '@/components/settings/themes-settings';
 import { PluginsSettings } from '@/components/settings/plugins-settings';
+import { ProtocolHandlerSettings } from '@/components/settings/protocol-handler-settings';
 import { useAuthStore, redirectToLogin } from '@/stores/auth-store';
 import { useEmailStore } from '@/stores/email-store';
 import { usePluginStore } from '@/stores/plugin-store';
@@ -98,6 +100,7 @@ type Tab =
   | 'calendar'
   | 'contacts'
   | 'files'
+  | 'protocol_handlers'
   | 'sidebar_apps'
   | 'about_data'
   | 'themes'
@@ -133,6 +136,7 @@ const tabIcons: Record<Tab, LucideIcon> = {
   calendar: Calendar,
   contacts: BookUser,
   files: HardDrive,
+  protocol_handlers: LinkIcon,
   sidebar_apps: PanelLeftClose,
   about_data: Info,
   themes: Palette,
@@ -211,6 +215,7 @@ const tabSearchPaths: Record<Tab, string[]> = {
   calendar: ['calendar.settings', 'calendar.management'],
   contacts: ['settings.contacts', 'contacts'],
   files: ['settings.files'],
+  protocol_handlers: ['protocol_handlers'],
   sidebar_apps: ['settings.sidebar_apps', 'sidebar_apps'],
   about_data: ['settings.advanced'],
   themes: [],
@@ -240,6 +245,7 @@ const tabKeywords: Record<Tab, string> = {
   calendar: 'event schedule appointment meeting timezone',
   contacts: 'address book contact',
   files: 'attachments cloud drive storage upload',
+  protocol_handlers: 'mailto webcal links default app protocol handler',
   sidebar_apps: 'apps webview iframe',
   about_data: 'export import storage quota privacy backup',
   themes: 'custom theme css skin appearance',
@@ -560,6 +566,7 @@ export default function SettingsPage() {
     { id: 'account', label: t('tabs.account'), icon: tabIcons.account, group: 'general' },
     { id: 'language', label: t('tabs.language'), icon: tabIcons.language, group: 'general' },
     { id: 'notifications', label: t('tabs.notifications'), icon: tabIcons.notifications, group: 'general' },
+    { id: 'protocol_handlers', label: t('tabs.protocol_handlers'), icon: tabIcons.protocol_handlers, group: 'general' },
 
     // Appearance
     { id: 'appearance', label: t('tabs.appearance'), icon: tabIcons.appearance, group: 'appearance' },
@@ -666,6 +673,7 @@ export default function SettingsPage() {
       {effectiveActiveTab === 'calendar' && <><CalendarSettings /><div className="mt-8"><CalendarManagementSettings /></div></>}
       {effectiveActiveTab === 'contacts' && <><ContactsSettings /><div className="mt-8"><AddressBookManagementSettings /></div></>}
       {effectiveActiveTab === 'files' && <FilesSettingsComponent />}
+      {effectiveActiveTab === 'protocol_handlers' && <ProtocolHandlerSettings supportsCalendar={supportsCalendar} />}
       {effectiveActiveTab === 'sidebar_apps' && <SidebarAppsSettings />}
       {effectiveActiveTab === 'about_data' && <AboutDataSettings />}
       {effectiveActiveTab === 'themes' && <ThemesSettings />}

app/manifest.ts

@@ -2,13 +2,26 @@ import type { MetadataRoute } from "next";
 
 export const dynamic = "force-dynamic";
 
+type WebAppProtocolHandler = {
+  protocol: string;
+  url: string;
+};
+
+type ExtendedManifest = MetadataRoute.Manifest & {
+  protocol_handlers?: WebAppProtocolHandler[];
+  launch_handler?: {
+    client_mode?: "navigate-existing" | "auto" | "focus-existing" | "navigate-new"
+      | Array<"navigate-existing" | "auto" | "focus-existing" | "navigate-new">;
+  };
+};
+
 // Manifest paths must include the deployment subpath - browsers resolve them
 // against the document origin, not the manifest's location, and Next.js does
 // not auto-prefix string literals inside MetadataRoute payloads.
 const BASE_PATH = (process.env.NEXT_PUBLIC_BASE_PATH ?? "").replace(/\/+$/, "");
 const withBase = (p: string) => `${BASE_PATH}${p}`;
 
-export default function manifest(): MetadataRoute.Manifest {
+export default function manifest(): ExtendedManifest {
   const appName =
     process.env.APP_NAME ||
     process.env.NEXT_PUBLIC_APP_NAME ||
@@ -57,5 +70,12 @@ export default function manifest(): MetadataRoute.Manifest {
       { src: withBase("/screenshot-540x720.png"), sizes: "540x720", type: "image/png" },
       { src: withBase("/screenshot-1280x720.png"), sizes: "1280x720", type: "image/png" },
     ],
+    protocol_handlers: [
+      { protocol: "mailto", url: withBase("/protocol/mailto?url=%s") },
+      { protocol: "webcal", url: withBase("/protocol/webcal?url=%s") },
+    ],
+    launch_handler: {
+      client_mode: ["focus-existing", "navigate-new"],
+    },
   };
 }

app/protocol/mailto/page.tsx

@@ -0,0 +1,8 @@
+import { getTranslations } from "next-intl/server";
+import { MailtoProtocolClient } from "@/components/protocol/mailto-protocol-client";
+
+export default async function MailtoProtocolPage() {
+  const t = await getTranslations("protocol_handlers");
+
+  return <MailtoProtocolClient openingText={t("opening_mailto")} />;
+}

app/protocol/webcal/page.tsx

@@ -0,0 +1,8 @@
+import { getTranslations } from "next-intl/server";
+import { WebcalProtocolClient } from "@/components/protocol/webcal-protocol-client";
+
+export default async function WebcalProtocolPage() {
+  const t = await getTranslations("protocol_handlers");
+
+  return <WebcalProtocolClient openingText={t("opening_webcal")} />;
+}