@bobfrankston/mailx-store 0.1.25 → 0.1.27

package/charset.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Charset normalization for incoming email bodies.
+ *
+ * Many senders (esp. PHPMailer-driven marketing) declare
+ * `charset=iso-8859-1` but emit UTF-8 bytes. simpleParser honors the
+ * declared charset and produces "â??" garbage for every non-ASCII
+ * codepoint (em-dash, smart quotes, …). When the raw body bytes are
+ * valid UTF-8, rewrite the charset header before parsing. We only
+ * override the obviously-wrong legacy declarations; explicit utf-8 /
+ * koi8 / etc. pass through.
+ */
+/** Returns either the original buffer (no change needed) or a copy with
+ *  the leading charset declaration rewritten to utf-8. */
+export declare function sniffAndFixCharset(raw: Buffer): Buffer;
+//# sourceMappingURL=charset.d.ts.map

package/charset.js

@@ -0,0 +1,61 @@
+/**
+ * Charset normalization for incoming email bodies.
+ *
+ * Many senders (esp. PHPMailer-driven marketing) declare
+ * `charset=iso-8859-1` but emit UTF-8 bytes. simpleParser honors the
+ * declared charset and produces "â??" garbage for every non-ASCII
+ * codepoint (em-dash, smart quotes, …). When the raw body bytes are
+ * valid UTF-8, rewrite the charset header before parsing. We only
+ * override the obviously-wrong legacy declarations; explicit utf-8 /
+ * koi8 / etc. pass through.
+ */
+/** Returns either the original buffer (no change needed) or a copy with
+ *  the leading charset declaration rewritten to utf-8. */
+export function sniffAndFixCharset(raw) {
+    const HEAD_LIMIT = 16384;
+    const head = raw.subarray(0, Math.min(HEAD_LIMIT, raw.length)).toString("latin1");
+    const re = /charset\s*=\s*"?(iso-8859-1|us-ascii|windows-1252|latin1)"?/gi;
+    if (!re.test(head))
+        return raw;
+    if (!isValidUtf8(raw))
+        return raw;
+    const fixed = head.replace(/charset\s*=\s*"?(iso-8859-1|us-ascii|windows-1252|latin1)"?/gi, "charset=utf-8");
+    return Buffer.concat([Buffer.from(fixed, "latin1"), raw.subarray(head.length)]);
+}
+/** Strict UTF-8 validity check: rejects overlong forms, invalid start
+ *  bytes, and dangling continuations. Used to confirm the body is really
+ *  UTF-8 before overriding a Latin-1 declaration. */
+function isValidUtf8(buf) {
+    let i = 0;
+    while (i < buf.length) {
+        const b = buf[i];
+        if (b < 0x80) {
+            i++;
+            continue;
+        }
+        let need;
+        if ((b & 0xE0) === 0xC0) {
+            if (b < 0xC2)
+                return false;
+            need = 1;
+        }
+        else if ((b & 0xF0) === 0xE0)
+            need = 2;
+        else if ((b & 0xF8) === 0xF0) {
+            if (b > 0xF4)
+                return false;
+            need = 3;
+        }
+        else
+            return false;
+        if (i + need >= buf.length)
+            return false;
+        for (let k = 1; k <= need; k++) {
+            if ((buf[i + k] & 0xC0) !== 0x80)
+                return false;
+        }
+        i += need + 1;
+    }
+    return true;
+}
+//# sourceMappingURL=charset.js.map

package/index.d.ts

@@ -5,6 +5,8 @@
 export { MailxDB } from "./db.js";
 export { FileMessageStore } from "./file-store.js";
 export { parseSerial, prewarmParseWorker } from "./parse-serial.js";
+export { Store } from "./store.js";
+export type { StoreMessage } from "./store.js";
 export { StoreBus, storeBus } from "@bobfrankston/mailx-bus";
 export type { StoreEvent, StoreEventKind, StoreEventHandler } from "@bobfrankston/mailx-bus";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -5,6 +5,8 @@
 export { MailxDB } from "./db.js";
 export { FileMessageStore } from "./file-store.js";
 export { parseSerial, prewarmParseWorker } from "./parse-serial.js";
+// Store — the nexus. Owns DB + .eml files + operations + bus.
+export { Store } from "./store.js";
 // Store-event bus lives in `@bobfrankston/mailx-bus` so the browser-side
 // store (mailx-store-web) and the desktop-side store (this package) share
 // the same bus. Re-exported here so existing callers don't have to learn

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-store",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
@@ -9,9 +9,9 @@
   },
   "license": "ISC",
   "dependencies": {
-    "@bobfrankston/mailx-types": "^0.1.13",
+    "@bobfrankston/mailx-types": "^0.1.14",
     "@bobfrankston/mailx-settings": "^0.1.17",
-    "@bobfrankston/mailx-bus": "^0.1.0",
+    "@bobfrankston/mailx-bus": "^0.1.2",
     "mailparser": "^3.7.2"
   },
   "repository": {
@@ -29,9 +29,9 @@
   },
   ".transformedSnapshot": {
     "dependencies": {
-      "@bobfrankston/mailx-types": "^0.1.13",
+      "@bobfrankston/mailx-types": "^0.1.14",
       "@bobfrankston/mailx-settings": "^0.1.17",
-      "@bobfrankston/mailx-bus": "^0.1.0",
+      "@bobfrankston/mailx-bus": "^0.1.2",
       "mailparser": "^3.7.2"
     }
   }

