@bobfrankston/mailx-types 0.1.38 → 0.1.41

package/index.d.ts

@@ -11,6 +11,8 @@ export type { GroupMap, RecipientToken, ExpansionResult } from "./groups.js";
 export { REMINDER_STATE_FILE, normalizeReminderState, mergeReminderStates, reminderStatesEqual, } from "./reminder-state.js";
 export type { ReminderState } from "./reminder-state.js";
 export { extractInlineImages } from "./mime-inline-images.js";
+export { buildMimeMessage } from "./mime-build.js";
+export type { BuildMimeOptions, BuiltMime, MimeAttachment } from "./mime-build.js";
 export type { InlineImagePart } from "./mime-inline-images.js";
 /** Supported authentication methods */
 export type AuthMethod = "password" | "oauth2";
@@ -363,6 +365,46 @@ export declare function sanitizeHtml(html: string): {
     html: string;
     hasRemoteContent: boolean;
 };
+/**
+ * Encode a header VALUE as RFC 2047 encoded-words when it contains non-ASCII.
+ *
+ * Why this has to exist: a header carrying raw 8-bit UTF-8 makes the whole
+ * message an EAI message (RFC 6530), which can only be relayed over SMTPUTF8
+ * (RFC 6531). Plenty of receivers still don't advertise that extension, and a
+ * sending MTA that can't downgrade has no choice but to bounce. mailx built
+ * every outgoing header with bare interpolation — `Subject: ${msg.subject}` —
+ * so ONE curly apostrophe was enough to make a message undeliverable:
+ *
+ *   Subject: Re: … One of Canada’s Fastest Fiber Networks     (U+2019, raw UTF-8)
+ *   → <alland@soundbytesradio.com>: EAI message but server 17.57.152.5
+ *     does not support SMTPUTF8 … This is a permanent error
+ *
+ * (Bob 2026-08-08, qmail bounce from gal.iecc.com — iCloud, Zoho and
+ * land-com all refused it; herot.com, gmail and bob.ma took it, so it looked
+ * like a partial failure.) Reply subjects inherit whatever punctuation the
+ * original used, and Word/paste smart quotes do the rest, so this fires
+ * constantly and silently.
+ *
+ * Pure-ASCII values are returned untouched — encoding them would be legal but
+ * needlessly unreadable in every mail client's raw-source view.
+ *
+ * Base64 rather than Q-encoding: it is uniform (no per-character escaping
+ * rules that differ between phrase and unstructured context) and never
+ * produces a token needing further escaping. Chunks are split so each
+ * encoded-word stays inside RFC 2047's 75-character limit, split on CHARACTER
+ * boundaries so a multi-byte sequence is never cut in half.
+ */
+export declare function encodeHeaderWord(text: string): string;
+/**
+ * Encode an address header value (From/To/Cc/Bcc/Reply-To), encoding only the
+ * DISPLAY NAME of each address. The addr-spec must stay literal: encoding it
+ * would corrupt the address, and a non-ASCII addr-spec is genuinely EAI and
+ * cannot be represented any other way.
+ *
+ * Splits on commas outside angle brackets and quotes so a display name
+ * containing a comma ("Frankston, Bob" <x@y>) survives.
+ */
+export declare function encodeAddressHeader(value: string): string;
 /** Encode text as RFC 2045 quoted-printable. */
 export declare function encodeQuotedPrintable(text: string): string;
 /** Render an HTML document as a plain-text approximation suitable for the

package/index.js

@@ -20,6 +20,7 @@ export { REMINDER_STATE_FILE, normalizeReminderState, mergeReminderStates, remin
 // Outgoing-mail inline images: data: URI → cid: extraction shared by both
 // MIME assemblers (desktop send + Android/web send).
 export { extractInlineImages } from "./mime-inline-images.js";
+export { buildMimeMessage } from "./mime-build.js";
 // ── Message flag state ──
 //
 // External API surface for the IMAP system flags. The literal strings
@@ -106,6 +107,123 @@ export function sanitizeHtml(html) {
     clean = clean.replace(/<iframe\b[^>]*>[\s\S]*?<\/iframe>/gi, "");
     return { html: clean, hasRemoteContent };
 }
+/**
+ * Encode a header VALUE as RFC 2047 encoded-words when it contains non-ASCII.
+ *
+ * Why this has to exist: a header carrying raw 8-bit UTF-8 makes the whole
+ * message an EAI message (RFC 6530), which can only be relayed over SMTPUTF8
+ * (RFC 6531). Plenty of receivers still don't advertise that extension, and a
+ * sending MTA that can't downgrade has no choice but to bounce. mailx built
+ * every outgoing header with bare interpolation — `Subject: ${msg.subject}` —
+ * so ONE curly apostrophe was enough to make a message undeliverable:
+ *
+ *   Subject: Re: … One of Canada’s Fastest Fiber Networks     (U+2019, raw UTF-8)
+ *   → <alland@soundbytesradio.com>: EAI message but server 17.57.152.5
+ *     does not support SMTPUTF8 … This is a permanent error
+ *
+ * (Bob 2026-08-08, qmail bounce from gal.iecc.com — iCloud, Zoho and
+ * land-com all refused it; herot.com, gmail and bob.ma took it, so it looked
+ * like a partial failure.) Reply subjects inherit whatever punctuation the
+ * original used, and Word/paste smart quotes do the rest, so this fires
+ * constantly and silently.
+ *
+ * Pure-ASCII values are returned untouched — encoding them would be legal but
+ * needlessly unreadable in every mail client's raw-source view.
+ *
+ * Base64 rather than Q-encoding: it is uniform (no per-character escaping
+ * rules that differ between phrase and unstructured context) and never
+ * produces a token needing further escaping. Chunks are split so each
+ * encoded-word stays inside RFC 2047's 75-character limit, split on CHARACTER
+ * boundaries so a multi-byte sequence is never cut in half.
+ */
+export function encodeHeaderWord(text) {
+    if (!text)
+        return "";
+    // eslint-disable-next-line no-control-regex
+    if (!/[^\x00-\x7F]/.test(text))
+        return text;
+    const encoder = new TextEncoder();
+    // "=?UTF-8?B?" + payload + "?=" must be ≤ 75 chars, so the base64 payload
+    // gets 75 - 12 = 63 chars, and base64 only splits cleanly every 4 chars →
+    // 60 chars of payload = 45 bytes of input per encoded-word.
+    const MAX_BYTES_PER_WORD = 45;
+    const words = [];
+    let chunk = [];
+    for (const ch of text) { // iterate by code point
+        const bytes = Array.from(encoder.encode(ch));
+        if (chunk.length + bytes.length > MAX_BYTES_PER_WORD) {
+            words.push(chunk);
+            chunk = [];
+        }
+        chunk.push(...bytes);
+    }
+    if (chunk.length)
+        words.push(chunk);
+    // Continuation lines are joined with CRLF + space: consecutive
+    // encoded-words separated by folding whitespace are concatenated by the
+    // receiver with the whitespace REMOVED (RFC 2047 §6.2), which is what we
+    // want — the original text had no space there.
+    return words
+        .map(b => `=?UTF-8?B?${bytesToBase64(Uint8Array.from(b))}?=`)
+        .join("\r\n ");
+}
+/** Base64 without assuming Buffer (this package is browser-capable). */
+function bytesToBase64(bytes) {
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    // btoa exists in browsers and in Node ≥16.
+    return btoa(bin);
+}
+/**
+ * Encode an address header value (From/To/Cc/Bcc/Reply-To), encoding only the
+ * DISPLAY NAME of each address. The addr-spec must stay literal: encoding it
+ * would corrupt the address, and a non-ASCII addr-spec is genuinely EAI and
+ * cannot be represented any other way.
+ *
+ * Splits on commas outside angle brackets and quotes so a display name
+ * containing a comma ("Frankston, Bob" <x@y>) survives.
+ */
+export function encodeAddressHeader(value) {
+    if (!value)
+        return "";
+    // eslint-disable-next-line no-control-regex
+    if (!/[^\x00-\x7F]/.test(value))
+        return value;
+    const parts = [];
+    let cur = "";
+    let inAngle = false;
+    let inQuote = false;
+    for (const ch of value) {
+        if (ch === '"')
+            inQuote = !inQuote;
+        else if (ch === "<" && !inQuote)
+            inAngle = true;
+        else if (ch === ">" && !inQuote)
+            inAngle = false;
+        if (ch === "," && !inAngle && !inQuote) {
+            parts.push(cur);
+            cur = "";
+            continue;
+        }
+        cur += ch;
+    }
+    if (cur.trim())
+        parts.push(cur);
+    return parts.map(part => {
+        const p = part.trim();
+        const m = /^(.*?)\s*(<[^>]*>)\s*$/.exec(p);
+        if (!m)
+            return p; // bare addr-spec, nothing to encode
+        const display = m[1].replace(/^"(.*)"$/s, "$1");
+        if (!display)
+            return m[2];
+        // eslint-disable-next-line no-control-regex
+        if (!/[^\x00-\x7F]/.test(display))
+            return p; // ASCII name — leave the quoting alone
+        return `${encodeHeaderWord(display)} ${m[2]}`;
+    }).join(", ");
+}
 /** Encode text as RFC 2045 quoted-printable. */
 export function encodeQuotedPrintable(text) {
     const encoder = new TextEncoder();

package/mime-build.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Assemble an RFC 5322 / MIME message. The ONE place that does this.
+ *
+ * Why it exists: four live code paths built messages by hand — desktop send
+ * and draft (`mailx-service`), Android/web send and draft (`mailx-store-web`)
+ * — 72% identical line-for-line, plus four more copies in packages nothing
+ * could reach. Every fix to the shape had to be found and applied N times,
+ * and the N-th was routinely missed:
+ *
+ *   - v1.2.166  envelope scraped quoted headers — "SAME shape in 3 files"
+ *   - v1.2.179  inline images data: → cid: — had to land in BOTH send paths
+ *   - v1.2.226  RFC 2047 encoded-words — 7 sites by hand, and the Android
+ *               path still got only Subject: its From/To/Cc/Bcc were raw
+ *               interpolation until this unification (2026-08-09), so an
+ *               accented display name sent from Android was still an EAI
+ *               message that non-SMTPUTF8 receivers bounce
+ *
+ * The shape produced is unchanged from what desktop send has emitted since
+ * v1.2.179 — this is an extraction, verified byte-for-byte against the old
+ * code over a matrix of body/attachment/inline-image/header combinations
+ * (see `test/mime-build.test.mjs`), not a rewrite.
+ *
+ * Structure it emits, narrowest form that carries the content:
+ *
+ *   text only ............... text/plain
+ *   html .................... multipart/alternative (plain derived + html)
+ *   html + pasted images .... multipart/related [ alternative, image parts ]
+ *   any of those + files .... multipart/mixed [ the above, attachments ]
+ *   draft (simpleHtml) ...... a single text/html part, no alternative
+ */
+export interface MimeAttachment {
+    filename?: string;
+    mimeType?: string;
+    dataBase64?: string;
+}
+export interface BuildMimeOptions {
+    /** Already-formatted address strings ("Name <a@b>", comma-separated). */
+    from: string;
+    to?: string;
+    cc?: string;
+    bcc?: string;
+    subject: string;
+    bodyHtml?: string;
+    bodyText?: string;
+    attachments?: MimeAttachment[];
+    inReplyTo?: string;
+    references?: string[];
+    /** Supply to reuse an existing id; omit and one is generated from `domain`. */
+    messageId?: string;
+    /** Domain for the generated Message-ID and for inline-image cid: ids. */
+    domain: string;
+    /** Extra header lines inserted before MIME-Version (e.g. X-Mailx-Draft-ID). */
+    extraHeaders?: string[];
+    /** Emit no Message-ID header at all — the draft paths never carried one. */
+    omitMessageId?: boolean;
+    /** Draft mode: one text/html part, no alternative / related / mixed and no
+     *  inline-image extraction. A draft is re-parsed by the compose window, not
+     *  delivered, so the multipart machinery would only get in the way. */
+    simpleHtml?: boolean;
+    /** Injectable for tests; defaults to `new Date()`. */
+    now?: Date;
+    /** Injectable for tests so boundaries and ids are reproducible. */
+    unique?: () => string;
+}
+export interface BuiltMime {
+    /** The complete message, CRLF line endings, ready for SMTP or APPEND. */
+    raw: string;
+    /** The Message-ID actually used (empty when `omitMessageId`). */
+    messageId: string;
+    /** How many data: images became cid: parts — worth logging. */
+    inlineImageCount: number;
+}
+export declare function buildMimeMessage(opts: BuildMimeOptions): BuiltMime;
+//# sourceMappingURL=mime-build.d.ts.map

package/mime-build.js

@@ -0,0 +1,160 @@
+/**
+ * Assemble an RFC 5322 / MIME message. The ONE place that does this.
+ *
+ * Why it exists: four live code paths built messages by hand — desktop send
+ * and draft (`mailx-service`), Android/web send and draft (`mailx-store-web`)
+ * — 72% identical line-for-line, plus four more copies in packages nothing
+ * could reach. Every fix to the shape had to be found and applied N times,
+ * and the N-th was routinely missed:
+ *
+ *   - v1.2.166  envelope scraped quoted headers — "SAME shape in 3 files"
+ *   - v1.2.179  inline images data: → cid: — had to land in BOTH send paths
+ *   - v1.2.226  RFC 2047 encoded-words — 7 sites by hand, and the Android
+ *               path still got only Subject: its From/To/Cc/Bcc were raw
+ *               interpolation until this unification (2026-08-09), so an
+ *               accented display name sent from Android was still an EAI
+ *               message that non-SMTPUTF8 receivers bounce
+ *
+ * The shape produced is unchanged from what desktop send has emitted since
+ * v1.2.179 — this is an extraction, verified byte-for-byte against the old
+ * code over a matrix of body/attachment/inline-image/header combinations
+ * (see `test/mime-build.test.mjs`), not a rewrite.
+ *
+ * Structure it emits, narrowest form that carries the content:
+ *
+ *   text only ............... text/plain
+ *   html .................... multipart/alternative (plain derived + html)
+ *   html + pasted images .... multipart/related [ alternative, image parts ]
+ *   any of those + files .... multipart/mixed [ the above, attachments ]
+ *   draft (simpleHtml) ...... a single text/html part, no alternative
+ */
+import { encodeQuotedPrintable, encodeHeaderWord, encodeAddressHeader, htmlToPlainText } from "./index.js";
+import { extractInlineImages } from "./mime-inline-images.js";
+/** Base64 must be folded at ≤76 chars per RFC 2045. */
+function wrap76(s) {
+    return s.match(/.{1,76}/g)?.join("\r\n") || s;
+}
+export function buildMimeMessage(opts) {
+    const now = opts.now || new Date();
+    const unique = opts.unique
+        || (() => `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`);
+    const newBoundary = () => `mailx_${unique()}`;
+    const messageId = opts.omitMessageId
+        ? ""
+        : (opts.messageId || `<${Date.now()}.${Math.random().toString(36).slice(2)}@${opts.domain}>`);
+    const hasHtml = !!opts.bodyHtml;
+    // ── headers ──
+    // RFC 2047 on every header that can carry a display name or free text.
+    // Raw 8-bit here makes the whole message EAI (RFC 6530), which a receiver
+    // without SMTPUTF8 (RFC 6531) must refuse — one curly apostrophe in a
+    // Subject cost three recipients on 2026-08-08.
+    const headers = [
+        `From: ${encodeAddressHeader(opts.from)}`,
+        opts.to ? `To: ${encodeAddressHeader(opts.to)}` : null,
+        opts.cc ? `Cc: ${encodeAddressHeader(opts.cc)}` : null,
+        // Bcc belongs IN a draft — the SEND path strips it, so that a saved
+        // draft reopened for editing still shows who was on Bcc.
+        opts.bcc ? `Bcc: ${encodeAddressHeader(opts.bcc)}` : null,
+        `Subject: ${encodeHeaderWord(opts.subject)}`,
+        `Date: ${now.toUTCString()}`,
+        messageId ? `Message-ID: ${messageId}` : null,
+        opts.inReplyTo ? `In-Reply-To: ${opts.inReplyTo}` : null,
+        opts.references?.length ? `References: ${opts.references.join(" ")}` : null,
+        ...(opts.extraHeaders || []),
+        `MIME-Version: 1.0`,
+    ];
+    const commonHeaders = headers.filter((h) => h !== null);
+    // ── draft: a single text/html part and nothing else ──
+    if (opts.simpleHtml) {
+        const body = opts.bodyHtml || opts.bodyText || "";
+        const raw = [
+            ...commonHeaders,
+            `Content-Type: text/html; charset=UTF-8`,
+            `Content-Transfer-Encoding: quoted-printable`,
+        ].join("\r\n") + `\r\n\r\n` + encodeQuotedPrintable(body);
+        return { raw, messageId, inlineImageCount: 0 };
+    }
+    // Pasted images live in the editor HTML as data: URIs — fine in a WebView,
+    // broken for recipients on Outlook desktop (won't render data: images) and
+    // Gmail web (sanitizer strips them). Extract to cid:-referenced parts.
+    const extracted = hasHtml
+        ? extractInlineImages(opts.bodyHtml, opts.domain)
+        : { html: "", images: [] };
+    const htmlBody = extracted.html;
+    const inlineImages = extracted.images;
+    // HTML-bodied mail carries a text/plain alternative too: spam filters score
+    // HTML-only mail 1–2 points worse, and plain-text readers still exist.
+    const textBody = opts.bodyText || (hasHtml ? htmlToPlainText(htmlBody) : "");
+    const htmlEncoded = hasHtml ? encodeQuotedPrintable(htmlBody) : "";
+    const textEncoded = encodeQuotedPrintable(textBody);
+    /** The body part that carries the message text, without envelope headers,
+     *  so it can stand alone OR become the first part of a multipart/mixed. */
+    const makeInner = () => {
+        if (hasHtml) {
+            const altBoundary = newBoundary();
+            const body = `--${altBoundary}\r\n` +
+                `Content-Type: text/plain; charset=UTF-8\r\n` +
+                `Content-Transfer-Encoding: quoted-printable\r\n\r\n` +
+                `${textEncoded}\r\n` +
+                `--${altBoundary}\r\n` +
+                `Content-Type: text/html; charset=UTF-8\r\n` +
+                `Content-Transfer-Encoding: quoted-printable\r\n\r\n` +
+                `${htmlEncoded}\r\n` +
+                `--${altBoundary}--\r\n`;
+            const alt = {
+                headers: [`Content-Type: multipart/alternative; boundary="${altBoundary}"`],
+                body,
+            };
+            if (inlineImages.length === 0)
+                return alt;
+            const relBoundary = newBoundary();
+            const relParts = [
+                `--${relBoundary}\r\n` + alt.headers.join("\r\n") + `\r\n\r\n` + alt.body,
+                ...inlineImages.map(im => `--${relBoundary}\r\n` +
+                    `Content-Type: ${im.mime}\r\n` +
+                    `Content-ID: <${im.contentId}>\r\n` +
+                    `Content-Disposition: inline\r\n` +
+                    `Content-Transfer-Encoding: base64\r\n\r\n` +
+                    `${wrap76(im.base64)}\r\n`),
+            ];
+            return {
+                headers: [`Content-Type: multipart/related; boundary="${relBoundary}"; type="multipart/alternative"`],
+                body: relParts.join("") + `--${relBoundary}--\r\n`,
+            };
+        }
+        return {
+            headers: [
+                `Content-Type: text/plain; charset=UTF-8`,
+                `Content-Transfer-Encoding: quoted-printable`,
+            ],
+            body: textEncoded,
+        };
+    };
+    const attachments = opts.attachments || [];
+    let raw;
+    if (attachments.length > 0) {
+        const mixedBoundary = newBoundary();
+        const inner = makeInner();
+        const parts = [
+            `--${mixedBoundary}\r\n` + inner.headers.join("\r\n") + `\r\n\r\n` + inner.body,
+        ];
+        for (const att of attachments) {
+            // A quote or newline in a filename would break out of the header.
+            const filename = (att.filename || "attachment").replace(/[\r\n"]/g, "_");
+            const mime = att.mimeType || "application/octet-stream";
+            parts.push(`--${mixedBoundary}\r\n` +
+                `Content-Type: ${mime}; name="${filename}"\r\n` +
+                `Content-Disposition: attachment; filename="${filename}"\r\n` +
+                `Content-Transfer-Encoding: base64\r\n\r\n` +
+                `${wrap76(att.dataBase64 || "")}\r\n`);
+        }
+        raw = [...commonHeaders, `Content-Type: multipart/mixed; boundary="${mixedBoundary}"`].join("\r\n")
+            + `\r\n\r\n` + parts.join("") + `--${mixedBoundary}--\r\n`;
+    }
+    else {
+        const inner = makeInner();
+        raw = [...commonHeaders, ...inner.headers].join("\r\n") + `\r\n\r\n` + inner.body;
+    }
+    return { raw, messageId, inlineImageCount: inlineImages.length };
+}
+//# sourceMappingURL=mime-build.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-types",
-  "version": "0.1.38",
+  "version": "0.1.41",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",

package/test/mime-build.test.mjs

@@ -0,0 +1,200 @@
+/**
+ * buildMimeMessage must be a pure EXTRACTION of the send/draft assembly that
+ * lived in mailx-service and mailx-store-web — same bytes out, not "close
+ * enough". This compares it against a verbatim copy of the pre-2026-08-09
+ * desktop code (below, `legacyBuild`) across the shapes the app actually
+ * sends. Volatile parts (boundary strings, Message-ID, Date) are injected or
+ * normalised so a diff means a real structural difference.
+ *
+ * Run: node packages/mailx-types/test/mime-build.test.mjs
+ */
+import assert from "node:assert";
+import {
+    buildMimeMessage, encodeQuotedPrintable, encodeHeaderWord,
+    encodeAddressHeader, htmlToPlainText, extractInlineImages,
+} from "../index.js";
+
+// ── the code as it stood in mailx-service/index.ts before the unification ──
+function legacyBuild(o) {
+    const hasHtml = !!o.bodyHtml;
+    const domain = o.domain;
+    const messageId = o.messageId;
+    const extracted = hasHtml ? extractInlineImages(o.bodyHtml, domain) : { html: "", images: [] };
+    const htmlBody = extracted.html;
+    const inlineImages = extracted.images;
+    const textBody = o.bodyText || (hasHtml ? htmlToPlainText(htmlBody) : "");
+    const htmlEncoded = hasHtml ? encodeQuotedPrintable(htmlBody) : "";
+    const textEncoded = encodeQuotedPrintable(textBody);
+    const hasAttachments = Array.isArray(o.attachments) && o.attachments.length > 0;
+    const commonHeaders = [
+        `From: ${encodeAddressHeader(o.from)}`, `To: ${encodeAddressHeader(o.to)}`,
+        o.cc ? `Cc: ${encodeAddressHeader(o.cc)}` : null,
+        o.bcc ? `Bcc: ${encodeAddressHeader(o.bcc)}` : null,
+        `Subject: ${encodeHeaderWord(o.subject)}`, `Date: ${o.now.toUTCString()}`,
+        `Message-ID: ${messageId}`,
+        o.inReplyTo ? `In-Reply-To: ${o.inReplyTo}` : null,
+        o.references?.length ? `References: ${o.references.join(" ")}` : null,
+        `MIME-Version: 1.0`,
+    ].filter(h => h !== null);
+
+    let rawMessage;
+    let n = 0;
+    const newBoundary = () => `mailx_B${n++}`;
+    const wrap76 = (s) => s.match(/.{1,76}/g)?.join("\r\n") || s;
+    const makeInner = () => {
+        if (hasHtml) {
+            const altBoundary = newBoundary();
+            const body =
+                `--${altBoundary}\r\n` +
+                `Content-Type: text/plain; charset=UTF-8\r\n` +
+                `Content-Transfer-Encoding: quoted-printable\r\n\r\n` +
+                `${textEncoded}\r\n` +
+                `--${altBoundary}\r\n` +
+                `Content-Type: text/html; charset=UTF-8\r\n` +
+                `Content-Transfer-Encoding: quoted-printable\r\n\r\n` +
+                `${htmlEncoded}\r\n` +
+                `--${altBoundary}--\r\n`;
+            const alt = { headers: [`Content-Type: multipart/alternative; boundary="${altBoundary}"`], body };
+            if (inlineImages.length === 0) return alt;
+            const relBoundary = newBoundary();
+            const relParts = [
+                `--${relBoundary}\r\n` + alt.headers.join("\r\n") + `\r\n\r\n` + alt.body,
+                ...inlineImages.map(im =>
+                    `--${relBoundary}\r\n` +
+                    `Content-Type: ${im.mime}\r\n` +
+                    `Content-ID: <${im.contentId}>\r\n` +
+                    `Content-Disposition: inline\r\n` +
+                    `Content-Transfer-Encoding: base64\r\n\r\n` +
+                    `${wrap76(im.base64)}\r\n`),
+            ];
+            return {
+                headers: [`Content-Type: multipart/related; boundary="${relBoundary}"; type="multipart/alternative"`],
+                body: relParts.join("") + `--${relBoundary}--\r\n`,
+            };
+        }
+        return {
+            headers: [`Content-Type: text/plain; charset=UTF-8`, `Content-Transfer-Encoding: quoted-printable`],
+            body: textEncoded,
+        };
+    };
+    if (hasAttachments) {
+        const mixedBoundary = newBoundary();
+        const inner = makeInner();
+        const parts = [`--${mixedBoundary}\r\n` + inner.headers.join("\r\n") + `\r\n\r\n` + inner.body];
+        for (const att of o.attachments) {
+            const filename = (att.filename || "attachment").replace(/[\r\n"]/g, "_");
+            const mime = att.mimeType || "application/octet-stream";
+            parts.push(
+                `--${mixedBoundary}\r\n` +
+                `Content-Type: ${mime}; name="${filename}"\r\n` +
+                `Content-Disposition: attachment; filename="${filename}"\r\n` +
+                `Content-Transfer-Encoding: base64\r\n\r\n` +
+                `${wrap76(att.dataBase64 || "")}\r\n`
+            );
+        }
+        rawMessage = [...commonHeaders, `Content-Type: multipart/mixed; boundary="${mixedBoundary}"`].join("\r\n")
+            + `\r\n\r\n` + parts.join("") + `--${mixedBoundary}--\r\n`;
+    } else {
+        const inner = makeInner();
+        rawMessage = [...commonHeaders, ...inner.headers].join("\r\n") + `\r\n\r\n` + inner.body;
+    }
+    return rawMessage;
+}
+
+// ── the legacy DRAFT assembly, verbatim ──
+function legacyDraft(o) {
+    const body = o.bodyHtml || o.bodyText || "";
+    return [
+        `From: ${encodeAddressHeader(o.from)}`,
+        o.to ? `To: ${encodeAddressHeader(o.to)}` : null,
+        o.cc ? `Cc: ${encodeAddressHeader(o.cc)}` : null,
+        o.bcc ? `Bcc: ${encodeAddressHeader(o.bcc)}` : null,
+        `Subject: ${encodeHeaderWord(o.subject)}`, `Date: ${o.now.toUTCString()}`,
+        `X-Mailx-Draft-ID: ${o.draftId}`,
+        `MIME-Version: 1.0`, `Content-Type: text/html; charset=UTF-8`,
+        `Content-Transfer-Encoding: quoted-printable`,
+    ].filter(h => h !== null).join("\r\n") + `\r\n\r\n` + encodeQuotedPrintable(body);
+}
+
+const PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
+const now = new Date("Sat, 09 Aug 2026 13:30:00 GMT");
+const messageId = "<fixed.id@bob.ma>";
+const base = { from: "Bob <bob@bob.ma>", to: "A <a@x.com>", subject: "hello", domain: "bob.ma", now, messageId };
+
+const cases = [
+    ["plain text only", { ...base, bodyText: "just text\nwith a line" }],
+    ["html (alternative)", { ...base, bodyHtml: "<p>hi <b>there</b></p>" }],
+    ["html + explicit text", { ...base, bodyHtml: "<p>hi</p>", bodyText: "hi" }],
+    ["html + inline image (related)", { ...base, bodyHtml: `<p>see</p><img src="data:image/png;base64,${PNG}">` }],
+    ["text + attachment (mixed)", { ...base, bodyText: "see file", attachments: [{ filename: "a.txt", mimeType: "text/plain", dataBase64: "aGVsbG8=" }] }],
+    ["html + inline image + 2 attachments", {
+        ...base, bodyHtml: `<p>x</p><img src="data:image/png;base64,${PNG}">`,
+        attachments: [
+            { filename: 'we"ird\nname.pdf', mimeType: "application/pdf", dataBase64: PNG },
+            { dataBase64: "AAAA" },
+        ],
+    }],
+    ["cc + bcc + threading headers", {
+        ...base, bodyText: "t", cc: "C <c@x.com>", bcc: "D <d@x.com>",
+        inReplyTo: "<prev@x.com>", references: ["<a@x.com>", "<b@x.com>"],
+    }],
+    ["non-ASCII display name and subject", {
+        ...base, from: "Bøb Frankstøn <bob@bob.ma>", to: "Renée <r@x.com>",
+        subject: "Canada’s fastest — really", bodyText: "t",
+    }],
+    ["long base64 folding", { ...base, bodyText: "t", attachments: [{ filename: "big.bin", dataBase64: "Q".repeat(500) }] }],
+];
+
+/** extractInlineImages mints a random cid: id per call, so two runs over the
+ *  same input differ there by design. Normalise it for the comparison — what
+ *  must hold is that the SAME id appears in the <img src> and in that part's
+ *  Content-ID, which is asserted separately below. */
+const normCid = (s) => s.replace(/img\d+\.[a-z0-9]+@/g, "img.CID@");
+
+let pass = 0;
+for (const [name, o] of cases) {
+    let n = 0;
+    const got = buildMimeMessage({ ...o, unique: () => `B${n++}` }).raw;
+    const want = legacyBuild(o);
+    assert.strictEqual(normCid(got), normCid(want),
+        `MISMATCH in "${name}"\n--- new ---\n${got}\n--- old ---\n${want}`);
+    // cid self-consistency: every id occurs exactly twice (src + Content-ID)
+    const ids = [...got.matchAll(/img\d+\.[a-z0-9]+@[a-z0-9.]+/g)].map(m => m[0]);
+    for (const id of new Set(ids)) {
+        assert.strictEqual(ids.filter(x => x === id).length, 2,
+            `cid ${id} should appear in both the <img src> and its Content-ID in "${name}"`);
+    }
+    pass++;
+}
+
+// draft path
+for (const [name, o] of [
+    ["draft html", { ...base, bodyHtml: "<p>draft</p>", draftId: "mailx-draft-1" }],
+    ["draft with bcc + alias From", { ...base, from: "Alias <alias@bob.ma>", bodyHtml: "<p>d</p>", cc: "c@x.com", bcc: "b@x.com", draftId: "mailx-draft-2" }],
+    ["draft non-ASCII recipient", { ...base, to: "Renée <r@x.com>", bodyHtml: "<p>d</p>", draftId: "mailx-draft-3" }],
+]) {
+    const got = buildMimeMessage({
+        ...o, simpleHtml: true, omitMessageId: true,
+        extraHeaders: [`X-Mailx-Draft-ID: ${o.draftId}`],
+    }).raw;
+    const want = legacyDraft(o);
+    assert.strictEqual(got, want, `MISMATCH in "${name}"\n--- new ---\n${got}\n--- old ---\n${want}`);
+    pass++;
+}
+
+// Structural guarantees that must hold regardless of the legacy comparison.
+const withImg = buildMimeMessage({ ...base, bodyHtml: `<img src="data:image/png;base64,${PNG}">`, unique: (() => { let i = 0; return () => `B${i++}`; })() });
+assert.match(withImg.raw, /multipart\/related/, "inline image must produce multipart/related");
+assert.match(withImg.raw, /Content-ID: </, "inline image must carry a Content-ID");
+assert.strictEqual(withImg.inlineImageCount, 1);
+assert.ok(!/data:image\/png;base64/.test(withImg.raw), "no data: URI may survive into the wire format");
+pass++;
+
+const eai = buildMimeMessage({ ...base, from: "Bøb <bob@bob.ma>", to: "Renée <r@x.com>", subject: "Canada’s", bodyText: "t" });
+for (const line of eai.raw.split("\r\n")) {
+    if (!line) break;                                  // headers end at the blank line
+    assert.ok(!/[€-￿]/.test(line), `8-bit byte survived in header: ${line}`);
+}
+pass++;
+
+console.log(`mime-build: ${pass} checks passed`);