@bobfrankston/mailx 1.0.362 → 1.0.368

package/bin/mailx.js

@@ -1284,11 +1284,32 @@ RFC 5322 with CRLF line endings. Bodies are quoted-printable encoded (readable i
     if (settings.accounts.some(a => a.enabled)) {
         imapManager.syncAll()
             .then(() => imapManager.startWatching())
+            .then(() => {
+            // Seed the contacts table from received messages so address
+            // autocomplete works on the first compose without waiting for
+            // the user to manually trigger it. Cheap — one grouped SELECT
+            // + one INSERT per new sender. No-op if contact already exists.
+            const added = db.seedContactsFromMessages();
+            if (added > 0)
+                console.log(`  [contacts] seeded ${added} from message senders`);
+        })
             .catch(e => console.error(`  Sync error: ${e.message}`));
     }
     imapManager.startPeriodicSync(settings.sync.intervalMinutes);
     imapManager.startOutboxWorker();
     imapManager.watchConfigFiles();
+    // Re-seed contacts every 30 min so newly-received senders surface in
+    // autocomplete without restarting mailx. Cheap; idempotent.
+    setInterval(() => {
+        try {
+            const added = db.seedContactsFromMessages();
+            if (added > 0)
+                console.log(`  [contacts] periodic seed added ${added} new senders`);
+        }
+        catch (e) {
+            console.error(`  [contacts] periodic seed error: ${e.message}`);
+        }
+    }, 30 * 60_000);
     // Auto-update: periodically check npm for a newer version and push a
     // notification to the WebView so the user can update with one click.
     const UPDATE_CHECK_MS = 30 * 60_000; // 30 minutes

package/client/app.js

@@ -240,6 +240,11 @@ let currentFolderSpecialUse = "";
 function clearViewer() {
     messageState.select(null); // Deselect — viewer clears via subscription
 }
+// Anyone can ask the viewer to clear by dispatching a `mailx-clear-viewer`
+// CustomEvent on document. Used by message-list's loadSearchResults so the
+// stale preview from the prior selection doesn't linger over the new search
+// results. Slice D will replace this with row-object-level `unfocus()`.
+document.addEventListener("mailx-clear-viewer", () => clearViewer());
 const folderTitleEl = document.getElementById("ml-folder-title");
 let currentFolderName = "";
 let currentFolderSyncedAt;
@@ -1436,10 +1441,22 @@ onWsEvent((event) => {
             // Don't refresh folder tree on connect — it's already loaded by initFolderTree
             break;
         case "syncProgress": {
+            // Aggregate folders phases ("folders:<path>" when starting a folder,
+            // "folders-done" between folders) print as a proportion so the user
+            // can see forward progress instead of a meaningless "47%". Older
+            // phase strings ("sync:<path>", "folders") still render raw.
+            let label = `${event.phase} ${event.progress || 0}%`;
+            if (typeof event.phase === "string" && event.phase.startsWith("folders:")) {
+                const folderPath = event.phase.slice("folders:".length);
+                label = `folders — ${folderPath} (${event.progress || 0}%)`;
+            }
+            else if (event.phase === "folders-done") {
+                label = `folders ${event.progress || 0}% done`;
+            }
             if (statusSync)
-                statusSync.textContent = `Syncing ${event.accountId}: ${event.phase} ${event.progress || 0}%`;
+                statusSync.textContent = `Syncing ${event.accountId}: ${label}`;
             if (startupStatus)
-                startupStatus.textContent = `Syncing ${event.accountId}: ${event.phase}`;
+                startupStatus.textContent = `Syncing ${event.accountId}: ${label}`;
             // Mark syncing folder in tree — bubble up to visible parent if collapsed
             const syncPath = event.phase?.startsWith("sync:") ? event.phase.slice(5) : null;
             // Clear previous syncing markers for this account
@@ -2551,20 +2568,56 @@ function renderOutboxStatus(s) {
 }
 setInterval(async () => {
     try {
-        const { getOutboxStatus } = await import("./lib/api-client.js");
-        const s = await getOutboxStatus();
-        renderOutboxStatus(s);
+        const { getOutboxStatus, getDiagnostics } = await import("./lib/api-client.js");
+        renderOutboxStatus(await getOutboxStatus());
+        renderDiagnosticsBadge(await getDiagnostics());
     }
     catch { /* service unreachable */ }
 }, 15000);
 // First read on startup so the bar isn't blank.
 (async () => {
     try {
-        const { getOutboxStatus } = await import("./lib/api-client.js");
+        const { getOutboxStatus, getDiagnostics } = await import("./lib/api-client.js");
         renderOutboxStatus(await getOutboxStatus());
+        renderDiagnosticsBadge(await getDiagnostics());
     }
     catch { /* */ }
 })();
+/** Render the ⚠ "something's wrong" badge next to status-sync. Shown when
+ *  any account has non-zero diagnostic counters (inactivity timeouts,
+ *  connection-cap hits, rate-limit waits). Tooltip breaks down per-account. */
+function renderDiagnosticsBadge(snapshot) {
+    const host = document.getElementById("status-diag");
+    if (!host)
+        return;
+    const issues = (snapshot || []).filter(d => d.inactivityTimeouts > 0 || d.connCapHits > 0 || d.rateLimitWaits > 0);
+    if (issues.length === 0) {
+        host.hidden = true;
+        host.textContent = "";
+        host.title = "";
+        return;
+    }
+    host.hidden = false;
+    host.textContent = "⚠";
+    const totalTimeouts = issues.reduce((a, d) => a + d.inactivityTimeouts, 0);
+    const totalCapHits = issues.reduce((a, d) => a + d.connCapHits, 0);
+    const totalRateLimits = issues.reduce((a, d) => a + d.rateLimitWaits, 0);
+    const summary = [
+        totalTimeouts > 0 ? `${totalTimeouts} IMAP inactivity timeout${totalTimeouts === 1 ? "" : "s"}` : null,
+        totalCapHits > 0 ? `${totalCapHits} conn-cap rejection${totalCapHits === 1 ? "" : "s"}` : null,
+        totalRateLimits > 0 ? `${totalRateLimits} rate-limit wait${totalRateLimits === 1 ? "" : "s"}` : null,
+    ].filter(Boolean).join("; ");
+    const detail = issues.map(d => {
+        const parts = [
+            d.inactivityTimeouts > 0 ? `${d.inactivityTimeouts} timeout${d.inactivityTimeouts === 1 ? "" : "s"}` : null,
+            d.connCapHits > 0 ? `${d.connCapHits} conn-cap` : null,
+            d.rateLimitWaits > 0 ? `${d.rateLimitWaits} rate-limit` : null,
+        ].filter(Boolean).join(", ");
+        const last = d.lastCommand ? `\n  last: ${d.lastCommand}` : "";
+        return `${d.accountId}: ${parts}${last}`;
+    }).join("\n");
+    host.title = `Connection issues — ${summary}\n\n${detail}`;
+}
 // Q64: pop-out a message into a floating overlay (real-OS-window pending C44).
 document.addEventListener("mailx-popout-message", (async (e) => {
     const { accountId, uid, folderId, subject } = e.detail || {};

package/client/components/message-list.js

@@ -220,6 +220,11 @@ export async function loadSearchResults(query, scope = "all", accountId = "", fo
     const body = document.getElementById("ml-body");
     if (!body)
         return;
+    // Clear the preview pane — old preview from the prior selection lingers
+    // until the user clicks a search result. Atomic clear-on-list-mutation
+    // is what Slice D's row-objects-own-preview will do generally; this is
+    // the band-aid for the search-specific case until that lands.
+    document.dispatchEvent(new CustomEvent("mailx-clear-viewer"));
     body.innerHTML = `<div class="ml-empty">Searching...</div>`;
     try {
         // Regex search: filter client-side
@@ -455,6 +460,10 @@ function appendMessages(body, accountId, items) {
             row.classList.add("flagged");
         if (!msg.bodyPath)
             row.classList.add("not-downloaded");
+        // Pink-row visible reconciliation state (S1 slice C): a queued local
+        // action (move/flag/delete) hasn't been ACK'd by the server yet.
+        if (msg.pending)
+            row.classList.add("pending-reconcile");
         row.dataset.uid = String(msg.uid);
         row.dataset.accountId = msgAccountId;
         row.dataset.folderId = String(msg.folderId);

package/client/components/message-viewer.js

@@ -34,7 +34,17 @@ export function initViewer() {
                 clearViewer();
             }
         }
-        // "messages" change (sync reload) — don't touch the viewer
+        else if (change === "messages") {
+            // List was replaced (search, folder switch, sync reload). If the
+            // currently-displayed message is no longer in the list, clear the
+            // viewer — otherwise the user sees a preview that doesn't match
+            // any visible row. (The "search-clears-preview" bug class.)
+            // setMessages already deselects in this case; we just need to
+            // notice and clear here since the viewer ignored "messages" before.
+            if (currentMessage && !state.getSelected()) {
+                clearViewer();
+            }
+        }
     });
 }
 // Zoom is persisted across messages via localStorage

package/client/index.html

@@ -157,6 +157,7 @@
     <footer class="status-bar" id="status-bar">
         <span id="status-accounts"></span>
         <span id="status-sync">Syncing...</span>
+        <span id="status-diag" class="status-diag" hidden title=""></span>
         <span id="status-pending"></span>
         <span id="status-queue"></span>
         <span class="app-version" id="status-version">mailx</span>

package/client/lib/api-client.js

@@ -131,6 +131,9 @@ export function reauthenticate(accountId) {
 export function getSyncPending() {
     return ipc().getSyncPending();
 }
+export function getDiagnostics() {
+    return ipc().getDiagnostics?.() ?? Promise.resolve([]);
+}
 export function getOutboxStatus() {
     return ipc().getOutboxStatus();
 }

package/client/lib/mailxapi.js

@@ -159,6 +159,7 @@
         syncAccount: function(accountId) { return callNode("syncAccount", { accountId: accountId }); },
         getSyncPending: function() { return callNode("getSyncPending"); },
         getOutboxStatus: function() { return callNode("getOutboxStatus"); },
+        getDiagnostics: function() { return callNode("getDiagnostics"); },
         listQueuedOutgoing: function() { return callNode("listQueuedOutgoing"); },
         cancelQueuedOutgoing: function(p) { return callNode("cancelQueuedOutgoing", { path: p }); },
         reauthenticate: function(accountId) { return callNode("reauthenticate", { accountId: accountId }); },

package/client/styles/components.css

@@ -779,6 +779,17 @@ button.tb-menu-item { background: none; border: none; color: inherit; width: 100
     opacity: 0.5;
 }
 
+/* S1 slice C — pink row when a local action (move/flag/delete) is queued
+   but the server hasn't ACK'd. Visible reconciliation state: "we did your
+   thing locally, the server hasn't agreed yet." Selection still wins
+   visually so the active row is identifiable. */
+.ml-row.pending-reconcile {
+    background: oklch(0.96 0.04 350);  /* pale pink */
+}
+.ml-row.pending-reconcile.selected {
+    background: oklch(0.85 0.10 350);  /* deeper pink when selected */
+}
+
 .ml-empty {
     grid-column: 1 / -1;
     display: flex;
@@ -1072,6 +1083,15 @@ button.tb-menu-item { background: none; border: none; color: inherit; width: 100
     font-size: var(--font-size-sm);
     color: var(--color-text-muted);
 }
+
+/* Diagnostics ⚠ badge next to status-sync — inactivity timeouts and similar
+   server-misbehavior counters. Hover for per-account detail. */
+.status-diag {
+    color: oklch(0.70 0.18 55);  /* amber */
+    cursor: help;
+    font-size: var(--font-size-base);
+    margin-left: calc(var(--gap-xs) * -1);
+}
 .status-action {
     border: 1px solid oklch(0.65 0.15 25);
     background: transparent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx",
-  "version": "1.0.362",
+  "version": "1.0.368",
   "description": "Local-first email client with IMAP sync and standalone native app",
   "type": "module",
   "main": "bin/mailx.js",

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

@@ -57,6 +57,7 @@ export declare function getMessage(params: {
     folderId: number;
     folderName?: string;
     uid: number;
+    uuid?: string;
     messageId: string;
     inReplyTo: string;
     references: string[];
@@ -72,6 +73,7 @@ export declare function getMessage(params: {
     preview: string;
     bodyPath?: string;
     providerId?: string;
+    pending?: boolean;
 }>;
 export declare function updateFlags(params: {
     accountId: string;

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

@@ -28,6 +28,20 @@ export interface ImapManagerEvents {
      *  queue-status indicator without polling. Aggregate status across all
      *  accounts is included so the listener doesn't have to reassemble it. */
     outboxStatus: (status: OutboxStatus) => void;
+    /** Per-account health counter update. Fires when an inactivity timeout,
+     *  connection-cap hit, or rate-limit wait happens. */
+    diagnostics: (accountId: string, snapshot: AccountDiagnostics) => void;
+}
+/** Per-account diagnostic counters — tracks "something's wrong" events the
+ *  user should be able to see without opening the log. */
+export interface AccountDiagnostics {
+    accountId: string;
+    inactivityTimeouts: number;
+    connCapHits: number;
+    rateLimitWaits: number;
+    lastTimeoutAt: number;
+    lastCommand: string;
+    lastError: string;
 }
 /** Per-account outbox queue breakdown, plus totals for the UI. */
 export interface OutboxStatus {
@@ -57,6 +71,19 @@ export declare class ImapManager extends EventEmitter {
     useNativeClient: boolean;
     /** Accounts hitting connection limits — back off until this time */
     private connectionBackoff;
+    /** Per-account health counters. Incremented when the server misbehaves
+     *  in ways that suggest a problem the user should know about (inactivity
+     *  timeouts, connection-cap hits, rate-limit waits). Surfaced via a
+     *  `diagnostics` event + `getDiagnostics` IPC so the UI can show a ⚠
+     *  badge instead of burying the issue in the log. */
+    private diagnostics;
+    private getDiagnosticsEntry;
+    /** Classify an error message and bump the relevant counter; emit the
+     *  updated diagnostics snapshot. Call this from every catch in the sync
+     *  paths so the UI can count "something's wrong" in real time. */
+    private recordError;
+    /** Public read for the IPC surface: snapshot of all account diagnostics. */
+    getDiagnosticsSnapshot(): AccountDiagnostics[];
     private transportFactory;
     constructor(db: MailxDB, transportFactory: TransportFactory);
     /** Get OAuth access token for an account (for SMTP auth) */

package/packages/mailx-imap/index.js

@@ -148,6 +148,48 @@ export class ImapManager extends EventEmitter {
     /** Accounts hitting connection limits — back off until this time */
     connectionBackoff = new Map();
     // Connection management: see withConnection() below — no semaphore needed
+    /** Per-account health counters. Incremented when the server misbehaves
+     *  in ways that suggest a problem the user should know about (inactivity
+     *  timeouts, connection-cap hits, rate-limit waits). Surfaced via a
+     *  `diagnostics` event + `getDiagnostics` IPC so the UI can show a ⚠
+     *  badge instead of burying the issue in the log. */
+    diagnostics = new Map();
+    getDiagnosticsEntry(accountId) {
+        let d = this.diagnostics.get(accountId);
+        if (!d) {
+            d = { accountId, inactivityTimeouts: 0, connCapHits: 0, rateLimitWaits: 0, lastTimeoutAt: 0, lastCommand: "", lastError: "" };
+            this.diagnostics.set(accountId, d);
+        }
+        return d;
+    }
+    /** Classify an error message and bump the relevant counter; emit the
+     *  updated diagnostics snapshot. Call this from every catch in the sync
+     *  paths so the UI can count "something's wrong" in real time. */
+    recordError(accountId, errMsg) {
+        const d = this.getDiagnosticsEntry(accountId);
+        if (/inactivity timeout/i.test(errMsg)) {
+            d.inactivityTimeouts++;
+            d.lastTimeoutAt = Date.now();
+            const m = errMsg.match(/A\d+ [A-Z ]+.*$/);
+            if (m)
+                d.lastCommand = m[0].slice(0, 120);
+        }
+        else if (/UNAVAILABLE|Maximum number of connections|too many connections/i.test(errMsg)) {
+            d.connCapHits++;
+        }
+        else if (/429|rate limit/i.test(errMsg)) {
+            d.rateLimitWaits++;
+        }
+        else {
+            return; // not a known diagnostic class — don't emit
+        }
+        d.lastError = errMsg.slice(0, 200);
+        this.emit("diagnostics", accountId, { ...d });
+    }
+    /** Public read for the IPC surface: snapshot of all account diagnostics. */
+    getDiagnosticsSnapshot() {
+        return Array.from(this.diagnostics.values()).map(d => ({ ...d }));
+    }
     transportFactory;
     constructor(db, transportFactory) {
         super();
@@ -1080,47 +1122,77 @@ export class ImapManager extends EventEmitter {
             else {
                 console.log(`  [sync] ${accountId}: no INBOX folder found`);
             }
-            // Step 3: Sync remaining folders
+            // Step 3: Sync remaining folders.
+            //
+            // Parallel pool (concurrency 2) with a per-folder wall-clock cap.
+            // Previous serial loop meant one slow Dovecot UID FETCH could park
+            // every other folder behind it for minutes — user observed "mailx
+            // says synced but 90 folders are empty" because the loop never
+            // progressed past the stalled FETCH before the next sync tick.
+            //
+            // Parallelism uses independent IMAP sockets from the ops-client
+            // pool, so one stalled socket doesn't block the others. The 60s
+            // timeout abandons a stalled command instead of waiting out
+            // Dovecot's 300s server-side inactivity timer; the next sync tick
+            // retries on a fresh socket.
             const remaining = folders.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;
             });
-            let consecutiveErrors = 0;
-            for (const folder of remaining) {
+            const CONCURRENCY = 2;
+            const PER_FOLDER_TIMEOUT_MS = 60_000;
+            const total = remaining.length;
+            let done = 0;
+            let idx = 0;
+            const syncOne = async (folder) => {
                 const isTrashChild = folder.path.includes("/") && folder.path.toLowerCase().startsWith("trash");
                 const highestUid = this.db.getHighestUid(accountId, folder.id);
                 if (isTrashChild && highestUid === 0)
-                    continue;
+                    return;
                 try {
-                    client = await this.getOpsClient(accountId);
-                    await this.syncFolder(accountId, folder.id, client);
-                    consecutiveErrors = 0;
+                    const fresh = await this.getOpsClient(accountId);
+                    await Promise.race([
+                        this.syncFolder(accountId, folder.id, fresh),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error(`per-folder timeout (${PER_FOLDER_TIMEOUT_MS / 1000}s): ${folder.path}`)), PER_FOLDER_TIMEOUT_MS)),
+                    ]);
                 }
                 catch (e) {
-                    consecutiveErrors++;
                     if (e.responseText?.includes("doesn't exist")) {
                         this.db.deleteFolder(folder.id);
                     }
                     else {
                         console.error(`  Skipping ${folder.path}: ${e.message}`);
-                        // Connection is probably dead — reconnect
-                        await this.reconnectOps(accountId);
-                    }
-                    // Too many consecutive errors = connection fundamentally broken
-                    if (consecutiveErrors >= 3) {
-                        console.error(`  [sync] ${accountId}: ${consecutiveErrors} consecutive errors — aborting sync`);
-                        break;
+                        this.recordError(accountId, e.message || String(e));
+                        // A timeout or stale-socket failure — drop the ops
+                        // client so the next iteration reconnects rather than
+                        // inheriting the doomed socket.
+                        await this.reconnectOps(accountId).catch(() => { });
                     }
                 }
-            }
+            };
+            const worker = async () => {
+                while (true) {
+                    const myIdx = idx++;
+                    if (myIdx >= remaining.length)
+                        return;
+                    const folder = remaining[myIdx];
+                    this.emit("syncProgress", accountId, `folders:${folder.path}`, Math.round((done / Math.max(total, 1)) * 100));
+                    await syncOne(folder);
+                    done++;
+                    this.emit("syncProgress", accountId, `folders-done`, Math.round((done / Math.max(total, 1)) * 100));
+                    console.log(`  [sync] ${accountId}: folder ${done}/${total} done (${folder.path})`);
+                }
+            };
+            await Promise.all(Array.from({ length: Math.min(CONCURRENCY, remaining.length) }, () => worker()));
             this.accountErrorShown.delete(accountId);
             this.emit("syncComplete", accountId);
         }
         catch (e) {
             const errMsg = imapError(e);
             this.emit("syncError", accountId, errMsg);
+            this.recordError(accountId, errMsg);
             console.error(`Sync error for ${accountId}: ${errMsg}`);
             this.handleSyncError(accountId, errMsg);
         }

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

@@ -36,6 +36,9 @@ export declare class MailxService {
     };
     /** Outbox queue depth + retry status for the UI status bar. Cheap to call. */
     getOutboxStatus(): any;
+    /** Per-account health snapshot: inactivity-timeout count, conn-cap hits,
+     *  last failed IMAP command. Drives the diagnostics ⚠ badge in the UI. */
+    getDiagnostics(): any;
     /** List queued outgoing messages with parsed envelope headers so the UI
      *  can render a pink-row "pending" view before IMAP APPEND succeeds. */
     listQueuedOutgoing(): any[];

package/packages/mailx-service/index.js

@@ -413,6 +413,11 @@ export class MailxService {
     getOutboxStatus() {
         return this.imapManager.getOutboxStatus();
     }
+    /** Per-account health snapshot: inactivity-timeout count, conn-cap hits,
+     *  last failed IMAP command. Drives the diagnostics ⚠ badge in the UI. */
+    getDiagnostics() {
+        return this.imapManager.getDiagnosticsSnapshot();
+    }
     /** List queued outgoing messages with parsed envelope headers so the UI
      *  can render a pink-row "pending" view before IMAP APPEND succeeds. */
     listQueuedOutgoing() {
@@ -822,6 +827,14 @@ export class MailxService {
         if (!folder)
             throw new Error("Folder not found");
         this.db.deleteAllMessages(accountId, folderId);
+        // Recalc + broadcast so the folder-tree badge drops to 0 immediately.
+        // Without this, the badge kept showing the old unread count even
+        // though the list was empty (user-reported bug).
+        this.db.recalcFolderCounts(folderId);
+        try {
+            this.imapManager.emit?.("folderCountsChanged", accountId, {});
+        }
+        catch { /* non-fatal */ }
         const client = this.imapManager.createPublicClient(accountId);
         try {
             const uids = await client.getUids(folder.path);

package/packages/mailx-service/jsonrpc.js

@@ -94,6 +94,8 @@ async function dispatchAction(svc, action, p) {
             return { ok: true };
         case "getSyncPending":
             return svc.getSyncPending();
+        case "getDiagnostics":
+            return svc.getDiagnostics();
         case "getOutboxStatus":
             return svc.getOutboxStatus();
         case "listQueuedOutgoing":

package/packages/mailx-store/db.d.ts

@@ -7,6 +7,10 @@ import type { MessageEnvelope, Folder, EmailAddress, PagedResult, MessageQuery }
 export declare class MailxDB {
     private db;
     constructor(dbDir: string);
+    /** One-time: assign UUIDs to every `messages` row that's missing one.
+     *  Runs on every startup but the WHERE clause makes it a no-op after the
+     *  first pass. */
+    private backfillUuids;
     /** Has this Message-ID already been sent? Used to prevent the outbox from
      *  re-sending the same raw file across crash/restart cycles. */
     hasSentMessage(messageId: string): boolean;
@@ -85,7 +89,17 @@ export declare class MailxDB {
     getMessages(query: MessageQuery): PagedResult<MessageEnvelope>;
     /** Unified inbox: all inbox folders across accounts, sorted by date, paginated in SQL */
     getUnifiedInbox(page?: number, pageSize?: number): PagedResult<MessageEnvelope>;
+    /** Map a `messages` row to a MessageEnvelope. Exposes `uuid` (stable local
+     *  identity) and `bodyPath` (authoritative on-disk location) in addition
+     *  to the server-binding metadata. */
+    private rowToEnvelope;
     getMessageByUid(accountId: string, uid: number, folderId?: number): MessageEnvelope;
+    /** Look up a message by its stable local UUID. Returned envelope includes
+     *  the current (folder_id, uid) — these may have changed since the UUID
+     *  was minted (folder move or server UID renumber) but the UUID itself
+     *  is stable. Use this as the identity in any long-lived reference
+     *  (compose in-reply-to, dally, undo stacks). */
+    getMessageByUuid(uuid: string): MessageEnvelope;
     getMessageBodyPath(accountId: string, uid: number): string;
     updateMessageFlags(accountId: string, uid: number, flags: string[]): void;
     updateMessageFolder(accountId: string, uid: number, targetFolderId: number): void;

package/packages/mailx-store/db.js

@@ -4,6 +4,7 @@
  * Message bodies are NOT here -- they live in the MessageStore backend.
  */
 import { DatabaseSync } from "node:sqlite";
+import { randomUUID } from "node:crypto";
 import * as path from "node:path";
 import * as fs from "node:fs";
 const SCHEMA = `
@@ -166,6 +167,46 @@ export class MailxDB {
         // directly instead of paginating listMessageIds for every body fetch
         // — a UID-only path costs 2-3 rate-limited API calls per message.
         this.addColumnIfMissing("messages", "provider_id", "TEXT");
+        // uuid: stable per-message local identity. Assigned the first time
+        // mailx sees the message and never changes — survives server UID
+        // renumbers, UIDVALIDITY bumps, and cross-folder moves (the sync
+        // rebinds the (folder_id, uid) tuple but keeps the UUID). All UI
+        // references SHOULD flow through uuid; (account_id, folder_id, uid)
+        // remains the server-binding metadata used only by sync.
+        this.addColumnIfMissing("messages", "uuid", "TEXT");
+        try {
+            this.db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_messages_uuid ON messages(uuid)");
+        }
+        catch { /* already exists */ }
+        // Backfill UUIDs for any pre-existing rows that were inserted before
+        // this column landed. One UPDATE + an id roundtrip per row — cheap
+        // at our row counts, runs once per DB upgrade.
+        this.backfillUuids();
+    }
+    /** One-time: assign UUIDs to every `messages` row that's missing one.
+     *  Runs on every startup but the WHERE clause makes it a no-op after the
+     *  first pass. */
+    backfillUuids() {
+        try {
+            const rows = this.db.prepare("SELECT id FROM messages WHERE uuid IS NULL OR uuid = ''").all();
+            if (rows.length === 0)
+                return;
+            console.log(`  [db] backfilling ${rows.length} message UUIDs`);
+            const upd = this.db.prepare("UPDATE messages SET uuid = ? WHERE id = ?");
+            this.db.exec("BEGIN");
+            try {
+                for (const r of rows)
+                    upd.run(randomUUID().replace(/-/g, ""), r.id);
+                this.db.exec("COMMIT");
+            }
+            catch (e) {
+                this.db.exec("ROLLBACK");
+                throw e;
+            }
+        }
+        catch (e) {
+            console.error(`  [db] backfillUuids failed: ${e.message}`);
+        }
     }
     // ── Sent-log (dedup) ──
     /** Has this Message-ID already been sent? Used to prevent the outbox from
@@ -423,6 +464,24 @@ export class MailxDB {
             }
             return existing.id;
         }
+        // Move-detection: if this Message-ID already exists for this account
+        // in a DIFFERENT folder, treat it as a server-side move rather than a
+        // new arrival. Rebind that row to (folder_id, uid) — keep the UUID,
+        // body_path, flags, all the local state. Saves a body re-fetch and
+        // preserves any local references (in_reply_to, dally entries, undo
+        // stacks) that point at the UUID. Only kicks in when messageId is
+        // present (servers usually include it; if not we fall through to a
+        // fresh insert which mints a new UUID).
+        if (msg.messageId) {
+            const moved = this.db.prepare("SELECT id, folder_id, uid FROM messages WHERE account_id = ? AND message_id = ? LIMIT 1").get(msg.accountId, msg.messageId);
+            if (moved) {
+                console.log(`  [move-detect] ${msg.accountId} ${msg.messageId}: rebinding row ${moved.id} (folder ${moved.folder_id}/uid ${moved.uid} → folder ${msg.folderId}/uid ${msg.uid})`);
+                // Update folder_id + uid; preserve uuid, body_path, flags
+                // (server flags will catch up on the next full sync).
+                this.db.prepare("UPDATE messages SET folder_id = ?, uid = ?, cached_at = ? WHERE id = ?").run(msg.folderId, msg.uid, Date.now(), moved.id);
+                return moved.id;
+            }
+        }
         const toText = msg.to.map(a => `${a.name} ${a.address}`).join(" ");
         const ccText = msg.cc.map(a => `${a.name} ${a.address}`).join(" ");
         // Thread id = oldest ancestor in the reference chain, or the in-reply-to
@@ -430,13 +489,17 @@ export class MailxDB {
         // whether an existing row already has a thread_id for any of the refs,
         // so late-arriving replies latch onto the same thread.
         const threadId = this.computeThreadId(msg.accountId, msg.messageId, msg.inReplyTo, msg.references);
+        // Mint a per-message local identity UUID at first-sight. Stable for
+        // the life of the row — survives server UID renumbers, folder moves
+        // (sync rebinds folder_id/uid but keeps uuid), UIDVALIDITY bumps.
+        const uuid = randomUUID().replace(/-/g, "");
         const result = this.db.prepare(`
             INSERT INTO messages (
-                account_id, folder_id, uid, message_id, in_reply_to, refs, thread_id,
+                account_id, folder_id, uid, uuid, message_id, in_reply_to, refs, thread_id,
                 date, subject, from_address, from_name, to_json, cc_json,
                 flags_json, size, has_attachments, preview, body_path, cached_at, provider_id
-            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-        `).run(msg.accountId, msg.folderId, msg.uid, msg.messageId, msg.inReplyTo, JSON.stringify(msg.references), threadId, msg.date, msg.subject, msg.from.address, msg.from.name, JSON.stringify(msg.to), JSON.stringify(msg.cc), JSON.stringify(msg.flags), msg.size, msg.hasAttachments ? 1 : 0, msg.preview, msg.bodyPath, Date.now(), msg.providerId || null);
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(msg.accountId, msg.folderId, msg.uid, uuid, msg.messageId, msg.inReplyTo, JSON.stringify(msg.references), threadId, msg.date, msg.subject, msg.from.address, msg.from.name, JSON.stringify(msg.to), JSON.stringify(msg.cc), JSON.stringify(msg.flags), msg.size, msg.hasAttachments ? 1 : 0, msg.preview, msg.bodyPath, Date.now(), msg.providerId || null);
         const rowId = Number(result.lastInsertRowid);
         // Index for full-text search
         try {
@@ -466,12 +529,22 @@ export class MailxDB {
             where += " AND flags_json LIKE '%\\\\Flagged%'";
         }
         const total = this.db.prepare(`SELECT COUNT(*) as cnt FROM messages WHERE ${where}`).get(...params).cnt;
-        const rows = this.db.prepare(`SELECT * FROM messages WHERE ${where} ORDER BY ${sortCol} ${sortDir} LIMIT ? OFFSET ?`).all(...params, pageSize, offset);
+        // LEFT JOIN sync_actions so each row carries a `pending` flag —
+        // true when the user has a queued local action (move/flag/delete)
+        // not yet acknowledged by the server. UI renders these in pink so
+        // local-only state is visible (Slice C of S1).
+        const rows = this.db.prepare(`SELECT m.*, EXISTS(
+                SELECT 1 FROM sync_actions sa
+                WHERE sa.account_id = m.account_id AND sa.uid = m.uid
+            ) AS pending
+            FROM messages m WHERE ${where.replace(/\b(account_id|folder_id|uid|date|subject|from_name|from_address|flags_json)\b/g, "m.$1")}
+            ORDER BY m.${sortCol} ${sortDir} LIMIT ? OFFSET ?`).all(...params, pageSize, offset);
         const items = rows.map(r => ({
             id: r.id,
             accountId: r.account_id,
             folderId: r.folder_id,
             uid: r.uid,
+            uuid: r.uuid || "",
             messageId: r.message_id || "",
             inReplyTo: r.in_reply_to || "",
             references: JSON.parse(r.refs || "[]"),
@@ -485,7 +558,8 @@ export class MailxDB {
             size: r.size,
             hasAttachments: !!r.has_attachments,
             preview: r.preview,
-            bodyPath: r.body_path || ""
+            bodyPath: r.body_path || "",
+            pending: !!r.pending,
         }));
         return { items, total, page, pageSize };
     }
@@ -522,19 +596,16 @@ export class MailxDB {
         }));
         return { items, total, page, pageSize };
     }
-    getMessageByUid(accountId, uid, folderId) {
-        const sql = folderId != null
-            ? "SELECT * FROM messages WHERE account_id = ? AND uid = ? AND folder_id = ?"
-            : "SELECT * FROM messages WHERE account_id = ? AND uid = ?";
-        const params = folderId != null ? [accountId, uid, folderId] : [accountId, uid];
-        const r = this.db.prepare(sql).get(...params);
-        if (!r)
-            return null;
+    /** Map a `messages` row to a MessageEnvelope. Exposes `uuid` (stable local
+     *  identity) and `bodyPath` (authoritative on-disk location) in addition
+     *  to the server-binding metadata. */
+    rowToEnvelope(r) {
         return {
             id: r.id,
             accountId: r.account_id,
             folderId: r.folder_id,
             uid: r.uid,
+            uuid: r.uuid || "",
             messageId: r.message_id || "",
             inReplyTo: r.in_reply_to || "",
             references: JSON.parse(r.refs || "[]"),
@@ -548,9 +619,33 @@ export class MailxDB {
             size: r.size,
             hasAttachments: !!r.has_attachments,
             preview: r.preview,
+            bodyPath: r.body_path || "",
             providerId: r.provider_id || undefined,
         };
     }
+    getMessageByUid(accountId, uid, folderId) {
+        const sql = folderId != null
+            ? "SELECT * FROM messages WHERE account_id = ? AND uid = ? AND folder_id = ?"
+            : "SELECT * FROM messages WHERE account_id = ? AND uid = ?";
+        const params = folderId != null ? [accountId, uid, folderId] : [accountId, uid];
+        const r = this.db.prepare(sql).get(...params);
+        if (!r)
+            return null;
+        return this.rowToEnvelope(r);
+    }
+    /** Look up a message by its stable local UUID. Returned envelope includes
+     *  the current (folder_id, uid) — these may have changed since the UUID
+     *  was minted (folder move or server UID renumber) but the UUID itself
+     *  is stable. Use this as the identity in any long-lived reference
+     *  (compose in-reply-to, dally, undo stacks). */
+    getMessageByUuid(uuid) {
+        if (!uuid)
+            return null;
+        const r = this.db.prepare("SELECT * FROM messages WHERE uuid = ?").get(uuid);
+        if (!r)
+            return null;
+        return this.rowToEnvelope(r);
+    }
     getMessageBodyPath(accountId, uid) {
         const r = this.db.prepare("SELECT body_path FROM messages WHERE account_id = ? AND uid = ?").get(accountId, uid);
         return r?.body_path || "";

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

@@ -62,7 +62,8 @@ export interface MessageEnvelope {
     accountId: string;
     folderId: number;
     folderName?: string; /** Leaf folder name; populated by cross-folder search so the UI can tag each hit */
-    uid: number; /** IMAP UID */
+    uid: number; /** IMAP UID (server-side identity; changes on move, UIDVALIDITY bump) */
+    uuid?: string; /** Stable local identity, minted once at first-sight; never changes */
     messageId: string; /** RFC Message-ID header */
     inReplyTo: string; /** For threading */
     references: string[]; /** For threading */
@@ -78,6 +79,7 @@ export interface MessageEnvelope {
     preview: string; /** First ~200 chars of body text */
     bodyPath?: string; /** Local body location: "idb:..." or "gmail:<id>" */
     providerId?: string; /** Native server id (Gmail hex id, Outlook Graph id) — bypasses UID→id pagination on body fetch */
+    pending?: boolean; /** True when a queued local action (move/flag/delete) hasn't been ACK'd by the server yet — UI renders pink */
 }
 /** Full message with body content */
 export interface Message extends MessageEnvelope {

package/todo.json

@@ -0,0 +1,13 @@
+{
+  "url": "file:///Y:/dev/email/mailx/TODO.md",
+  "size": {
+    "width": 1000,
+    "height": 1200
+  },
+  "pos": {
+    "x": 100,
+    "y": 100,
+    "screen": 1
+  },
+  "detach": true
+}