package/parse-worker.js

@@ -21,18 +21,43 @@ import { simpleParser } from "mailparser";
 if (!parentPort) {
     throw new Error("parse-worker: must be spawned as a worker, parentPort is null");
 }
-// Self-warmup: parse a synthetic RFC 5322 message at worker startup so V8
-// JIT, libmime / iconv-lite module loading, and mailparser's lazy
-// initialisation all complete *before* the worker accepts its first real
-// request. Sub-50 ms parses become the norm even on the first user click,
-// instead of the 14-25 s cold-start observed when this work happened
-// on-demand. Buffered messages received during warmup queue behind it.
+// Self-warmup: parse a synthetic message at worker startup so V8 JIT,
+// libmime / iconv-lite loading, and mailparser's lazy init all complete
+// *before* the worker accepts its first real request.
+//
+// CRITICAL (Bob 2026-05-15): the warmup message MUST exercise every heavy
+// code path a real email hits, or the cold-start cost just moves to the
+// first real parse. The previous warmup was a trivial text/plain message
+// — it JIT'd the basic path but NOT the HTML pipeline, quoted-printable
+// decode, multipart boundary handling, or attachment extraction. Result:
+// the first real parse (a 96 KB multipart/alternative) took 33 SECONDS
+// in the log — the cold start was never actually absorbed. This warmup
+// message is multipart/mixed → multipart/alternative(text + QP-encoded
+// HTML) + a base64 attachment, with HTML entities and a non-ASCII char,
+// so the first real parse rides warm JIT for all of them.
 const _warmupT0 = Date.now();
