@bobfrankston/mailx-store 0.1.23 → 0.1.25

package/bus.d.ts

@@ -0,0 +1,79 @@
+/**
+ * StoreBus — typed pub/sub for Store events.
+ *
+ * Postmessage-style: subscribers register a topic string + handler; publishers
+ * emit a {topic, kind, ...} object. The exact same shape works inside Node,
+ * across worker_threads (postMessage), and across the WebView⇄host boundary
+ * (also postMessage). That's the load-bearing property: one mental model from
+ * DB write to UI re-render, on any platform.
+ *
+ * Topics
+ * ──────
+ *   `message:<uuid>`   — a specific message changed (flags, body, removal)
+ *   `folder:<id>`      — anything inside folder <id> changed; the bus fans
+ *                        out per-message events to the parent folder topic
+ *                        automatically (see fanOutToFolder())
+ *   `account:<id>`     — account-scoped event (sync status, auth, quota)
+ *   `*`                — wildcard; receives every event. Use for the IPC
+ *                        forwarder that pushes to the WebView, and for
+ *                        diagnostics. Avoid in normal UI subscribers.
+ *
+ * Batching
+ * ────────
+ * Bulk writes (sync round inserts 200 envelopes) would emit 200 events. The
+ * `withBatch(fn)` wrapper buffers events fired during fn() and coalesces
+ * per-topic into one {kind:"batch", changedUuids, summary} event at the end.
+ * Subscribers either iterate `changedUuids` or treat batch as "rerender this
+ * topic." Nested withBatch() is supported; inner scopes just append to the
+ * outer's buffer.
+ */
+export type StoreEventKind = "messageInserted" | "messageUpdated" | "messageRemoved" | "messageMoved" | "flagsChanged" | "bodyAvailable" | "bodyFetchError" | "folderCountsChanged" | "draftSaved" | "draftSaveDeferred" | "batch";
+export interface StoreEvent {
+    topic: string;
+    kind: StoreEventKind;
+    accountId?: string;
+    folderId?: number;
+    targetFolderId?: number;
+    uid?: number;
+    msgUuid?: string;
+    flags?: string[];
+    error?: string;
+    /** Set on `batch` events. UUIDs of every message touched in the scope. */
+    changedUuids?: string[];
+    /** Set on `batch` events. */
+    summary?: {
+        inserted: number;
+        updated: number;
+        deleted: number;
+    };
+    /** Arbitrary additional payload for kind-specific data the typed fields
+     *  above don't cover (e.g. flag-set details, body path). Keep small. */
+    [extra: string]: unknown;
+}
+export type StoreEventHandler = (event: StoreEvent) => void;
+export declare class StoreBus {
+    private subscribers;
+    private batchDepth;
+    private buffer;
+    subscribe(topic: string, handler: StoreEventHandler): () => void;
+    /** Publish an event. If a folderId is set and the topic is a message
+     *  topic, the bus also publishes a copy to the parent folder topic so
+     *  list views (subscribed to folder:<id>) wake without subscribing to
+     *  every message individually. */
+    publish(event: StoreEvent): void;
+    /** Run `fn` with publishes buffered. On exit, coalesces per-topic and
+     *  delivers either the single event (when only one fired for that topic)
+     *  or a synthetic batch event summarizing the changes. */
+    withBatch<T>(fn: () => T): T;
+    private flush;
+    private deliver;
+    /** When a message-topic event fires and carries a folderId, generate
+     *  the parallel folder-topic event so folder subscribers don't have to
+     *  also subscribe to every message individually. Returns null when no
+     *  fan-out applies. */
+    private fanOutToFolder;
+}
+/** Singleton bus shared by every Store consumer in the process. Workers
+ *  get their own; the worker boundary serializes events via postMessage. */
+export declare const storeBus: StoreBus;
+//# sourceMappingURL=bus.d.ts.map

package/bus.js

