@bobfrankston/rmfmail 1.2.6 → 1.2.8

package/packages/mailx-settings/docs/clean-architecture.md

@@ -0,0 +1,161 @@
+# rmfmail / mailx — Target Architecture & Migration Plan
+
+**Date:** 2026-06-12
+**Goal:** Thunderbird/Outlook-grade reliability without a green-field rewrite. Re-architect the **core data + sync layer**; keep the existing UI and feature surface and migrate it onto the new core in shippable, reversible phases.
+**Companion:** `architecture-review.md` (the diagnosis this design answers).
+
+---
+
+## 1. The two principles that make mail clients reliable
+
+Every reliable mail client (Thunderbird's global DB / "Panorama", Outlook's OST, Apple Mail's Envelope Index) obeys these:
+
+1. **The display layer never blocks on the network.** A local store (a database) is the single source of truth for *everything the user sees and does*. Opening a folder, reading a message, searching, deleting — all are local operations that complete instantly. The network is a **separate, fully asynchronous background engine** that reconciles the store with the server. A dead/slow server makes mail *stale*, never makes the UI *freeze*.
+
+2. **One canonical store, one stable identity, one path per operation.** A message has one durable local identity that survives folder moves and server UID renumbering. Each operation (delete, move, flag) has exactly one implementation that mutates the store and queues a server action. There are no parallel code paths to drift.
+
+rmfmail violates both today (see review §3, §6). This design restores both.
+
+---
+
+## 2. Three layers, strictly separated
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  UI (client/)                                                │
+│  • reads: pure store queries (instant, never await network)  │
+│  • writes: call Store mutation → optimistic local change     │
+│            + enqueue server action; return immediately       │
+│  • re-renders from Store change events                       │
+└───────────────▲───────────────────────────┬─────────────────┘
+                │ store events               │ read / mutate (local only)
+┌───────────────┴───────────────────────────▼─────────────────┐
+│  STORE  (the source of truth for display)                    │
+│  • SQLite. Stable message identity = local UUID.             │
+│  • Pure, synchronous, network-free read API.                 │
+│  • Mutation funnel: trash/move/flag/copy/deletePermanent —   │
+│    one function each, keyed by UUID. Each = local change +    │
+│    durable queued action + change event.                     │
+│  • Durable action queue (idempotent, UUID-keyed).            │
+└───────────────▲───────────────────────────┬─────────────────┘
+                │ "here is new/changed data" │ "drain these actions"
+┌───────────────┴───────────────────────────▼─────────────────┐
+│  SYNC ENGINE  (the ONLY thing that touches the network)      │
+│  • Owns all IMAP/Gmail connections, fully isolated.          │
+│  • PULL: incremental fetch (QRESYNC/CONDSTORE → set-diff).   │
+│  • PUSH: drain the action queue to the server, idempotently. │
+│  • RECONCILE: re-bind identity across UID changes by         │
+│    Message-ID / UUID. Maintain (folder,uid,uidvalidity) map. │
+│  • Bounded connections, per-op timeout + cancellation,       │
+│    backoff, poison-action cap. A hung op affects ONLY here.  │
+└──────────────────────────────────────────────────────────────┘
+```
+
+The hard rule: **an arrow never points "up-and-blocking."** The UI calls into the Store and returns; it never awaits the Sync Engine. The Sync Engine pushes results down into the Store and the Store emits events up to the UI. There is no path where a network stall can sit inside a UI read.
+
+---
+
+## 3. Identity (fixes review §5 — the reappear/ghost/wipe class)
+
+- Every message gets a **stable local `id` (UUID)** at first sight.
+- The identity key is **Message-ID** when present; otherwise a synthesized stable hash of `(account, internaldate, from, subject, size)`. This guarantees an identity even for malformed / Message-ID-less mail (the gap that breaks re-binding today).
+- `(folder, server_uid, uidvalidity)` is **transient routing metadata**, owned and maintained only by the Sync Engine, in a `message_locations` table. **Nothing in the UI or Store mutations is ever keyed on a bare `uid`.**
+- Multi-folder membership (Gmail labels, or a message genuinely in two folders) is N rows in `message_locations` pointing at one message UUID.
+- Server-side UID renumber (move, UIDVALIDITY bump) re-binds the location row to the same UUID by Message-ID match — never creates a new identity, never orphans the body.
+
+**Consequence:** the 70k-row wipe (a `WHERE uid=?` that hit every folder) becomes structurally impossible — there is no UID-only delete. Cross-folder collisions, stars-on-wrong-rows, ghosts, wrong-row-on-auto-advance all dissolve because UID is no longer identity.
+
+---
+
+## 4. Mutation funnel (fixes review §6 — "every fix breaks another path")
+
+The Store exposes exactly these mutators, each taking message UUIDs:
+
+```
+store.trash(uuids)            // move to Trash, or permanent-expunge if already in Trash
+store.move(uuids, toFolder)
+store.copy(uuids, toFolder)
+store.flag(uuids, flag, on)
+store.deletePermanent(uuids)
+store.markRead(uuids, on)
+```
+
+Each does, atomically: **(1)** update local rows + folder counts, **(2)** record an undo entry, **(3)** enqueue a durable, idempotent server action keyed by UUID, **(4)** emit a change event.
+
+- **Every** UI trigger (Delete key, toolbar, drag, right-drag menu, context menu, pop-out, undo) calls these and nothing else. No optimistic-removal logic scattered in the UI; the UI just re-renders from the change event.
+- `emptyFolder` becomes `store.deletePermanent(all-uuids-in-folder)` — same funnel, not a separate IMAP loop.
+- **Delete `packages/mailx-core`** (dead duplicate).
+- **Android shares this exact Store + queue.** The only platform difference is the `Transport` the Sync Engine injects (Node TCP vs bridge). No second `trashMessage`.
+
+---
+
+## 5. Read path & dispatch isolation (fixes review §1/§2 — the timeouts you're hitting now)
+
+- All reads — `listFolder`, `unifiedInbox`, `getMessage`, `search` — are **pure synchronous SQLite** behind a single read facade. They **cannot** call the network. `getMessage` returns the cached body if present, else `{cached:false}` and the UI shows a placeholder while the Sync Engine fetches and emits `bodyReady`. A read **can never time out.**
+- The IPC dispatch (`bin/mailx.ts`) must not serialize a read behind a network write. Two concrete options (pick after measuring):
+  - **(A)** Run the Sync Engine's network work off the dispatch thread (worker), so `dispatch()` only ever does fast local work.
+  - **(B)** Split dispatch into a read lane (own SQLite read handle, always-fast) and a write/command lane; reads are answered immediately regardless of what the write lane is doing.
+- Network handlers get a hard wall-clock timeout + cancellation; a hung op is abandoned and its connection discarded, never occupying a shared slot. (The `withTimeout`/dual-lane machinery already exists in `mailx-imap` — it just needs to be *above* nothing that a read depends on.)
+
+**Consequence:** `getUnifiedInbox` (and every list/read) returns instantly even while the server is hung. The "nothing in the summary" / `mailxapi timeout` failure class is gone by construction.
+
+---
+
+## 6. Sync Engine robustness (the part that earns "Thunderbird-grade")
+
+- **Connection discipline:** per-account budget with a **dedicated interactive connection** that background sync/prefetch can never starve. Per-host semaphore stays as the server-cap guard.
+- **Every op:** wall-clock timeout + cancellation; on timeout, discard the connection and back off. A single un-fetchable message (today's 4966060) is recorded with backoff and never re-attempted in a tight loop.
+- **Push queue:** durable, idempotent, UUID-keyed actions; retry with backoff; a **poison cap** (give up after N, surface to the UI) so one bad action can't loop forever.
+- **Pull:** capability-gated incremental sync — QRESYNC/CONDSTORE when the server advertises them, UID set-diff fallback otherwise; persist per-folder `UIDVALIDITY` + `HIGHESTMODSEQ`. (Memory note: capability-gate, don't hostname-branch.)
+- **Reconcile:** the only place that re-binds UID↔UUID; tombstones with retained UUID suppress re-fetch of locally-deleted mail; UIDVALIDITY bump triggers a clean re-map, not a wipe.
+
+---
+
+## 7. Migration plan — phased, shippable, reversible (NOT big-bang)
+
+Each phase ships on its own, is independently verifiable, and can be reverted. We do **not** rewrite the UI or the features.
+
+**Phase 0 — Read isolation (do first; ends the timeouts).**
+- Guarantee every read RPC is network-free and cannot be head-of-line-blocked. Implement §5 option A or B in `bin/mailx.ts` + the service read methods. Add hard timeouts/cancellation to network handlers.
+- *Exit test:* with the IMAP server artificially hung, the list, folder switch, search, and cached-message open all still respond instantly. No `mailxapi timeout` on any read.
+
+**Phase 1 — Identity + mutation funnel.**
+- Introduce/standardize the UUID identity and `message_locations`; backfill UUIDs (rebuild-from-server is acceptable per the "no migrations, redownload" rule).
+- Route all deletes/moves/flags through the §4 funnel; delete `mailx-core`; converge `emptyFolder`.
+- *Exit test:* a scripted scenario with the same numeric UID in INBOX + Trash + Sent — delete/flag/move one and confirm the others are untouched. No ghost rows after a move+delete cycle.
+
+**Phase 2 — Sync Engine extraction.**
+- Make the Sync Engine the sole network owner with §6 discipline; move cross-account move and outbox under it. Dedicated interactive lane.
+- *Exit test:* hung-folder fault injection — background sync stalls, interactive open/delete stay responsive; poison action gives up instead of looping.
+
+**Phase 3 — Search unification + Android convergence.**
+- One query parser feeding the (local-FTS / server-IMAP) executors. Android uses the shared Store + queue + a `Transport`.
+- *Exit test:* identical query semantics across scopes; Android delete sets the same pending/tombstone state as desktop.
+
+Order rationale: Phase 0 stops the bleeding you're seeing *right now*; Phase 1 removes the data-integrity class (the scary one — the wipe); Phases 2–3 are robustness + cleanup.
+
+---
+
+## 8. What we explicitly do NOT do
+
+- No green-field rewrite. The UI, compose/editor, providers, OAuth, calendar/tasks, Android shell, and the feature set stay.
+- No big-bang cutover. Each phase coexists with the rest.
+- No hot-patching the live daemon during this work — changes land, get built, and are verified deliberately (the firefighting pattern is over).
+
+---
+
+## 9. How we'll verify reliability (the Thunderbird bar)
+
+A short fault-injection harness, run after each phase:
+1. **Server hung** (stall `BODY[]` / SELECT): UI reads stay instant; no timeouts.
+2. **Server slow** (5s/op): actions queue and drain; UI never blocks.
+3. **Offline → online:** queued actions drain in order, idempotently; no dupes, no loss.
+4. **UID collision** across folders: per-message ops never hit the wrong message.
+5. **UIDVALIDITY bump:** re-map, no wipe.
+6. **Crash mid-action:** durable queue resumes; nothing lost, nothing double-applied.
+
+When all six pass under injection, we're at the reliability bar you're asking for.
+
+---
+
+*This is the target. Phase 0 is the next concrete step and is self-contained.*

package/packages/mailx-settings/docs/outlook.md

@@ -0,0 +1,215 @@
+# Outlook.com / Microsoft 365 Support
+
+Status (2026-06-05): **scaffolding present, not usable.** An account auto-detects
+the right hosts but cannot authenticate — there is no Microsoft OAuth wired, and
+Microsoft has disabled basic-auth (password) for outlook.com / office365, so the
+IMAP path can't fall back to a password either. Gmail is the only fully-wired
+OAuth provider today.
+
+This doc scopes what it takes to make Outlook a first-class account.
+
+---
+
+## What already exists
+
+| Piece | Where | State |
+|---|---|---|
+| Graph API provider | `@bobfrankston/mailx-sync/outlook.ts` (re-exported `packages/mailx-imap/providers/outlook-api.ts`) | **Read-only**: `listFolders`, `fetchSince/ByDate/ByUids/One`, `getUids`. No send, no write-back, no drafts/attachments. |
+| Host auto-config | `packages/mailx-settings/index.ts:503` (`outlook.com`, `hotmail.com` → `outlook.office365.com:993` / `smtp.office365.com:587`, `auth: "oauth2"`) | Done |
+| MX-based detection | `bin/mailx.ts:1307` (`*.outlook.com` / `*.protection.outlook.com` MX → Microsoft 365) | Done |
+| Generic OAuth flow | `@bobfrankston/oauthsupport` `OAuthTokenManager.ts:369` — validates `client_id/client_secret/auth_uri/token_uri` from the creds file; localhost loopback auth-code flow | **Provider-agnostic** — not Google-specific |
+| OAuth SMTP send | `packages/mailx-imap/index.ts:1533` builds `{type:"OAuth2", user, accessToken}` from `config.tokenProvider()` | Works for any provider with a tokenProvider |
+
+The single thing that makes Gmail work and Outlook not: the **tokenProvider** at
+`packages/mailx-imap/index.ts:798-848` is built only for Google. It hardcodes the
+Google credentials file (`~/.mailx/google-credentials.json`) and the all-Google
+scope string. Nothing constructs a Microsoft tokenProvider, so
+`OutlookApiProvider` is never instantiated and the office365 IMAP host has no
+token to present.
+
+---
+
+## Decision: Graph API vs IMAP/XOAUTH2
+
+Both need the same Azure app registration + Microsoft OAuth. The difference is
+the sync transport once you have a token.
+
+**Recommended: Graph API.** It mirrors the Gmail-API model the codebase already
+follows (`isGmailAccount()` branch → REST provider, no IMAP client). Wins: no
+connection-limit/timeout class of bugs (the entire `inactivityTimeout` /
+`greetingTimeout` / chunk-size tuning at `index.ts:862` is IMAP-only pain);
+provider is already half-written; same `MailProvider` interface so Android reuses
+it verbatim. Cost: the provider is read-only — send + flag/move/delete + drafts
+must be added (Graph endpoints, ~a day). Sharp edge: `idToUid()`
+(`outlook.ts` ~135) hashes Graph's long string IDs to 48-bit ints, and
+`fetchByUids`/`fetchOne` re-list the **whole** folder then filter — O(folder) per
+fetch with collision risk. Real sync needs a UID↔providerId map (we already keep
+`provider_id` in the DB) and direct `GET /messages/{id}` instead of list-and-scan.
+
+**Alternative: IMAP + XOAUTH2.** Reuses the existing iflow-direct sync path
+unchanged — just feed it a Microsoft token instead of a Google one. Wins: zero
+new sync/send code; flag/move/delete/append already work over IMAP. Cost:
+inherits every IMAP fragility we've spent months hardening for Dovecot/Gmail, now
+against Exchange Online's quirks. Sharp edge: Microsoft is steering third-party
+clients toward Graph and away from consumer IMAP; betting the integration on
+office365 IMAP is the less future-proof path.
+
+Pragmatic call: **IMAP/XOAUTH2 first** as the fast path to a working account (it's
+mostly OAuth plumbing), then migrate sync to Graph for parity with Gmail. The
+OAuth work below is shared, so it's not wasted either way.
+
+---
+
+## Work breakdown
+
+### 1. Azure app registration  [S, one-time, external]
+Register an app in Entra/Azure AD:
+- Account type: "personal Microsoft accounts" (consumer outlook.com) and/or
+  "any org directory" (Microsoft 365). For both, use the `/common` authority.
+- Redirect URI: `http://localhost` (loopback) — matches oauthsupport's flow
+  (`OAuthTokenManager.ts:463`, parses the loopback callback).
+- API permissions (delegated):
+    - Graph path: `Mail.ReadWrite`, `Mail.Send`, `offline_access`, `openid`,
+      `profile`.
+    - IMAP path: `https://outlook.office.com/IMAP.AccessAsUser.All`,
+      `https://outlook.office.com/SMTP.Send`, `offline_access`.
+- Produce a `microsoft-credentials.json` shaped like the Google one, with
+  `auth_uri: https://login.microsoftonline.com/common/oauth2/v2.0/authorize`,
+  `token_uri: https://login.microsoftonline.com/common/oauth2/v2.0/token`,
+  `redirect_uris: ["http://localhost"]`, plus `client_id` / `client_secret`.
+
+Store at `~/.mailx/microsoft-credentials.json` (parallel to
+`google-credentials.json`).
+
+### 2. Microsoft tokenProvider  [M]
+Generalize `index.ts:798-848` so the provider isn't Google-only:
+- Pick the creds file + scope by account kind (gmail vs outlook), keyed off the
+  same signal `account.imap.auth === "oauth2"` plus host/email domain.
+- For Outlook, point `authenticateOAuth` at `microsoft-credentials.json` with the
+  Microsoft scope set. The flow itself is unchanged — oauthsupport already reads
+  the endpoints from the creds file, so no oauthsupport changes are required
+  (confirm consumer-account PKCE: Microsoft may require `code_challenge` for the
+  loopback client; if so, add PKCE support in `OAuthTokenManager.getToken`).
+- Token cache dir reuses the existing `tokens/<user>/` convention (`index.ts:814`).
+
+This single change makes the **IMAP/XOAUTH2 path work end-to-end** — the office365
+host config already exists, and SMTP OAuth (`index.ts:1533`) consumes the same
+tokenProvider. Verify the token is minted with Outlook IMAP/SMTP scopes, not Graph
+scopes (they're different audiences).
+
+### 3. Provider selection  [S]
+Add an `isOutlookAccount()` sibling to `isGmailAccount()` (`index.ts:898`) and an
+`getOutlookProvider()` mirroring `getGmailProvider()` (`index.ts:906`) that does
+`new OutlookApiProvider(config.tokenProvider)`. Then extend each
+`isGmailAccount()` branch (sync, periodic STATUS, IDLE-skip, etc. — ~10 sites) to
+a three-way provider switch. *(Only needed for the Graph path; the IMAP path
+needs none of this — it flows through the normal IMAP code.)*
+
+### 4. Graph write-back + send  [M] *(Graph path only)*
+Add to `OutlookApiProvider`:
+- `sendMail`: `POST /sendMail` with the MIME or the Graph message object.
+- mark read/flag: `PATCH /messages/{id}` (`isRead`, `flag`).
+- move: `POST /messages/{id}/move`.
+- delete: `DELETE /messages/{id}` (or move to deleteditems).
+- draft create/update: `POST /messages` / `PATCH`.
+- attachments: `GET /messages/{id}/attachments`.
+Replace list-and-scan in `fetchByUids`/`fetchOne` with direct
+`GET /messages/{providerId}` using the DB's `provider_id` mapping.
+
+### 5. Setup UX  [S]
+`bin/mailx.ts` `knownOAuth` list (~line 1320) already includes `outlook.com` /
+`hotmail.com`. Once the tokenProvider exists, first-run setup triggers the
+Microsoft consent screen the same way Gmail does — no extra UI. Add an error
+banner case for "Microsoft credentials missing" pointing at
+`microsoft-credentials.json`.
+
+---
+
+## Step-by-step (with URLs)
+
+### A. Register the Azure app — the part only you can do
+1. Sign in to the Entra admin center → **App registrations**:
+   https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade
+   (equivalently Azure portal → "Microsoft Entra ID" → "App registrations":
+   https://portal.azure.com)
+2. **New registration** (guide:
+   https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app):
+   - Name: `rmfmail`.
+   - Supported account types: **"Accounts in any organizational directory and
+     personal Microsoft accounts"** (covers both outlook.com consumer and M365).
+   - Redirect URI: platform **"Mobile and desktop applications"**, value
+     **`http://localhost`** (loopback — what oauthsupport's flow listens on).
+     Desktop/loopback registration:
+     https://learn.microsoft.com/en-us/entra/identity-platform/scenario-desktop-app-registration
+3. Copy the **Application (client) ID** from the app's Overview page.
+4. **Certificates & secrets** → **New client secret** → copy the secret *value*
+   (not the ID). (Public-client/PKCE is the alternative if you'd rather not ship a
+   secret — see Sharp edges.)
+5. **API permissions** → **Add a permission** → **Microsoft Graph** → **Delegated**
+   (permissions reference:
+   https://learn.microsoft.com/en-us/graph/permissions-reference):
+   - Graph path: `Mail.ReadWrite`, `Mail.Send`, `offline_access`, `openid`,
+     `profile`.
+   - IMAP path instead/also: `IMAP.AccessAsUser.All`, `SMTP.Send`,
+     `offline_access` (these live under the *Office 365 Exchange Online* API, not
+     Graph). Microsoft's IMAP/SMTP-OAuth guide:
+     https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth
+   - Click **Grant admin consent** if it's a work tenant (personal accounts
+     consent at first sign-in).
+
+Reference for the endpoints used below:
+- Authorize: `https://login.microsoftonline.com/common/oauth2/v2.0/authorize`
+- Token: `https://login.microsoftonline.com/common/oauth2/v2.0/token`
+- Auth-code flow spec:
+  https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow
+- Graph mail API overview:
+  https://learn.microsoft.com/en-us/graph/api/resources/mail-api-overview
+
+### B. Drop in the credentials file
+Create `~/.mailx/microsoft-credentials.json` mirroring the Google one's shape so
+oauthsupport's `OAuthTokenManager` (reads `client_id`/`client_secret`/`auth_uri`/
+`token_uri`, `OAuthTokenManager.ts:369`) consumes it unchanged:
+
+    {
+        "installed": {
+            "client_id": "<Application (client) ID>",
+            "client_secret": "<secret value>",
+            "auth_uri": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+            "token_uri": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+            "redirect_uris": ["http://localhost"]
+        }
+    }
+
+### C. Wire the code (steps 2-3 from the work breakdown)
+1. In `packages/mailx-imap/index.ts` (~798), branch the tokenProvider on account
+   kind: Outlook accounts use `microsoft-credentials.json` + the Microsoft scope
+   string (IMAP scopes for the IMAP path, Graph scopes for the Graph path).
+2. For the **IMAP path** that's the whole change — the office365 host config
+   (`mailx-settings/index.ts:503`) and OAuth-SMTP (`index.ts:1533`) already
+   consume the tokenProvider. Test sign-in: first send triggers the loopback
+   consent at `http://localhost`.
+3. For the **Graph path**, add `isOutlookAccount()`/`getOutlookProvider()` next to
+   the Gmail equivalents (`index.ts:898/906`) and fill the provider's write-back
+   gaps (`sendMail`, flag/move/delete, drafts).
+
+## Sharp edges / open questions
+
+- **Consumer vs M365 differ.** Personal outlook.com and Microsoft 365 work
+  accounts use different scope audiences and consent behavior. `/common` covers
+  both at the authority level, but test both — a token good for Graph isn't valid
+  for IMAP and vice-versa.
+- **PKCE.** Microsoft increasingly requires PKCE for loopback clients. If consent
+  fails with `invalid_request`, add `code_challenge`/`code_verifier` to
+  oauthsupport's auth-code flow (it's the one oauthsupport change that might be
+  needed).
+- **Basic auth is gone.** Don't add a password fallback for office365 — it will
+  always fail. The error path should say "Outlook requires sign-in", not "wrong
+  password".
+- **Drive/OneDrive is unrelated.** `cloud.ts` already sketches MS Graph
+  `Files.ReadWrite` scopes for OneDrive storage — that's a separate app/scope from
+  mail and shares none of this wiring (and OneDrive cloud storage was removed;
+  GDrive only).
+- **`idToUid` collisions.** A 32-bit hash of Graph IDs across a 10-year mailbox
+  will eventually collide. The Graph path must key on `provider_id`
+  (string) as identity, with the integer UID as a display/sort convenience only —
+  same lesson as `imap_uid_not_identity`.

package/packages/mailx-settings/index.d.ts

@@ -27,6 +27,12 @@ export declare function getLastCloudError(): string | null;
 declare function getSharedDir(): string;
 /** Read a file via cloud API (when filesystem mount not available) */
 export declare function cloudRead(filename: string): Promise<string | null>;
+/** Read a file from the shared cloud config folder as raw bytes, base64-encoded.
+ *  Binary-safe sibling of cloudRead — used for the optional custom reminder
+ *  sound that lives next to the JSONC config on Drive. Returns null if cloud
+ *  isn't configured, the file is missing, or the read errors (caller falls back
+ *  to the built-in chime). */
+export declare function cloudReadBinary(filename: string): Promise<string | null>;
 /** Write a file via cloud API. Throws on failure with a descriptive error,
  *  and updates lastCloudError so UI banners pick it up via getStorageInfo()
  *  and the onCloudError listener. */
@@ -79,6 +85,9 @@ declare const DEFAULT_PREFERENCES: {
         historyDays: number;
         prefetch: boolean;
     };
+    reminders: {
+        sound: string;
+    };
     autocomplete: {
         enabled: boolean;
         provider: "ollama";

package/packages/mailx-settings/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"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"}

package/packages/mailx-settings/index.js

@@ -288,6 +288,35 @@ export async function cloudRead(filename) {
     // Don't set error for missing files — they may not exist yet (e.g., clients.jsonc on first run)
     return content;
 }
+/** Read a file from the shared cloud config folder as raw bytes, base64-encoded.
+ *  Binary-safe sibling of cloudRead — used for the optional custom reminder
+ *  sound that lives next to the JSONC config on Drive. Returns null if cloud
+ *  isn't configured, the file is missing, or the read errors (caller falls back
+ *  to the built-in chime). */
+export async function cloudReadBinary(filename) {
+    if (!pendingCloudConfig)
+        return null;
+    if (!pendingCloudConfig.folderId) {
+        pendingCloudConfig.folderId = await gDriveFindOrCreateFolder() || undefined;
+        if (pendingCloudConfig.folderId)
+            saveFolderIdToConfig(pendingCloudConfig.folderId);
+        if (!pendingCloudConfig.folderId)
+            return null;
+    }
+    const provider = getCloudProvider(pendingCloudConfig.provider, pendingCloudConfig.folderId);
+    if (!provider?.readBinary)
+        return null;
+    try {
+        return await Promise.race([
+            provider.readBinary(filename),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`cloudReadBinary ${filename}: 15s timeout`)), 15_000)),
+        ]);
+    }
+    catch (e) {
+        console.error(`  [cloud] readBinary ${filename}: ${e?.message || e}`);
+        return null;
+    }
+}
 /** Write a file via cloud API. Throws on failure with a descriptive error,
  *  and updates lastCloudError so UI banners pick it up via getStorageInfo()
  *  and the onCloudError listener. */
@@ -622,6 +651,16 @@ const DEFAULT_PREFERENCES = {
         historyDays: 30,
         prefetch: true,
     },
+    reminders: {
+        // Sound played when a calendar/task reminder fires.
+        //   ""      → built-in chime (a soft two-note tone, no file needed)
+        //   "none"  → silent
+        //   <name>  → a custom sound FILE, resolved relative to the config:
+        //             tried in the LOCAL config dir (~/.rmfmail/<name>) first,
+        //             then in the shared cloud config folder on Drive. If it
+        //             can't be read or played, falls back to the built-in chime.
+        sound: "",
+    },
     autocomplete: {
         enabled: false,
         provider: "ollama",