@bobfrankston/mailx 1.0.171 → 1.0.172

package/client/app.js

@@ -4,8 +4,9 @@
  */
 import { initFolderTree, refreshFolderTree, updateFolderCounts } from "./components/folder-tree.js";
 import { initMessageList, loadMessages, loadUnifiedInbox, loadSearchResults, reloadCurrentFolder, getSelectedMessages } from "./components/message-list.js";
-import { showMessage, getCurrentMessage } from "./components/message-viewer.js";
+import { showMessage, getCurrentMessage, initViewer } from "./components/message-viewer.js";
 import { connectWebSocket, onWsEvent, triggerSync, syncAccount, reauthenticate, getAccounts, getFolders, deleteMessages, undeleteMessage, restartServer, rebuildServer, getSyncPending, getVersion, getSettings, saveSettings, getAutocompleteSettings, saveAutocompleteSettings, repairAccounts } from "./lib/api-client.js";
+import * as messageState from "./lib/message-state.js";
 // ── New message badge (favicon + title) ──
 let baseTitle = "mailx";
 let lastSeenCount = 0;
@@ -117,15 +118,7 @@ alertDismiss?.addEventListener("click", hideAlert);
 const folderTree = document.getElementById("folder-tree");
 let currentFolderSpecialUse = "";
 function clearViewer() {
-    const body = document.getElementById("mv-body");
-    const header = document.getElementById("mv-header");
-    const att = document.getElementById("mv-attachments");
-    if (body)
-        body.innerHTML = "";
-    if (header)
-        header.hidden = true;
-    if (att)
-        att.hidden = true;
+    messageState.select(null); // Deselect — viewer clears via subscription
 }
 initFolderTree(folderTree, (accountId, folderId, folderName, specialUse) => {
     currentFolderSpecialUse = specialUse;
@@ -152,6 +145,7 @@ initMessageList((accountId, uid, folderId) => {
         document.getElementById("message-list")?.classList.add("narrow-hidden");
     }
 });
+initViewer();
 // ── Auto two-line when message list is narrow ──
 const messageList = document.getElementById("message-list");
 if (messageList) {
@@ -320,17 +314,8 @@ async function deleteSelectedMessages() {
         selected.push({ accountId: current.accountId, uid: current.message.uid, folderId: current.message.folderId });
     }
     const statusSync = document.getElementById("status-sync");
-    const mlBody = document.getElementById("ml-body");
     try {
-        // Find the row after the last selected for re-selection
-        let nextRow = null;
-        if (mlBody) {
-            const lastRow = mlBody.querySelector(`.ml-row[data-uid="${selected[selected.length - 1].uid}"]`);
-            if (lastRow)
-                nextRow = (lastRow.nextElementSibling || lastRow.previousElementSibling);
-        }
-        // Delete all selected — bulk operation, one IMAP session
-        // Group by account
+        // Delete on server — group by account for bulk operations
         const byAccount = new Map();
         for (const msg of selected) {
             const uids = byAccount.get(msg.accountId) || [];
@@ -340,11 +325,6 @@ async function deleteSelectedMessages() {
         for (const [accountId, uids] of byAccount) {
             await deleteMessages(accountId, uids);
         }
-        // Remove rows from DOM
-        for (const msg of selected) {
-            if (mlBody)
-                mlBody.querySelector(`.ml-row[data-uid="${msg.uid}"]`)?.remove();
-        }
         // Undo supports the last batch
         if (selected.length === 1) {
             lastDeleted = { ...selected[0], subject: "" };
@@ -352,7 +332,7 @@ async function deleteSelectedMessages() {
                 statusSync.textContent = `Deleted 1 message — Ctrl+Z to undo`;
         }
         else {
-            lastDeleted = null; // Multi-delete undo not supported yet
+            lastDeleted = null;
             if (statusSync)
                 statusSync.textContent = `Deleted ${selected.length} messages`;
         }
@@ -363,18 +343,8 @@ async function deleteSelectedMessages() {
             if (statusSync?.textContent?.includes("undo"))
                 statusSync.textContent = "";
         }, 30000);
-        // Select next row or clear viewer
-        if (nextRow?.classList.contains("ml-row")) {
-            nextRow.click();
-        }
-        else {
-            const bodyEl = document.getElementById("mv-body");
-            const headerEl = document.getElementById("mv-header");
-            if (bodyEl)
-                bodyEl.innerHTML = `<div class="mv-empty">Select a message to read</div>`;
-            if (headerEl)
-                headerEl.hidden = true;
-        }
+        // Remove from shared state — list and viewer update automatically
+        messageState.removeMessages(selected);
     }
     catch (e) {
         console.error(`Delete failed: ${e.message}`);
@@ -454,8 +424,7 @@ searchInput?.addEventListener("keydown", (e) => {
         reloadCurrentFolder();
     }
 });
-// ── Reload message list after drag-move ──
-document.addEventListener("mailx-message-moved", () => reloadCurrentFolder());
+// Message state handles move/delete — no manual event listener needed
 // ── Folder filter ──
 const ftFilterInput = document.getElementById("ft-filter-input");
 if (ftFilterInput) {

package/client/components/folder-tree.js

@@ -248,10 +248,11 @@ function renderNode(node, container, depth) {
                         return;
                     try {
                         await emptyFolder(node.accountId, node.id);
+                        const { setMessages } = await import("../lib/message-state.js");
+                        setMessages([]); // Folder emptied — clear list and viewer
                         const treeContainer = document.getElementById("folder-tree");
                         if (treeContainer)
                             loadFolderTree(treeContainer);
-                        document.dispatchEvent(new CustomEvent("mailx-message-moved"));
                     }
                     catch (err) {
                         alert(`Failed: ${err.message}`);
@@ -298,10 +299,12 @@ function renderNode(node, container, depth) {
                 const moved = toMove.length;
                 if (statusEl)
                     statusEl.textContent = `Moved ${moved} message${moved > 1 ? "s" : ""} to ${node.name}`;
+                // Remove from shared state — list and viewer update automatically
+                const { removeMessages } = await import("../lib/message-state.js");
+                removeMessages(toMove);
                 const treeContainer = document.getElementById("folder-tree");
                 if (treeContainer)
                     loadFolderTree(treeContainer);
-                document.dispatchEvent(new CustomEvent("mailx-message-moved"));
             }
             catch (err) {
                 console.error(`Move failed: ${err.message}`);

package/client/components/message-list.js

@@ -1,17 +1,9 @@
 /**
- * Message list component -- renders paginated message rows.
- * Loads more messages on scroll.
+ * Message list component — renders paginated message rows.
+ * Reads from message-state; operations mutate state, list reacts.
  */
-import { getMessages, getUnifiedInbox, searchMessages, updateFlags } from "../lib/api-client.js";
-/** Clear the message viewer when no message is selected */
-function clearViewer() {
-    const bodyEl = document.getElementById("mv-body");
-    const headerEl = document.getElementById("mv-header");
-    if (bodyEl)
-        bodyEl.innerHTML = `<div class="mv-empty">Select a message to read</div>`;
-    if (headerEl)
-        headerEl.hidden = true;
-}
+import { getMessages as apiGetMessages, getUnifiedInbox as apiGetUnifiedInbox, searchMessages, updateFlags } from "../lib/api-client.js";
+import * as state from "../lib/message-state.js";
 let onMessageSelect;
 let currentAccountId;
 let currentFolderId;
@@ -71,6 +63,48 @@ export function initMessageList(handler) {
             }
         });
     }
+    // Subscribe to state changes — react to removeMessages (move/delete)
+    state.subscribe((change) => {
+        if (change === "removed") {
+            syncDomToState();
+        }
+    });
+}
+/**
+ * Sync DOM rows to current state after messages are removed.
+ * Removes DOM rows that are no longer in state, updates selection.
+ */
+function syncDomToState() {
+    const body = document.getElementById("ml-body");
+    if (!body)
+        return;
+    // Build set of UIDs still in state
+    const stateUids = new Set(state.getMessages().map(m => `${m.accountId}:${m.uid}`));
+    // Remove rows not in state
+    for (const row of Array.from(body.querySelectorAll(".ml-row"))) {
+        const el = row;
+        const key = `${el.dataset.accountId}:${el.dataset.uid}`;
+        if (!stateUids.has(key)) {
+            el.remove();
+        }
+    }
+    // Update selection to match state
+    clearSelection();
+    const sel = state.getSelected();
+    if (sel) {
+        const row = body.querySelector(`.ml-row[data-uid="${sel.uid}"][data-account-id="${sel.accountId}"]`)
+            || body.querySelector(`.ml-row[data-uid="${sel.uid}"]`);
+        if (row) {
+            row.classList.add("selected");
+            lastClickedRow = row;
+            // Trigger viewer update
+            onMessageSelect(sel.accountId, sel.uid, sel.folderId);
+        }
+    }
+    // If no messages left, show empty
+    if (state.getMessages().length === 0) {
+        body.innerHTML = `<div class="ml-empty">No messages</div>`;
+    }
 }
 /** Reload the currently displayed folder (preserves current selection) */
 export function reloadCurrentFolder() {
@@ -86,8 +120,6 @@ export function reloadCurrentFolder() {
 }
 /** Load unified inbox (all accounts) */
 export async function loadUnifiedInbox(autoSelect = true) {
-    if (autoSelect)
-        clearViewer();
     unifiedMode = true;
     currentPage = 1;
     totalMessages = 0;
@@ -96,36 +128,25 @@ export async function loadUnifiedInbox(autoSelect = true) {
         return;
     const savedScroll = !autoSelect ? body.scrollTop : 0;
     const savedUid = !autoSelect ? body.querySelector(".ml-row.selected")?.getAttribute("data-uid") : null;
-    // Only show loading indicator on fresh navigation, not reloads
     if (autoSelect) {
         body.innerHTML = `<div class="ml-empty">Loading...</div>`;
     }
     try {
-        const result = await getUnifiedInbox(1);
+        const result = await apiGetUnifiedInbox(1);
         totalMessages = result.total;
         if (result.items.length === 0) {
+            state.setMessages([]);
             body.innerHTML = `<div class="ml-empty">${result.total > 0 ? `${result.total} messages syncing...` : "Syncing — messages will appear shortly"}</div>`;
             return;
         }
-        // Build new rows into a fragment, then swap atomically (no flash)
-        const fragment = document.createDocumentFragment();
-        const tempDiv = document.createElement("div");
-        appendMessages(tempDiv, "", result.items);
-        while (tempDiv.firstChild)
-            fragment.appendChild(tempDiv.firstChild);
-        body.replaceChildren(fragment);
+        state.setMessages(result.items);
+        renderMessages(body, "", result.items);
         if (autoSelect) {
-            const firstRow = body.querySelector(".ml-row");
-            if (firstRow)
-                firstRow.click();
+            selectFirst(body);
         }
         else {
             body.scrollTop = savedScroll;
-            if (savedUid) {
-                const row = body.querySelector(`.ml-row[data-uid="${savedUid}"]`);
-                if (row)
-                    row.classList.add("selected");
-            }
+            restoreSelection(body, savedUid);
         }
     }
     catch (e) {
@@ -157,29 +178,29 @@ export async function loadSearchResults(query, scope = "all", accountId = "", fo
                 body.innerHTML = `<div class="ml-empty">Invalid regex</div>`;
                 return;
             }
-            // Get all messages from current context and filter
             const source = scope === "current" && accountId
-                ? await getMessages(accountId, folderId, 1, 10000)
+                ? await apiGetMessages(accountId, folderId, 1, 10000)
                 : await searchMessages("*", 1, 10000, "all");
             const matches = source.items.filter((m) => regex.test(m.subject || "") || regex.test(m.from?.name || "") || regex.test(m.from?.address || "") || regex.test(m.preview || ""));
             totalMessages = matches.length;
+            state.setMessages(matches);
             if (matches.length === 0) {
                 body.innerHTML = `<div class="ml-empty">No regex matches</div>`;
                 return;
             }
             body.innerHTML = "";
             appendMessages(body, "", matches);
-            const firstRow = body.querySelector(".ml-row");
-            if (firstRow)
-                firstRow.click();
+            selectFirst(body);
             return;
         }
         const result = await searchMessages(query, 1, 50, scope, accountId, folderId);
         totalMessages = result.total;
         if (result.items.length === 0) {
+            state.setMessages([]);
             body.innerHTML = `<div class="ml-empty">No results for "${query}"</div>`;
             return;
         }
+        state.setMessages(result.items);
         body.innerHTML = "";
         appendMessages(body, "", result.items);
     }
@@ -188,9 +209,6 @@ export async function loadSearchResults(query, scope = "all", accountId = "", fo
     }
 }
 export async function loadMessages(accountId, folderId, page = 1, specialUse = "", autoSelect = true) {
-    // Clear viewer when navigating to a new folder (not on reloads)
-    if (autoSelect)
-        clearViewer();
     searchMode = false;
     unifiedMode = false;
     showToInsteadOfFrom = ["sent", "drafts", "outbox"].includes(specialUse) ||
@@ -206,49 +224,34 @@ export async function loadMessages(accountId, folderId, page = 1, specialUse = "
     const fromHeader = document.querySelector(".ml-col-from");
     if (fromHeader)
         fromHeader.textContent = showToInsteadOfFrom ? "To" : "From";
-    // Save scroll position and selected UID for non-autoSelect reloads
     const savedScroll = !autoSelect ? body.scrollTop : 0;
     const savedUid = !autoSelect ? body.querySelector(".ml-row.selected")?.getAttribute("data-uid") : null;
-    // Only show loading indicator on fresh navigation, not reloads
     if (autoSelect) {
         body.innerHTML = `<div class="ml-empty">Loading...</div>`;
     }
     try {
-        const result = await getMessages(accountId, folderId, 1);
+        const result = await apiGetMessages(accountId, folderId, 1);
         totalMessages = result.total;
         if (result.items.length === 0) {
+            state.setMessages([]);
             body.innerHTML = `<div class="ml-empty">No messages</div>`;
-            clearViewer();
             return;
         }
-        // Build new rows into a fragment, then swap atomically (no flash)
-        const fragment = document.createDocumentFragment();
-        const tempDiv = document.createElement("div");
-        appendMessages(tempDiv, accountId, result.items);
-        while (tempDiv.firstChild)
-            fragment.appendChild(tempDiv.firstChild);
-        body.replaceChildren(fragment);
+        state.setMessages(result.items);
+        renderMessages(body, accountId, result.items);
         if (autoSelect) {
-            // Explicit folder navigation — select first message
-            const firstRow = body.querySelector(".ml-row");
-            if (firstRow)
-                firstRow.click();
+            selectFirst(body);
         }
         else {
-            // Sync reload — restore scroll position and selection after layout
             requestAnimationFrame(() => {
                 body.scrollTop = savedScroll;
-                if (savedUid) {
-                    const row = body.querySelector(`.ml-row[data-uid="${savedUid}"]`);
-                    if (row)
-                        row.classList.add("selected");
-                }
+                restoreSelection(body, savedUid);
             });
         }
     }
     catch (e) {
         if (e.name === "AbortError")
-            return; // Superseded by newer request
+            return;
         body.innerHTML = `<div class="ml-empty">Error: ${e.message}</div>`;
     }
 }
@@ -262,8 +265,11 @@ async function loadMoreMessages() {
         const result = searchMode
             ? await searchMessages(currentSearchQuery, currentPage)
             : unifiedMode
-                ? await getUnifiedInbox(currentPage)
-                : await getMessages(currentAccountId, currentFolderId, currentPage);
+                ? await apiGetUnifiedInbox(currentPage)
+                : await apiGetMessages(currentAccountId, currentFolderId, currentPage);
+        // Append to state
+        const current = state.getMessages();
+        state.setMessages([...current, ...result.items]);
         appendMessages(body, unifiedMode ? "" : currentAccountId, result.items);
     }
     catch (e) {
@@ -273,9 +279,29 @@ async function loadMoreMessages() {
         loading = false;
     }
 }
+/** Replace body contents with rendered rows */
+function renderMessages(body, accountId, items) {
+    const fragment = document.createDocumentFragment();
+    const tempDiv = document.createElement("div");
+    appendMessages(tempDiv, accountId, items);
+    while (tempDiv.firstChild)
+        fragment.appendChild(tempDiv.firstChild);
+    body.replaceChildren(fragment);
+}
+function selectFirst(body) {
+    const firstRow = body.querySelector(".ml-row");
+    if (firstRow)
+        firstRow.click();
+}
+function restoreSelection(body, savedUid) {
+    if (savedUid) {
+        const row = body.querySelector(`.ml-row[data-uid="${savedUid}"]`);
+        if (row)
+            row.classList.add("selected");
+    }
+}
 function appendMessages(body, accountId, items) {
     for (const msg of items) {
-        // Use per-message accountId for unified inbox, fallback to list-level accountId
         const msgAccountId = msg.accountId || accountId;
         const row = document.createElement("div");
         row.className = "ml-row";
@@ -289,7 +315,7 @@ function appendMessages(body, accountId, items) {
         row.dataset.folderId = String(msg.folderId);
         const flag = document.createElement("span");
         flag.className = "ml-flag";
-        flag.textContent = msg.flags.includes("\\Flagged") ? "\u2605" : "\u2606"; // ★ or ☆
+        flag.textContent = msg.flags.includes("\\Flagged") ? "\u2605" : "\u2606";
         flag.title = "Toggle flag";
         const from = document.createElement("span");
         from.className = "ml-from";
@@ -299,13 +325,11 @@ function appendMessages(body, accountId, items) {
         else {
             from.textContent = msg.from.name || msg.from.address;
         }
-        // Account tag for unified inbox
         if (!accountId && msgAccountId) {
             const tag = document.createElement("span");
             tag.className = "ml-account-tag";
-            const label = msgAccountId;
-            tag.textContent = label.charAt(0).toUpperCase();
-            tag.title = label;
+            tag.textContent = msgAccountId.charAt(0).toUpperCase();
+            tag.title = msgAccountId;
             from.prepend(tag);
         }
         const subject = document.createElement("span");
@@ -341,25 +365,23 @@ function appendMessages(body, accountId, items) {
         row.appendChild(subject);
         row.addEventListener("click", (e) => {
             if (e.shiftKey && lastClickedRow) {
-                // Shift+click: range select from last clicked to this row
                 clearSelection();
                 selectRange(lastClickedRow, row);
             }
             else if (e.ctrlKey || e.metaKey) {
-                // Ctrl+click: toggle this row
                 row.classList.toggle("selected");
             }
             else {
-                // Plain click: single select
                 clearSelection();
                 row.classList.add("selected");
             }
             lastClickedRow = row;
             row.classList.remove("unread");
+            // Update shared state + notify viewer
+            state.select(msg);
             onMessageSelect(msgAccountId, msg.uid, msg.folderId);
         });
         row.addEventListener("dragstart", (e) => {
-            // If dragging a non-selected row, select it first
             if (!row.classList.contains("selected")) {
                 clearSelection();
                 row.classList.add("selected");
@@ -367,7 +389,6 @@ function appendMessages(body, accountId, items) {
             }
             const selected = getSelectedMessages();
             e.dataTransfer.setData("application/x-mailx-messages", JSON.stringify(selected));
-            // Legacy single-message format for backwards compat
             e.dataTransfer.setData("application/x-mailx-message", JSON.stringify({
                 accountId: msgAccountId,
                 uid: msg.uid,
@@ -376,7 +397,6 @@ function appendMessages(body, accountId, items) {
             }));
             e.dataTransfer.effectAllowed = "copyMove";
             row.classList.add("dragging");
-            // Show drag count
             if (selected.length > 1) {
                 const badge = document.createElement("div");
                 badge.textContent = `${selected.length} messages`;

package/client/components/message-viewer.js

@@ -1,7 +1,9 @@
 /**
  * Message viewer component -- displays full message in sandboxed iframe.
+ * Subscribes to message-state: clears when selected becomes null.
  */
 import { getMessage, updateFlags, allowRemoteContent } from "../lib/api-client.js";
+import * as state from "../lib/message-state.js";
 /** Currently displayed message (for reply/forward) */
 let currentMessage = null;
 let currentAccountId = "";
@@ -12,6 +14,35 @@ export function getCurrentMessage() {
         return null;
     return { accountId: currentAccountId, message: currentMessage };
 }
+/** Initialize viewer — subscribe to state changes */
+export function initViewer() {
+    state.subscribe((change) => {
+        if (change === "removed" || change === "messages") {
+            const sel = state.getSelected();
+            if (!sel) {
+                clearViewer();
+            }
+            else if (sel.uid !== currentMessage?.uid || sel.accountId !== currentAccountId) {
+                // State auto-selected a new message after removal — show it
+                showMessage(sel.accountId, sel.uid, sel.folderId);
+            }
+        }
+    });
+}
+function clearViewer() {
+    currentMessage = null;
+    currentAccountId = "";
+    showMessageGeneration++;
+    const headerEl = document.getElementById("mv-header");
+    const bodyEl = document.getElementById("mv-body");
+    const attEl = document.getElementById("mv-attachments");
+    if (bodyEl)
+        bodyEl.innerHTML = `<div class="mv-empty">Select a message to read</div>`;
+    if (headerEl)
+        headerEl.hidden = true;
+    if (attEl)
+        attEl.hidden = true;
+}
 export async function showMessage(accountId, uid, folderId, specialUse, isRetry = false) {
     const gen = ++showMessageGeneration;
     if (!isRetry)

package/client/lib/message-state.js

@@ -0,0 +1,83 @@
+/**
+ * Shared message state — single source of truth for the message list and viewer.
+ *
+ * The message list and viewer both reference message objects from this store.
+ * Operations (move, delete, sync) mutate the store; UI components subscribe
+ * and update themselves. No manual DOM cleanup, no custom events.
+ */
+/** The currently loaded messages (what the list shows) */
+let messages = [];
+/** The currently selected/viewed message (same ref as an entry in messages[]) */
+let selected = null;
+const listeners = [];
+/** Subscribe to state changes. Returns unsubscribe function. */
+export function subscribe(fn) {
+    listeners.push(fn);
+    return () => {
+        const i = listeners.indexOf(fn);
+        if (i >= 0)
+            listeners.splice(i, 1);
+    };
+}
+function notify(change) {
+    for (const fn of listeners) {
+        try {
+            fn(change);
+        }
+        catch { /* don't let one subscriber break others */ }
+    }
+}
+/** Replace the entire message list (folder load, search, unified inbox) */
+export function setMessages(msgs) {
+    messages = msgs;
+    // If the previously selected message is no longer in the list, deselect
+    if (selected && !messages.find(m => m.uid === selected.uid && m.accountId === selected.accountId)) {
+        selected = null;
+    }
+    notify("messages");
+}
+/** Get current messages */
+export function getMessages() {
+    return messages;
+}
+/** Select a message (by reference or null to deselect) */
+export function select(msg) {
+    selected = msg;
+    notify("selected");
+}
+/** Get the selected message */
+export function getSelected() {
+    return selected;
+}
+/**
+ * Remove messages from the list (after move or delete).
+ * If the selected message is removed, auto-selects the next message or null.
+ */
+export function removeMessages(uids) {
+    const removeSet = new Set(uids.map(u => `${u.accountId}:${u.uid}`));
+    let selectedIdx = -1;
+    if (selected) {
+        selectedIdx = messages.findIndex(m => m.uid === selected.uid && m.accountId === selected.accountId);
+    }
+    const wasSelectedRemoved = selected && removeSet.has(`${selected.accountId}:${selected.uid}`);
+    messages = messages.filter(m => !removeSet.has(`${m.accountId}:${m.uid}`));
+    if (wasSelectedRemoved) {
+        // Auto-select next message (same index, or last, or null)
+        if (messages.length > 0) {
+            const nextIdx = Math.min(selectedIdx, messages.length - 1);
+            selected = messages[nextIdx];
+        }
+        else {
+            selected = null;
+        }
+    }
+    notify("removed");
+}
+/** Update flags on a message in the list */
+export function updateMessageFlags(accountId, uid, flags) {
+    const msg = messages.find(m => m.uid === uid && m.accountId === accountId);
+    if (msg)
+        msg.flags = flags;
+    // No notify — flag changes are cosmetic, handled inline by the list
+}
+//# sourceMappingURL=message-state.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx",
-  "version": "1.0.171",
+  "version": "1.0.172",
   "description": "Local-first email client with IMAP sync and standalone native app",
   "type": "module",
   "main": "bin/mailx.js",
@@ -20,11 +20,11 @@
     "postinstall": "node bin/postinstall.js"
   },
   "dependencies": {
-    "@bobfrankston/iflow-direct": "^0.1.3",
+    "@bobfrankston/iflow-direct": "^0.1.4",
     "@bobfrankston/iflow-node": "^0.1.1",
     "@bobfrankston/miscinfo": "^1.0.7",
     "@bobfrankston/oauthsupport": "^1.0.20",
-    "@bobfrankston/msger": "^0.1.220",
+    "@bobfrankston/msger": "^0.1.221",
     "@capacitor/android": "^8.3.0",
     "@capacitor/cli": "^8.3.0",
     "@capacitor/core": "^8.3.0",

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

@@ -73,6 +73,12 @@ export declare class ImapManager extends EventEmitter {
     getAccountCount(): number;
     /** Register an account */
     addAccount(account: AccountConfig): Promise<void>;
+    /** Check if an account uses Gmail (should use API instead of IMAP) */
+    private isGmailAccount;
+    /** Get a Gmail API provider for an account (reuses tokenProvider from IMAP config) */
+    private getGmailProvider;
+    /** Convert ProviderMessage to the shape expected by storeMessages/upsertMessage */
+    private providerMsgToLocal;
     /** Sync folder list for an account */
     syncFolders(accountId: string, client?: any): Promise<Folder[]>;
     /** Store a batch of messages to DB immediately — used by onChunk for incremental sync */
@@ -84,6 +90,12 @@ export declare class ImapManager extends EventEmitter {
     private _syncAll;
     /** Sync a single account — manages its own connection lifecycle */
     private syncAccount;
+    /** Sync a Gmail account via REST API — no IMAP connections */
+    private syncAccountViaApi;
+    /** Sync a single folder via Gmail/Outlook API */
+    private syncFolderViaApi;
+    /** Store API-fetched messages to DB */
+    private storeApiMessages;
     /** Kill and recreate the persistent ops connection */
     private reconnectOps;
     /** Handle sync errors — classify and emit appropriate UI events */
@@ -115,6 +127,8 @@ export declare class ImapManager extends EventEmitter {
     private enqueueFetch;
     /** Fetch a single message body on demand, caching in the store */
     fetchMessageBody(accountId: string, folderId: number, uid: number): Promise<Buffer | null>;
+    /** Fetch message body via Gmail/Outlook API */
+    private fetchMessageBodyViaApi;
     /** Get the body store for direct access */
     getBodyStore(): FileMessageStore;
     /** Bulk trash messages — local-first, single IMAP connection for all */

package/packages/mailx-imap/index.js

@@ -11,6 +11,7 @@ import { EventEmitter } from "node:events";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { simpleParser } from "mailparser";
+import { GmailApiProvider } from "./providers/gmail-api.js";
 import { createTransport } from "nodemailer";
 import * as os from "node:os";
 /** Extract full error detail with provenance */
@@ -369,11 +370,46 @@ export class ImapManager extends EventEmitter {
                 }
                 else if (!this.accountErrorShown.has(account.id)) {
                     this.accountErrorShown.add(account.id);
-                    this.emit("accountError", account.id, errMsg, "Authentication may have expired", true);
+                    const config = this.configs.get(account.id);
+                    this.emit("accountError", account.id, errMsg, errMsg, !!config?.tokenProvider);
                 }
             }
         }
     }
+    /** Check if an account uses Gmail (should use API instead of IMAP) */
+    isGmailAccount(accountId) {
+        const settings = loadSettings();
+        const account = settings.accounts.find(a => a.id === accountId);
+        if (!account)
+            return false;
+        return account.imap?.host?.includes("gmail") || account.email?.endsWith("@gmail.com") || false;
+    }
+    /** Get a Gmail API provider for an account (reuses tokenProvider from IMAP config) */
+    getGmailProvider(accountId) {
+        const config = this.configs.get(accountId);
+        if (!config?.tokenProvider)
+            throw new Error(`No tokenProvider for ${accountId}`);
+        return new GmailApiProvider(config.tokenProvider);
+    }
+    /** Convert ProviderMessage to the shape expected by storeMessages/upsertMessage */
+    providerMsgToLocal(msg) {
+        return {
+            uid: msg.uid,
+            messageId: msg.messageId,
+            date: msg.date || new Date(),
+            subject: msg.subject,
+            from: msg.from,
+            to: msg.to,
+            cc: msg.cc,
+            seen: msg.seen,
+            flagged: msg.flagged,
+            answered: msg.answered,
+            draft: msg.draft,
+            size: msg.size,
+            source: msg.source,
+            providerId: msg.providerId,
+        };
+    }
     /** Sync folder list for an account */
     async syncFolders(accountId, client) {
         if (!client)
@@ -486,7 +522,7 @@ export class ImapManager extends EventEmitter {
             : new Date(0);
         if (highestUid > 0) {
             // Incremental: fetch new messages — prefetch bodies for offline access
-            const fetched = await client.fetchMessagesSinceUid(folder.path, highestUid, { source: prefetch });
+            const fetched = await client.fetchMessagesSinceUid(folder.path, highestUid, { source: false });
             // Filter out the last known message (IMAP * always returns at least one)
             messages = fetched.filter((m) => m.uid > highestUid);
             // Gap detection: check for missing UIDs within the range we've already synced
@@ -507,7 +543,7 @@ export class ImapManager extends EventEmitter {
                         for (let i = 0; i < missingUids.length; i += chunkSize) {
                             const chunk = missingUids.slice(i, i + chunkSize);
                             const range = chunk.join(",");
-                            const recovered = await client.fetchMessages(folder.path, range, { source: prefetch });
+                            const recovered = await client.fetchMessages(folder.path, range, { source: false });
                             messages.push(...recovered);
                         }
                     }
@@ -523,7 +559,7 @@ export class ImapManager extends EventEmitter {
             const oldestDate = this.db.getOldestDate(accountId, folderId);
             if (oldestDate > 0 && startDate.getTime() < oldestDate) {
                 const existingUids = new Set(this.db.getUidsForFolder(accountId, folderId));
-                const backfill = await client.fetchMessageByDate(folder.path, startDate, new Date(oldestDate), { source: prefetch });
+                const backfill = await client.fetchMessageByDate(folder.path, startDate, new Date(oldestDate), { source: false });
                 const newBackfill = backfill.filter((m) => !existingUids.has(m.uid));
                 if (newBackfill.length > 0) {
                     console.log(`  ${folder.path}: backfilling ${newBackfill.length} older messages`);
@@ -543,7 +579,8 @@ export class ImapManager extends EventEmitter {
                 }
             };
             const tomorrow = new Date(Date.now() + 86400000); // IMAP BEFORE is exclusive
-            messages = await client.fetchMessageByDate(folder.path, startDate, tomorrow, { source: prefetch }, onChunk);
+            // First sync: metadata only for fast UI — bodies prefetched in background after
+            messages = await client.fetchMessageByDate(folder.path, startDate, tomorrow, { source: false }, onChunk);
             if (totalStored > 0) {
                 console.log(`  ${folder.path}: ${totalStored} messages (streamed)`);
                 this.db.recalcFolderCounts(folderId);
@@ -697,6 +734,10 @@ export class ImapManager extends EventEmitter {
     }
     /** Sync a single account — manages its own connection lifecycle */
     async syncAccount(accountId, priorityOrder) {
+        // Gmail: use REST API instead of IMAP
+        if (this.isGmailAccount(accountId)) {
+            return this.syncAccountViaApi(accountId, priorityOrder);
+        }
         try {
             // Step 1: Get folder list (fast — <1s typically)
             let client = await this.getOpsClient(accountId);
@@ -781,6 +822,145 @@ export class ImapManager extends EventEmitter {
             this.handleSyncError(accountId, errMsg);
         }
     }
+    /** Sync a Gmail account via REST API — no IMAP connections */
+    async syncAccountViaApi(accountId, priorityOrder) {
+        try {
+            const api = this.getGmailProvider(accountId);
+            const t0 = Date.now();
+            // Step 1: Sync folder list via API
+            console.log(`  [api] ${accountId}: listing labels...`);
+            const apiFolders = await api.listFolders();
+            console.log(`  [api] ${accountId}: ${apiFolders.length} labels in ${Date.now() - t0}ms`);
+            // Store folders in DB (same as IMAP path)
+            for (const f of apiFolders) {
+                const specialUse = f.specialUse || "";
+                this.db.upsertFolder(accountId, f.path, f.name, specialUse, f.delimiter);
+            }
+            this.emit("folderCountsChanged", accountId, {});
+            const dbFolders = this.db.getFolders(accountId);
+            // Step 2: Sync folders — INBOX first, then by priority
+            const inbox = dbFolders.find(f => f.specialUse === "inbox");
+            const remaining = dbFolders.filter(f => f.specialUse !== "inbox");
+            remaining.sort((a, b) => {
+                const pa = priorityOrder.indexOf(a.specialUse || "") >= 0 ? priorityOrder.indexOf(a.specialUse || "") : 5;
+                const pb = priorityOrder.indexOf(b.specialUse || "") >= 0 ? priorityOrder.indexOf(b.specialUse || "") : 5;
+                return pa - pb;
+            });
+            const foldersToSync = inbox ? [inbox, ...remaining] : remaining;
+            for (const folder of foldersToSync) {
+                try {
+                    await this.syncFolderViaApi(accountId, folder, api);
+                }
+                catch (e) {
+                    console.error(`  [api] ${accountId}/${folder.path}: ${e.message}`);
+                }
+            }
+            await api.close();
+            this.accountErrorShown.delete(accountId);
+            this.emit("syncComplete", accountId);
+        }
+        catch (e) {
+            const errMsg = e.message || String(e);
+            this.emit("syncError", accountId, errMsg);
+            console.error(`  [api] Sync error for ${accountId}: ${errMsg}`);
+            this.handleSyncError(accountId, errMsg);
+        }
+    }
+    /** Sync a single folder via Gmail/Outlook API */
+    async syncFolderViaApi(accountId, folder, api) {
+        const highestUid = this.db.getHighestUid(accountId, folder.id);
+        const historyDays = getHistoryDays(accountId);
+        const effectiveDays = (historyDays === 0 && highestUid === 0) ? 30 : historyDays;
+        const startDate = effectiveDays > 0 ? new Date(Date.now() - effectiveDays * 86400000) : new Date(0);
+        const tomorrow = new Date(Date.now() + 86400000);
+        this.emit("syncProgress", accountId, `sync:${folder.path}`, 0);
+        console.log(`  [api] ${accountId}/${folder.path}: syncing (highestUid=${highestUid})...`);
+        let messages;
+        if (highestUid > 0) {
+            // Incremental: fetch messages since last known UID
+            messages = await api.fetchSince(folder.path, highestUid, { source: false });
+        }
+        else {
+            // First sync: fetch by date range
+            messages = await api.fetchByDate(folder.path, startDate, tomorrow, { source: false }, (chunk) => {
+                // Stream chunks to DB for instant UI
+                const stored = this.storeApiMessages(accountId, folder.id, chunk, highestUid);
+                if (stored > 0) {
+                    this.db.recalcFolderCounts(folder.id);
+                    this.emit("folderCountsChanged", accountId, {});
+                }
+            });
+            // First sync chunks already stored via onChunk — just update counts
+            this.db.recalcFolderCounts(folder.id);
+            this.emit("folderCountsChanged", accountId, {});
+            this.emit("syncProgress", accountId, `sync:${folder.path}`, 100);
+            if (messages.length > 0)
+                console.log(`  [api] ${accountId}/${folder.path}: ${messages.length} messages`);
+            return;
+        }
+        if (messages.length > 0) {
+            console.log(`  [api] ${accountId}/${folder.path}: ${messages.length} new messages`);
+            this.storeApiMessages(accountId, folder.id, messages, highestUid);
+        }
+        // Reconcile deletions
+        try {
+            const serverUids = new Set(await api.getUids(folder.path));
+            const localUids = this.db.getUidsForFolder(accountId, folder.id);
+            let deleted = 0;
+            for (const uid of localUids) {
+                if (!serverUids.has(uid)) {
+                    this.db.deleteMessage(accountId, uid);
+                    this.bodyStore.deleteMessage(accountId, folder.id, uid).catch(() => { });
+                    deleted++;
+                }
+            }
+            if (deleted > 0)
+                console.log(`  [api] ${accountId}/${folder.path}: ${deleted} deleted`);
+        }
+        catch (e) {
+            console.error(`  [api] ${accountId}/${folder.path}: reconciliation error: ${e.message}`);
+        }
+        this.db.recalcFolderCounts(folder.id);
+        this.emit("folderCountsChanged", accountId, {});
+        this.emit("syncProgress", accountId, `sync:${folder.path}`, 100);
+    }
+    /** Store API-fetched messages to DB */
+    storeApiMessages(accountId, folderId, msgs, highestUid) {
+        let stored = 0;
+        this.db.beginTransaction();
+        try {
+            for (const msg of msgs) {
+                if (msg.uid <= highestUid)
+                    continue;
+                const flags = [];
+                if (msg.seen)
+                    flags.push("\\Seen");
+                if (msg.flagged)
+                    flags.push("\\Flagged");
+                if (msg.answered)
+                    flags.push("\\Answered");
+                if (msg.draft)
+                    flags.push("\\Draft");
+                this.db.upsertMessage({
+                    accountId, folderId, uid: msg.uid,
+                    messageId: msg.messageId || "", inReplyTo: "", references: [],
+                    date: msg.date instanceof Date ? msg.date.getTime() : Date.now(),
+                    subject: msg.subject || "",
+                    from: toEmailAddress(msg.from?.[0] || {}),
+                    to: toEmailAddresses(msg.to || []),
+                    cc: toEmailAddresses(msg.cc || []),
+                    flags, size: msg.size || 0, hasAttachments: false, preview: "", bodyPath: ""
+                });
+                stored++;
+            }
+            this.db.commitTransaction();
+        }
+        catch (e) {
+            this.db.rollbackTransaction();
+            console.error(`  [api] storeApiMessages error: ${e.message}`);
+        }
+        return stored;
+    }
     /** Kill and recreate the persistent ops connection */
     async reconnectOps(accountId) {
         const old = this.opsClients.get(accountId);
@@ -818,7 +998,7 @@ export class ImapManager extends EventEmitter {
         }
         else if (!this.accountErrorShown.has(accountId)) {
             this.accountErrorShown.add(accountId);
-            this.emit("accountError", accountId, errMsg, isOAuth ? "Authentication may have expired" : "Check server connectivity", isOAuth);
+            this.emit("accountError", accountId, errMsg, errMsg, isOAuth);
         }
     }
     /** Sync just INBOX for each account (fast check for new mail) */
@@ -855,6 +1035,8 @@ export class ImapManager extends EventEmitter {
             return;
         if (this.reauthenticating.has(accountId))
             return;
+        if (this.isGmailAccount(accountId))
+            return; // Gmail uses API sync, not IMAP polling
         this.quickCheckRunning.add(accountId);
         let client = null;
         try {
@@ -995,13 +1177,16 @@ export class ImapManager extends EventEmitter {
         const folder = this.db.getFolders(accountId).find(f => f.id === folderId);
         if (!folder)
             return null;
-        // Serialize: only one body fetch per account at a time (IMAP can only handle one command)
+        // Gmail: use API for body fetch (no IMAP connection needed)
+        if (this.isGmailAccount(accountId)) {
+            return this.fetchMessageBodyViaApi(accountId, folderId, uid, folder.path);
+        }
+        // IMAP: serialize — only one body fetch per account at a time
         return this.enqueueFetch(accountId, async () => {
             // Re-check cache — may have been fetched while queued
             if (await this.bodyStore.hasMessage(accountId, folderId, uid)) {
                 return this.bodyStore.getMessage(accountId, folderId, uid);
             }
-            // Body fetch uses a fresh connection — never waits behind background sync
             let client = null;
             try {
                 client = this.newClient(accountId);
@@ -1027,6 +1212,24 @@ export class ImapManager extends EventEmitter {
             }
         });
     }
+    /** Fetch message body via Gmail/Outlook API */
+    async fetchMessageBodyViaApi(accountId, folderId, uid, folderPath) {
+        try {
+            const api = this.getGmailProvider(accountId);
+            const msg = await api.fetchOne(folderPath, uid, { source: true });
+            await api.close();
+            if (!msg?.source)
+                return null;
+            const raw = Buffer.from(msg.source, "utf-8");
+            const bodyPath = await this.bodyStore.putMessage(accountId, folderId, uid, raw);
+            this.db.updateBodyPath(accountId, uid, bodyPath);
+            return raw;
+        }
+        catch (e) {
+            console.error(`  [api] Body fetch error (${accountId}/${uid}): ${e.message}`);
+            return null;
+        }
+    }
     /** Get the body store for direct access */
     getBodyStore() {
         return this.bodyStore;
@@ -1472,6 +1675,12 @@ export class ImapManager extends EventEmitter {
         const outboxFolder = this.findFolder(accountId, "outbox");
         if (!outboxFolder)
             return;
+        // Skip if this account's sync is failing — don't pile up connections
+        if (this.connectionBackoff.has(accountId) && Date.now() < (this.connectionBackoff.get(accountId) || 0))
+            return;
+        // Gmail uses SMTP for sending (not IMAP outbox) — skip IMAP outbox check
+        if (this.isGmailAccount(accountId))
+            return;
         const settings = loadSettings();
         const account = settings.accounts.find(a => a.id === accountId);
         if (!account)
@@ -1621,9 +1830,9 @@ export class ImapManager extends EventEmitter {
                     this.outboxBackoffDelay.delete(accountId);
                 }
                 catch (e) {
-                    // Exponential backoff: 30s → 60s → 120s → 300s (max 5min)
+                    // Exponential backoff: 60s → 120s → 300s (max 5min)
                     const prevDelay = this.outboxBackoffDelay.get(accountId) || 0;
-                    const delay = prevDelay ? Math.min(prevDelay * 2, 300000) : 30000;
+                    const delay = prevDelay ? Math.min(prevDelay * 2, 300000) : 60000;
                     this.outboxBackoffDelay.set(accountId, delay);
                     this.outboxBackoff.set(accountId, now + delay);
                     console.error(`  [outbox] Error for ${accountId}: ${imapError(e)} (retry in ${Math.round(delay / 1000)}s)`);

package/packages/mailx-imap/providers/gmail-api.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Gmail API provider — replaces IMAP for Gmail accounts.
+ * Uses REST API for fast, reliable sync without connection limit issues.
+ */
+import type { MailProvider, ProviderFolder, ProviderMessage, FetchOptions } from "./types.js";
+export declare class GmailApiProvider implements MailProvider {
+    private tokenProvider;
+    constructor(tokenProvider: () => Promise<string>);
+    private fetch;
+    listFolders(): Promise<ProviderFolder[]>;
+    /** List message IDs matching a query, handling pagination */
+    private listMessageIds;
+    /** Batch-fetch message metadata or full content */
+    private batchFetch;
+    /** Parse a Gmail API message response into ProviderMessage */
+    private parseMessage;
+    fetchSince(folder: string, sinceUid: number, options?: FetchOptions): Promise<ProviderMessage[]>;
+    fetchByDate(folder: string, since: Date, before: Date, options?: FetchOptions, onChunk?: (msgs: ProviderMessage[]) => void): Promise<ProviderMessage[]>;
+    fetchByUids(folder: string, uids: number[], options?: FetchOptions): Promise<ProviderMessage[]>;
+    fetchOne(folder: string, uid: number, options?: FetchOptions): Promise<ProviderMessage | null>;
+    getUids(folder: string): Promise<number[]>;
+    close(): Promise<void>;
+    /** Map folder path to Gmail label query term */
+    private folderToLabel;
+    /** Format date for Gmail query (YYYY/MM/DD) */
+    private formatDate;
+}
+//# sourceMappingURL=gmail-api.d.ts.map

package/packages/mailx-imap/providers/gmail-api.js

@@ -0,0 +1,227 @@
+/**
+ * Gmail API provider — replaces IMAP for Gmail accounts.
+ * Uses REST API for fast, reliable sync without connection limit issues.
+ */
+const API = "https://gmail.googleapis.com/gmail/v1/users/me";
+/** Convert Gmail hex ID to integer UID (lower 48 bits — deterministic, stable) */
+function idToUid(id) {
+    const hex = id.length > 12 ? id.slice(-12) : id;
+    return parseInt(hex, 16);
+}
+/** Map Gmail label to IMAP-style specialUse */
+function labelSpecialUse(label) {
+    switch (label.id) {
+        case "INBOX": return "inbox";
+        case "SENT": return "sent";
+        case "DRAFT": return "drafts";
+        case "TRASH": return "trash";
+        case "SPAM": return "junk";
+        case "STARRED": return "";
+        case "IMPORTANT": return "";
+        default: return "";
+    }
+}
+/** Parse RFC 2822 headers from Gmail metadata payload */
+function getHeader(headers, name) {
+    return headers.find(h => h.name.toLowerCase() === name.toLowerCase())?.value || "";
+}
+/** Parse "Name <addr>" or "addr" into { name, address } */
+function parseAddress(raw) {
+    const match = raw.match(/^"?([^"<]*?)"?\s*<([^>]+)>/);
+    if (match)
+        return { name: match[1].trim(), address: match[2].trim() };
+    return { address: raw.trim() };
+}
+function parseAddressList(raw) {
+    if (!raw)
+        return [];
+    // Split on commas that aren't inside quotes
+    return raw.split(/,(?=(?:[^"]*"[^"]*")*[^"]*$)/).map(s => parseAddress(s.trim())).filter(a => a.address);
+}
+export class GmailApiProvider {
+    tokenProvider;
+    constructor(tokenProvider) {
+        this.tokenProvider = tokenProvider;
+    }
+    async fetch(path, options = {}) {
+        const token = await this.tokenProvider();
+        const res = await globalThis.fetch(`${API}${path}`, {
+            ...options,
+            headers: {
+                "Authorization": `Bearer ${token}`,
+                "Content-Type": "application/json",
+                ...options.headers,
+            },
+        });
+        if (!res.ok) {
+            const err = await res.text().catch(() => "");
+            throw new Error(`Gmail API ${res.status}: ${err.substring(0, 200)}`);
+        }
+        return res.json();
+    }
+    async listFolders() {
+        const data = await this.fetch("/labels");
+        const labels = data.labels || [];
+        const folders = [];
+        for (const label of labels) {
+            // Skip system labels that aren't useful as folders
+            if (["UNREAD", "STARRED", "IMPORTANT", "CATEGORY_PERSONAL",
+                "CATEGORY_SOCIAL", "CATEGORY_PROMOTIONS", "CATEGORY_UPDATES",
+                "CATEGORY_FORUMS", "CHAT"].includes(label.id))
+                continue;
+            const specialUse = labelSpecialUse(label);
+            // Map Gmail path separators (/) to IMAP-style
+            const path = label.name || label.id;
+            const name = path.includes("/") ? path.split("/").pop() : path;
+            folders.push({
+                path,
+                name,
+                delimiter: "/",
+                specialUse,
+                flags: label.type === "system" ? ["\\Noselect"] : [],
+            });
+        }
+        return folders;
+    }
+    /** List message IDs matching a query, handling pagination */
+    async listMessageIds(query, maxResults = 500) {
+        const ids = [];
+        let pageToken = "";
+        while (true) {
+            const params = new URLSearchParams({ q: query, maxResults: String(Math.min(maxResults - ids.length, 500)) });
+            if (pageToken)
+                params.set("pageToken", pageToken);
+            const data = await this.fetch(`/messages?${params}`);
+            for (const msg of data.messages || []) {
+                ids.push(msg.id);
+            }
+            if (!data.nextPageToken || ids.length >= maxResults)
+                break;
+            pageToken = data.nextPageToken;
+        }
+        return ids;
+    }
+    /** Batch-fetch message metadata or full content */
+    async batchFetch(ids, options = {}, onChunk) {
+        const all = [];
+        const chunkSize = options.source ? 10 : 50; // Smaller chunks for full bodies
+        const format = options.source ? "raw" : "metadata";
+        const metadataHeaders = "From,To,Cc,Subject,Message-ID,Date";
+        for (let i = 0; i < ids.length; i += chunkSize) {
+            const chunk = ids.slice(i, i + chunkSize);
+            const messages = await Promise.all(chunk.map(id => {
+                const params = new URLSearchParams({ format });
+                if (format === "metadata")
+                    params.set("metadataHeaders", metadataHeaders);
+                return this.fetch(`/messages/${id}?${params}`);
+            }));
+            const parsed = messages.map(msg => this.parseMessage(msg, options));
+            all.push(...parsed);
+            if (onChunk)
+                onChunk(parsed);
+        }
+        return all;
+    }
+    /** Parse a Gmail API message response into ProviderMessage */
+    parseMessage(msg, options = {}) {
+        const labels = msg.labelIds || [];
+        const headers = msg.payload?.headers || [];
+        let source = "";
+        if (options.source && msg.raw) {
+            // Gmail returns URL-safe base64 — convert to standard base64 then decode
+            const base64 = msg.raw.replace(/-/g, "+").replace(/_/g, "/");
+            source = Buffer.from(base64, "base64").toString("utf-8");
+        }
+        const fromRaw = getHeader(headers, "From");
+        const toRaw = getHeader(headers, "To");
+        const ccRaw = getHeader(headers, "Cc");
+        const dateRaw = getHeader(headers, "Date") || "";
+        const subject = getHeader(headers, "Subject") || msg.snippet || "";
+        const messageId = getHeader(headers, "Message-ID") || "";
+        return {
+            uid: idToUid(msg.id),
+            messageId,
+            providerId: msg.id,
+            date: dateRaw ? new Date(dateRaw) : (msg.internalDate ? new Date(Number(msg.internalDate)) : null),
+            subject,
+            from: parseAddressList(fromRaw),
+            to: parseAddressList(toRaw),
+            cc: parseAddressList(ccRaw),
+            seen: !labels.includes("UNREAD"),
+            flagged: labels.includes("STARRED"),
+            answered: false, // Gmail API doesn't expose this directly
+            draft: labels.includes("DRAFT"),
+            size: msg.sizeEstimate || 0,
+            source,
+        };
+    }
+    async fetchSince(folder, sinceUid, options = {}) {
+        // Gmail doesn't have UIDs — use date-based query for incremental
+        // For now, fetch recent messages and let the caller filter by UID
+        const query = `in:${this.folderToLabel(folder)}`;
+        const ids = await this.listMessageIds(query, 200);
+        const messages = await this.batchFetch(ids, options);
+        return messages.filter(m => m.uid > sinceUid);
+    }
+    async fetchByDate(folder, since, before, options = {}, onChunk) {
+        const afterDate = this.formatDate(since);
+        const beforeDate = this.formatDate(before);
+        const query = `in:${this.folderToLabel(folder)} after:${afterDate} before:${beforeDate}`;
+        const ids = await this.listMessageIds(query);
+        return this.batchFetch(ids, options, onChunk);
+    }
+    async fetchByUids(folder, uids, options = {}) {
+        // UIDs are derived from Gmail IDs — we'd need a reverse lookup
+        // For now, fetch all messages in folder and filter
+        const query = `in:${this.folderToLabel(folder)}`;
+        const ids = await this.listMessageIds(query);
+        const uidSet = new Set(uids);
+        const matchingIds = ids.filter(id => uidSet.has(idToUid(id)));
+        return this.batchFetch(matchingIds, options);
+    }
+    async fetchOne(folder, uid, options = {}) {
+        // Need to find the Gmail ID from the UID — search all messages in folder
+        const query = `in:${this.folderToLabel(folder)}`;
+        const ids = await this.listMessageIds(query, 1000);
+        const id = ids.find(id => idToUid(id) === uid);
+        if (!id)
+            return null;
+        const format = options.source ? "raw" : "metadata";
+        const params = new URLSearchParams({ format });
+        if (format === "metadata")
+            params.set("metadataHeaders", "From,To,Cc,Subject,Message-ID,Date");
+        const msg = await this.fetch(`/messages/${id}?${params}`);
+        return this.parseMessage(msg, options);
+    }
+    async getUids(folder) {
+        const query = `in:${this.folderToLabel(folder)}`;
+        const ids = await this.listMessageIds(query, 10000);
+        return ids.map(idToUid);
+    }
+    async close() {
+        // No persistent connection to close
+    }
+    /** Map folder path to Gmail label query term */
+    folderToLabel(path) {
+        const lower = path.toLowerCase();
+        if (lower === "inbox")
+            return "inbox";
+        if (lower === "sent" || lower === "[gmail]/sent mail")
+            return "sent";
+        if (lower === "drafts" || lower === "[gmail]/drafts")
+            return "drafts";
+        if (lower === "trash" || lower === "[gmail]/trash")
+            return "trash";
+        if (lower === "spam" || lower === "[gmail]/spam" || lower === "junk email")
+            return "spam";
+        if (lower === "archive" || lower === "[gmail]/all mail")
+            return "all";
+        // Custom label — use exact name
+        return `"${path}"`;
+    }
+    /** Format date for Gmail query (YYYY/MM/DD) */
+    formatDate(d) {
+        return `${d.getFullYear()}/${String(d.getMonth() + 1).padStart(2, "0")}/${String(d.getDate()).padStart(2, "0")}`;
+    }
+}
+//# sourceMappingURL=gmail-api.js.map

package/packages/mailx-imap/providers/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Mail provider interface — abstraction over IMAP, Gmail API, and Microsoft Graph.
+ * Sync code uses this interface; never calls IMAP/REST directly.
+ */
+export interface ProviderFolder {
+    path: string;
+    name: string;
+    delimiter: string;
+    specialUse: string;
+    flags: string[];
+}
+export interface ProviderMessage {
+    uid: number;
+    messageId: string;
+    providerId: string;
+    date: Date | null;
+    subject: string;
+    from: {
+        name?: string;
+        address?: string;
+    }[];
+    to: {
+        name?: string;
+        address?: string;
+    }[];
+    cc: {
+        name?: string;
+        address?: string;
+    }[];
+    seen: boolean;
+    flagged: boolean;
+    answered: boolean;
+    draft: boolean;
+    size: number;
+    source: string;
+}
+export interface FetchOptions {
+    source?: boolean;
+}
+/**
+ * A mail provider that can list folders, fetch messages, and perform actions.
+ * Implementations: ImapProvider (existing iflow), GmailApiProvider, GraphApiProvider.
+ */
+export interface MailProvider {
+    /** List all folders/labels */
+    listFolders(): Promise<ProviderFolder[]>;
+    /** Fetch messages newer than sinceUid (incremental sync) */
+    fetchSince(folder: string, sinceUid: number, options?: FetchOptions): Promise<ProviderMessage[]>;
+    /** Fetch messages by date range (first sync) */
+    fetchByDate(folder: string, since: Date, before: Date, options?: FetchOptions, onChunk?: (msgs: ProviderMessage[]) => void): Promise<ProviderMessage[]>;
+    /** Fetch specific messages by UID */
+    fetchByUids(folder: string, uids: number[], options?: FetchOptions): Promise<ProviderMessage[]>;
+    /** Fetch a single message by UID */
+    fetchOne(folder: string, uid: number, options?: FetchOptions): Promise<ProviderMessage | null>;
+    /** Get all UIDs in a folder (for reconciliation) */
+    getUids(folder: string): Promise<number[]>;
+    /** Close/cleanup */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/packages/mailx-imap/providers/types.js

@@ -0,0 +1,6 @@
+/**
+ * Mail provider interface — abstraction over IMAP, Gmail API, and Microsoft Graph.
+ * Sync code uses this interface; never calls IMAP/REST directly.
+ */
+export {};
+//# sourceMappingURL=types.js.map