@@ -0,0 +1,155 @@
+/**
+ * StoreBus — typed pub/sub for Store events.
+ *
+ * Postmessage-style: subscribers register a topic string + handler; publishers
+ * emit a {topic, kind, ...} object. The exact same shape works inside Node,
+ * across worker_threads (postMessage), and across the WebView⇄host boundary
+ * (also postMessage). That's the load-bearing property: one mental model from
+ * DB write to UI re-render, on any platform.
+ *
+ * Topics
+ * ──────
+ *   `message:<uuid>`   — a specific message changed (flags, body, removal)
+ *   `folder:<id>`      — anything inside folder <id> changed; the bus fans
+ *                        out per-message events to the parent folder topic
+ *                        automatically (see fanOutToFolder())
+ *   `account:<id>`     — account-scoped event (sync status, auth, quota)
+ *   `*`                — wildcard; receives every event. Use for the IPC
+ *                        forwarder that pushes to the WebView, and for
+ *                        diagnostics. Avoid in normal UI subscribers.
+ *
+ * Batching
+ * ────────
+ * Bulk writes (sync round inserts 200 envelopes) would emit 200 events. The
+ * `withBatch(fn)` wrapper buffers events fired during fn() and coalesces
+ * per-topic into one {kind:"batch", changedUuids, summary} event at the end.
+ * Subscribers either iterate `changedUuids` or treat batch as "rerender this
+ * topic." Nested withBatch() is supported; inner scopes just append to the
+ * outer's buffer.
+ */
+export class StoreBus {
+    subscribers = new Map();
+    batchDepth = 0;
+    buffer = [];
+    subscribe(topic, handler) {
+        let set = this.subscribers.get(topic);
+        if (!set) {
+            set = new Set();
+            this.subscribers.set(topic, set);
+        }
+        set.add(handler);
+        return () => {
+            const s = this.subscribers.get(topic);
+            if (s) {
+                s.delete(handler);
+                if (s.size === 0)
+                    this.subscribers.delete(topic);
+            }
+        };
+    }
+    /** Publish an event. If a folderId is set and the topic is a message
+     *  topic, the bus also publishes a copy to the parent folder topic so
+     *  list views (subscribed to folder:<id>) wake without subscribing to
+     *  every message individually. */
+    publish(event) {
+        if (this.batchDepth > 0) {
+            this.buffer.push(event);
+            // Folder fan-out also buffers; coalesces at flush time.
+            const fanned = this.fanOutToFolder(event);
+            if (fanned)
+                this.buffer.push(fanned);
+            return;
+        }
+        this.deliver(event);
+        const fanned = this.fanOutToFolder(event);
+        if (fanned)
+            this.deliver(fanned);
+    }
+    /** Run `fn` with publishes buffered. On exit, coalesces per-topic and
+     *  delivers either the single event (when only one fired for that topic)
+     *  or a synthetic batch event summarizing the changes. */
+    withBatch(fn) {
+        this.batchDepth++;
+        try {
+            return fn();
+        }
+        finally {
+            this.batchDepth--;
+            if (this.batchDepth === 0)
+                this.flush();
+        }
+    }
+    flush() {
+        const buf = this.buffer;
+        this.buffer = [];
+        if (buf.length === 0)
+            return;
+        const byTopic = new Map();
+        for (const e of buf) {
+            let arr = byTopic.get(e.topic);
+            if (!arr) {
+                arr = [];
+                byTopic.set(e.topic, arr);
+            }
+            arr.push(e);
+        }
+        for (const [topic, events] of byTopic) {
+            if (events.length === 1) {
+                this.deliver(events[0]);
+                continue;
+            }
+            const summary = { inserted: 0, updated: 0, deleted: 0 };
+            const uuids = new Set();
+            for (const e of events) {
+                if (e.kind === "messageInserted")
+                    summary.inserted++;
+                else if (e.kind === "messageRemoved")
+                    summary.deleted++;
+                else
+                    summary.updated++;
+                if (e.msgUuid)
+                    uuids.add(e.msgUuid);
+            }
+            this.deliver({ topic, kind: "batch", changedUuids: [...uuids], summary });
+        }
+    }
+    deliver(event) {
+        const exact = this.subscribers.get(event.topic);
+        if (exact)
+            for (const h of exact) {
+                try {
+                    h(event);
+                }
+                catch (e) {
+                    console.error("[store-bus]", e);
+                }
+            }
+        const wild = this.subscribers.get("*");
+        if (wild)
+            for (const h of wild) {
+                try {
+                    h(event);
+                }
+                catch (e) {
+                    console.error("[store-bus]", e);
+                }
+            }
+    }
+    /** When a message-topic event fires and carries a folderId, generate
+     *  the parallel folder-topic event so folder subscribers don't have to
+     *  also subscribe to every message individually. Returns null when no
+     *  fan-out applies. */
+    fanOutToFolder(event) {
+        if (event.kind === "batch")
+            return null;
+        if (!event.topic.startsWith("message:"))
+            return null;
+        if (event.folderId == null)
+            return null;
+        return { ...event, topic: `folder:${event.folderId}` };
+    }
+}
+/** Singleton bus shared by every Store consumer in the process. Workers
+ *  get their own; the worker boundary serializes events via postMessage. */
+export const storeBus = new StoreBus();
+//# sourceMappingURL=bus.js.map

package/db.d.ts

