@ultimat3/mail 1.0.0

package/src/mime.ts

@@ -0,0 +1,233 @@
+// Single responsibility: serialise a `MailMessage` into the raw RFC 5322 / MIME text the SMTP
+// transport writes to `DATA` — header order, RFC 2047 subject encoding, header folding and
+// quoted-printable body encoding. Pure: no I/O, no clock read beyond the `Date` it is given.
+
+import { instant, toZoned, UTC } from '@ultimat3/time';
+import { base64Utf8 } from './base64';
+import { type MailMessage, messageHeaders } from './driver';
+import { headerInvalid } from './errors';
+
+export interface MimeOptions {
+  /** `Postly <no-reply@postly.test>` or a bare `no-reply@postly.test`. */
+  readonly from: string;
+  /** The full `Message-ID` header value, angle brackets included: `<abc@postly.test>`. */
+  readonly messageId: string;
+  readonly date: Date;
+  /** multipart boundary token; the driver generates it. */
+  readonly boundary: string;
+}
+
+const CRLF = '\r\n';
+/** RFC 5322's soft line-fold target for headers. */
+const MAX_FOLD_LINE = 78;
+/** RFC 2045's hard line-length cap for quoted-printable, the trailing `=` included. */
+const MAX_QP_LINE = 76;
+/** RFC 2047: an encoded-word (prefix + payload + suffix) may not exceed this. */
+const MAX_ENCODED_WORD = 75;
+const ENCODED_WORD_PREFIX = '=?UTF-8?B?';
+const ENCODED_WORD_SUFFIX = '?=';
+// The largest byte chunk whose base64 form still fits the encoded-word budget above.
+const MAX_CHUNK_BYTES =
+  Math.floor((MAX_ENCODED_WORD - ENCODED_WORD_PREFIX.length - ENCODED_WORD_SUFFIX.length) / 4) * 3;
+
+const WEEKDAY_NAMES = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'] as const;
+const MONTH_NAMES = [
+  'Jan',
+  'Feb',
+  'Mar',
+  'Apr',
+  'May',
+  'Jun',
+  'Jul',
+  'Aug',
+  'Sep',
+  'Oct',
+  'Nov',
+  'Dec',
+] as const;
+
+/** The complete RFC 5322 message: headers, blank line, multipart/alternative body. CRLF throughout. */
+export function buildMimeMessage(message: MailMessage, options: MimeOptions): string {
+  const headerLines: string[] = [];
+  // Every header goes through one gate, so the CR/LF injection check cannot be forgotten by
+  // whichever header is added next. The check runs on the RAW value: encoding first would let a
+  // non-ASCII subject hide a line break inside an encoded word instead of refusing it, so the
+  // same input would be accepted or rejected depending on whether it happened to be ASCII.
+  const header = (name: string, value: string, encode = false): void => {
+    if (value.includes('\r') || value.includes('\n')) throw headerInvalid(name, message.mailId);
+    headerLines.push(foldHeaderLine(name, encode ? encodeHeaderValue(value) : value));
+  };
+
+  header('From', options.from);
+  header('To', message.to.join(', '));
+  if (message.cc !== undefined && message.cc.length > 0) header('Cc', message.cc.join(', '));
+  header('Subject', message.subject, true);
+  header('Date', rfc5322Date(options.date));
+  header('Message-ID', options.messageId);
+  header('MIME-Version', '1.0');
+  // RFC 8058 one-click unsubscribe and friends: computed once in driver.ts, emitted verbatim
+  // here so there is exactly one place that decides which of these headers a message gets.
+  for (const [name, value] of Object.entries(messageHeaders(message))) header(name, value);
+  header('Content-Type', `multipart/alternative; boundary="${options.boundary}"`);
+
+  return `${headerLines.join(CRLF)}${CRLF}${CRLF}${buildBody(message, options.boundary)}`;
+}
+
+/** multipart/alternative: text first, html second — clients render the last part they understand. */
+function buildBody(message: MailMessage, boundary: string): string {
+  return (
+    `--${boundary}${CRLF}` +
+    bodyPart('text/plain', message.text) +
+    `--${boundary}${CRLF}` +
+    bodyPart('text/html', message.html) +
+    `--${boundary}--${CRLF}`
+  );
+}
+
+function bodyPart(contentType: string, text: string): string {
+  return (
+    `Content-Type: ${contentType}; charset=utf-8${CRLF}` +
+    `Content-Transfer-Encoding: quoted-printable${CRLF}` +
+    CRLF +
+    `${quotedPrintable(text)}${CRLF}`
+  );
+}
+
+/** `Postly <no-reply@postly.test>` -> `no-reply@postly.test`. A bare address is returned as-is. */
+export function addressSpec(address: string): string {
+  const match = /<([^<>]+)>\s*$/.exec(address);
+  return match?.[1] ?? address;
+}
+
+/** The domain half of an address spec, for building a `Message-ID`. */
+export function addressDomain(address: string): string {
+  const spec = addressSpec(address);
+  const at = spec.lastIndexOf('@');
+  return at === -1 ? spec : spec.slice(at + 1);
+}
+
+/** RFC 2047 `=?UTF-8?B?…?=` when the value is not pure ASCII, otherwise the value unchanged. */
+export function encodeHeaderValue(value: string): string {
+  if (isPureAscii(value)) return value;
+  // Encoded-words are joined by a plain space, not a hard fold: RFC 2047 says any linear
+  // whitespace between adjacent encoded-words is discarded on decode, so `foldHeaderLine`
+  // is free to turn that space into a CRLF continuation later without changing the meaning.
+  return utf8Chunks(value)
+    .map((chunk) => `${ENCODED_WORD_PREFIX}${base64Utf8(chunk)}${ENCODED_WORD_SUFFIX}`)
+    .join(' ');
+}
+
+/** Splits `text` on whole code points so no chunk's UTF-8 form exceeds `MAX_CHUNK_BYTES`. */
+function utf8Chunks(text: string): string[] {
+  const encoder = new TextEncoder();
+  const chunks: string[] = [];
+  let chunk = '';
+  let chunkBytes = 0;
+  for (const char of text) {
+    const charBytes = encoder.encode(char).length;
+    if (chunk !== '' && chunkBytes + charBytes > MAX_CHUNK_BYTES) {
+      chunks.push(chunk);
+      chunk = '';
+      chunkBytes = 0;
+    }
+    chunk += char;
+    chunkBytes += charBytes;
+  }
+  if (chunk !== '') chunks.push(chunk);
+  return chunks;
+}
+
+// A `\xNN` regex range trips Biome's control-character lint, so ASCII-ness is a byte scan.
+function isPureAscii(value: string): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    if (value.charCodeAt(index) > 0x7f) return false;
+  }
+  return true;
+}
+
+/**
+ * `Name: value` folded to <= 78 chars per line with CRLF + single space continuations. The value
+ * is copied through, never re-spaced: unfolding restores exactly one space per fold point, so a
+ * subject that legitimately holds a run of spaces survives the round trip. A value with no fold
+ * point (one very long URL) stays over-long rather than being broken mid-token.
+ */
+export function foldHeaderLine(name: string, value: string): string {
+  const lines: string[] = [];
+  let remainder = `${name}: ${value}`;
+  // The space after the colon is not a fold point, and neither is a continuation's own leading
+  // space: folding there would emit a line holding nothing but the field name.
+  let earliest = name.length + 1;
+  while (remainder.length > MAX_FOLD_LINE) {
+    const at = remainder.lastIndexOf(' ', MAX_FOLD_LINE);
+    if (at <= earliest) break;
+    lines.push(remainder.slice(0, at));
+    remainder = ` ${remainder.slice(at + 1)}`;
+    earliest = 0;
+  }
+  lines.push(remainder);
+  return lines.join(CRLF);
+}
+
+/** RFC 2045 quoted-printable, CRLF line endings, soft breaks at 76 chars. */
+export function quotedPrintable(text: string): string {
+  // Collapse any line-ending style down to `\n` first, then re-expand to `\r\n` — the only
+  // way to guarantee a bare `\n` becomes `\r\n` without ever doubling an existing `\r\n`.
+  return text.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n').map(encodeQpLine).join(CRLF);
+}
+
+function encodeQpLine(line: string): string {
+  const tokens = [...new TextEncoder().encode(line)].map((byte) =>
+    isQpLiteral(byte) ? String.fromCharCode(byte) : qpEscape(byte),
+  );
+  protectTrailingWhitespace(tokens);
+  return wrapQpTokens(tokens);
+}
+
+function isQpLiteral(byte: number): boolean {
+  if (byte === 0x09 || byte === 0x20) return true; // tab, space — protected below if trailing
+  return byte >= 33 && byte <= 126 && byte !== 0x3d; // printable ASCII, '=' excluded
+}
+
+function qpEscape(byte: number): string {
+  return `=${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+}
+
+/** A trailing run of literal space/tab risks silent loss in transit; escape all of it. */
+function protectTrailingWhitespace(tokens: string[]): void {
+  for (let index = tokens.length - 1; index >= 0; index -= 1) {
+    const token = tokens[index];
+    if (token !== ' ' && token !== '\t') break;
+    tokens[index] = qpEscape(token.charCodeAt(0));
+  }
+}
+
+/** Greedily packs tokens (never split) into <= 76-char lines, reserving one column for `=`. */
+function wrapQpTokens(tokens: string[]): string {
+  const lines: string[] = [];
+  let line = '';
+  for (const token of tokens) {
+    if (line.length + token.length > MAX_QP_LINE - 1) {
+      lines.push(`${line}=`);
+      line = '';
+    }
+    line += token;
+  }
+  lines.push(line);
+  return lines.join(CRLF);
+}
+
+/** `Tue, 09 Aug 2026 12:34:56 +0000` — always UTC, and the zone is stated, never ambient. */
+export function rfc5322Date(at: Date): string {
+  const zoned = toZoned(instant(at), UTC);
+  // weekday is ISO 1-7 and month is 1-12 by ZonedDateTime's own contract, so these never miss;
+  // the fallback exists only to satisfy noUncheckedIndexedAccess.
+  const weekday = WEEKDAY_NAMES[zoned.weekday - 1] ?? 'Mon';
+  const month = MONTH_NAMES[zoned.month - 1] ?? 'Jan';
+  const date = `${pad2(zoned.day)} ${month} ${zoned.year}`;
+  const time = `${pad2(zoned.hour)}:${pad2(zoned.minute)}:${pad2(zoned.second)}`;
+  return `${weekday}, ${date} ${time} +0000`;
+}
+
+function pad2(value: number): string {
+  return String(value).padStart(2, '0');
+}

package/src/render.d.ts

@@ -0,0 +1,26 @@
+import { type Translator } from '@ultimat3/i18n';
+import type { MailBlock, MailTemplate } from './blocks';
+/** What the renderer needs from a mail. `MailDefinition` adds the input schema on top. */
+export interface RenderableMail<I> {
+    readonly id: string;
+    readonly subject: string;
+    readonly template: MailTemplate<I>;
+    readonly layout: string;
+}
+export interface RenderOptions {
+    readonly locale: string;
+    readonly tz: string;
+    readonly unsubscribeUrl?: string | undefined;
+}
+export interface RenderedMail {
+    readonly subject: string;
+    readonly preheader: string;
+    readonly html: string;
+    readonly text: string;
+}
+export declare const FOOTER_KEYS: readonly ['mail.footer.legal', 'mail.footer.help'];
+export declare const UNSUBSCRIBE_KEY = "mail.footer.unsubscribe";
+export declare function renderMail<I>(mail: RenderableMail<I>, data: I, options: RenderOptions): RenderedMail;
+/** The text part, block by block. Never derived from the HTML. */
+export declare function textOf(list: readonly MailBlock[], t: Translator): string;
+//# sourceMappingURL=render.d.ts.map

package/src/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["render.ts"],"names":[],"mappings":"AAKA,OAAO,EAAmC,KAAK,UAAU,EAAiB,MAAM,gBAAgB,CAAC;AACjG,OAAO,KAAK,EAAe,SAAS,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAKrE,0FAA0F;AAC1F,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,WAAW,YAAI,mBAAmB,EAAE,kBAAkB,CAAU,CAAC;AAC9E,eAAO,MAAM,eAAe,4BAA4B,CAAC;AAEzD,wBAAgB,UAAU,CAAC,CAAC,EAC1B,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,aAAa,GACrB,YAAY,CAmCd;AAED,kEAAkE;AAClE,wBAAgB,MAAM,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,EAAE,CAAC,EAAE,UAAU,GAAG,MAAM,CAoBxE"}

package/src/render.js

@@ -0,0 +1,149 @@
+// Single responsibility: turn a template's block list into BOTH an HTML part and a plain-text
+// part. One source of truth per mail — the text is derived from the blocks, never scraped back
+// out of the HTML, so it never rots. Styling is inlined from the layout's tokens because most
+// clients drop <style>; the dark-mode block is the one exception, for clients that honour it.
+import { directionOf, translatorFor } from '@ultimat3/i18n';
+import { layoutUnknown, textMissing } from './errors';
+import { escapeHtml, safeUrl, styleAttr } from './html';
+import { layoutFor, registeredLayouts, token } from './layout';
+export const FOOTER_KEYS = ['mail.footer.legal', 'mail.footer.help'];
+export const UNSUBSCRIBE_KEY = 'mail.footer.unsubscribe';
+export function renderMail(mail, data, options) {
+    const layout = layoutFor(mail.layout);
+    if (layout === undefined)
+        throw layoutUnknown(mail.id, mail.layout, registeredLayouts());
+    const t = translatorFor(options.locale);
+    const vars = toVars(data);
+    const subject = t(mail.subject, vars);
+    const preheaderKey = `mail.${mail.id}.preheader`;
+    const preheader = t.has(preheaderKey) ? t(preheaderKey, vars) : subject;
+    const list = mail.template({ data, t, locale: options.locale, tz: options.tz });
+    const bodyText = textOf(list, t);
+    if (bodyText.trim() === '')
+        throw textMissing(mail.id);
+    const footer = FOOTER_KEYS.filter((key) => t.has(key)).map((key) => t(key, vars));
+    const unsubscribe = options.unsubscribeUrl === undefined
+        ? undefined
+        : { label: t(UNSUBSCRIBE_KEY), url: options.unsubscribeUrl };
+    const html = layout({
+        subject,
+        preheader,
+        content: list.map((block) => htmlOf(block, t)).join(''),
+        footer,
+        unsubscribe,
+        locale: options.locale,
+        direction: directionOf(options.locale),
+    });
+    const tail = [...footer];
+    if (unsubscribe !== undefined)
+        tail.push(`${unsubscribe.label}: ${safeUrl(unsubscribe.url)}`);
+    const text = tail.length === 0 ? bodyText : `${bodyText}\n\n--\n${tail.join('\n')}`;
+    return { subject, preheader, html, text };
+}
+/** The text part, block by block. Never derived from the HTML. */
+export function textOf(list, t) {
+    const lines = [];
+    for (const block of list) {
+        switch (block.kind) {
+            case 'heading':
+            case 'paragraph':
+            case 'callout':
+                lines.push(t(block.key, block.vars));
+                break;
+            case 'button':
+                lines.push(`${t(block.key, block.vars)}: ${safeUrl(block.href)}`);
+                break;
+            case 'detail':
+                lines.push(`${t(block.key)}: ${block.value}`);
+                break;
+            case 'divider':
+                break;
+        }
+    }
+    return lines.join('\n\n');
+}
+const HEADING_STYLE = styleAttr([
+    'margin:0 0 16px 0',
+    'font-size:24px',
+    'line-height:32px',
+    'font-weight:600',
+    `color:${token('textPrimary')}`,
+]);
+const PARAGRAPH_STYLE = styleAttr([
+    'margin:0 0 16px 0',
+    'font-size:16px',
+    'line-height:24px',
+    `color:${token('textPrimary')}`,
+]);
+const DETAIL_LABEL_STYLE = styleAttr([`color:${token('textMuted')}`, 'font-size:14px']);
+const BUTTON_LINK_STYLE = styleAttr([
+    'display:inline-block',
+    'padding:12px 22px',
+    'font-size:16px',
+    'font-weight:600',
+    'text-decoration:none',
+    `color:${token('accentText')}`,
+    `background-color:${token('accentBg')}`,
+    'border-radius:8px',
+]);
+const DIVIDER_STYLE = styleAttr([
+    `border-top:1px solid ${token('borderSubtle')}`,
+    'font-size:0',
+    'line-height:0',
+    'height:1px',
+    'padding:8px 0 0 0',
+]);
+const TABLE_ATTRS = 'role="presentation" cellpadding="0" cellspacing="0" border="0"';
+function calloutStyle(tone) {
+    const bg = tone === 'danger' ? token('calloutDangerBg') : token('calloutInfoBg');
+    const fg = tone === 'danger' ? token('calloutDangerText') : token('calloutInfoText');
+    return styleAttr([
+        `background-color:${bg}`,
+        `color:${fg}`,
+        'padding:16px',
+        'border-radius:8px',
+        'font-size:15px',
+        'line-height:22px',
+    ]);
+}
+function htmlOf(block, t) {
+    switch (block.kind) {
+        case 'heading':
+            return `<h1 data-x="h" ${HEADING_STYLE}>${escapeHtml(t(block.key, block.vars))}</h1>`;
+        case 'paragraph':
+            return `<p data-x="p" ${PARAGRAPH_STYLE}>${escapeHtml(t(block.key, block.vars))}</p>`;
+        case 'button': {
+            const href = escapeHtml(safeUrl(block.href));
+            const label = escapeHtml(t(block.key, block.vars));
+            const anchor = `<a data-x="btn" href="${href}" ${BUTTON_LINK_STYLE}>${label}</a>`;
+            return `<table ${TABLE_ATTRS}><tr><td>${anchor}</td></tr></table>`;
+        }
+        case 'callout': {
+            const role = block.tone === 'danger' ? 'cd' : 'ci';
+            const body = escapeHtml(t(block.key, block.vars));
+            const cell = `<td data-x="${role}" ${calloutStyle(block.tone)}>${body}</td>`;
+            return `<table ${TABLE_ATTRS} width="100%"><tr>${cell}</tr></table>`;
+        }
+        case 'detail': {
+            const label = `<span data-x="mut" ${DETAIL_LABEL_STYLE}>${escapeHtml(t(block.key))}</span>`;
+            return `<p data-x="p" ${PARAGRAPH_STYLE}>${label} ${escapeHtml(block.value)}</p>`;
+        }
+        case 'divider': {
+            const cell = `<td data-x="hr" ${DIVIDER_STYLE}></td>`;
+            return `<table ${TABLE_ATTRS} width="100%"><tr>${cell}</tr></table>`;
+        }
+    }
+}
+/** Scalar fields of the payload become interpolation vars; Dates and objects never do. */
+function toVars(data) {
+    const vars = {};
+    if (typeof data !== 'object' || data === null)
+        return vars;
+    for (const [key, value] of Object.entries(data)) {
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            vars[key] = value;
+        }
+    }
+    return vars;
+}
+//# sourceMappingURL=render.js.map

package/src/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["render.ts"],"names":[],"mappings":"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"}

package/src/render.ts

@@ -0,0 +1,190 @@
+// Single responsibility: turn a template's block list into BOTH an HTML part and a plain-text
+// part. One source of truth per mail — the text is derived from the blocks, never scraped back
+// out of the HTML, so it never rots. Styling is inlined from the layout's tokens because most
+// clients drop <style>; the dark-mode block is the one exception, for clients that honour it.
+
+import { directionOf, type TranslateVars, type Translator, translatorFor } from '@ultimat3/i18n';
+import type { CalloutTone, MailBlock, MailTemplate } from './blocks';
+import { layoutUnknown, textMissing } from './errors';
+import { escapeHtml, safeUrl, styleAttr } from './html';
+import { layoutFor, registeredLayouts, token } from './layout';
+
+/** What the renderer needs from a mail. `MailDefinition` adds the input schema on top. */
+export interface RenderableMail<I> {
+  readonly id: string;
+  readonly subject: string;
+  readonly template: MailTemplate<I>;
+  readonly layout: string;
+}
+
+export interface RenderOptions {
+  readonly locale: string;
+  readonly tz: string;
+  readonly unsubscribeUrl?: string | undefined;
+}
+
+export interface RenderedMail {
+  readonly subject: string;
+  readonly preheader: string;
+  readonly html: string;
+  readonly text: string;
+}
+
+export const FOOTER_KEYS = ['mail.footer.legal', 'mail.footer.help'] as const;
+export const UNSUBSCRIBE_KEY = 'mail.footer.unsubscribe';
+
+export function renderMail<I>(
+  mail: RenderableMail<I>,
+  data: I,
+  options: RenderOptions,
+): RenderedMail {
+  const layout = layoutFor(mail.layout);
+  if (layout === undefined) throw layoutUnknown(mail.id, mail.layout, registeredLayouts());
+
+  const t = translatorFor(options.locale);
+  const vars = toVars(data);
+  const subject = t(mail.subject, vars);
+  const preheaderKey = `mail.${mail.id}.preheader`;
+  const preheader = t.has(preheaderKey) ? t(preheaderKey, vars) : subject;
+
+  const list = mail.template({ data, t, locale: options.locale, tz: options.tz });
+  const bodyText = textOf(list, t);
+  if (bodyText.trim() === '') throw textMissing(mail.id);
+
+  const footer = FOOTER_KEYS.filter((key) => t.has(key)).map((key) => t(key, vars));
+  const unsubscribe =
+    options.unsubscribeUrl === undefined
+      ? undefined
+      : { label: t(UNSUBSCRIBE_KEY), url: options.unsubscribeUrl };
+
+  const html = layout({
+    subject,
+    preheader,
+    content: list.map((block) => htmlOf(block, t)).join(''),
+    footer,
+    unsubscribe,
+    locale: options.locale,
+    direction: directionOf(options.locale),
+  });
+
+  const tail = [...footer];
+  if (unsubscribe !== undefined) tail.push(`${unsubscribe.label}: ${safeUrl(unsubscribe.url)}`);
+  const text = tail.length === 0 ? bodyText : `${bodyText}\n\n--\n${tail.join('\n')}`;
+
+  return { subject, preheader, html, text };
+}
+
+/** The text part, block by block. Never derived from the HTML. */
+export function textOf(list: readonly MailBlock[], t: Translator): string {
+  const lines: string[] = [];
+  for (const block of list) {
+    switch (block.kind) {
+      case 'heading':
+      case 'paragraph':
+      case 'callout':
+        lines.push(t(block.key, block.vars));
+        break;
+      case 'button':
+        lines.push(`${t(block.key, block.vars)}: ${safeUrl(block.href)}`);
+        break;
+      case 'detail':
+        lines.push(`${t(block.key)}: ${block.value}`);
+        break;
+      case 'divider':
+        break;
+    }
+  }
+  return lines.join('\n\n');
+}
+
+const HEADING_STYLE = styleAttr([
+  'margin:0 0 16px 0',
+  'font-size:24px',
+  'line-height:32px',
+  'font-weight:600',
+  `color:${token('textPrimary')}`,
+]);
+
+const PARAGRAPH_STYLE = styleAttr([
+  'margin:0 0 16px 0',
+  'font-size:16px',
+  'line-height:24px',
+  `color:${token('textPrimary')}`,
+]);
+
+const DETAIL_LABEL_STYLE = styleAttr([`color:${token('textMuted')}`, 'font-size:14px']);
+
+const BUTTON_LINK_STYLE = styleAttr([
+  'display:inline-block',
+  'padding:12px 22px',
+  'font-size:16px',
+  'font-weight:600',
+  'text-decoration:none',
+  `color:${token('accentText')}`,
+  `background-color:${token('accentBg')}`,
+  'border-radius:8px',
+]);
+
+const DIVIDER_STYLE = styleAttr([
+  `border-top:1px solid ${token('borderSubtle')}`,
+  'font-size:0',
+  'line-height:0',
+  'height:1px',
+  'padding:8px 0 0 0',
+]);
+
+const TABLE_ATTRS = 'role="presentation" cellpadding="0" cellspacing="0" border="0"';
+
+function calloutStyle(tone: CalloutTone): string {
+  const bg = tone === 'danger' ? token('calloutDangerBg') : token('calloutInfoBg');
+  const fg = tone === 'danger' ? token('calloutDangerText') : token('calloutInfoText');
+  return styleAttr([
+    `background-color:${bg}`,
+    `color:${fg}`,
+    'padding:16px',
+    'border-radius:8px',
+    'font-size:15px',
+    'line-height:22px',
+  ]);
+}
+
+function htmlOf(block: MailBlock, t: Translator): string {
+  switch (block.kind) {
+    case 'heading':
+      return `<h1 data-x="h" ${HEADING_STYLE}>${escapeHtml(t(block.key, block.vars))}</h1>`;
+    case 'paragraph':
+      return `<p data-x="p" ${PARAGRAPH_STYLE}>${escapeHtml(t(block.key, block.vars))}</p>`;
+    case 'button': {
+      const href = escapeHtml(safeUrl(block.href));
+      const label = escapeHtml(t(block.key, block.vars));
+      const anchor = `<a data-x="btn" href="${href}" ${BUTTON_LINK_STYLE}>${label}</a>`;
+      return `<table ${TABLE_ATTRS}><tr><td>${anchor}</td></tr></table>`;
+    }
+    case 'callout': {
+      const role = block.tone === 'danger' ? 'cd' : 'ci';
+      const body = escapeHtml(t(block.key, block.vars));
+      const cell = `<td data-x="${role}" ${calloutStyle(block.tone)}>${body}</td>`;
+      return `<table ${TABLE_ATTRS} width="100%"><tr>${cell}</tr></table>`;
+    }
+    case 'detail': {
+      const label = `<span data-x="mut" ${DETAIL_LABEL_STYLE}>${escapeHtml(t(block.key))}</span>`;
+      return `<p data-x="p" ${PARAGRAPH_STYLE}>${label} ${escapeHtml(block.value)}</p>`;
+    }
+    case 'divider': {
+      const cell = `<td data-x="hr" ${DIVIDER_STYLE}></td>`;
+      return `<table ${TABLE_ATTRS} width="100%"><tr>${cell}</tr></table>`;
+    }
+  }
+}
+
+/** Scalar fields of the payload become interpolation vars; Dates and objects never do. */
+function toVars(data: unknown): TranslateVars {
+  const vars: TranslateVars = {};
+  if (typeof data !== 'object' || data === null) return vars;
+  for (const [key, value] of Object.entries(data)) {
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      vars[key] = value;
+    }
+  }
+  return vars;
+}