@bobfrankston/rmfmail 1.0.705 → 1.0.706

package/packages/mailx-store/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/packages/mailx-store/parse-serial.js.map

@@ -1 +1 @@
-{"version":3,"file":"parse-serial.js","sourceRoot":"","sources":["parse-serial.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,YAAY,EAAgC,MAAM,YAAY,CAAC;AAexE,MAAM,KAAK,GAAc,EAAE,CAAC,CAAE,kCAAkC;AAChE,MAAM,KAAK,GAAc,EAAE,CAAC,CAAE,oBAAoB;AAClD,IAAI,QAAQ,GAAG,KAAK,CAAC;AAErB,KAAK,UAAU,IAAI;IACf,IAAI,QAAQ;QAAE,OAAO;IACrB,QAAQ,GAAG,IAAI,CAAC;IAChB,IAAI,CAAC;QACD,SAAS,CAAC;YACN,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,EAAE,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAC5C,IAAI,CAAC,IAAI;gBAAE,MAAM;YACjB,IAAI,CAAC;gBACD,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC/C,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACzB,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACT,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACnB,CAAC;QACL,CAAC;IACL,CAAC;YAAS,CAAC;QACP,QAAQ,GAAG,KAAK,CAAC;IACrB,CAAC;AACL,CAAC;AAED;;sDAEsD;AACtD,MAAM,CAAC,KAAK,UAAU,WAAW,CAC7B,MAAc,EACd,WAAwC,YAAY;IAEpD,OAAO,IAAI,OAAO,CAAa,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC/C,MAAM,KAAK,GAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QACnD,IAAI,QAAQ,KAAK,YAAY;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;;YAC5C,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvB,IAAI,EAAE,CAAC;IACX,CAAC,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"parse-serial.js","sourceRoot":"","sources":["parse-serial.ts"],"names":[],"mappings":"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"}

package/packages/mailx-store/parse-serial.ts

@@ -1,55 +1,114 @@
 /**
- * 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, type ParsedMail, type Source } from "mailparser";
+import { Worker } from "node:worker_threads";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import type { ParsedMail, Source } from "mailparser";
 
-/**
- * Priority queue. A background pump runs the next pending parse; UI calls
- * insert at the head of the line, sync calls go to the tail. Without this,
- * a first-sync of 96 folders × thousands of messages each can queue
- * thousands of `extractPreview` parses ahead of a single user click — the
- * preview pane sits on "Loading body…" for minutes while the back-fill
- * grinds through. Same parses, different order.
- */
 type Pending = {
+    id: number;
     source: Source;
     resolve: (m: ParsedMail) => void;
     reject: (e: unknown) => void;
 };
-const _head: Pending[] = [];  // UI / foreground — drained first
-const _tail: Pending[] = [];  // sync / background
+const _head: Pending[] = [];
+const _tail: Pending[] = [];
 let _pumping = false;
+let _worker: Worker | null = null;
+let _nextId = 1;
+const _inflight = new Map<number, Pending>();
 
-async function pump(): Promise<void> {
+function getWorker(): Worker {
+    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: { id?: number; ok?: boolean; result?: ParsedMail; error?: string; warmupMs?: number }) => {
+        // 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 as ParsedMail);
+        else entry.reject(new Error(msg.error || "parse-worker error"));
+        signalCompletion();
+    });
+    w.on("error", (e: Error) => {
+        // 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: number) => {
+        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(): Promise<void> {
     if (_pumping) return;
     _pumping = true;
     try {
+        const { simpleParser } = await import("mailparser");
         for (;;) {
             const next = _head.shift() ?? _tail.shift();
             if (!next) break;
@@ -65,17 +124,72 @@ async function pump(): Promise<void> {
     }
 }
 
-/** 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: (() => void) | null = null;
+function signalCompletion(): void {
+    const fn = _completionSignal;
+    _completionSignal = null;
+    if (fn) fn();
+}
+
+async function pumpViaWorker(): Promise<void> {
+    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<void>(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(): void {
+    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: Source,
     priority: "foreground" | "background" = "foreground",
 ): Promise<ParsedMail> {
     return new Promise<ParsedMail>((resolve, reject) => {
-        const entry: Pending = { source, resolve, reject };
+        const entry: Pending = { 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: unknown) {
+            console.error(`  [parse-serial] worker unavailable, falling back to main-thread parse: ${e instanceof Error ? e.message : String(e)}`);
+            pumpInMain();
+        }
     });
 }

package/packages/mailx-store/parse-worker.d.ts

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

package/packages/mailx-store/parse-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-worker.d.ts","sourceRoot":"","sources":["parse-worker.ts"],"names":[],"mappings":""}

package/packages/mailx-store/parse-worker.js

@@ -0,0 +1,53 @@
+/**
+ * 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 {
+        const result = await simpleParser(source);
+        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

package/packages/mailx-store/parse-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-worker.js","sourceRoot":"","sources":["parse-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAe,MAAM,YAAY,CAAC;AAEvD,IAAI,CAAC,UAAU,EAAE,CAAC;IACd,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;AACrF,CAAC;AAOD,0EAA0E;AAC1E,kEAAkE;AAClE,yEAAyE;AACzE,0EAA0E;AAC1E,qEAAqE;AACrE,uEAAuE;AACvE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;AAC7B,MAAM,cAAc,GAAG,YAAY,CAAC,MAAM,CAAC,IAAI,CAC3C,wDAAwD;MACtD,0CAA0C;MAC1C,iDAAiD;MACjD,gDAAgD,EAClD,MAAM,CACT,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;IACT,kEAAkE;IAClE,UAAW,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;AAClE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAA8D,CAAC,CAAC,CAAC;AAE/E,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,GAAiB,EAAE,EAAE;IACjD,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IAC3B,oEAAoE;IACpE,kEAAkE;IAClE,mDAAmD;IACnD,MAAM,cAAc,CAAC;IACrB,IAAI,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;QAC1C,UAAW,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,CAAU,EAAE,CAAC;QAClB,MAAM,KAAK,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACzD,UAAW,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACtD,CAAC;AACL,CAAC,CAAC,CAAC"}

package/packages/mailx-store/parse-worker.ts

@@ -0,0 +1,62 @@
+/**
+ * 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, type Source } from "mailparser";
+
+if (!parentPort) {
+    throw new Error("parse-worker: must be spawned as a worker, parentPort is null");
+}
+
+interface ParseRequest {
+    id: number;
+    source: Source;
+}
+
+// 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(() => { /* warmup is best-effort; fall through to real handling */ });
+
+parentPort.on("message", async (msg: ParseRequest) => {
+    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 {
+        const result = await simpleParser(source);
+        parentPort!.postMessage({ id, ok: true, result });
+    } catch (e: unknown) {
+        const error = e instanceof Error ? e.message : String(e);
+        parentPort!.postMessage({ id, ok: false, error });
+    }
+});