@@ -53,15 +53,46 @@ export declare class MailxDB {
      *  user's own Sent copy, so it's still a reliable signal that this user
      *  habitually Bccs when writing to this recipient. */
     hasBccHistoryTo(recipientEmail: string): boolean;
-    /** Mark a Message-ID as locally-deleted for an account. No-op if messageId
-     *  is empty (e.g. provider stripped the header) — without a stable id we
-     *  can't check against future sync results anyway. */
+    /** Mark a local row as "delete pending server confirmation". The row
+     *  stays visible (UI greys / strikes it through) until the server
+     *  confirms via QRESYNC VANISHED or its UID drops out of the set-diff. */
+    setMessagePendingDelete(accountId: string, uid: number, folderId: number): void;
+    /** Clear the pending-delete flag — used when the IMAP MOVE/EXPUNGE is
+     *  refused by the server and the row should revert to a normal visible
+     *  state, and by Ctrl-Z undelete. */
+    clearMessagePendingDelete(accountId: string, uid: number, folderId: number): void;
+    /** Query: is this (folder, uid) pending server-side delete? */
+    isMessagePendingDelete(accountId: string, uid: number, folderId: number): boolean;
+    /** @deprecated — superseded by setMessagePendingDelete. Retained as a
+     *  no-op so legacy delete paths still compile; the table is preserved
+     *  but never read by the sync path anymore. */
     addTombstone(accountId: string, messageId: string, subject?: string): void;
-    /** Is this Message-ID tombstoned for this account? */
+    /** Is this Message-ID tombstoned for this account? Tombstones suppress
+     *  re-import of a row the user just deleted/moved while the server-side
+     *  IMAP action is still in flight; without this, the moved-out source
+     *  folder would re-insert the message on the next sync (server still
+     *  sees the UID; mailx has no other way to know "I just moved this").
+     *
+     *  Lifetime: created at the local-delete/move moment, removed on
+     *  successful IMAP action complete OR on PERMANENT IMAP action failure.
+     *  The failure-clear is the 2026-05-13 fix for the "tombstones outlive
+     *  failed deletes" bug — `failSyncAction` calls `clearTombstoneForUid`
+     *  after the final retry attempt so the user sees the row reappear on
+     *  the next sync (server still has it, mailx now agrees). QRESYNC
+     *  servers don't need this fallback because VANISHED is authoritative;
+     *  tombstones are no-ops on the QRESYNC fast path. */
     hasTombstone(accountId: string, messageId: string): boolean;
-    /** Remove a tombstone — used by "undelete" (Ctrl-Z) so a subsequent sync
-     *  re-imports the message as normal. Also lets the user recover from a
-     *  mistaken local delete. */
+    /** Clear the tombstone for the message currently at (accountId, uid,
+     *  folderId). Used by the sync-action failure path: when an IMAP MOVE
+     *  or EXPUNGE fails terminally, the row is still on the server and the
+     *  user should see it again — so the suppression must lift. The lookup
+     *  is by (accountId, uid, folderId) → message_id, since the action
+     *  table stores UID not Message-ID. No-op if the row no longer exists
+     *  (concurrent server-side EXPUNGE etc.). */
+    clearTombstoneForUid(accountId: string, uid: number, folderId: number): void;
+    /** @deprecated — use clearMessagePendingDelete instead. Retained as a
+     *  no-op for legacy callers (Ctrl-Z undelete paths still work because
+     *  their sibling clearMessagePendingDelete is called). */
     removeTombstone(accountId: string, messageId: string): void;
     /** Age-out tombstones older than the given cutoff. Keeps the table from
      *  growing unboundedly. Default retention is 30 days; caller passes the

package/db.js

@@ -357,6 +357,14 @@ const SCHEMA = `
         folder_id INTEGER NOT NULL,
         uid INTEGER NOT NULL,
         last_seen_at INTEGER NOT NULL,
+        -- 0 = normal, 1 = user initiated delete, server-sync in flight.
+        -- Replaces the old tombstones table: rather than hide a row server
+        -- still has, we keep it visible with this flag and let the UI render
+        -- it as a struck-through "in flight" row. On server-confirmed
+        -- deletion (QRESYNC VANISHED, or absence from a set-diff with the
+        -- 50% safety guard) the row is dropped. On server-refused deletion
+        -- the flag is cleared and the row reverts to normal.
+        pending_delete INTEGER DEFAULT 0,
         UNIQUE(folder_id, uid)
     );
     CREATE INDEX IF NOT EXISTS idx_message_folders_msg ON message_folders(message_row_id);
@@ -420,6 +428,9 @@ export class MailxDB {
         // calendar's defaultReminders pre-resolved server-side and pulled
         // through here too.
         this.addColumnIfMissing("calendar_events", "reminder_minutes_json", "TEXT DEFAULT '[]'");
+        // pending_delete on message_folders replaces the old tombstones table.
+        // See the table comment for semantics — visible in-flight delete state.
+        this.addColumnIfMissing("message_folders", "pending_delete", "INTEGER DEFAULT 0");
         // 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.
@@ -692,10 +703,61 @@ export class MailxDB {
             return false;
         }
     }
-    // ── Tombstones (local-delete record so server echo can't resurrect) ──
-    /** Mark a Message-ID as locally-deleted for an account. No-op if messageId
-     *  is empty (e.g. provider stripped the header) — without a stable id we
-     *  can't check against future sync results anyway. */
+    // ── Pending-delete state (replaces tombstones) ──
+    //
+    // Tombstones were a client-side invention that hid messages the server
+    // still considered present. With QRESYNC (RFC 7162) the server is
+    // authoritative — VANISHED tells us definitively what's deleted, so the
+    // tombstone hack is obsolete. For the non-QRESYNC case, the natural
+    // upsert-by-(folder, uid) behaviour of the sync path is already correct:
+    // a row pending deletion just has `pending_delete = 1`; the sync upserts
+    // refresh `last_seen_at` but don't reset the flag.
+    //
+    // The old tombstone API stubs below remain temporarily so legacy callers
+    // compile; they delegate to pending_delete by (folder, uid) when possible
+    // and no-op otherwise. Plan is to remove the stubs once every caller has
+    // been migrated to the (uid, folderId) form.
+    /** Mark a local row as "delete pending server confirmation". The row
+     *  stays visible (UI greys / strikes it through) until the server
+     *  confirms via QRESYNC VANISHED or its UID drops out of the set-diff. */
+    setMessagePendingDelete(accountId, uid, folderId) {
+        try {
+            this.db.prepare(`UPDATE message_folders SET pending_delete = 1
+                 WHERE folder_id = ? AND uid = ?
+                   AND message_row_id IN (SELECT id FROM messages WHERE account_id = ?)`).run(folderId, uid, accountId);
+        }
+        catch (e) {
+            console.error(`  [pending-delete] failed to mark ${accountId}/${folderId}/${uid}: ${e.message}`);
+        }
+    }
+    /** Clear the pending-delete flag — used when the IMAP MOVE/EXPUNGE is
+     *  refused by the server and the row should revert to a normal visible
+     *  state, and by Ctrl-Z undelete. */
+    clearMessagePendingDelete(accountId, uid, folderId) {
+        try {
+            this.db.prepare(`UPDATE message_folders SET pending_delete = 0
+                 WHERE folder_id = ? AND uid = ?
+                   AND message_row_id IN (SELECT id FROM messages WHERE account_id = ?)`).run(folderId, uid, accountId);
+        }
+        catch (e) {
+            console.error(`  [pending-delete] failed to clear ${accountId}/${folderId}/${uid}: ${e.message}`);
+        }
+    }
+    /** Query: is this (folder, uid) pending server-side delete? */
+    isMessagePendingDelete(accountId, uid, folderId) {
+        const row = this.db.prepare(`SELECT mf.pending_delete
+             FROM message_folders mf
+             JOIN messages m ON m.id = mf.message_row_id
+             WHERE mf.folder_id = ? AND mf.uid = ? AND m.account_id = ?
+             LIMIT 1`).get(folderId, uid, accountId);
+        return !!row && row.pending_delete === 1;
+    }
+    // ── Legacy tombstone API — stubs for backwards compatibility ────────────
+    // TODO(tombstone-removal): once all call sites use the (uid, folderId)
+    // pending_delete API, delete these stubs and drop the tombstones table.
+    /** @deprecated — superseded by setMessagePendingDelete. Retained as a
+     *  no-op so legacy delete paths still compile; the table is preserved
+     *  but never read by the sync path anymore. */
     addTombstone(accountId, messageId, subject = "") {
         if (!messageId)
             return;
@@ -706,16 +768,42 @@ export class MailxDB {
             console.error(`  [tombstones] failed to record ${messageId}: ${e.message}`);
         }
     }
-    /** Is this Message-ID tombstoned for this account? */
+    /** Is this Message-ID tombstoned for this account? Tombstones suppress
+     *  re-import of a row the user just deleted/moved while the server-side
+     *  IMAP action is still in flight; without this, the moved-out source
+     *  folder would re-insert the message on the next sync (server still
+     *  sees the UID; mailx has no other way to know "I just moved this").
+     *
+     *  Lifetime: created at the local-delete/move moment, removed on
+     *  successful IMAP action complete OR on PERMANENT IMAP action failure.
+     *  The failure-clear is the 2026-05-13 fix for the "tombstones outlive
+     *  failed deletes" bug — `failSyncAction` calls `clearTombstoneForUid`
+     *  after the final retry attempt so the user sees the row reappear on
+     *  the next sync (server still has it, mailx now agrees). QRESYNC
+     *  servers don't need this fallback because VANISHED is authoritative;
+     *  tombstones are no-ops on the QRESYNC fast path. */
     hasTombstone(accountId, messageId) {
         if (!messageId)
             return false;
         const row = this.db.prepare("SELECT 1 FROM tombstones WHERE account_id = ? AND message_id = ? LIMIT 1").get(accountId, messageId);
         return !!row;
     }
-    /** Remove a tombstone — used by "undelete" (Ctrl-Z) so a subsequent sync
-     *  re-imports the message as normal. Also lets the user recover from a
-     *  mistaken local delete. */
+    /** Clear the tombstone for the message currently at (accountId, uid,
+     *  folderId). Used by the sync-action failure path: when an IMAP MOVE
+     *  or EXPUNGE fails terminally, the row is still on the server and the
+     *  user should see it again — so the suppression must lift. The lookup
+     *  is by (accountId, uid, folderId) → message_id, since the action
+     *  table stores UID not Message-ID. No-op if the row no longer exists
+     *  (concurrent server-side EXPUNGE etc.). */
+    clearTombstoneForUid(accountId, uid, folderId) {
+        const env = this.getMessageByUid(accountId, uid, folderId);
+        if (!env?.messageId)
+            return;
+        this.removeTombstone(accountId, env.messageId);
+    }
+    /** @deprecated — use clearMessagePendingDelete instead. Retained as a
+     *  no-op for legacy callers (Ctrl-Z undelete paths still work because
+     *  their sibling clearMessagePendingDelete is called). */
     removeTombstone(accountId, messageId) {
         if (!messageId)
             return;

package/index.d.ts

@@ -4,5 +4,7 @@
  */
 export { MailxDB } from "./db.js";
 export { FileMessageStore } from "./file-store.js";
-export { parseSerial } from "./parse-serial.js";
+export { parseSerial, prewarmParseWorker } from "./parse-serial.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

@@ -4,5 +4,10 @@
  */
 export { MailxDB } from "./db.js";
 export { FileMessageStore } from "./file-store.js";
-export { parseSerial } from "./parse-serial.js";
+export { parseSerial, prewarmParseWorker } from "./parse-serial.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
+// the new import path.
+export { StoreBus, storeBus } from "@bobfrankston/mailx-bus";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-store",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
@@ -9,8 +9,9 @@
   },
   "license": "ISC",
   "dependencies": {
-    "@bobfrankston/mailx-types": "^0.1.11",
-    "@bobfrankston/mailx-settings": "^0.1.16",
+    "@bobfrankston/mailx-types": "^0.1.13",
+    "@bobfrankston/mailx-settings": "^0.1.17",
+    "@bobfrankston/mailx-bus": "^0.1.0",
     "mailparser": "^3.7.2"
   },
   "repository": {
@@ -23,12 +24,14 @@
   ".dependencies": {
     "@bobfrankston/mailx-types": "file:../mailx-types",
     "@bobfrankston/mailx-settings": "file:../mailx-settings",
+    "@bobfrankston/mailx-bus": "file:../mailx-bus",
     "mailparser": "^3.7.2"
   },
   ".transformedSnapshot": {
     "dependencies": {
-      "@bobfrankston/mailx-types": "^0.1.11",
-      "@bobfrankston/mailx-settings": "^0.1.16",
+      "@bobfrankston/mailx-types": "^0.1.13",
+      "@bobfrankston/mailx-settings": "^0.1.17",
+      "@bobfrankston/mailx-bus": "^0.1.0",
       "mailparser": "^3.7.2"
     }
   }

package/parse-serial.d.ts

@@ -1,34 +1,50 @@
 /**
- * Process-wide serialized simpleParser.
+ * Worker-thread-backed simpleParser dispatcher.
  *
  * mailparser's `simpleParser` is declared `async` but its work is CPU-bound
- * (Node Streams + libmime decoding). When N parses run concurrently on the
- * single-threaded event loop they share CPU and each finishes at roughly
- * N× wall-clock. Real evidence (2026-05-13): four near-concurrent parses
- * each reported `14691ms for 3 KB` — pure contention, not size.
+ * (Node Streams + libmime decoding). When it runs on the main event loop:
+ *   - The first parse after a fresh process takes 14-25 seconds (cold V8
+ *     JIT + libmime + iconv-lite + charset-table loading). See log
+ *     2026-05-14 01:11:44 — simpleParser 14524ms for 5 KB.
+ *   - Every parse, cold or warm, blocks the IPC stdin pump for its
+ *     duration. A 200 ms parse delays every queued IPC message by 200 ms.
  *
- * The downstream symptom is the IPC pipe: while the event loop is
- * saturated by interleaving parses, unrelated IPC operations (mark-as-spam,
- * move, delete) wait their turn and the WebView-side `mailxapi` shim
- * times out at 120s with a misleading "stayed in the list" alert.
+ * Moving the parse to a `worker_threads` Worker fixes both problems:
+ *   - The main event loop stays responsive — IPC, sync, timers all run
+ *     during the parse. Click-to-render latency is bounded by post-message
+ *     RTT (sub-ms) + parse time on the worker, but the rest of the app
+ *     stays alive.
+ *   - The worker absorbs cold-start once. Subsequent parses ride the
+ *     worker's warm JIT and run in their natural 50-500 ms budget.
  *
- * Serializing through a module-level promise chain bounds the damage with
- * minimal plumbing: a single parse runs at full CPU and finishes in its
- * natural ~50-500ms budget; the next parse starts when it's done. Each
- * UI click produces a clean preview latency instead of a 14-second stall.
+ * Priority queue: foreground (UI clicks) jumps over background (sync /
+ * prefetch) when more than one parse is pending. Each parse still runs
+ * sequentially on the worker — the single-worker design intentionally
+ * mirrors the prior in-process serialization to keep CPU bounded.
  *
- * Lives in mailx-store rather than mailx-service so both the UI-hot path
- * (mailx-service/local-store.ts) and the sync path (mailx-imap) can share
- * one queue — otherwise sync-time parses would still contend with UI
- * parses through the event loop, just not through this module's chain.
+ * Lazy spawn: the worker is created on first call. boot/setup code that
+ * runs no parses pays nothing.
+ *
+ * Worker lifecycle: the worker is process-singleton, never explicitly
+ * terminated. Node exits cleanly because the worker is `unref()`d so it
+ * doesn't keep the event loop alive.
  *
- * Future work: replace the in-process chain with a `node:worker_threads`
- * pool. The chain is the precursor that bounds the worst case while the
- * pool is built.
+ * Lives in mailx-store rather than mailx-service so both the UI-hot path
+ * (mailx-service/local-store.ts) and the sync path (mailx-imap) share one
+ * worker — otherwise each module would spawn its own (parallel workers
+ * would defeat the bound on CPU, and each pays its own cold start).
  */
-import { type ParsedMail, type Source } from "mailparser";
-/** Serialized wrapper around `mailparser.simpleParser`. `priority` defaults
- *  to "foreground" — only sync/background callers should pass "background"
- *  so user clicks aren't stuck behind a back-fill. */
+import type { ParsedMail, Source } from "mailparser";
+/** Spawn the parse worker early so its cold-start (mailparser module
+ *  loading, V8 JIT, libmime / iconv-lite tables — empirically 14-25 s)
+ *  runs in parallel with the rest of boot. Safe to call multiple times;
+ *  the worker is a process-singleton. Returns immediately; the actual
+ *  cold-start completes in the worker's internal self-warm. */
+export declare function prewarmParseWorker(): void;
+/** Serialized wrapper around `mailparser.simpleParser` running in a worker
+ *  thread. `priority` defaults to "foreground" — only sync/background
+ *  callers should pass "background" so user clicks aren't stuck behind a
+ *  back-fill. If the worker can't be spawned (rare), falls back to an
+ *  in-main-thread serial pump so the system still functions. */
 export declare function parseSerial(source: Source, priority?: "foreground" | "background"): Promise<ParsedMail>;
 //# sourceMappingURL=parse-serial.d.ts.map

package/parse-serial.js

@@ -1,40 +1,111 @@
 /**
- * Process-wide serialized simpleParser.
+ * Worker-thread-backed simpleParser dispatcher.
  *
  * mailparser's `simpleParser` is declared `async` but its work is CPU-bound
- * (Node Streams + libmime decoding). When N parses run concurrently on the
- * single-threaded event loop they share CPU and each finishes at roughly
- * N× wall-clock. Real evidence (2026-05-13): four near-concurrent parses
- * each reported `14691ms for 3 KB` — pure contention, not size.
+ * (Node Streams + libmime decoding). When it runs on the main event loop:
+ *   - The first parse after a fresh process takes 14-25 seconds (cold V8
+ *     JIT + libmime + iconv-lite + charset-table loading). See log
+ *     2026-05-14 01:11:44 — simpleParser 14524ms for 5 KB.
+ *   - Every parse, cold or warm, blocks the IPC stdin pump for its
+ *     duration. A 200 ms parse delays every queued IPC message by 200 ms.
  *
- * The downstream symptom is the IPC pipe: while the event loop is
- * saturated by interleaving parses, unrelated IPC operations (mark-as-spam,
- * move, delete) wait their turn and the WebView-side `mailxapi` shim
- * times out at 120s with a misleading "stayed in the list" alert.
+ * Moving the parse to a `worker_threads` Worker fixes both problems:
+ *   - The main event loop stays responsive — IPC, sync, timers all run
+ *     during the parse. Click-to-render latency is bounded by post-message
+ *     RTT (sub-ms) + parse time on the worker, but the rest of the app
+ *     stays alive.
+ *   - The worker absorbs cold-start once. Subsequent parses ride the
+ *     worker's warm JIT and run in their natural 50-500 ms budget.
  *
- * Serializing through a module-level promise chain bounds the damage with
- * minimal plumbing: a single parse runs at full CPU and finishes in its
- * natural ~50-500ms budget; the next parse starts when it's done. Each
- * UI click produces a clean preview latency instead of a 14-second stall.
+ * Priority queue: foreground (UI clicks) jumps over background (sync /
+ * prefetch) when more than one parse is pending. Each parse still runs
+ * sequentially on the worker — the single-worker design intentionally
+ * mirrors the prior in-process serialization to keep CPU bounded.
  *
- * Lives in mailx-store rather than mailx-service so both the UI-hot path
- * (mailx-service/local-store.ts) and the sync path (mailx-imap) can share
- * one queue — otherwise sync-time parses would still contend with UI
- * parses through the event loop, just not through this module's chain.
+ * Lazy spawn: the worker is created on first call. boot/setup code that
+ * runs no parses pays nothing.
+ *
+ * Worker lifecycle: the worker is process-singleton, never explicitly
+ * terminated. Node exits cleanly because the worker is `unref()`d so it
+ * doesn't keep the event loop alive.
  *
- * Future work: replace the in-process chain with a `node:worker_threads`
- * pool. The chain is the precursor that bounds the worst case while the
- * pool is built.
+ * Lives in mailx-store rather than mailx-service so both the UI-hot path
+ * (mailx-service/local-store.ts) and the sync path (mailx-imap) share one
+ * worker — otherwise each module would spawn its own (parallel workers
+ * would defeat the bound on CPU, and each pays its own cold start).
  */
-import { simpleParser } from "mailparser";
-const _head = []; // UI / foreground — drained first
-const _tail = []; // sync / background
+import { Worker } from "node:worker_threads";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+const _head = [];
+const _tail = [];
 let _pumping = false;
-async function pump() {
+let _worker = null;
+let _nextId = 1;
+const _inflight = new Map();
+function getWorker() {
+    if (_worker)
+        return _worker;
+    // Resolve parse-worker.js alongside the compiled parse-serial.js.
+    // import.meta.url is the running .js URL after tsc compilation, so
+    // the worker resolves cleanly from the package install location.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const workerPath = join(here, "parse-worker.js");
+    const w = new Worker(workerPath);
+    w.on("message", (msg) => {
+        // Warmup heartbeat (no `id`). Logs the worker cold-start cost so
+        // we can confirm the absorber is working on each boot.
+        if (typeof msg.warmupMs === "number") {
+            console.log(`  [parse-worker] cold-start absorbed in worker in ${msg.warmupMs}ms`);
+            return;
+        }
+        if (typeof msg.id !== "number")
+            return;
+        const entry = _inflight.get(msg.id);
+        if (!entry)
+            return;
+        _inflight.delete(msg.id);
+        if (msg.ok)
+            entry.resolve(msg.result);
+        else
+            entry.reject(new Error(msg.error || "parse-worker error"));
+        signalCompletion();
+    });
+    w.on("error", (e) => {
+        // Fatal worker crash — fail every in-flight parse, then null the
+        // singleton so the next call respawns.
+        for (const entry of _inflight.values())
+            entry.reject(e);
+        _inflight.clear();
+        _worker = null;
+        signalCompletion();
+    });
+    w.on("exit", (code) => {
+        if (_inflight.size > 0) {
+            const err = new Error(`parse-worker exited (code=${code}) with ${_inflight.size} in-flight`);
+            for (const entry of _inflight.values())
+                entry.reject(err);
+            _inflight.clear();
+        }
+        _worker = null;
+        signalCompletion();
+    });
+    // Don't let the worker prevent process exit.
+    w.unref();
+    _worker = w;
+    return w;
+}
+/** In-main-thread fallback. Used when the worker spawn itself fails (e.g.,
+ *  a packaged build where parse-worker.js can't be resolved). Falls back
+ *  to the original behavior — blocks the event loop, but at least works.
+ *  Lazy-imports mailparser so the main thread doesn't pay the (heavy)
+ *  module-init cost unless the fallback actually fires. */
+async function pumpInMain() {
     if (_pumping)
         return;
     _pumping = true;
     try {
+        const { simpleParser } = await import("mailparser");
         for (;;) {
             const next = _head.shift() ?? _tail.shift();
             if (!next)
@@ -52,17 +123,78 @@ async function pump() {
         _pumping = false;
     }
 }
-/** Serialized wrapper around `mailparser.simpleParser`. `priority` defaults
- *  to "foreground" — only sync/background callers should pass "background"
- *  so user clicks aren't stuck behind a back-fill. */
+// Notifier the pump awaits to drive the next iteration. When a reply
+// arrives from the worker, completing the in-flight parse, this fires
+// and unblocks the pump so it can pop the next queued parse. Avoids the
+// busy-wait setTimeout-poll version.
+let _completionSignal = null;
+function signalCompletion() {
+    const fn = _completionSignal;
+    _completionSignal = null;
+    if (fn)
+        fn();
+}
+async function pumpViaWorker() {
+    if (_pumping)
+        return;
+    _pumping = true;
+    try {
+        for (;;) {
+            const next = _head.shift() ?? _tail.shift();
+            if (!next)
+                break;
+            _inflight.set(next.id, next);
+            try {
+                getWorker().postMessage({ id: next.id, source: next.source });
+            }
+            catch (e) {
+                _inflight.delete(next.id);
+                next.reject(e);
+                continue;
+            }
+            // Wait for THIS parse to complete before sending the next.
+            // Preserves the priority order — a foreground entry that arrives
+            // after we've already postMessage'd a background parse will be
+            // next in line, NOT after several already-queued backgrounds.
+            await new Promise(resolve => { _completionSignal = resolve; });
+        }
+    }
+    finally {
+        _pumping = false;
+    }
+}
+/** Spawn the parse worker early so its cold-start (mailparser module
+ *  loading, V8 JIT, libmime / iconv-lite tables — empirically 14-25 s)
+ *  runs in parallel with the rest of boot. Safe to call multiple times;
+ *  the worker is a process-singleton. Returns immediately; the actual
+ *  cold-start completes in the worker's internal self-warm. */
+export function prewarmParseWorker() {
+    try {
+        getWorker();
+    }
+    catch { /* fallback path handles it on first parseSerial */ }
+}
+/** Serialized wrapper around `mailparser.simpleParser` running in a worker
+ *  thread. `priority` defaults to "foreground" — only sync/background
+ *  callers should pass "background" so user clicks aren't stuck behind a
+ *  back-fill. If the worker can't be spawned (rare), falls back to an
+ *  in-main-thread serial pump so the system still functions. */
 export async function parseSerial(source, priority = "foreground") {
     return new Promise((resolve, reject) => {
-        const entry = { source, resolve, reject };
+        const entry = { id: _nextId++, source, resolve, reject };
         if (priority === "foreground")
             _head.push(entry);
         else
             _tail.push(entry);
-        pump();
+        // Try the worker first; fall back transparently if the spawn fails.
+        try {
+            getWorker();
+            pumpViaWorker();
+        }
+        catch (e) {
+            console.error(`  [parse-serial] worker unavailable, falling back to main-thread parse: ${e instanceof Error ? e.message : String(e)}`);
+            pumpInMain();
+        }
     });
 }
 //# sourceMappingURL=parse-serial.js.map

package/parse-worker.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=parse-worker.d.ts.map

package/parse-worker.js

@@ -0,0 +1,69 @@
+/**
+ * mailparser worker thread.
+ *
+ * Runs simpleParser off the main event loop so a 14-25 second cold-start
+ * (or any slow parse) can't block IPC. The main thread's `parse-serial.ts`
+ * spawns this worker once at first use, then dispatches every parse here
+ * via postMessage and awaits the reply.
+ *
+ * Protocol:
+ *   main → worker: { id: number, source: Buffer | string }
+ *   worker → main: { id: number, ok: true,  result: ParsedMail }
+ *                | { id: number, ok: false, error: string }
+ *
+ * The worker holds its own mailparser module instance — JIT cost and
+ * libmime/iconv-lite loading happen exactly once per worker process. The
+ * main thread sees only the postMessage round-trip (~1 ms on local
+ * structured-clone of a small Buffer + parsed object).
+ */
+import { parentPort } from "node:worker_threads";
+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.
+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"
+    + "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.
+    parentPort.postMessage({ warmupMs: Date.now() - _warmupT0 });
+}).catch(() => { });
+parentPort.on("message", async (msg) => {
+    const { id, source } = msg;
+    // If a real parse arrives during warmup, queue behind it. The await
+    // resolves immediately once warmup is done; trivially fast on hot
+    // worker since _warmupPromise is already resolved.
+    await _warmupPromise;
+    try {
+        // CRITICAL: `Buffer` sent across `worker_threads.postMessage` arrives
+        // as plain `Uint8Array` (Node docs: "Buffer instances passed to
+        // Worker.postMessage() are passed as Uint8Array instances when
+        // received"). mailparser's `simpleParser` uses `Buffer.isBuffer(input)`
+        // to discriminate Buffer / string / Stream. A Uint8Array fails that
+        // check and gets routed to the Stream branch, which calls
+        // `input.once("end", …)` and immediately throws
+        //   `input.once is not a function`
+        // Re-wrap with `Buffer.from(src.buffer, src.byteOffset, src.byteLength)`
+        // — zero-copy view over the same memory, but with the Buffer prototype
+        // so `Buffer.isBuffer` is true.
+        let normalized = source;
+        if (source instanceof Uint8Array && !Buffer.isBuffer(source)) {
+            const u = source;
+            normalized = Buffer.from(u.buffer, u.byteOffset, u.byteLength);
+        }
+        const result = await simpleParser(normalized);
+        parentPort.postMessage({ id, ok: true, result });
+    }
+    catch (e) {
+        const error = e instanceof Error ? e.message : String(e);
+        parentPort.postMessage({ id, ok: false, error });
+    }
+});
+//# sourceMappingURL=parse-worker.js.map