-const _warmupPromise = simpleParser(Buffer.from("From: warmup@mailx.local\r\nTo: warmup@mailx.local\r\n"
-    + "Subject: warmup\r\nMIME-Version: 1.0\r\n"
+const _warmupMessage = "From: warmup@mailx.local\r\nTo: warmup@mailx.local\r\n"
+    + "Subject: =?UTF-8?Q?warm=E2=80=91up?=\r\nMIME-Version: 1.0\r\n"
+    + "Content-Type: multipart/mixed; boundary=\"MIX\"\r\n\r\n"
+    + "--MIX\r\n"
+    + "Content-Type: multipart/alternative; boundary=\"ALT\"\r\n\r\n"
+    + "--ALT\r\n"
     + "Content-Type: text/plain; charset=UTF-8\r\n\r\n"
-    + "parse-worker cold-start absorber. Discard.\r\n", "utf8")).then(() => {
-    // Optional: emit a heartbeat so the main thread can log the cost.
+    + "parse-worker cold-start absorber — discard.\r\n"
+    + "--ALT\r\n"
+    + "Content-Type: text/html; charset=UTF-8\r\n"
+    + "Content-Transfer-Encoding: quoted-printable\r\n\r\n"
+    + "<html><body><p>warm=E2=80=91up &amp; discard</p>"
+    + "<blockquote>quoted</blockquote><a href=3D\"http://x\">link</a></body></html>\r\n"
+    + "--ALT--\r\n"
+    + "--MIX\r\n"
+    + "Content-Type: application/octet-stream; name=\"w.bin\"\r\n"
+    + "Content-Transfer-Encoding: base64\r\n"
+    + "Content-Disposition: attachment; filename=\"w.bin\"\r\n\r\n"
+    + "d2FybXVw\r\n"
+    + "--MIX--\r\n";
+const _warmupPromise = simpleParser(Buffer.from(_warmupMessage, "utf8")).then(() => {
+    // Heartbeat so the main thread can log the absorbed cost.
     parentPort.postMessage({ warmupMs: Date.now() - _warmupT0 });
 }).catch(() => { });
 parentPort.on("message", async (msg) => {

package/store.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Store — the nexus. Owns the local database, the .eml file store, the
+ * operations API, and the event bus. Single source of truth for everything
+ * about a mailx account that lives on this device.
+ *
+ *   UI ──┐                                ┌── Sync clients (IMAP, Gmail API, …)
+ *        │  reads / writes / subscribes  │   read pending actions, commit
+ *        ↓                                ↓   server-discovered changes
+ *                          [ Store ]
+ *
+ * Contract: every method here mutates local-only state. No IMAP, no Gmail,
+ * no SMTP, no DNS, no Drive API. Mutations emit on the bus; subscribers
+ * (UI in another process, in-process reconciler, etc.) react. Sync clients
+ * (mailx-imap, mailx-sync) hold a Store reference and never touch the
+ * underlying MailxDB / FileMessageStore directly.
+ *
+ * This was previously named `Store` and lived in mailx-service. It
+ * moved to mailx-store because mailx-imap (and other sync clients) must
+ * be able to consume it without depending on mailx-service — that's the
+ * "arrow points the right way" property of the architecture.
+ */
+import { MailxDB } from "./db.js";
+import { FileMessageStore } from "./file-store.js";
+import type { StoreBus } from "./bus.js";
+import type { MessageEnvelope, MessageQuery, PagedResult } from "@bobfrankston/mailx-types";
+/** What the UI gets back from a body read. Mirrors the historical
+ *  `getMessage` shape so call-site migration is mechanical. `cached: false`
+ *  means the body isn't on disk yet — the UI shows a "downloading…"
+ *  placeholder and listens for `bodyAvailable` to re-render. The reconciler
+ *  is responsible for actually fetching and emitting the event. */
+export interface StoreMessage extends MessageEnvelope {
+    bodyHtml: string;
+    bodyText: string;
+    hasRemoteContent: boolean;
+    remoteAllowed: boolean;
+    attachments: Array<{
+        id: number;
+        filename: string;
+        mimeType: string;
+        size: number;
+        contentId: string;
+    }>;
+    cached: boolean;
+    /** Disambiguates `cached: false`:
+     *   - bodyOnDisk false → the .eml is NOT on disk; caller should queue
+     *     an IMAP/Gmail fetch.
+     *   - bodyOnDisk true  → the .eml IS on disk; a parse is in flight.
+     *     Caller MUST NOT queue a fetch — just wait for the `bodyAvailable`
+     *     bus event. Queuing a fetch here caused the 10-Hz "Loading body…"
+     *     loop (Bob 2026-05-15): cached:false → MailxService fetched →
+     *     reconciler re-published bodyAvailable → viewer re-called → repeat. */
+    bodyOnDisk: boolean;
+    deliveredTo: string;
+    returnPath: string;
+    listUnsubscribe: string;
+    listUnsubscribeMail: string;
+    listUnsubscribeHttp: string;
+    listUnsubscribeOneClick: boolean;
+    emlPath: string;
+    isFlagged: boolean;
+}
+export declare class Store {
+    /** SQLite metadata index. Exposed as a public field — sync clients
+     *  (mailx-imap, mailx-sync) read/write through it during the
+     *  refactor. Future state: every external mutation routes through
+     *  a Store method that emits a bus event; raw `store.db.X()` calls
+     *  shrink to zero. Today, this is read mostly. */
+    readonly db: MailxDB;
+    /** .eml file backend. Same migration story as `db` — sync clients
+     *  read/write directly today, will route through Store methods. */
+    readonly bodyStore: FileMessageStore;
+    /** Event bus for Store mutations. Defaults to the process-singleton
+     *  so cross-package subscribers (bin/mailx.ts forwarder → WebView,
+     *  in-process reconciler triggers) see all writes without explicit
+     *  wiring. Tests can pass a fresh StoreBus for isolation. */
+    readonly bus: StoreBus;
+    private static readonly PARSED_LRU_CAPACITY;
+    private parsedLru;
+    private parsedLruGet;
+    private parsedLruPut;
+    private _allowlistCache;
+    private _settingsCache;
+    private getCachedAllowlist;
+    private getCachedSettings;
+    invalidateConfigCaches(): void;
+    constructor(
+    /** SQLite metadata index. Exposed as a public field — sync clients
+     *  (mailx-imap, mailx-sync) read/write through it during the
+     *  refactor. Future state: every external mutation routes through
+     *  a Store method that emits a bus event; raw `store.db.X()` calls
+     *  shrink to zero. Today, this is read mostly. */
+    db: MailxDB, 
+    /** .eml file backend. Same migration story as `db` — sync clients
+     *  read/write directly today, will route through Store methods. */
+    bodyStore: FileMessageStore, 
+    /** Event bus for Store mutations. Defaults to the process-singleton
+     *  so cross-package subscribers (bin/mailx.ts forwarder → WebView,
+     *  in-process reconciler triggers) see all writes without explicit
+     *  wiring. Tests can pass a fresh StoreBus for isolation. */
+    bus?: StoreBus);
+    /** DB-shape account list (id/name/email/lastSync). The richer
+     *  AccountConfig (with imap/smtp/etc.) lives in accounts.jsonc and is
+     *  loaded by mailx-settings, not the DB — that path stays in
+     *  MailxService until step 3 of the local-first plan. */
+    getAccounts(): {
+        id: string;
+        name: string;
+        email: string;
+        lastSync: number;
+    }[];
+    getFolders(accountId: string): any[];
+    /** Look up a folder by RFC 6154 specialUse tag (`trash`, `drafts`, `sent`,
+     *  `junk`, etc.) for the given account. Falls back to a case-insensitive
+     *  path match for legacy rows where specialUse never got tagged.
+     *  Returns null when the account has no such folder configured. */
+    findSpecialFolder(accountId: string, specialUse: string): {
+        id: number;
+        path: string;
+    } | null;
+    /** Single envelope by (account, uid, folder). Null when the row isn't
+     *  in the DB — caller decides whether to show "deleted" or queue a
+     *  server lookup via the reconciler. */
+    getMessageEnvelope(accountId: string, uid: number, folderId?: number): MessageEnvelope | null;
+    /** Paginated message list for a (account, folder, ...) query. */
+    getMessages(query: MessageQuery): PagedResult<MessageEnvelope>;
+    /** All-Inboxes view: union of every account's INBOX, paginated. */
+    getUnifiedInbox(page?: number, pageSize?: number): PagedResult<MessageEnvelope>;
+    /** Local FTS5 search. Server-scope search is the reconciler's job. */
+    searchMessages(query: string, page?: number, pageSize?: number, accountId?: string, folderId?: number, includeTrashSpam?: boolean): PagedResult<MessageEnvelope>;
+    /** Read a fully-parsed message (envelope + body + attachments) entirely
+     *  from local state. Returns null when the envelope isn't known.
+     *  Returns `{ ...envelope, cached: false }` when the envelope is known
+     *  but the body file isn't on disk — UI shows a placeholder and the
+     *  reconciler queues the fetch.
+     *
+     *  `allowRemote=true` skips HTML sanitization. Used when the user has
+     *  explicitly allowed remote content for this sender / domain. */
+    getMessage(accountId: string, uid: number, allowRemote: boolean, folderId?: number): Promise<StoreMessage | null>;
+    getCalendarEvents(accountId: string, fromMs: number, toMs: number): any[];
+    getTasks(accountId: string, includeCompleted?: boolean): any[];
+    searchContacts(query: string, limit?: number): any[];
+    listContacts(query: string, page?: number, pageSize?: number): any;
+    /** Update a message's flag set. Local DB write completes synchronously;
+     *  the server-mirror enqueue is the caller's responsibility (typically
+     *  via SyncQueue.enqueueFlag) so callers that don't want a server push
+     *  — pure-local UI state like "pin in pane" — can skip it.
+     *
+     *  Publishes:
+     *    `message:<uuid>` { kind: "flagsChanged" }
+     *    `folder:<id>`    (auto fan-out)
+     */
+    updateFlags(accountId: string, uid: number, folderId: number, flags: string[]): void;
+    /** Move a message between folders in the same account. Adds a tombstone
+     *  on the Message-ID so the next sync doesn't re-import the pre-move row
+     *  in the source folder before the server-side MOVE completes; tombstone
+     *  is cleared on terminal IMAP failure (see processSyncActions).
+     *
+     *  Returns true if a local row existed and was moved, false otherwise.
+     *
+     *  Publishes:
+     *    `message:<uuid>` { kind: "messageMoved", folderId: source, targetFolderId }
+     *    `folder:<source>` and `folder:<target>` (auto fan-out + explicit count)
+     */
+    moveMessage(accountId: string, uid: number, fromFolderId: number, targetFolderId: number): boolean;
+    /** Trash a message. If a trash folder is configured and the message is
+     *  not already in it, this is a move-to-trash. If the message is already
+     *  in trash (or no trash exists), it's a hard delete + body unlink.
+     *
+     *  Returns "moved-to-trash" or "expunged" so the caller knows whether
+     *  to enqueue an IMAP MOVE or a DELETE+EXPUNGE on the queue.
+     */
+    trashMessage(accountId: string, uid: number, folderId: number, trashFolderId: number | null): "moved-to-trash" | "expunged";
+    /** Restore a message from trash back to its original folder. Local-only;
+     *  caller handles the queue (cancel-pending-MOVE vs queue-counter-MOVE).
+     *  Returns true if a local row was moved. */
+    undeleteMessage(accountId: string, uid: number, trashFolderId: number, originalFolderId: number): boolean;
+}
+//# sourceMappingURL=store.d.ts.map

package/store.js

@@ -0,0 +1,518 @@
+/**
+ * Store — the nexus. Owns the local database, the .eml file store, the
+ * operations API, and the event bus. Single source of truth for everything
+ * about a mailx account that lives on this device.
+ *
+ *   UI ──┐                                ┌── Sync clients (IMAP, Gmail API, …)
+ *        │  reads / writes / subscribes  │   read pending actions, commit
+ *        ↓                                ↓   server-discovered changes
+ *                          [ Store ]
+ *
+ * Contract: every method here mutates local-only state. No IMAP, no Gmail,
+ * no SMTP, no DNS, no Drive API. Mutations emit on the bus; subscribers
+ * (UI in another process, in-process reconciler, etc.) react. Sync clients
+ * (mailx-imap, mailx-sync) hold a Store reference and never touch the
+ * underlying MailxDB / FileMessageStore directly.
+ *
+ * This was previously named `Store` and lived in mailx-service. It
+ * moved to mailx-store because mailx-imap (and other sync clients) must
+ * be able to consume it without depending on mailx-service — that's the
+ * "arrow points the right way" property of the architecture.
+ */
+import * as fs from "node:fs";
+import { parseSerial } from "./parse-serial.js";
+import { storeBus } from "./bus.js";
+import { sanitizeHtml } from "@bobfrankston/mailx-types";
+import { loadSettings, loadAllowlist } from "@bobfrankston/mailx-settings";
+import { sniffAndFixCharset } from "./charset.js";
+/** Parse `List-Unsubscribe` (RFC 2369) and `List-Unsubscribe-Post` (RFC 8058).
+ *  mailparser only exposes ONE of mail/url even when both are present, so we
+ *  also scan the raw header text for the full set of angle-bracketed URIs. */
+function parseListUnsubscribe(headers) {
+    let mail = "";
+    let http = "";
+    let oneClick = false;
+    const raw = headers.get("list-unsubscribe");
+    const rawStr = typeof raw === "string" ? raw : (raw && typeof raw.text === "string" ? raw.text : "");
+    if (rawStr) {
+        const matches = rawStr.match(/<([^>]+)>/g) || [];
+        for (const m of matches) {
+            const url = m.slice(1, -1).trim();
+            if (!mail && /^mailto:/i.test(url))
+                mail = url;
+            else if (!http && /^https?:/i.test(url))
+                http = url;
+        }
+    }
+    if (!mail && !http) {
+        const listHeaders = headers.get("list");
+        if (listHeaders?.unsubscribe) {
+            const unsub = listHeaders.unsubscribe;
+            if (unsub.url)
+                http = Array.isArray(unsub.url) ? unsub.url[0] : unsub.url;
+            if (unsub.mail)
+                mail = `mailto:${Array.isArray(unsub.mail) ? unsub.mail[0] : unsub.mail}`;
+        }
+    }
+    const post = headers.get("list-unsubscribe-post");
+    const postStr = typeof post === "string" ? post : (post && typeof post.text === "string" ? post.text : "");
+    if (postStr && /one-?click/i.test(postStr))
+        oneClick = true;
+    return { listUnsubscribeMail: mail, listUnsubscribeHttp: http, listUnsubscribeOneClick: oneClick };
+}
+export class Store {
+    db;
+    bodyStore;
+    bus;
+    // Parsed-body LRU. `simpleParser` is the dominant cost of getMessage on
+    // a body that's already on disk — 100-500 ms for a typical Gmail message
+    // (heavier multipart/alternative + embedded-image swizzling than plainer
+    // IMAP mail). Stash the parsed result keyed by .eml path + mtime so
+    // repeat views of the same message return in microseconds.
+    //
+    // Invalidation is implicit: when the underlying .eml is overwritten
+    // (rare — bodies are immutable once cached, but reconcile can re-fetch
+    // on UIDVALIDITY change), the new mtime won't match the cached key.
+    // Capacity 200 entries × ~50 kB parsed envelope = ~10 MB ceiling.
+    static PARSED_LRU_CAPACITY = 200;
+    parsedLru = new Map();
+    parsedLruGet(key) {
+        const v = this.parsedLru.get(key);
+        if (!v)
+            return undefined;
+        // Bump recency.
+        this.parsedLru.delete(key);
+        this.parsedLru.set(key, v);
+        return v;
+    }
+    parsedLruPut(key, msg) {
+        this.parsedLru.delete(key);
+        this.parsedLru.set(key, msg);
+        while (this.parsedLru.size > Store.PARSED_LRU_CAPACITY) {
+            const oldest = this.parsedLru.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.parsedLru.delete(oldest);
+        }
+    }
+    // Allowlist + settings caches. Both files live on the GDrive-mounted
+    // shared dir; their sync `readFileSync` calls in `loadAllowlist()` and
+    // `loadSettings()` can stall for seconds per call. getMessage runs on
+    // every preview click, so paying that twice each click made .eml
+    // display "go to GDrive" even though the body itself is local. Cached
+    // here; invalidated externally via invalidateConfigCaches() when the
+    // parent service receives a `configChanged` event.
+    _allowlistCache = null;
+    _settingsCache = null;
+    getCachedAllowlist() {
+        if (!this._allowlistCache)
+            this._allowlistCache = loadAllowlist();
+        return this._allowlistCache;
+    }
+    getCachedSettings() {
+        if (!this._settingsCache)
+            this._settingsCache = loadSettings();
+        return this._settingsCache;
+    }
+    invalidateConfigCaches() {
+        this._allowlistCache = null;
+        this._settingsCache = null;
+    }
+    constructor(
+    /** SQLite metadata index. Exposed as a public field — sync clients
+     *  (mailx-imap, mailx-sync) read/write through it during the
+     *  refactor. Future state: every external mutation routes through
+     *  a Store method that emits a bus event; raw `store.db.X()` calls
+     *  shrink to zero. Today, this is read mostly. */
+    db, 
+    /** .eml file backend. Same migration story as `db` — sync clients
+     *  read/write directly today, will route through Store methods. */
+    bodyStore, 
+    /** Event bus for Store mutations. Defaults to the process-singleton
+     *  so cross-package subscribers (bin/mailx.ts forwarder → WebView,
+     *  in-process reconciler triggers) see all writes without explicit
+     *  wiring. Tests can pass a fresh StoreBus for isolation. */
+    bus = storeBus) {
+        this.db = db;
+        this.bodyStore = bodyStore;
+        this.bus = bus;
+    }
+    // ── Account list (read-only here; mutations go through MailxService
+    //    until the cloud-write path is part of the queue too) ──
+    /** DB-shape account list (id/name/email/lastSync). The richer
+     *  AccountConfig (with imap/smtp/etc.) lives in accounts.jsonc and is
+     *  loaded by mailx-settings, not the DB — that path stays in
+     *  MailxService until step 3 of the local-first plan. */
+    getAccounts() {
+        return this.db.getAccounts();
+    }
+    // ── Folders ──
+    getFolders(accountId) {
+        return this.db.getFolders(accountId);
+    }
+    /** Look up a folder by RFC 6154 specialUse tag (`trash`, `drafts`, `sent`,
+     *  `junk`, etc.) for the given account. Falls back to a case-insensitive
+     *  path match for legacy rows where specialUse never got tagged.
+     *  Returns null when the account has no such folder configured. */
+    findSpecialFolder(accountId, specialUse) {
+        const folders = this.db.getFolders(accountId);
+        const f = folders.find(x => x.specialUse === specialUse ||
+            x.path.toLowerCase() === specialUse.toLowerCase());
+        return f ? { id: f.id, path: f.path } : null;
+    }
+    // ── Message envelopes ──
+    /** Single envelope by (account, uid, folder). Null when the row isn't
+     *  in the DB — caller decides whether to show "deleted" or queue a
+     *  server lookup via the reconciler. */
+    getMessageEnvelope(accountId, uid, folderId) {
+        const env = this.db.getMessageByUid(accountId, uid, folderId);
+        return env || null;
+    }
+    /** Paginated message list for a (account, folder, ...) query. */
+    getMessages(query) {
+        return this.db.getMessages(query);
+    }
+    /** All-Inboxes view: union of every account's INBOX, paginated. */
+    getUnifiedInbox(page = 1, pageSize = 50) {
+        return this.db.getUnifiedInbox(page, pageSize);
+    }
+    /** Local FTS5 search. Server-scope search is the reconciler's job. */
+    searchMessages(query, page = 1, pageSize = 50, accountId, folderId, includeTrashSpam = false) {
+        return this.db.searchMessages(query, page, pageSize, accountId, folderId, includeTrashSpam);
+    }
+    // ── Message body (read-from-disk only) ──
+    /** Read a fully-parsed message (envelope + body + attachments) entirely
+     *  from local state. Returns null when the envelope isn't known.
+     *  Returns `{ ...envelope, cached: false }` when the envelope is known
+     *  but the body file isn't on disk — UI shows a placeholder and the
+     *  reconciler queues the fetch.
+     *
+     *  `allowRemote=true` skips HTML sanitization. Used when the user has
+     *  explicitly allowed remote content for this sender / domain. */
+    async getMessage(accountId, uid, allowRemote, folderId) {
+        const envelope = this.db.getMessageByUid(accountId, uid, folderId);
+        if (!envelope)
+            return null;
+        const allowList = this.getCachedAllowlist();
+        const senderAddr = (envelope.from?.address || "").toLowerCase();
+        const senderDomain = senderAddr.split("@")[1] || "";
+        const toAddrs = (envelope.to || []).map((a) => (a.address || "").toLowerCase());
+        // Allowlist auto-allow: trusted sender / domain / recipient skips
+        // sanitization. Same rule as the legacy service implementation.
+        if (!allowRemote) {
+            const senders = (allowList.senders || []).map((s) => (s || "").toLowerCase());
+            const domains = (allowList.domains || []).map((d) => (d || "").toLowerCase());
+            const recipients = (allowList.recipients || []).map((r) => (r || "").toLowerCase());
+            if (senders.includes(senderAddr) ||
+                domains.includes(senderDomain) ||
+                toAddrs.some((a) => recipients.includes(a))) {
+                allowRemote = true;
+            }
+        }
+        const isFlagged = !!((allowList.flaggedSenders || []).some((s) => (s || "").toLowerCase() === senderAddr) ||
+            (allowList.flaggedDomains || []).some((d) => (d || "").toLowerCase() === senderDomain));
+        // Resolve body path: prefer the row's own bodyPath, fall back to
+        // the historical lookup. Either may be empty (body never fetched).
+        let storedPath = envelope.bodyPath || "";
+        if (!storedPath)
+            storedPath = this.db.getMessageBodyPath(accountId, uid) || "";
+        const empty = {
+            ...envelope,
+            bodyHtml: "", bodyText: "",
+            hasRemoteContent: false, remoteAllowed: allowRemote,
+            attachments: [],
+            cached: false,
+            bodyOnDisk: false, // overridden to true on the parse-pending return
+            deliveredTo: "", returnPath: "",
+            listUnsubscribe: "", listUnsubscribeMail: "", listUnsubscribeHttp: "", listUnsubscribeOneClick: false,
+            emlPath: "",
+            isFlagged,
+        };
+        // No body file → caller should queue a fetch (bodyOnDisk stays false).
+        if (!storedPath)
+            return empty;
+        if (!await this.bodyStore.hasByPath(storedPath))
+            return empty;
+        // Parse-cache lookup. Key = path + mtime so a re-fetched body
+        // (mtime changes) invalidates automatically. mtime stat is cheap
+        // (sub-ms) compared to the parse it avoids (~100-500 ms).
+        let mtimeMs = 0;
+        try {
+            mtimeMs = (await fs.promises.stat(storedPath)).mtimeMs;
+        }
+        catch { /* will fall through and fail at readByPath */ }
+        const cacheKey = `${storedPath}|${mtimeMs}`;
+        const cached = this.parsedLruGet(cacheKey);
+        if (cached) {
+            // Allowlist state can change between views even with the same
+            // body cached; recompute the volatile fields and overlay.
+            return { ...cached, remoteAllowed: allowRemote, isFlagged };
+        }
+        // Synchronous parse. The .eml is on disk; read + parse it inline
+        // and return the fully-rendered message. The parse runs on the
+        // parse-worker thread (off the main event loop) — the IPC promise
+        // just awaits the worker's reply, ~50-200 ms on a warm worker.
+        //
+        // 2026-05-15: this REPLACED an async "return envelope now, parse
+        // later, emit bodyAvailable" split. That split overloaded
+        // `cached:false` (was it "no body file" or "parse pending"?),
+        // which made MailxService queue redundant fetches, which churned
+        // the .eml mtime, which invalidated the cache key, which spawned
+        // duplicate parses — a 10 Hz "Loading body…" loop and 30-second
+        // queue-contention parses. Synchronous parse makes the whole
+        // class structurally impossible: getMessage either returns the
+        // body or returns `cached:false` meaning exactly "fetch it."
+        const raw = await this.bodyStore.readByPath(storedPath);
+        const adjusted = sniffAndFixCharset(raw);
+        const _parseT0 = Date.now();
+        const parsed = await parseSerial(adjusted);
+        const _parseMs = Date.now() - _parseT0;
+        if (_parseMs > 50) {
+            console.log(`  [parse] simpleParser ${_parseMs}ms for ${(raw.length / 1024).toFixed(0)} KB (${storedPath})`);
+        }
+        let bodyHtml = parsed.html || "";
+        const bodyText = parsed.text || "";
+        // Backfill FTS body_text now that we've parsed the body. upsertMessage
+        // only had the short `preview` snippet at index time; without this
+        // backfill, searches miss any word that only appears deeper in the
+        // body. Fire-and-forget — failures are non-fatal, never block the
+        // user's preview render.
+        if (bodyText) {
+            try {
+                this.db.updateFtsBodyByUid(accountId, envelope.folderId, uid, bodyText);
+            }
+            catch { /* */ }
+        }
+        let hasRemoteContent = false;
+        // Filter out "spurious" attachments: mailing-list footers and signature
+        // blocks frequently arrive as a separate text/plain MIME part with
+        // Content-Disposition: inline and no filename. mailparser dutifully
+        // surfaces them as attachments. Showing them as attachment chips
+        // confuses the user (Bob 2026-05-13: spurious image-shaped chip on
+        // a list message that had no real attachment). Rule: if the part is
+        // text/* AND has no filename AND is dispositionally inline (or no
+        // disposition at all), it's body content, not a real attachment.
+        // Keep the original index even for filtered rows so getAttachment's
+        // index lookup still works for the surviving ones.
+        const attachments = (parsed.attachments || [])
+            .map((a, i) => {
+            const mime = (a.contentType || "application/octet-stream").toLowerCase();
+            const disposition = (a.contentDisposition || "").toLowerCase();
+            const isSpuriousTextPart = mime.startsWith("text/")
+                && !a.filename
+                && (disposition === "inline" || disposition === "");
+            return { a, i, isSpuriousTextPart };
+        })
+            .filter(x => !x.isSpuriousTextPart)
+            .map(x => ({
+            id: x.i,
+            filename: x.a.filename || `attachment-${x.i}`,
+            mimeType: x.a.contentType || "application/octet-stream",
+            size: x.a.size || 0,
+            contentId: x.a.contentId || "",
+        }));
+        if (bodyHtml && !allowRemote) {
+            const result = sanitizeHtml(bodyHtml);
+            bodyHtml = result.html;
+            hasRemoteContent = result.hasRemoteContent;
+        }
+        // Header extraction — Delivered-To, Return-Path, List-Unsubscribe.
+        // mlproc preprocesses Delivered-To server-side, so the inner
+        // address is already clean by the time mailx sees it. We take the
+        // last entry of the chain (the final-delivery hop). The
+        // `relayDomains` filtering layer was retired 2026-05-13: nothing
+        // configures it in practice and the conditional made the code
+        // harder to reason about than the one-liner that replaces it.
+        let deliveredTo = "";
+        const rawDelivered = parsed.headers.get("delivered-to");
+        if (rawDelivered) {
+            const deliveredList = Array.isArray(rawDelivered) ? rawDelivered : [rawDelivered];
+            const d = deliveredList[deliveredList.length - 1];
+            deliveredTo = typeof d === "string" ? d : d?.text || d?.address || String(d);
+        }
+        const hdr = (key) => {
+            let v = parsed.headers.get(key);
+            if (!v)
+                return "";
+            if (Array.isArray(v))
+                v = v[0];
+            if (typeof v === "string")
+                return v;
+            if (typeof v === "object" && v !== null) {
+                if ("text" in v)
+                    return v.text || "";
+                if ("value" in v)
+                    return String(v.value);
+                if ("address" in v)
+                    return v.address || "";
+            }
+            return String(v);
+        };
+        const returnPath = hdr("return-path").replace(/[<>]/g, "");
+        const { listUnsubscribeMail, listUnsubscribeHttp, listUnsubscribeOneClick } = parseListUnsubscribe(parsed.headers);
+        const listUnsubscribe = listUnsubscribeHttp || listUnsubscribeMail;
+        const result = {
+            ...envelope,
+            bodyHtml, bodyText,
+            hasRemoteContent, remoteAllowed: allowRemote,
+            attachments,
+            cached: true,
+            deliveredTo, returnPath,
+            listUnsubscribe, listUnsubscribeMail, listUnsubscribeHttp, listUnsubscribeOneClick,
+            // body_path in the DB is stored relative to the body-store
+            // basePath; resolve to absolute so the UI's "Source" button
+            // can hand the path to an OS file open without re-deriving
+            // basePath every time.
+            emlPath: this.bodyStore.absolutePath(storedPath),
+            isFlagged,
+        };
+        // Memoize for instant re-view of the same message. cacheKey is
+        // path+mtime so a re-fetch (mtime changes) invalidates naturally.
+        // The LRU is a perf tier only — correctness never depends on it.
+        if (mtimeMs > 0)
+            this.parsedLruPut(cacheKey, result);
+        return result;
+    }
+    // ── Calendar / tasks / contacts (read paths) ──
+    getCalendarEvents(accountId, fromMs, toMs) {
+        return this.db.getCalendarEvents(accountId, fromMs, toMs);
+    }
+    getTasks(accountId, includeCompleted = false) {
+        return this.db.getTasks(accountId, includeCompleted);
+    }
+    searchContacts(query, limit = 10) {
+        return this.db.searchContacts(query, limit);
+    }
+    listContacts(query, page = 1, pageSize = 100) {
+        return this.db.listContacts(query, page, pageSize);
+    }
+    // ── Write paths (local-only; mirror to server is queued separately) ──
+    /** Update a message's flag set. Local DB write completes synchronously;
+     *  the server-mirror enqueue is the caller's responsibility (typically
+     *  via SyncQueue.enqueueFlag) so callers that don't want a server push
+     *  — pure-local UI state like "pin in pane" — can skip it.
+     *
+     *  Publishes:
+     *    `message:<uuid>` { kind: "flagsChanged" }
+     *    `folder:<id>`    (auto fan-out)
+     */
+    updateFlags(accountId, uid, folderId, flags) {
+        this.db.updateMessageFlags(accountId, uid, flags);
+        const env = this.db.getMessageByUid(accountId, uid, folderId);
+        const msgUuid = env?.uuid;
+        if (msgUuid) {
+            this.bus.publish({
+                topic: `message:${msgUuid}`,
+                kind: "flagsChanged",
+                accountId, folderId, uid, msgUuid, flags,
+            });
+        }
+    }
+    /** Move a message between folders in the same account. Adds a tombstone
+     *  on the Message-ID so the next sync doesn't re-import the pre-move row
+     *  in the source folder before the server-side MOVE completes; tombstone
+     *  is cleared on terminal IMAP failure (see processSyncActions).
+     *
+     *  Returns true if a local row existed and was moved, false otherwise.
+     *
+     *  Publishes:
+     *    `message:<uuid>` { kind: "messageMoved", folderId: source, targetFolderId }
+     *    `folder:<source>` and `folder:<target>` (auto fan-out + explicit count)
+     */
+    moveMessage(accountId, uid, fromFolderId, targetFolderId) {
+        const env = this.db.getMessageByUid(accountId, uid, fromFolderId);
+        if (!env)
+            return false;
+        if (env.messageId)
+            this.db.addTombstone(accountId, env.messageId, env.subject || "");
+        const moved = this.db.moveMessageLocal(accountId, uid, fromFolderId, targetFolderId);
+        if (!moved)
+            return false;
+        this.db.recalcFolderCounts(fromFolderId);
+        this.db.recalcFolderCounts(targetFolderId);
+        const msgUuid = env?.uuid;
+        if (msgUuid) {
+            this.bus.publish({
+                topic: `message:${msgUuid}`,
+                kind: "messageMoved",
+                accountId, folderId: fromFolderId, targetFolderId, uid, msgUuid,
+            });
+        }
+        // Folder count change isn't tied to a specific message uuid — publish
+        // to both folder topics directly. (The fan-out only covers the source
+        // via the message event's folderId; target needs its own publish.)
+        this.bus.publish({
+            topic: `folder:${targetFolderId}`,
+            kind: "folderCountsChanged",
+            accountId, folderId: targetFolderId,
+        });
+        return true;
+    }
+    /** Trash a message. If a trash folder is configured and the message is
+     *  not already in it, this is a move-to-trash. If the message is already
+     *  in trash (or no trash exists), it's a hard delete + body unlink.
+     *
+     *  Returns "moved-to-trash" or "expunged" so the caller knows whether
+     *  to enqueue an IMAP MOVE or a DELETE+EXPUNGE on the queue.
+     */
+    trashMessage(accountId, uid, folderId, trashFolderId) {
+        const env = this.db.getMessageByUid(accountId, uid, folderId);
+        if (env?.messageId)
+            this.db.addTombstone(accountId, env.messageId, env.subject || "");
+        const msgUuid = env?.uuid;
+        if (trashFolderId != null && trashFolderId !== folderId) {
+            this.db.moveMessageLocal(accountId, uid, folderId, trashFolderId);
+            this.db.recalcFolderCounts(folderId);
+            this.db.recalcFolderCounts(trashFolderId);
+            if (msgUuid) {
+                this.bus.publish({
+                    topic: `message:${msgUuid}`,
+                    kind: "messageMoved",
+                    accountId, folderId, targetFolderId: trashFolderId, uid, msgUuid,
+                });
+            }
+            this.bus.publish({
+                topic: `folder:${trashFolderId}`,
+                kind: "folderCountsChanged",
+                accountId, folderId: trashFolderId,
+            });
+            return "moved-to-trash";
+        }
+        this.db.deleteMessage(accountId, uid, "user-initiated trash (already in trash → expunge)", "Store.trashMessage");
+        this.db.recalcFolderCounts(folderId);
+        if (msgUuid) {
+            this.bus.publish({
+                topic: `message:${msgUuid}`,
+                kind: "messageRemoved",
+                accountId, folderId, uid, msgUuid,
+            });
+        }
+        return "expunged";
+    }
+    /** Restore a message from trash back to its original folder. Local-only;
+     *  caller handles the queue (cancel-pending-MOVE vs queue-counter-MOVE).
+     *  Returns true if a local row was moved. */
+    undeleteMessage(accountId, uid, trashFolderId, originalFolderId) {
+        const moved = this.db.moveMessageLocal(accountId, uid, trashFolderId, originalFolderId);
+        if (!moved)
+            return false;
+        this.db.recalcFolderCounts(trashFolderId);
+        this.db.recalcFolderCounts(originalFolderId);
+        const env = this.db.getMessageByUid(accountId, uid, originalFolderId);
+        const msgUuid = env?.uuid;
+        if (msgUuid) {
+            this.bus.publish({
+                topic: `message:${msgUuid}`,
+                kind: "messageMoved",
+                accountId, folderId: trashFolderId, targetFolderId: originalFolderId, uid, msgUuid,
+            });
+        }
+        this.bus.publish({
+            topic: `folder:${originalFolderId}`,
+            kind: "folderCountsChanged",
+            accountId, folderId: originalFolderId,
+        });
+        return true;
+    }
+}
+//# sourceMappingURL=store.js.map