@rapidmx/web-client 0.5.0 → 0.7.0

package/dist/apps/shared/components/layout/AppShell.js

@@ -5,7 +5,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 ///////////////////////////////////////////////////////////////////////////////
 import "../../styles/app.css";
 import { useEffect, useRef, useState } from "react";
-import { HiOutlineCalendarDays, HiOutlineClipboardDocumentList, HiOutlineEnvelope, HiOutlineUsers } from "react-icons/hi2";
+import { HiOutlineCalendarDays, HiOutlineClipboardDocumentList, HiOutlineEnvelope, HiOutlinePuzzlePiece, HiOutlineUsers, } from "react-icons/hi2";
 import { useRedirectIfUnauthenticated } from "@rapidmx/react-shared/auth/session.js";
 import { getSetupStatus } from "@rapidmx/react-shared/admin/setupApi.js";
 import { stopImpersonating } from "@rapidmx/react-shared/mail/mailApi.js";
@@ -21,6 +21,7 @@ import { SIGN_OUT_CHANNEL, destroyAllLocalIndexes } from "../../search/localInde
 import { authApiFetch } from "@rapidmx/react-shared/util/api.js";
 import { destroyUnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
 import { clearPinnedSignerCache } from "../mail/pinnedSigners.js";
+import { mergePluginNavItems } from "../../plugins/pluginNav.js";
 /** How long sign-out waits for auth-server's logout before navigating anyway. */
 export const LOGOUT_TIMEOUT_MS = 3000;
 /**
@@ -50,15 +51,13 @@ export const APPS = [
     { id: "contacts", href: "/contacts", label: "Contacts", icon: HiOutlineUsers },
     { id: "tasks", href: "/tasks", label: "Tasks", icon: HiOutlineClipboardDocumentList },
 ];
-/** The header title for every valid `active` value — a superset of `APPS`' own labels since `"settings"`
- * has no rail icon (and so no `AppDef`) but still needs a header title. */
-const ACTIVE_LABELS = {
-    mail: "Mail",
-    calendar: "Calendar",
-    contacts: "Contacts",
-    tasks: "Tasks",
-    settings: "Settings",
-};
+/** Ids plugin `appRail` items can't take besides `APPS`' own - `"settings"` has no rail icon but is still a
+ * core `active` value. */
+const RESERVED_APP_IDS = ["settings"];
+/** `APPS` followed by the plugins' `appRail` items (generic icon), core ids winning - see `mergePluginNavItems`. */
+export function appRailItems(pluginNav) {
+    return mergePluginNavItems(APPS, pluginNav?.appRail, ({ id, href, label }) => ({ id, href, label, icon: HiOutlinePuzzlePiece }), RESERVED_APP_IDS);
+}
 /**
  * The persistent chrome shared by every webmail app (Mail, Calendar, Contacts, Tasks): a left icon rail for
  * switching apps (full page loads — see `MailShell`'s original doc comment on this framework having no
@@ -66,7 +65,7 @@ const ACTIVE_LABELS = {
  * Each app's own shell (e.g. `MailShell`) renders its own contextual sidebar + content as `children`, inside
  * the area to the right of the icon rail and below the header.
  */
-export default function AppShell({ active, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, children, }) {
+export default function AppShell({ active, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, children, }) {
     const [stoppingImpersonation, setStoppingImpersonation] = useState(false);
     const signingOutRef = useRef(false);
     const { branding, iconSrc } = useBranding();
@@ -155,10 +154,13 @@ export default function AppShell({ active, userUid, authServerUrl, impersonating
     if (!userUid) {
         return _jsx("div", { className: "min-h-screen" });
     }
-    return (_jsx(UnlockPromptProvider, { children: _jsx(ComposeProvider, { userUid: userUid, trusted: !!trusted && !impersonating, children: _jsxs("div", { className: "min-h-screen flex flex-col bg-surface-alt", children: [_jsx(BrandingHeader, { branding: branding }), impersonating && (_jsxs("div", { className: "h-10 shrink-0 bg-warning text-warning-contrast flex items-center justify-center gap-3 text-sm font-medium px-4", children: [_jsxs("span", { children: ["You are viewing as ", _jsx("strong", { children: userUid }), "."] }), _jsx("button", { type: "button", onClick: handleStopImpersonating, disabled: stoppingImpersonation, className: "underline hover:no-underline disabled:opacity-60", children: stoppingImpersonation ? "Returning to admin…" : "Return to admin" })] })), _jsxs("div", { className: "flex-1 flex min-h-0", children: [_jsxs("nav", { "aria-label": "Apps", className: "hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center py-3 gap-1", children: [_jsx("img", { src: iconSrc, width: "96", height: "96", alt: "", className: "mb-3" }), APPS.map(({ id, href, label, icon: Icon }) => (_jsx("a", { href: href, "aria-label": label, "aria-current": id === active ? "page" : undefined, title: label, className: [
+    const apps = appRailItems(pluginNav);
+    // The header title: "settings" has no rail item, everything else is labelled by its own rail item.
+    const activeLabel = active === "settings" ? "Settings" : apps.find((app) => app.id === active)?.label;
+    return (_jsx(UnlockPromptProvider, { children: _jsx(ComposeProvider, { userUid: userUid, trusted: !!trusted && !impersonating, children: _jsxs("div", { className: "min-h-screen flex flex-col bg-surface-alt", children: [_jsx(BrandingHeader, { branding: branding }), impersonating && (_jsxs("div", { className: "h-10 shrink-0 bg-warning text-warning-contrast flex items-center justify-center gap-3 text-sm font-medium px-4", children: [_jsxs("span", { children: ["You are viewing as ", _jsx("strong", { children: userUid }), "."] }), _jsx("button", { type: "button", onClick: handleStopImpersonating, disabled: stoppingImpersonation, className: "underline hover:no-underline disabled:opacity-60", children: stoppingImpersonation ? "Returning to admin…" : "Return to admin" })] })), _jsxs("div", { className: "flex-1 flex min-h-0", children: [_jsxs("nav", { "aria-label": "Apps", className: "hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center py-3 gap-1", children: [_jsx("img", { src: iconSrc, width: "96", height: "96", alt: "", className: "mb-3" }), apps.map(({ id, href, label, icon: Icon }) => (_jsx("a", { href: href, "aria-label": label, "aria-current": id === active ? "page" : undefined, title: label, className: [
                                             "w-10 h-10 flex items-center justify-center rounded-sm",
                                             id === active
                                                 ? "bg-primary/10 text-primary-dark"
                                                 : "text-text-muted hover:bg-surface-alt hover:text-text",
-                                        ].join(" "), children: _jsx(Icon, { size: 20, "aria-hidden": "true" }) }, id)))] }), _jsx(BottomTabBar, { apps: APPS, active: active }), _jsxs("div", { className: "flex-1 flex flex-col min-w-0", children: [_jsxs("header", { className: "h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-6", children: [_jsx("span", { className: "font-display font-bold text-lg uppercase tracking-wide", children: ACTIVE_LABELS[active] }), _jsx(UserMenu, { userUid: userUid, authServerUrl: authServerUrl, onSignOut: handleSignOut, showAdminLink: trusted, showSettingsLink: true })] }), _jsx("div", { className: "flex-1 flex min-h-0 pb-14 md:pb-0", children: children })] })] }), _jsx(BrandingFooter, { branding: branding })] }) }) }));
+                                        ].join(" "), children: _jsx(Icon, { size: 20, "aria-hidden": "true" }) }, id)))] }), _jsx(BottomTabBar, { apps: apps, active: active }), _jsxs("div", { className: "flex-1 flex flex-col min-w-0", children: [_jsxs("header", { className: "h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-6", children: [_jsx("span", { className: "font-display font-bold text-lg uppercase tracking-wide", children: activeLabel }), _jsx(UserMenu, { userUid: userUid, authServerUrl: authServerUrl, onSignOut: handleSignOut, showAdminLink: trusted, showSettingsLink: true })] }), _jsx("div", { className: "flex-1 flex min-h-0 pb-14 md:pb-0", children: children })] })] }), _jsx(BrandingFooter, { branding: branding })] }) }) }));
 }

package/dist/apps/shared/components/layout/BrandingChrome.d.ts

@@ -0,0 +1,18 @@
+import React from "react";
+import { Branding } from "@rapidmx/react-shared/branding/brandingApi.js";
+/**
+ * Sanitizes admin-configured branding HTML before it's rendered. The server sanitizes on save too; this also
+ * covers anything stored before that. Returns `""` where there's no DOM to sanitize with (server-side
+ * rendering), so unsanitized HTML is never emitted.
+ */
+export declare function sanitizeBrandingHtml(html: string): string;
+/**
+ * Renders the admin-configured `Branding.headerHtml`/`footerHtml` (see `useBranding()`), sanitized - shared by
+ * the webmail and admin chromes. The escrow console deliberately renders no branding HTML at all.
+ */
+export declare function BrandingHeader({ branding }: {
+    branding: Branding | null;
+}): React.JSX.Element;
+export declare function BrandingFooter({ branding }: {
+    branding: Branding | null;
+}): React.JSX.Element;

package/dist/apps/shared/components/layout/KeyEnrollmentGate.d.ts

@@ -0,0 +1,51 @@
+import React from "react";
+import { PublicKey } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+export interface KeyEnrollmentGateProps {
+    /** Undefined while the caller's mailbox hasn't resolved yet (or has none) - renders `children`
+     * unchanged in that case, so this component can be mounted unconditionally at a stable tree
+     * position (see this component's own doc comment for why that matters). */
+    mailboxUid?: string;
+    mailboxAddress?: string;
+    /** The mailbox's currently-published public keys (`Mailbox.keys`) - needed to unlock an
+     * already-enrolled vault (see `unlockWithPassword()`'s own signature), not just to provision a new
+     * one. Treated as empty when undefined - a mailbox with no public keys published yet has nothing to
+     * unlock, so this only affects the already-enrolled path. */
+    mailboxKeys?: PublicKey[];
+    /**
+     * `true` (default) preserves this component's original behavior: a mailbox with an existing vault
+     * but no unlocked session blocks `children` behind a full-page unlock form. Set to `false` for a
+     * mount point that shouldn't block merely because a mailbox resolved - `MailShell` does this, since
+     * unlocking is only actually required to sign/encrypt a compose, read an already-encrypted message,
+     * or change encryption settings (see `UnlockPromptProvider.tsx`'s `useUnlockPrompt()`, which those
+     * specific call sites use instead). Has no effect on first-time provisioning
+     * (`setup_password`/`enrolling`/`show_recovery_codes`), which still always blocks regardless - that
+     * only ever happens once per mailbox and is a genuine prerequisite, not the source of "unlock keeps
+     * popping up" friction this prop exists to avoid.
+     */
+    blocking?: boolean;
+    /**
+     * `true` when the caller may provision this mailbox's first encryption key - i.e. they own it and aren't
+     * an administrator impersonating them. `false` (default, so a caller that forgets it never provisions) for
+     * a shared/delegated mailbox the caller doesn't own, or an impersonated session: a mailbox with no vault yet then
+     * renders `children` instead of the "Protect your mailbox" setup, so a delegate never enrolls keys
+     * (and recovery codes) for someone else's mailbox. Unlocking an existing vault is unaffected.
+     */
+    canProvision?: boolean;
+    children: React.ReactNode;
+}
+/**
+ * Gates a mailbox's normal content behind one-time E2E encryption key setup, per
+ * `specs/end-to-end_encryption.md`'s "Generate signing and encryption keypairs on the client's device on
+ * first sign-in." Rendered by `MailShell` wrapping its own returned content unconditionally, not only
+ * once a mailbox is resolved — mounting this component at a *different* tree position depending on
+ * `mailboxUid`'s readiness (e.g. only wrapping once ready, rendering bare content beforehand) would make
+ * `children` (real `AppShell` chrome) itself remount the moment `mailboxUid` resolves, tearing down any
+ * state/effects it had already started. Always wrapping keeps `AppShell` mounted continuously across
+ * that transition; this component simply passes `children` through untouched while `mailboxUid` is
+ * still unresolved, and only starts its own check once a real `mailboxUid` is supplied.
+ *
+ * A `getKeyVault()` failure (network error, server not yet wired up to serve this endpoint) also renders
+ * `children` unchanged rather than blocking mail entirely - encryption is optional and gradual by design
+ * (the spec's own "near zero frictionless experience" goal), not a hard prerequisite for reading mail.
+ */
+export default function KeyEnrollmentGate({ mailboxUid, mailboxAddress, mailboxKeys, blocking, canProvision, children, }: KeyEnrollmentGateProps): React.JSX.Element | null;

package/dist/apps/shared/components/layout/MailboxProvisioning.d.ts

@@ -0,0 +1,13 @@
+import React from "react";
+/**
+ * Rendered by each app's shell (Mail/Calendar/Contacts/Tasks) *instead of* the normal `AppShell`
+ * chrome (icon rail, header, folder tree, ...) when the caller has no mailbox — a full-screen,
+ * 404-style takeover, not a small message nested inside the rest of the client UI, since there's
+ * nothing else in the app for a mailbox-less caller to do yet. Attempts self-service
+ * auto-provisioning — see `BaseMailboxRoute.autoProvision()`'s own doc comment in `@rapidmx/restapi`
+ * for the full contract — which is itself a no-op (a 404) unless an admin has both turned it on
+ * (`mail:auto_provision:enabled`) and configured at least one domain (`mail:domains`). Safe to render
+ * unconditionally in that place: any failure (disabled, no registered username, the identity service
+ * unreachable) just falls back to the same plain "no mailbox" message this replaces.
+ */
+export default function MailboxProvisioning(): React.JSX.Element;

package/dist/apps/shared/components/layout/RecoveryCodeUnlock.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Unlocking with a recovery code, and what has to happen after it. A recovery code is single-use: once it has opened
+ * the keys, the user may set a new encryption password (`replacePasswordWrap()`), and then the used code is removed
+ * (`consumeRecoveryCode()`). The order matters - react-shared's `replacePasswordWrap()` refuses unless another own
+ * unlock method remains, and the not-yet-consumed code is that method.
+ *
+ * `UnlockPromptProvider` and `KeyEnrollmentGate` both unlock with `startRecoveryUnlock()`, settle whatever was waiting
+ * on the unlock straight away, and then show `RecoveryFollowUpModal` for the follow-up steps.
+ */
+import React from "react";
+import { type PublicKey } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+/** The same minimum every other "set an encryption password" form in this app uses. */
+export declare const MIN_PASSWORD_LENGTH = 8;
+/** Where recovery codes are regenerated. */
+export declare const ENCRYPTION_SETTINGS_HREF = "/settings/encryption";
+/** Deliberately generic: a wrong code and a vault with no recovery codes fail the same way. */
+export declare const RECOVERY_CODE_ERROR = "That recovery code didn't work.";
+export declare const REPLACE_ROTATED_MESSAGE = "Your encryption keys were changed on another device after you unlocked, so your password wasn't changed and your recovery code wasn't used. Reload the page and unlock again.";
+export declare const REPLACE_MULTIPLE_PASSWORDS_MESSAGE = "This mailbox has more than one encryption password, so it can't be replaced here. Nothing was changed. Remove the extra password in Settings > Encryption first.";
+export declare const REPLACE_NO_OTHER_METHOD_MESSAGE = "Your password wasn't changed, because this mailbox would be left with no other way to unlock. Your recovery code may already have been used in another window. Nothing was changed.";
+export declare const REPLACE_ADD_FAILED_RESTORED_MESSAGE = "Your new password couldn't be saved, so your old password still works. Nothing was changed. Try again.";
+export declare const REPLACE_ADD_FAILED_NOT_RESTORED_MESSAGE = "Your new password couldn't be saved, and your old password couldn't be put back, so this mailbox has no password right now. Your recovery code still works. Try again, or keep the code for now.";
+export declare const REPLACE_LOCKED_MESSAGE = "Your encryption keys were locked before your new password could be set, so nothing was changed and your recovery code still works. Unlock with it again to set a new password.";
+export declare const REPLACE_GENERIC_MESSAGE = "Your new password couldn't be saved. Nothing was changed. Try again.";
+export declare const CONSUME_FAILED_MESSAGE = "The recovery code you used couldn't be removed, so it may still work. Regenerate your recovery codes in Settings > Encryption to make sure it can't be used again.";
+/** What a successful recovery-code unlock hands to `RecoveryFollowUpModal`. */
+export interface RecoveryFollowUp {
+    mailboxUid: string;
+    recoveryMethodId?: string;
+    /** The codes left once the used one is consumed. */
+    remainingRecoveryCodes: number;
+    /** The vault's generation read *before* the unlock - see `startRecoveryUnlock()`. */
+    expectedMasterKeyGeneration?: number;
+    unopenableKeys: string[];
+}
+/**
+ * Unlocks `mailboxUid` with a recovery code (normalized by react-shared, so spacing and case don't matter). The
+ * vault's `masterKeyGeneration` is read first: if another device rotates the master key at any point after that read,
+ * the generation passed to `replacePasswordWrap()` later is stale and the replacement is refused, never written with
+ * a dead master key. A failed read just means no generation check. Rejects exactly as `unlockWithRecoveryCode()` does.
+ */
+export declare function startRecoveryUnlock(mailboxUid: string, mailboxKeys: PublicKey[], code: string): Promise<RecoveryFollowUp>;
+/** A "use a recovery code instead" / "use your password instead" switch for an unlock form. */
+export declare function UnlockModeToggle({ mode, disabled, onChange, }: {
+    mode: "password" | "recovery";
+    disabled: boolean;
+    onChange: (mode: "password" | "recovery") => void;
+}): React.JSX.Element;
+export interface RecoveryFollowUpModalProps {
+    followUp: RecoveryFollowUp;
+    /** `false` hides the dialog without losing its progress (e.g. while another unlock dialog is on top). */
+    open?: boolean;
+    onDone: () => void;
+}
+/**
+ * The steps after a recovery-code unlock, shown once the keys are already open:
+ *
+ * 1. Offer a new encryption password. Optional ("Skip") - unless this was the last code, where it's required before the
+ * code is used up (otherwise only a forgotten password would remain); then "Keep this code for now" closes without
+ * consuming anything.
+ * 2. Remove the used code. A failure is reported but never blocks anything - the keys are already open.
+ * 3. Say how many codes are left, nudging towards regenerating them at two or fewer.
+ *
+ * Mount it with a `key` per follow-up so each unlock starts from step 1.
+ */
+export declare function RecoveryFollowUpModal({ followUp, open, onDone }: RecoveryFollowUpModalProps): React.JSX.Element;

package/dist/apps/shared/components/layout/UnlockPromptProvider.d.ts

@@ -0,0 +1,45 @@
+import React from "react";
+import { UnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
+import type { PublicKey } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+/** Shown instead of "Incorrect password" when the password was right but the mailbox's encryption key itself
+ * won't open (`UnopenableEncryptionKeyError`) - retrying can't fix that, so it must not read as a typo. */
+export declare const UNOPENABLE_ENCRYPTION_KEY_MESSAGE = "Your password is correct, but one of your keys couldn't be opened, so encrypted mail can't be read or sent from this mailbox. Trying again won't help - contact support.";
+/** `UNOPENABLE_ENCRYPTION_KEY_MESSAGE`'s counterpart for a recovery-code unlock. */
+export declare const UNOPENABLE_ENCRYPTION_KEY_RECOVERY_MESSAGE = "Your recovery code is correct, but one of your keys couldn't be opened, so encrypted mail can't be read or sent from this mailbox. Trying again won't help - contact support.";
+/** The error text for a failed `unlockWithPassword()` (or, with `method` `"recovery"`, `unlockWithRecoveryCode()`). */
+export declare function unlockErrorMessage(err: unknown, method?: "password" | "recovery"): string;
+/**
+ * A non-blocking notice after an unlock that succeeded without some signing keys (`UnlockResult.unopenableKeys`):
+ * mail can still be read, but not signed with those keys on this device.
+ */
+export declare function UnopenableKeysNotice({ fingerprints, onDismiss }: {
+    fingerprints: string[];
+    onDismiss: () => void;
+}): React.JSX.Element;
+interface UnlockPromptContextValue {
+    /**
+     * Resolves immediately with this mailbox's already-unlocked keys if it has any this session -
+     * showing no UI at all. Otherwise shows an unlock dialog on top of whatever the user is currently
+     * doing and resolves once they enter the correct password, or rejects if they dismiss it.
+     */
+    requestUnlock(mailboxUid: string, mailboxKeys: PublicKey[]): Promise<UnlockedKeys>;
+}
+/**
+ * The on-demand counterpart to `KeyEnrollmentGate`'s blocking, first-sign-in-only provisioning flow.
+ * Per `specs/end-to-end_encryption.md`, unlocking is only actually *required* to (1) sign or encrypt an
+ * outgoing message, (2) read an already-encrypted message, or (3) change encryption settings that touch
+ * the master key - not merely to have a mailbox with an existing vault resolve. Mounted once in
+ * `AppShell.tsx` (shared by every top-level app shell: Mail, Calendar, Contacts, Tasks, Settings), so
+ * any of those three call sites (`ComposeWindow`'s sign/encrypt toggles, `MessageDetailPane`'s encrypted-
+ * message view, `Settings > Encryption`) can request an unlock right where it's needed via
+ * `useUnlockPrompt()`, instead of the whole app being blocked behind an unlock screen the moment a
+ * mailbox happens to resolve - see `KeyEnrollmentGate`'s `blocking` prop, which `MailShell` now sets to
+ * `false` for exactly this reason.
+ */
+export declare function UnlockPromptProvider({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** Throws outside an `<UnlockPromptProvider>` - every app shell mounts one (see `AppShell.tsx`), so
+ * reaching this from any real page is a wiring bug, not a runtime condition to degrade gracefully from. */
+export declare function useUnlockPrompt(): UnlockPromptContextValue;
+export {};

package/dist/apps/shared/components/layout/UserMenu.d.ts

@@ -0,0 +1,23 @@
+import React from "react";
+export interface UserMenuProps {
+    userUid: string;
+    /** auth-server's base URL — where the caller's own profile (name/avatar) is fetched from, if configured. */
+    authServerUrl?: string;
+    onSignOut: () => void;
+    /** Shows an "Admin" item linking to `/admin`, above "Sign Out" — pass only for a trusted-role caller. */
+    showAdminLink?: boolean;
+    /** Shows a "Settings" item, above "Admin"/"Sign Out" — an account-scoped surface (like "Admin"), not
+     * a content-scoped one, so it lives here rather than as a 5th `AppShell` rail icon. Links straight to
+     * `/settings/auto-reply`, the only settings section that exists today; repoint this at a real
+     * `/settings` landing page once a second section (Mail Filters, Signatures) makes one worth building. */
+    showSettingsLink?: boolean;
+}
+/**
+ * The top-right "who am I" menu shared by `MailShell` and `AdminShell`: an avatar-button trigger that opens a
+ * dropdown showing the caller's avatar/name, an optional "Admin" link (trusted-role callers only), and
+ * "Sign Out". Name/avatar come from auth-server's own profile endpoint (`GET /api/profiles/me`) — this
+ * service has no local user directory (see `.claude/NOTES.md`) — and fall back to the bare uid/its first
+ * letter when unset or unreachable, which is a fully valid, expected state for most password-registered
+ * accounts (only OIDC sign-in currently populates a real avatar).
+ */
+export default function UserMenu({ userUid, authServerUrl, onSignOut, showAdminLink, showSettingsLink }: UserMenuProps): React.JSX.Element;

package/dist/apps/shared/components/mail/ConversationList.d.ts

@@ -0,0 +1,47 @@
+import React from "react";
+import { Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import { ConversationSummary } from "@rapidmx/react-shared/mail/conversationsApi.js";
+export interface ConversationListProps {
+    conversations: ConversationSummary[];
+    /** The mailbox the conversations were listed from - `listConversationMessages()` is mailbox-scoped. */
+    mailboxUid: string;
+    /** The message currently open in the reading pane, so the row standing for it can be marked. */
+    selectedUid: string | null;
+    /**
+     * Opens a conversation in the reading pane, positioned at one of its messages: the one a child row
+     * stands for, or the conversation's own `latestMessageUid` for a parent row. The conversation goes
+     * with the uid because the pane shows the whole thread, not just that message.
+     */
+    onOpenMessage: (conversation: ConversationSummary, uid: string) => void;
+    /** Newer copies of messages this list already fetched - the reading pane marks the message it opens as
+     * read, which this list would otherwise keep showing as unread until the thread is collapsed and
+     * expanded again. */
+    messageOverrides?: Record<string, Message>;
+    /** Turns each parent row into a checkbox row: select mode here ticks whole conversations, since a
+     * conversation is what this list's rows are. A child row stays a plain "open this message" button - a
+     * mixed conversation/message selection has no sensible bulk semantics (see `MailListToolbar`). */
+    selectMode?: boolean;
+    /** The `conversationId`s currently ticked. */
+    selectedConversationIds?: Set<string>;
+    onToggleSelected?: (conversation: ConversationSummary) => void;
+    /**
+     * Whether a conversation's own messages read newest first, matching the order sense the rows themselves
+     * are in ("Newest on top"). `listConversationMessages()` always answers oldest first - the order a
+     * thread is read in - so this reverses that copy for display rather than asking for it differently.
+     */
+    newestFirst?: boolean;
+}
+/**
+ * The nested, Outlook-style conversation list: one parent row per conversation - its participants, subject,
+ * message count, unread count, flag/attachment hints and the latest message's preview - expanding via its
+ * own chevron into the conversation's individual messages as child rows, fetched on first expand with
+ * `listConversationMessages()` (one request for the whole thread, across folders, oldest first).
+ *
+ * Opening a row opens the whole conversation in `ConversationThreadPane`, positioned at the message the row
+ * stands for: the latest one for a parent row, that one for a child row.
+ *
+ * The chevron is a button of its own beside the row's own button rather than inside it (a button can't
+ * nest inside a button), so expanding and opening are separately reachable by keyboard and each carries
+ * its own name.
+ */
+export default function ConversationList({ conversations, mailboxUid, selectedUid, onOpenMessage, messageOverrides, selectMode, selectedConversationIds, onToggleSelected, newestFirst, }: ConversationListProps): React.JSX.Element;

package/dist/apps/shared/components/mail/ConversationList.js

@@ -1,17 +1,91 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/** The "By conversation" counterpart to the per-message list `apps/www/index.tsx` renders inline for
- * "By date" — conversations are mailbox-wide (see `conversationsApi.ts`), so there's no per-folder
- * empty/loading state to distinguish here beyond what the page itself already handles. */
-export default function ConversationList({ conversations, selectedId, onSelect }) {
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useState } from "react";
+import { HiChevronDown, HiChevronRight, HiOutlineFlag, HiOutlinePaperClip } from "react-icons/hi2";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { listConversationMessages } from "@rapidmx/react-shared/mail/conversationsApi.js";
+function participantNames(conversation) {
+    return conversation.participants.map((participant) => participant.displayName || participant.address).join(", ");
+}
+/**
+ * The nested, Outlook-style conversation list: one parent row per conversation - its participants, subject,
+ * message count, unread count, flag/attachment hints and the latest message's preview - expanding via its
+ * own chevron into the conversation's individual messages as child rows, fetched on first expand with
+ * `listConversationMessages()` (one request for the whole thread, across folders, oldest first).
+ *
+ * Opening a row opens the whole conversation in `ConversationThreadPane`, positioned at the message the row
+ * stands for: the latest one for a parent row, that one for a child row.
+ *
+ * The chevron is a button of its own beside the row's own button rather than inside it (a button can't
+ * nest inside a button), so expanding and opening are separately reachable by keyboard and each carries
+ * its own name.
+ */
+export default function ConversationList({ conversations, mailboxUid, selectedUid, onOpenMessage, messageOverrides, selectMode, selectedConversationIds, onToggleSelected, newestFirst, }) {
+    const [expanded, setExpanded] = useState(new Set());
+    const [messagesById, setMessagesById] = useState({});
+    const [loadingIds, setLoadingIds] = useState(new Set());
+    const [errorsById, setErrorsById] = useState({});
+    function toggle(conversation) {
+        const id = conversation.conversationId;
+        setExpanded((prev) => {
+            const next = new Set(prev);
+            if (next.has(id)) {
+                next.delete(id);
+            }
+            else {
+                next.add(id);
+            }
+            return next;
+        });
+        if (expanded.has(id) || messagesById[id] || loadingIds.has(id)) {
+            return;
+        }
+        setLoadingIds((prev) => new Set(prev).add(id));
+        setErrorsById((prev) => {
+            const next = { ...prev };
+            delete next[id];
+            return next;
+        });
+        listConversationMessages(mailboxUid, id)
+            .then((loaded) => setMessagesById((prev) => ({ ...prev, [id]: loaded })))
+            .catch((err) => setErrorsById((prev) => ({
+            ...prev,
+            [id]: err instanceof ApiRequestError ? err.message : "Could not load this conversation's messages.",
+        })))
+            .finally(() => setLoadingIds((prev) => {
+            const next = new Set(prev);
+            next.delete(id);
+            return next;
+        }));
+    }
     if (conversations.length === 0) {
-        return _jsx("p", { className: "p-4 text-sm text-text-muted", children: "No conversations in this mailbox." });
+        return _jsx("p", { className: "p-4 text-sm text-text-muted", children: "No conversations in this folder." });
     }
     return (_jsx("ul", { children: conversations.map((conversation) => {
+            const id = conversation.conversationId;
+            const isExpanded = expanded.has(id);
             const unread = conversation.unreadCount > 0;
-            return (_jsx("li", { children: _jsxs("button", { type: "button", onClick: () => onSelect(conversation), className: [
-                        "w-full text-left px-4 py-3 border-b border-border",
-                        conversation.conversationId === selectedId ? "bg-primary/10" : "hover:bg-surface-alt",
-                        unread ? "font-semibold" : "",
-                    ].join(" "), children: [_jsxs("div", { className: "flex items-center justify-between gap-2 text-sm", children: [_jsx("span", { className: "truncate", children: conversation.participants.map((p) => p.displayName || p.address).join(", ") }), _jsx("span", { className: "text-xs text-text-muted shrink-0", children: new Date(conversation.latestDate).toLocaleDateString() })] }), _jsx("div", { className: "text-sm truncate", children: conversation.subject || "(no subject)" }), _jsxs("div", { className: "flex items-center gap-2 mt-1 text-xs text-text-muted font-normal", children: [conversation.messageCount > 1 && _jsxs("span", { children: [conversation.messageCount, " messages"] }), unread && (_jsxs("span", { className: "py-0.5 px-2 rounded-pill bg-primary/10 text-primary-dark font-semibold", children: [conversation.unreadCount, " unread"] })), conversation.hasAttachments && _jsx("span", { "aria-label": "Has attachments", children: "\uD83D\uDCCE" })] })] }) }, conversation.conversationId));
+            const loaded = messagesById[id];
+            // `listConversationMessages()` answers oldest first; the rows read in whichever sense the
+            // list itself is arranged in. Copied before reversing - the fetched array is cached.
+            const children = loaded && newestFirst ? [...loaded].reverse() : loaded;
+            const panelId = `conversation-messages-${id}`;
+            const ticked = selectedConversationIds?.has(id) ?? false;
+            return (_jsxs("li", { children: [_jsxs("div", { className: [
+                            "flex items-stretch border-b border-border",
+                            conversation.latestMessageUid === selectedUid || ticked
+                                ? "bg-primary/10"
+                                : "hover:bg-surface-alt",
+                        ].join(" "), children: [selectMode && (_jsx("span", { className: "shrink-0 flex items-center pl-3", children: _jsx("input", { type: "checkbox", checked: ticked, onChange: () => onToggleSelected?.(conversation), "aria-label": `Select conversation: ${conversation.subject || "(no subject)"}`, className: "w-4 h-4 accent-primary" }) })), _jsx("button", { type: "button", onClick: () => toggle(conversation), "aria-expanded": isExpanded, "aria-controls": panelId, "aria-label": `${isExpanded ? "Collapse" : "Expand"} conversation: ${conversation.subject || "(no subject)"}`, className: "shrink-0 px-2 text-text-muted hover:text-text", children: isExpanded ? (_jsx(HiChevronDown, { size: 16, "aria-hidden": "true" })) : (_jsx(HiChevronRight, { size: 16, "aria-hidden": "true" })) }), _jsxs("button", { type: "button", onClick: () => onOpenMessage(conversation, conversation.latestMessageUid), className: ["flex-1 min-w-0 text-left pr-4 py-3", unread ? "font-semibold" : ""].join(" "), children: [_jsxs("div", { className: "flex items-center justify-between gap-2 text-sm", children: [_jsx("span", { className: "truncate", children: participantNames(conversation) }), _jsx("span", { className: "text-xs text-text-muted shrink-0", children: new Date(conversation.latestDate).toLocaleDateString() })] }), _jsx("div", { className: "text-sm truncate", children: conversation.subject || "(no subject)" }), _jsx("div", { className: "text-xs text-text-muted truncate font-normal", children: conversation.latestPreview }), _jsxs("div", { className: "flex items-center gap-2 mt-1 text-xs text-text-muted font-normal", children: [conversation.messageCount > 1 && _jsxs("span", { children: [conversation.messageCount, " messages"] }), unread && conversation.messageCount > 1 && (_jsxs("span", { className: "py-0.5 px-2 rounded-pill bg-primary/10 text-primary-dark font-semibold", children: [conversation.unreadCount, " unread"] })), conversation.hasAttachments && (_jsx(HiOutlinePaperClip, { size: 13, "aria-label": "Has attachments" })), conversation.flagged && (_jsx(HiOutlineFlag, { size: 13, "aria-label": "Flagged", className: "text-danger" }))] })] })] }), _jsxs("ul", { id: panelId, hidden: !isExpanded, children: [errorsById[id] && (_jsx("li", { role: "alert", className: "pl-8 pr-4 py-2 text-xs text-danger border-b border-border", children: errorsById[id] })), loadingIds.has(id) && (_jsx("li", { className: "pl-8 pr-4 py-2 text-xs text-text-muted border-b border-border", children: "Loading messages\u2026" })), children?.map((fetched) => {
+                                const message = messageOverrides?.[fetched.uid] ?? fetched;
+                                return (_jsx("li", { children: _jsxs("button", { type: "button", onClick: () => onOpenMessage(conversation, message.uid), className: [
+                                            "w-full text-left pl-8 pr-4 py-2 border-b border-border",
+                                            message.uid === selectedUid ? "bg-primary/10" : "hover:bg-surface-alt",
+                                            message.flags.read ? "" : "font-semibold",
+                                        ].join(" "), children: [_jsxs("div", { className: "flex items-center justify-between gap-2 text-sm", children: [_jsx("span", { className: "truncate", children: message.from.displayName || message.from.address }), _jsx("span", { className: "text-xs text-text-muted shrink-0", children: new Date(message.receivedDate).toLocaleDateString() })] }), _jsxs("div", { className: "flex items-center gap-2 text-xs text-text-muted font-normal", children: [_jsx("span", { className: "truncate", children: message.bodyPreview }), message.hasAttachments && (_jsx(HiOutlinePaperClip, { size: 12, "aria-label": "Has attachments" })), message.flags.flagged && (_jsx(HiOutlineFlag, { size: 12, "aria-label": "Flagged", className: "text-danger" }))] })] }) }, message.uid));
+                            })] })] }, id));
         }) }));
 }

package/dist/apps/shared/components/mail/ConversationThreadPane.d.ts

@@ -0,0 +1,62 @@
+import React from "react";
+import { Folder, Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import { ConversationSummary } from "@rapidmx/react-shared/mail/conversationsApi.js";
+import { Label } from "@rapidmx/react-shared/mail/labelsApi.js";
+/** One request's worth of the thread. The server's own default for `listConversationMessages()`. */
+export declare const THREAD_PAGE_SIZE = 100;
+/**
+ * How many of a conversation's messages this pane will load. The server reads at most
+ * `CONVERSATION_SCAN_LIMIT` (500) messages when it groups conversations, so a `ConversationSummary` never
+ * describes more than this many anyway; the cap is here so a thread that somehow reports more can't turn
+ * into an unbounded run of requests. Past it the pane says so and the rest stay readable from the list.
+ */
+export declare const THREAD_MESSAGE_LIMIT = 500;
+export interface ConversationThreadPaneProps {
+    conversation: ConversationSummary | null;
+    /** The mailbox the conversation was listed from - `listConversationMessages()` is mailbox-scoped. */
+    mailboxUid: string;
+    /**
+     * The message the reader opened: the thread is scrolled to it, it takes focus, and it is the *oldest*
+     * message left expanded (see `expandedFrom()`). `null`, or a uid this thread doesn't hold, falls back
+     * to the newest message - which is also what a parent row means by "open the conversation".
+     */
+    selectedUid: string | null;
+    /** The mailbox's full folder list. A conversation spans folders (an Inbox message and the Sent Items
+     * copy of its reply), so each message's own folder type is looked up against its own `folderUid`. */
+    folders: Folder[];
+    /** The mailbox's labels, passed through to every expanded message's own `MessageDetailPane`. */
+    labels?: Label[];
+    /**
+     * A newer copy of one of the thread's messages - read, flagged, labelled, classified, recalled - for
+     * the caller's own list to stay in step with what was done in here.
+     *
+     * `previous` is the copy this pane held before the change, where it has one: the conversation row this
+     * thread came from is a *summary* (a message count, an unread count), so a list showing those rows has
+     * no way to tell "this message has just been read" from "this already-read message was relabelled"
+     * without it - which is what left a row reporting "2 unread" after both had been read.
+     */
+    onMessagePatched: (updated: Message, previous?: Message) => void;
+    /** A message that left the folder being listed (archived, or a scheduled send sent back to Drafts). */
+    onMessageRemoved: (updated: Message) => void;
+    onLabelCreated?: (label: Label) => void;
+    /** A folder created from a message's own Move to prompt, for the folder sidebar to pick up. */
+    onFolderCreated?: (folder: Folder) => void;
+}
+/**
+ * The reading pane for the conversation list: the whole thread, **newest at the top**, opened at the message
+ * the reader picked. Every message from that one through to the newest is expanded - which in this order is
+ * the opened message and the entries above it - and the older ones, below it, are collapsed to a one-line
+ * summary (sender, date, preview) that expands on click or Enter. So opening the newest message shows just
+ * the top entry expanded, and opening 5 of 10 expands 10 down to 5.
+ *
+ * Newest first regardless of how the *list* is sorted: the list's own order arranges rows to pick from,
+ * while this is one conversation being read, and the entry a conversation row stands for - its latest
+ * message - is the one that should be at the top of the pane every time it is opened.
+ *
+ * Each *expanded* message is a `MessageDetailPane` of its own rather than a reimplementation of it, so the
+ * signature and verification badges, the verification-seal and decryption behaviour, the labels chips and
+ * menu, the attachments and Reply/Reply All/Forward/Archive all behave exactly as they do in the
+ * single-message pane, and each acts on the message it belongs to. A collapsed message mounts none of
+ * that - mounting a body iframe per message up front would be wasteful in a long thread.
+ */
+export default function ConversationThreadPane({ conversation, mailboxUid, selectedUid, folders, labels, onMessagePatched, onMessageRemoved, onLabelCreated, onFolderCreated, }: ConversationThreadPaneProps): React.JSX.Element;