From cd0d25593243861d3ca67b09a6ec86eea2ee64e3 Mon Sep 17 00:00:00 2001
From: Jan Hapke <github@janhapke.com>
Date: Thu, 4 Jun 2026 23:04:52 +0200
Subject: [PATCH 01/18] chore(export): install turndown dependencies

---
 package-lock.json | 35 +++++++++++++++++++++++++++++++++++
 package.json      |  3 +++
 2 files changed, 38 insertions(+)

diff --git a/package-lock.json b/package-lock.json
index 94f8c84..fd35085 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -18,6 +18,8 @@
         "mailparser": "^3.9.8",
         "simple-git": "3.36.0",
         "slugify": "^1.6.9",
+        "turndown": "^7.2.4",
+        "turndown-plugin-gfm": "^1.0.2",
         "zod": "^4.3.6"
       },
       "bin": {
@@ -26,6 +28,7 @@
       "devDependencies": {
         "@types/mailparser": "^3.4.6",
         "@types/node": "25.6.0",
+        "@types/turndown": "^5.0.6",
         "@vitest/coverage-v8": "^4.1.5",
         "tsx": "4.21.0",
         "typescript": "6.0.3",
@@ -938,6 +941,12 @@
       "integrity": "sha512-GaHYm+c0O9MjZRu0ongGBRbinu8gVAMd2UZjji6jVmqKtZluZnptXGWhz1E8j8D2HJ3f/yMxKAUC0b+57wncIw==",
       "license": "MIT"
     },
+    "node_modules/@mixmark-io/domino": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/@mixmark-io/domino/-/domino-2.2.0.tgz",
+      "integrity": "sha512-Y28PR25bHXUg88kCV7nivXrP2Nj2RueZ3/l/jdx6J9f8J4nsEGcgX0Qe6lt7Pa+J79+kPiJU3LguR6O/6zrLOw==",
+      "license": "BSD-2-Clause"
+    },
     "node_modules/@napi-rs/keyring": {
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/@napi-rs/keyring/-/keyring-1.3.0.tgz",
@@ -1562,6 +1571,13 @@
         "undici-types": "~7.19.0"
       }
     },
+    "node_modules/@types/turndown": {
+      "version": "5.0.6",
+      "resolved": "https://registry.npmjs.org/@types/turndown/-/turndown-5.0.6.tgz",
+      "integrity": "sha512-ru00MoyeeouE5BX4gRL+6m/BsDfbRayOskWqUvh7CLGW+UXxHQItqALa38kKnOiZPqJrtzJUgAC2+F0rL1S4Pg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@vitest/coverage-v8": {
       "version": "4.1.5",
       "resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.1.5.tgz",
@@ -3103,6 +3119,25 @@
         "fsevents": "~2.3.3"
       }
     },
+    "node_modules/turndown": {
+      "version": "7.2.4",
+      "resolved": "https://registry.npmjs.org/turndown/-/turndown-7.2.4.tgz",
+      "integrity": "sha512-I8yFsfRzmzK0WV1pNNOA4A7y4RDfFxPRxb3t+e3ui14qSGOxGtiSP6GjeX+Y6CHb7HYaFj7ECUD7VE5kQMZWGQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@mixmark-io/domino": "^2.2.0"
+      },
+      "engines": {
+        "node": ">=18",
+        "npm": ">=9"
+      }
+    },
+    "node_modules/turndown-plugin-gfm": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/turndown-plugin-gfm/-/turndown-plugin-gfm-1.0.2.tgz",
+      "integrity": "sha512-vwz9tfvF7XN/jE0dGoBei3FXWuvll78ohzCZQuOb+ZjWrs3a0XhQVomJEb2Qh4VHTPNRO4GPZh0V7VRbiWwkRg==",
+      "license": "MIT"
+    },
     "node_modules/typescript": {
       "version": "6.0.3",
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz",
diff --git a/package.json b/package.json
index 5c3fe26..300c6f6 100644
--- a/package.json
+++ b/package.json
@@ -48,6 +48,7 @@
   "devDependencies": {
     "@types/mailparser": "^3.4.6",
     "@types/node": "25.6.0",
+    "@types/turndown": "^5.0.6",
     "@vitest/coverage-v8": "^4.1.5",
     "tsx": "4.21.0",
     "typescript": "6.0.3",
@@ -63,6 +64,8 @@
     "mailparser": "^3.9.8",
     "simple-git": "3.36.0",
     "slugify": "^1.6.9",
+    "turndown": "^7.2.4",
+    "turndown-plugin-gfm": "^1.0.2",
     "zod": "^4.3.6"
   }
 }

From 91ed2a04487d869037938298505de5f1642c2631 Mon Sep 17 00:00:00 2001
From: Jan Hapke <github@janhapke.com>
Date: Thu, 4 Jun 2026 23:05:24 +0200
Subject: [PATCH 02/18] refactor(sync): export parseHeaderBlock and
 extractRawHeader

---
 src/core/index.ts | 2 +-
 src/core/sync.ts  | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/core/index.ts b/src/core/index.ts
index d3ca834..f60d7b5 100644
--- a/src/core/index.ts
+++ b/src/core/index.ts
@@ -11,7 +11,7 @@ export { findRepository } from './discovery.js'
 
 // Sync
 export type { SyncResult, SyncOptions, FolderSyncResult } from './sync.js'
-export { syncAccount, reindexLocalFolders, decodeMimeWords } from './sync.js'
+export { syncAccount, reindexLocalFolders, decodeMimeWords, parseHeaderBlock, extractRawHeader } from './sync.js'
 
 // Browse
 export type { MessageSummary } from './browse.js'
diff --git a/src/core/sync.ts b/src/core/sync.ts
index 37dad9c..b68b5cf 100644
--- a/src/core/sync.ts
+++ b/src/core/sync.ts
@@ -113,13 +113,13 @@ export function decodeMimeWords(value: string): string {
 }
 
 // Extract the first occurrence of a named header from the raw (unfolded) header block.
-function extractRawHeader(unfolded: string, name: string): string {
+export function extractRawHeader(unfolded: string, name: string): string {
   const re = new RegExp(`^${name}:[ \\t]*(.*)$`, 'im')
   return unfolded.match(re)?.[1]?.trim() ?? ''
 }
 
 // Unfold and extract just the header section from raw email bytes.
-function parseHeaderBlock(rawSource: Buffer | string): string {
+export function parseHeaderBlock(rawSource: Buffer | string): string {
   const text = typeof rawSource === 'string'
     ? rawSource.slice(0, 65536)
     : rawSource.subarray(0, 65536).toString('utf-8')

From 154bae5beba2f135bbe8a5d4853804008ac8b654 Mon Sep 17 00:00:00 2001
From: Jan Hapke <github@janhapke.com>
Date: Thu, 4 Jun 2026 23:12:20 +0200
Subject: [PATCH 03/18] feat(export): conversion helpers and frontmatter
 builder

---
 src/core/export.ts                 | 304 +++++++++++++++++++++++++++++
 src/types/turndown-plugin-gfm.d.ts |   6 +
 tests/unit/export.test.ts          | 244 +++++++++++++++++++++++
 3 files changed, 554 insertions(+)
 create mode 100644 src/core/export.ts
 create mode 100644 src/types/turndown-plugin-gfm.d.ts
 create mode 100644 tests/unit/export.test.ts

diff --git a/src/core/export.ts b/src/core/export.ts
new file mode 100644
index 0000000..0e04fec
--- /dev/null
+++ b/src/core/export.ts
@@ -0,0 +1,304 @@
+// src/core/export.ts — no exit calls, no console, no CLI imports.
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { simpleParser } from 'mailparser'
+import type { ParsedMail } from 'mailparser'
+import TurndownService from 'turndown'
+import { gfm } from 'turndown-plugin-gfm'
+import { parseHeaderBlock, extractRawHeader } from './sync.js'
+import { listFolders } from './browse.js'
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export interface ExportOptions {
+  excludeFolders?: string[]
+  onlyFolders?: string[]
+  verbose?: boolean
+  onLog?: (msg: string) => void
+}
+
+export interface ExportResult {
+  exported: number
+  errors: number
+  folderResults: FolderExportResult[]
+}
+
+export interface FolderExportResult {
+  path: string
+  exported: number
+  error?: Error
+}
+
+// ── HTML → Markdown ───────────────────────────────────────────────────────────
+
+export function preprocessHtml(html: string): string {
+  // Strip <style> and <script> blocks
+  let out = html.replace(/<style[\s\S]*?<\/style>/gi, '')
+  out = out.replace(/<script[\s\S]*?<\/script>/gi, '')
+
+  // Strip tracking-pixel <img> tags: width/height attr ≤ 1 or inline style width:0/height:0
+  out = out.replace(/<img\b[^>]*>/gi, (tag) => {
+    // Check width/height attributes
+    const widthAttr = tag.match(/\bwidth\s*=\s*["']?(\d+)["']?/i)
+    const heightAttr = tag.match(/\bheight\s*=\s*["']?(\d+)["']?/i)
+    if (widthAttr && parseInt(widthAttr[1]) <= 1) return ''
+    if (heightAttr && parseInt(heightAttr[1]) <= 1) return ''
+
+    // Check inline style for width:0 or height:0
+    const styleAttr = tag.match(/\bstyle\s*=\s*["']([^"']*)["']/i)
+    if (styleAttr) {
+      const style = styleAttr[1]
+      if (/width\s*:\s*0/.test(style) || /height\s*:\s*0/.test(style)) return ''
+    }
+
+    return tag
+  })
+
+  return out
+}
+
+export function htmlToMarkdown(html: string): string {
+  const cleaned = preprocessHtml(html)
+
+  const td = new TurndownService({ headingStyle: 'atx', codeBlockStyle: 'fenced' })
+  td.use(gfm)
+  const md = td.turndown(cleaned)
+
+  // Collapse 3+ consecutive blank lines to 2
+  return md.replace(/\n{3,}/g, '\n\n')
+}
+
+// ── receivedDate extraction ───────────────────────────────────────────────────
+
+export function extractReceivedDate(rawSource: Buffer | string): string {
+  const unfolded = parseHeaderBlock(rawSource)
+
+  const receivedLine = extractRawHeader(unfolded, 'received')
+  if (receivedLine) {
+    const semi = receivedLine.lastIndexOf(';')
+    if (semi !== -1) {
+      const parsed = new Date(receivedLine.slice(semi + 1).trim())
+      if (!isNaN(parsed.getTime())) {
+        return parsed.toISOString().replace('T', ' ').slice(0, 19)
+      }
+    }
+  }
+
+  const dateLine = extractRawHeader(unfolded, 'date')
+  if (dateLine) {
+    const parsed = new Date(dateLine.trim())
+    if (!isNaN(parsed.getTime())) {
+      return parsed.toISOString().replace('T', ' ').slice(0, 19)
+    }
+  }
+
+  return '0000-00-00 00:00:00'
+}
+
+// ── Frontmatter builder ───────────────────────────────────────────────────────
+
+function yamlQuote(s: string): string {
+  // Escape backslashes and double quotes, then wrap in double quotes
+  return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"'
+}
+
+export function buildFrontmatter(
+  parsed: ParsedMail,
+  rawSource: Buffer | string,
+  folderPath: string,
+): string {
+  const messageId = parsed.messageId ?? ''
+  const fromName = parsed.from?.value[0]?.name ?? ''
+  const fromEmail = parsed.from?.value[0]?.address ?? ''
+  const toList = (parsed.to ? (Array.isArray(parsed.to) ? parsed.to : [parsed.to]) : [])
+    .flatMap((a) => a.value)
+  const subject = parsed.subject ?? ''
+  const receivedDate = extractReceivedDate(rawSource)
+  const attachments = parsed.attachments ?? []
+
+  const lines: string[] = []
+  lines.push('---')
+  lines.push(`messageId: ${yamlQuote(messageId)}`)
+  lines.push('from:')
+  lines.push(`  name: ${yamlQuote(fromName)}`)
+  lines.push(`  email: ${yamlQuote(fromEmail)}`)
+
+  if (toList.length === 0) {
+    lines.push('to: []')
+  } else {
+    lines.push('to:')
+    for (const addr of toList) {
+      lines.push(`  - name: ${yamlQuote(addr.name ?? '')}`)
+      lines.push(`    email: ${yamlQuote(addr.address ?? '')}`)
+    }
+  }
+
+  lines.push(`subject: ${yamlQuote(subject)}`)
+  lines.push(`receivedDate: ${yamlQuote(receivedDate)}`)
+  lines.push('folders:')
+  lines.push(`  - ${yamlQuote(folderPath)}`)
+
+  if (attachments.length === 0) {
+    lines.push('attachments: []')
+  } else {
+    lines.push('attachments:')
+    for (const att of attachments) {
+      lines.push(`  - filename: ${yamlQuote(att.filename ?? '')}`)
+      lines.push(`    contentType: ${yamlQuote(att.contentType)}`)
+      lines.push(`    size: ${att.size ?? 0}`)
+    }
+  }
+
+  lines.push('---')
+  return lines.join('\n')
+}
+
+// ── Document assembler ────────────────────────────────────────────────────────
+
+export function assembleDocument(
+  parsed: ParsedMail,
+  rawSource: Buffer | string,
+  folderPath: string,
+): string {
+  const frontmatter = buildFrontmatter(parsed, rawSource, folderPath)
+
+  // mailparser auto-generates text from html and vice versa — check the raw
+  // content-type to determine which parts were explicitly present
+  const unfolded = parseHeaderBlock(rawSource)
+  const ct = extractRawHeader(unfolded, 'content-type').toLowerCase().trim()
+  const isTopLevelTextOnly = ct.startsWith('text/plain')
+  const isTopLevelHtmlOnly = ct.startsWith('text/html')
+
+  const hasHtml = !isTopLevelTextOnly && typeof parsed.html === 'string' && parsed.html.length > 0
+  const hasText = !isTopLevelHtmlOnly && typeof parsed.text === 'string' && parsed.text.length > 0
+
+  if (!hasHtml && !hasText) {
+    return frontmatter + '\n'
+  }
+
+  if (hasHtml && !hasText) {
+    return frontmatter + '\n\n' + htmlToMarkdown(parsed.html as string)
+  }
+
+  if (!hasHtml && hasText) {
+    return frontmatter + '\n\n' + (parsed.text as string)
+  }
+
+  // Both HTML and plain text
+  const divider = '\n\n---\n\n---\n\n---\n\n'
+  return (
+    frontmatter +
+    '\n\n' +
+    htmlToMarkdown(parsed.html as string) +
+    divider +
+    (parsed.text as string)
+  )
+}
+
+// ── Folder/account export ─────────────────────────────────────────────────────
+
+interface FolderMessage {
+  uid: number
+  'message-id': string
+  filename: string
+  flags: string[]
+}
+
+interface FolderState {
+  uidvalidity: string
+  uidnext: number
+  messages: FolderMessage[]
+}
+
+function filterStringFolders(
+  folders: string[],
+  onlyFolders?: string[],
+  excludeFolders?: string[],
+): string[] {
+  if (onlyFolders && onlyFolders.length > 0 && excludeFolders && excludeFolders.length > 0) {
+    throw new Error('onlyFolders and excludeFolders are mutually exclusive')
+  }
+  if (onlyFolders && onlyFolders.length > 0) {
+    return folders.filter((f) => onlyFolders.includes(f))
+  }
+  if (excludeFolders && excludeFolders.length > 0) {
+    return folders.filter((f) => !excludeFolders.includes(f))
+  }
+  return folders
+}
+
+export async function listExportFolders(
+  archivePath: string,
+  opts: { excludeFolders?: string[]; onlyFolders?: string[] },
+): Promise<string[]> {
+  const all = await listFolders(archivePath)
+  return filterStringFolders(all, opts.onlyFolders, opts.excludeFolders)
+}
+
+export async function exportFolder(
+  archivePath: string,
+  exportPath: string,
+  folderPath: string,
+  opts: { verbose?: boolean; onLog?: (m: string) => void },
+): Promise<FolderExportResult> {
+  const result: FolderExportResult = { path: folderPath, exported: 0 }
+
+  const stateFilePath = path.join(archivePath, folderPath, '.backmail_state.json')
+  let state: FolderState
+  try {
+    const content = await fs.readFile(stateFilePath, 'utf-8')
+    state = JSON.parse(content) as FolderState
+  } catch (err) {
+    result.error = err instanceof Error ? err : new Error(String(err))
+    return result
+  }
+
+  const outDir = path.join(exportPath, folderPath)
+  await fs.mkdir(outDir, { recursive: true })
+
+  for (const msg of state.messages) {
+    const emlPath = path.join(archivePath, folderPath, `${msg.filename}.eml`)
+    try {
+      const rawSource = await fs.readFile(emlPath)
+      const parsed = await simpleParser(rawSource)
+      const mdContent = assembleDocument(parsed, rawSource, folderPath)
+      const mdPath = path.join(outDir, `${msg.filename}.md`)
+      await fs.writeFile(mdPath, mdContent, 'utf-8')
+      result.exported++
+      if (opts.verbose) opts.onLog?.(`exported ${folderPath}/${msg.filename}.md`)
+    } catch (err) {
+      const msg2 = err instanceof Error ? err.message : String(err)
+      opts.onLog?.(`error exporting ${folderPath}/${msg.filename}.eml: ${msg2}`)
+      result.exported  // don't increment
+    }
+  }
+
+  return result
+}
+
+export async function exportAccount(
+  archivePath: string,
+  exportPath: string,
+  opts: ExportOptions,
+): Promise<ExportResult> {
+  const folders = await listExportFolders(archivePath, {
+    excludeFolders: opts.excludeFolders,
+    onlyFolders: opts.onlyFolders,
+  })
+
+  const folderResults: FolderExportResult[] = []
+  let totalExported = 0
+  let totalErrors = 0
+
+  for (const folder of folders) {
+    const fr = await exportFolder(archivePath, exportPath, folder, {
+      verbose: opts.verbose,
+      onLog: opts.onLog,
+    })
+    folderResults.push(fr)
+    totalExported += fr.exported
+    if (fr.error) totalErrors++
+  }
+
+  return { exported: totalExported, errors: totalErrors, folderResults }
+}
diff --git a/src/types/turndown-plugin-gfm.d.ts b/src/types/turndown-plugin-gfm.d.ts
new file mode 100644
index 0000000..637bf98
--- /dev/null
+++ b/src/types/turndown-plugin-gfm.d.ts
@@ -0,0 +1,6 @@
+declare module 'turndown-plugin-gfm' {
+  import TurndownService from 'turndown'
+  export function gfm(service: TurndownService): void
+  export function tables(service: TurndownService): void
+  export function strikethrough(service: TurndownService): void
+}
diff --git a/tests/unit/export.test.ts b/tests/unit/export.test.ts
new file mode 100644
index 0000000..c44162a
--- /dev/null
+++ b/tests/unit/export.test.ts
@@ -0,0 +1,244 @@
+import { describe, it, expect } from 'vitest'
+import { simpleParser } from 'mailparser'
+import {
+  preprocessHtml,
+  htmlToMarkdown,
+  extractReceivedDate,
+  buildFrontmatter,
+  assembleDocument,
+} from '../../src/core/export.js'
+
+// ── preprocessHtml ────────────────────────────────────────────────────────────
+
+describe('preprocessHtml', () => {
+  it('strips <style> blocks', () => {
+    const html = '<style>body { color: red; }</style><p>Hello</p>'
+    expect(preprocessHtml(html)).not.toContain('<style>')
+    expect(preprocessHtml(html)).toContain('<p>Hello</p>')
+  })
+
+  it('strips <script> blocks', () => {
+    const html = '<script>alert(1)</script><p>Text</p>'
+    expect(preprocessHtml(html)).not.toContain('<script>')
+    expect(preprocessHtml(html)).toContain('<p>Text</p>')
+  })
+
+  it('strips 1x1 tracking pixel img (width=1 height=1 attrs)', () => {
+    const html = '<img src="track.png" width="1" height="1"><p>Text</p>'
+    expect(preprocessHtml(html)).not.toContain('<img')
+    expect(preprocessHtml(html)).toContain('<p>Text</p>')
+  })
+
+  it('strips img with width=0 attribute', () => {
+    const html = '<img src="t.gif" width="0"><p>Text</p>'
+    expect(preprocessHtml(html)).not.toContain('<img')
+  })
+
+  it('strips img with style width:0', () => {
+    const html = '<img src="t.gif" style="width:0;height:0"><p>Text</p>'
+    expect(preprocessHtml(html)).not.toContain('<img')
+  })
+
+  it('preserves normal images', () => {
+    const html = '<img src="photo.jpg" width="800" height="600"><p>Text</p>'
+    expect(preprocessHtml(html)).toContain('<img')
+  })
+})
+
+// ── htmlToMarkdown ────────────────────────────────────────────────────────────
+
+describe('htmlToMarkdown', () => {
+  it('converts basic HTML to markdown', () => {
+    const result = htmlToMarkdown('<p><strong>Hello</strong> world</p>')
+    expect(result).toContain('**Hello**')
+  })
+
+  it('collapses 4+ consecutive blank lines to 2', () => {
+    // Force 4+ blank lines by injecting them after conversion
+    // We test by passing content that will produce multiple blank lines
+    const html = '<p>A</p><p></p><p></p><p></p><p>B</p>'
+    const result = htmlToMarkdown(html)
+    expect(result).not.toMatch(/\n{4,}/)
+  })
+})
+
+// ── extractReceivedDate ───────────────────────────────────────────────────────
+
+describe('extractReceivedDate', () => {
+  it('prefers Received: header timestamp after semicolon', () => {
+    const raw = 'Received: from mail.example.com by server; Thu, 15 Jan 2026 13:37:42 +0000\r\nDate: Mon, 1 Jan 2024 00:00:00 +0000\r\n\r\nBody'
+    expect(extractReceivedDate(raw)).toBe('2026-01-15 13:37:42')
+  })
+
+  it('falls back to Date: header when Received: is absent', () => {
+    const raw = 'Date: Wed, 15 Jan 2025 10:20:30 +0000\r\n\r\nBody'
+    expect(extractReceivedDate(raw)).toBe('2025-01-15 10:20:30')
+  })
+
+  it('falls back to 0000-00-00 00:00:00 when no date headers', () => {
+    const raw = 'From: foo@example.com\r\n\r\nBody'
+    expect(extractReceivedDate(raw)).toBe('0000-00-00 00:00:00')
+  })
+})
+
+// ── buildFrontmatter ──────────────────────────────────────────────────────────
+
+describe('buildFrontmatter', () => {
+  it('produces correct frontmatter for a basic email', async () => {
+    const eml = [
+      'From: Jane Doe <jane@example.com>',
+      'To: John Doe <john@example.com>',
+      'Subject: Hello World',
+      'Message-ID: <abc123@example.com>',
+      'Date: Thu, 15 Jan 2026 13:37:42 +0000',
+      '',
+      'Body text',
+    ].join('\r\n')
+    const parsed = await simpleParser(Buffer.from(eml))
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX')
+    expect(fm).toContain('messageId:')
+    expect(fm).toContain('subject: "Hello World"')
+    expect(fm).toContain('name: "Jane Doe"')
+    expect(fm).toContain('email: "jane@example.com"')
+    expect(fm).toContain('- "INBOX"')
+  })
+
+  it('produces to: [] when To header is absent', async () => {
+    const eml = 'From: foo@example.com\r\nSubject: Test\r\n\r\nBody'
+    const parsed = await simpleParser(Buffer.from(eml))
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX')
+    expect(fm).toContain('to: []')
+  })
+
+  it('produces YAML list when multiple To recipients', async () => {
+    const eml = [
+      'From: sender@example.com',
+      'To: Alice <alice@example.com>, Bob <bob@example.com>',
+      'Subject: Multi',
+      '',
+      'Body',
+    ].join('\r\n')
+    const parsed = await simpleParser(Buffer.from(eml))
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX')
+    expect(fm).toContain('email: "alice@example.com"')
+    expect(fm).toContain('email: "bob@example.com"')
+  })
+
+  it('sets subject to empty string when missing', async () => {
+    const eml = 'From: foo@example.com\r\n\r\nBody'
+    const parsed = await simpleParser(Buffer.from(eml))
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX')
+    expect(fm).toContain('subject: ""')
+  })
+
+  it('sets from name to empty string when not present', async () => {
+    const eml = 'From: foo@example.com\r\nSubject: Test\r\n\r\nBody'
+    const parsed = await simpleParser(Buffer.from(eml))
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX')
+    expect(fm).toContain('name: ""')
+  })
+
+  it('lists attachments with filename, contentType, size', async () => {
+    const boundary = 'abc123boundary'
+    const eml = [
+      'From: foo@example.com',
+      'Subject: With Attachment',
+      `Content-Type: multipart/mixed; boundary="${boundary}"`,
+      '',
+      `--${boundary}`,
+      'Content-Type: text/plain',
+      '',
+      'Body',
+      `--${boundary}`,
+      'Content-Type: application/pdf',
+      'Content-Disposition: attachment; filename="report.pdf"',
+      'Content-Transfer-Encoding: base64',
+      '',
+      'AAAA',
+      `--${boundary}--`,
+    ].join('\r\n')
+    const parsed = await simpleParser(Buffer.from(eml))
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX')
+    expect(fm).toContain('filename: "report.pdf"')
+    expect(fm).toContain('contentType: "application/pdf"')
+    expect(fm).toContain('size:')
+  })
+
+  it('sets attachments: [] when no attachments', async () => {
+    const eml = 'From: foo@example.com\r\nSubject: Test\r\n\r\nBody'
+    const parsed = await simpleParser(Buffer.from(eml))
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX')
+    expect(fm).toContain('attachments: []')
+  })
+})
+
+// ── assembleDocument ──────────────────────────────────────────────────────────
+
+describe('assembleDocument', () => {
+  it('HTML-only: body is markdown, no divider', async () => {
+    const eml = [
+      'From: foo@example.com',
+      'Subject: HTML Only',
+      'Content-Type: text/html',
+      '',
+      '<p><strong>Hello</strong></p>',
+    ].join('\r\n')
+    const parsed = await simpleParser(Buffer.from(eml))
+    const doc = assembleDocument(parsed, Buffer.from(eml), 'INBOX')
+    expect(doc).toContain('**Hello**')
+    expect(doc).not.toContain('\n\n---\n\n---\n\n---\n\n')
+  })
+
+  it('plain-text-only: body is plain text, no conversion', async () => {
+    const eml = 'From: foo@example.com\r\nSubject: Text\r\n\r\nHello plain world'
+    const parsed = await simpleParser(Buffer.from(eml))
+    const doc = assembleDocument(parsed, Buffer.from(eml), 'INBOX')
+    expect(doc).toContain('Hello plain world')
+  })
+
+  it('HTML + plain text: three-divider block present', async () => {
+    const boundary = 'div123'
+    const eml = [
+      'From: foo@example.com',
+      'Subject: Both',
+      `Content-Type: multipart/alternative; boundary="${boundary}"`,
+      '',
+      `--${boundary}`,
+      'Content-Type: text/plain',
+      '',
+      'Plain text here',
+      `--${boundary}`,
+      'Content-Type: text/html',
+      '',
+      '<p>HTML here</p>',
+      `--${boundary}--`,
+    ].join('\r\n')
+    const parsed = await simpleParser(Buffer.from(eml))
+    const doc = assembleDocument(parsed, Buffer.from(eml), 'INBOX')
+    expect(doc).toContain('\n\n---\n\n---\n\n---\n\n')
+    expect(doc).toContain('HTML here')
+    expect(doc).toContain('Plain text here')
+  })
+
+  it('pure-attachment: only frontmatter, no body content', async () => {
+    const boundary = 'att123'
+    const eml = [
+      'From: foo@example.com',
+      'Subject: Attachment Only',
+      `Content-Type: multipart/mixed; boundary="${boundary}"`,
+      '',
+      `--${boundary}`,
+      'Content-Type: application/pdf',
+      'Content-Disposition: attachment; filename="doc.pdf"',
+      'Content-Transfer-Encoding: base64',
+      '',
+      'AAAA',
+      `--${boundary}--`,
+    ].join('\r\n')
+    const parsed = await simpleParser(Buffer.from(eml))
+    const doc = assembleDocument(parsed, Buffer.from(eml), 'INBOX')
+    // Should end with --- (closing frontmatter delimiter) and newline, nothing else
+    const afterFm = doc.replace(/^---[\s\S]*?---\n/, '')
+    expect(afterFm.trim()).toBe('')
+  })
+})

From 426ef77952b6994afeabb38f13da376d0b4df86c Mon Sep 17 00:00:00 2001
From: Jan Hapke <github@janhapke.com>
Date: Thu, 4 Jun 2026 23:14:15 +0200
Subject: [PATCH 04/18] feat(export): exportAccount core logic

---
 src/core/index.ts         |   4 ++
 tests/unit/export.test.ts | 107 +++++++++++++++++++++++++++++++++++++-
 2 files changed, 110 insertions(+), 1 deletion(-)

diff --git a/src/core/index.ts b/src/core/index.ts
index f60d7b5..f7bda92 100644
--- a/src/core/index.ts
+++ b/src/core/index.ts
@@ -29,3 +29,7 @@ export { restoreAccount } from './restore.js'
 
 // Init
 export { initRepository } from './init.js'
+
+// Export
+export type { ExportOptions, ExportResult, FolderExportResult } from './export.js'
+export { exportAccount } from './export.js'
diff --git a/tests/unit/export.test.ts b/tests/unit/export.test.ts
index c44162a..f0a408e 100644
--- a/tests/unit/export.test.ts
+++ b/tests/unit/export.test.ts
@@ -1,4 +1,8 @@
-import { describe, it, expect } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import os from 'node:os'
+import path from 'node:path'
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
 import { simpleParser } from 'mailparser'
 import {
   preprocessHtml,
@@ -6,6 +10,8 @@ import {
   extractReceivedDate,
   buildFrontmatter,
   assembleDocument,
+  exportFolder,
+  exportAccount,
 } from '../../src/core/export.js'
 
 // ── preprocessHtml ────────────────────────────────────────────────────────────
@@ -242,3 +248,102 @@ describe('assembleDocument', () => {
     expect(afterFm.trim()).toBe('')
   })
 })
+
+// ── exportFolder / exportAccount (I/O) ────────────────────────────────────────
+
+const SIMPLE_EML = 'From: foo@example.com\r\nSubject: Test\r\n\r\nHello world'
+
+function makeState(messages: { filename: string }[]) {
+  return JSON.stringify({
+    uidvalidity: '1',
+    uidnext: messages.length + 1,
+    messages: messages.map((m, i) => ({
+      uid: i + 1,
+      'message-id': `<${m.filename}@test>`,
+      filename: m.filename,
+      flags: [],
+    })),
+  })
+}
+
+describe('exportFolder', () => {
+  let tmpDir: string
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'backmail-export-'))
+  })
+
+  afterEach(async () => {
+    await fsp.rm(tmpDir, { recursive: true, force: true })
+  })
+
+  it('writes .md at correct path for a single message', async () => {
+    const archivePath = path.join(tmpDir, 'archive')
+    const exportPath = path.join(tmpDir, 'export')
+    const folderDir = path.join(archivePath, 'INBOX')
+    await fsp.mkdir(folderDir, { recursive: true })
+    await fsp.writeFile(path.join(folderDir, '.backmail_state.json'), makeState([{ filename: '2026-01-01_test_abc12345' }]))
+    await fsp.writeFile(path.join(folderDir, '2026-01-01_test_abc12345.eml'), SIMPLE_EML)
+
+    const result = await exportFolder(archivePath, exportPath, 'INBOX', {})
+    expect(result.exported).toBe(1)
+    expect(result.error).toBeUndefined()
+
+    const mdPath = path.join(exportPath, 'INBOX', '2026-01-01_test_abc12345.md')
+    const content = await fsp.readFile(mdPath, 'utf-8')
+    expect(content).toContain('messageId:')
+  })
+
+  it('counts error and continues when .eml is missing', async () => {
+    const archivePath = path.join(tmpDir, 'archive')
+    const exportPath = path.join(tmpDir, 'export')
+    const folderDir = path.join(archivePath, 'INBOX')
+    await fsp.mkdir(folderDir, { recursive: true })
+    await fsp.writeFile(
+      path.join(folderDir, '.backmail_state.json'),
+      makeState([{ filename: 'missing_file' }, { filename: '2026-01-01_ok_abc12345' }]),
+    )
+    // Only write the second eml
+    await fsp.writeFile(path.join(folderDir, '2026-01-01_ok_abc12345.eml'), SIMPLE_EML)
+
+    const logs: string[] = []
+    const result = await exportFolder(archivePath, exportPath, 'INBOX', { onLog: (m) => logs.push(m) })
+    expect(result.exported).toBe(1)
+    expect(logs.some((l) => l.includes('missing_file'))).toBe(true)
+  })
+})
+
+describe('exportAccount', () => {
+  let tmpDir: string
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'backmail-exportacc-'))
+  })
+
+  afterEach(async () => {
+    await fsp.rm(tmpDir, { recursive: true, force: true })
+  })
+
+  it('exports two folders and sums counts correctly', async () => {
+    const archivePath = path.join(tmpDir, 'archive')
+    const exportPath = path.join(tmpDir, 'export')
+
+    for (const folder of ['INBOX', 'Sent']) {
+      const folderDir = path.join(archivePath, folder)
+      await fsp.mkdir(folderDir, { recursive: true })
+      await fsp.writeFile(
+        path.join(folderDir, '.backmail_state.json'),
+        makeState([{ filename: `2026-01-01_msg_${folder.toLowerCase()}` }]),
+      )
+      await fsp.writeFile(
+        path.join(folderDir, `2026-01-01_msg_${folder.toLowerCase()}.eml`),
+        SIMPLE_EML,
+      )
+    }
+
+    const result = await exportAccount(archivePath, exportPath, {})
+    expect(result.exported).toBe(2)
+    expect(result.errors).toBe(0)
+    expect(result.folderResults).toHaveLength(2)
+  })
+})

From 20a6b6a692cc86aa026173ea349e6f640b46c36a Mon Sep 17 00:00:00 2001
From: Jan Hapke <github@janhapke.com>
Date: Thu, 4 Jun 2026 23:15:40 +0200
Subject: [PATCH 05/18] feat(export): add export CLI command

---
 src/cli/index.ts | 46 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 45 insertions(+), 1 deletion(-)

diff --git a/src/cli/index.ts b/src/cli/index.ts
index 4b063a4..64dab6b 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -39,7 +39,7 @@ function getRepoRoot(): string {
   return repoRoot
 }
 
-import { syncAccount, getLog, checkoutCommit, listFolders, listMessages, viewMessage, restoreAccount } from '../core/index.js'
+import { syncAccount, getLog, checkoutCommit, listFolders, listMessages, viewMessage, restoreAccount, exportAccount } from '../core/index.js'
 
 function getErrorMessage(err: unknown): string {
   if (err instanceof Error) {
@@ -373,4 +373,48 @@ program
     }
   })
 
+// ── export ───────────────────────────────────────────────────────────────────
+program
+  .command('export')
+  .description('Export archive messages as Markdown files')
+  .option('--exclude-folder <name>', 'skip this folder (repeatable)', collectRepeatable, [])
+  .option('--only-folder <name>', 'restrict to this folder (repeatable)', collectRepeatable, [])
+  .option('--verbose', 'log one line per exported file')
+  .action(async (opts: { excludeFolder: string[]; onlyFolder: string[]; verbose?: boolean }) => {
+    if (opts.excludeFolder.length > 0 && opts.onlyFolder.length > 0) {
+      console.error('Error: --exclude-folder and --only-folder are mutually exclusive')
+      process.exit(1)
+    }
+
+    try {
+      const repoRoot = getRepoRoot()
+      const archivePath = path.join(repoRoot, 'archive')
+      const exportPath = path.join(repoRoot, 'export')
+      const verbose = opts.verbose ?? false
+
+      const result = await exportAccount(archivePath, exportPath, {
+        excludeFolders: opts.excludeFolder,
+        onlyFolders: opts.onlyFolder,
+        verbose,
+        onLog: verbose ? (msg) => console.log(msg) : undefined,
+      })
+
+      const partialTag = result.errors > 0 ? ' [partial]' : ''
+      console.log(`export${partialTag}: =${result.exported} exported`)
+
+      for (const fr of result.folderResults) {
+        if (fr.error) {
+          console.error(`folder ${fr.path} failed: ${fr.error.message}`)
+        }
+      }
+
+      if (result.errors > 0) {
+        process.exit(1)
+      }
+    } catch (err) {
+      console.error(getErrorMessage(err))
+      process.exit(1)
+    }
+  })
+
 program.parse(process.argv)

From faa52e394e0e46053be0c22e70d028efe2880c2d Mon Sep 17 00:00:00 2001
From: Jan Hapke <github@janhapke.com>
Date: Thu, 4 Jun 2026 23:17:53 +0200
Subject: [PATCH 06/18] feat(export): integration tests

---
 tests/fixtures/export/html-only.eml       |   9 ++
 tests/fixtures/export/multi-recipient.eml |   8 ++
 tests/fixtures/export/multipart.eml       |  18 +++
 tests/fixtures/export/plaintext-only.eml  |   9 ++
 tests/fixtures/export/pure-attachment.eml |  15 +++
 tests/integration/export.test.ts          | 142 ++++++++++++++++++++++
 6 files changed, 201 insertions(+)
 create mode 100644 tests/fixtures/export/html-only.eml
 create mode 100644 tests/fixtures/export/multi-recipient.eml
 create mode 100644 tests/fixtures/export/multipart.eml
 create mode 100644 tests/fixtures/export/plaintext-only.eml
 create mode 100644 tests/fixtures/export/pure-attachment.eml
 create mode 100644 tests/integration/export.test.ts

diff --git a/tests/fixtures/export/html-only.eml b/tests/fixtures/export/html-only.eml
new file mode 100644
index 0000000..b8ba57a
--- /dev/null
+++ b/tests/fixtures/export/html-only.eml
@@ -0,0 +1,9 @@
+From: sender@example.com
+To: recipient@example.com
+Subject: HTML Only Email
+Date: Thu, 15 Jan 2026 13:37:42 +0000
+Message-ID: <html-only@example.com>
+Content-Type: text/html; charset=UTF-8
+
+<p><strong>Hello</strong>, this is an HTML-only email.</p>
+<p>No plain text part.</p>
diff --git a/tests/fixtures/export/multi-recipient.eml b/tests/fixtures/export/multi-recipient.eml
new file mode 100644
index 0000000..0683647
--- /dev/null
+++ b/tests/fixtures/export/multi-recipient.eml
@@ -0,0 +1,8 @@
+From: sender@example.com
+To: Alice <alice@example.com>, Bob <bob@example.com>, Carol <carol@example.com>
+Subject: Multi-Recipient Email
+Date: Thu, 15 Jan 2026 17:00:00 +0000
+Message-ID: <multi-recipient@example.com>
+Content-Type: text/plain; charset=UTF-8
+
+Hello everyone, this email has three recipients.
diff --git a/tests/fixtures/export/multipart.eml b/tests/fixtures/export/multipart.eml
new file mode 100644
index 0000000..9456f85
--- /dev/null
+++ b/tests/fixtures/export/multipart.eml
@@ -0,0 +1,18 @@
+From: sender@example.com
+To: recipient@example.com
+Subject: Multipart Email
+Date: Thu, 15 Jan 2026 15:00:00 +0000
+Message-ID: <multipart@example.com>
+Content-Type: multipart/alternative; boundary="mp-boundary-123"
+
+--mp-boundary-123
+Content-Type: text/plain; charset=UTF-8
+
+Hello, this is the plain text part.
+
+--mp-boundary-123
+Content-Type: text/html; charset=UTF-8
+
+<p>Hello, this is the <strong>HTML part</strong>.</p>
+
+--mp-boundary-123--
diff --git a/tests/fixtures/export/plaintext-only.eml b/tests/fixtures/export/plaintext-only.eml
new file mode 100644
index 0000000..9a3302a
--- /dev/null
+++ b/tests/fixtures/export/plaintext-only.eml
@@ -0,0 +1,9 @@
+From: sender@example.com
+To: recipient@example.com
+Subject: Plain Text Only Email
+Date: Thu, 15 Jan 2026 14:00:00 +0000
+Message-ID: <plaintext-only@example.com>
+Content-Type: text/plain; charset=UTF-8
+
+Hello, this is a plain-text-only email.
+No HTML part here.
diff --git a/tests/fixtures/export/pure-attachment.eml b/tests/fixtures/export/pure-attachment.eml
new file mode 100644
index 0000000..c6f6b33
--- /dev/null
+++ b/tests/fixtures/export/pure-attachment.eml
@@ -0,0 +1,15 @@
+From: sender@example.com
+To: recipient@example.com
+Subject: Pure Attachment Email
+Date: Thu, 15 Jan 2026 16:00:00 +0000
+Message-ID: <pure-attachment@example.com>
+Content-Type: multipart/mixed; boundary="att-boundary-456"
+
+--att-boundary-456
+Content-Type: application/pdf
+Content-Disposition: attachment; filename="document.pdf"
+Content-Transfer-Encoding: base64
+
+JVBERi0xLjAK
+
+--att-boundary-456--
diff --git a/tests/integration/export.test.ts b/tests/integration/export.test.ts
new file mode 100644
index 0000000..db451c8
--- /dev/null
+++ b/tests/integration/export.test.ts
@@ -0,0 +1,142 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+import { exportAccount } from '../../src/core/export.js'
+
+// ── Fixture EML filenames (stems) ─────────────────────────────────────────────
+
+const FIXTURES_DIR = path.join(import.meta.dirname, '../fixtures/export')
+
+const FOLDER_A_FILES = [
+  '2026-01-15_html-only_aabbccdd',
+  '2026-01-15_plaintext_bbccddee',
+  '2026-01-15_multipart_ccddeeff',
+]
+
+const FOLDER_B_FILES = [
+  '2026-01-15_attachment_ddeeffgg',
+  '2026-01-15_multircpt_eeffgghh',
+]
+
+const FIXTURE_MAP: Record<string, string> = {
+  '2026-01-15_html-only_aabbccdd': 'html-only.eml',
+  '2026-01-15_plaintext_bbccddee': 'plaintext-only.eml',
+  '2026-01-15_multipart_ccddeeff': 'multipart.eml',
+  '2026-01-15_attachment_ddeeffgg': 'pure-attachment.eml',
+  '2026-01-15_multircpt_eeffgghh': 'multi-recipient.eml',
+}
+
+function makeState(filenames: string[]) {
+  return JSON.stringify({
+    uidvalidity: '1',
+    uidnext: filenames.length + 1,
+    messages: filenames.map((f, i) => ({
+      uid: i + 1,
+      'message-id': `<${f}@test>`,
+      filename: f,
+      flags: [],
+    })),
+  })
+}
+
+// ── Setup/teardown ────────────────────────────────────────────────────────────
+
+let tmpDir: string
+let archivePath: string
+let exportPath: string
+
+beforeAll(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'backmail-export-integration-'))
+  archivePath = path.join(tmpDir, 'archive')
+  exportPath = path.join(tmpDir, 'export')
+
+  // Create FolderA and FolderB under archive
+  for (const [folder, files] of [['FolderA', FOLDER_A_FILES], ['FolderB', FOLDER_B_FILES]] as const) {
+    const folderDir = path.join(archivePath, folder)
+    await fs.mkdir(folderDir, { recursive: true })
+    await fs.writeFile(path.join(folderDir, '.backmail_state.json'), makeState(files))
+    for (const stem of files) {
+      const fixtureName = FIXTURE_MAP[stem]
+      const src = path.join(FIXTURES_DIR, fixtureName)
+      await fs.copyFile(src, path.join(folderDir, `${stem}.eml`))
+    }
+  }
+})
+
+afterAll(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true })
+})
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe('exportAccount integration', () => {
+  it('exports all folders and mirrors archive directory structure', async () => {
+    const result = await exportAccount(archivePath, exportPath, {})
+    expect(result.errors).toBe(0)
+    expect(result.exported).toBe(FOLDER_A_FILES.length + FOLDER_B_FILES.length)
+
+    // Check directory structure
+    for (const folder of ['FolderA', 'FolderB']) {
+      const stat = await fs.stat(path.join(exportPath, folder))
+      expect(stat.isDirectory()).toBe(true)
+    }
+  })
+
+  it('produces one .md per .eml (file counts match)', async () => {
+    // Count .eml files under archivePath
+    let emlCount = 0
+    for (const folder of ['FolderA', 'FolderB']) {
+      const entries = await fs.readdir(path.join(archivePath, folder))
+      emlCount += entries.filter((e) => e.endsWith('.eml')).length
+    }
+
+    // Count .md files under exportPath
+    let mdCount = 0
+    for (const folder of ['FolderA', 'FolderB']) {
+      const entries = await fs.readdir(path.join(exportPath, folder))
+      mdCount += entries.filter((e) => e.endsWith('.md')).length
+    }
+
+    expect(mdCount).toBe(emlCount)
+  })
+
+  it('is idempotent: running twice produces identical output', async () => {
+    // Read current content
+    const readAll = async () => {
+      const contents: Record<string, string> = {}
+      for (const folder of ['FolderA', 'FolderB']) {
+        const dir = path.join(exportPath, folder)
+        const entries = await fs.readdir(dir)
+        for (const f of entries.filter((e) => e.endsWith('.md'))) {
+          contents[`${folder}/${f}`] = await fs.readFile(path.join(dir, f), 'utf-8')
+        }
+      }
+      return contents
+    }
+
+    const before = await readAll()
+    await exportAccount(archivePath, exportPath, {})
+    const after = await readAll()
+
+    expect(after).toEqual(before)
+  })
+
+  it('--only-folder: only specified folder is in output', async () => {
+    const onlyExportPath = path.join(tmpDir, 'export-only')
+    await exportAccount(archivePath, onlyExportPath, { onlyFolders: ['FolderA'] })
+
+    const entries = await fs.readdir(onlyExportPath)
+    expect(entries).toContain('FolderA')
+    expect(entries).not.toContain('FolderB')
+  })
+
+  it('--exclude-folder: excluded folder is absent from output', async () => {
+    const excExportPath = path.join(tmpDir, 'export-exclude')
+    await exportAccount(archivePath, excExportPath, { excludeFolders: ['FolderA'] })
+
+    const entries = await fs.readdir(excExportPath)
+    expect(entries).not.toContain('FolderA')
+    expect(entries).toContain('FolderB')
+  })
+})

From 490565fad7451f55a720fc84d46dd79c602b0190 Mon Sep 17 00:00:00 2001
From: Jan Hapke <github@janhapke.com>
Date: Thu, 4 Jun 2026 23:47:46 +0200
Subject: [PATCH 07/18] feat(export): preserve plain text line breaks and fix
 Markdown hazards

- Add convertPlainText(): appends trailing \ between consecutive prose
  lines to preserve hard line breaks in CommonMark
- Normalise ASCII divider lines (---, ===) to thematic breaks; inserts
  blank line before divider so preceding text is not parsed as a Setext
  heading
- Escape leading # on ATX heading lines (\# text) so plain text content
  is not promoted to a heading
- HTML-escape < and > throughout
- Detect manually typed list lines (- / * / N.) as block elements that
  never receive trailing \

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/core/export.ts        |  75 +++++++++++++++++++++-
 tests/unit/export.test.ts | 129 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 202 insertions(+), 2 deletions(-)

diff --git a/src/core/export.ts b/src/core/export.ts
index 0e04fec..9eb43a3 100644
--- a/src/core/export.ts
+++ b/src/core/export.ts
@@ -68,6 +68,77 @@ export function htmlToMarkdown(html: string): string {
   return md.replace(/\n{3,}/g, '\n\n')
 }
 
+// ── Plain text → Markdown ─────────────────────────────────────────────────────
+
+// Matches manually typed list lines: optional leading spaces, then "- " or "* " or "N. "
+const MANUAL_LIST_RE = /^[ ]*(?:[-*][ \t]|\d+\.[ \t])/
+
+// Matches ASCII divider lines: 2+ dashes or equals signs (optional trailing spaces).
+// These are Setext heading underlines in CommonMark — when they appear directly under
+// a text line they would turn it into a heading. We normalise them to thematic breaks.
+const DIVIDER_RE = /^[-=]{2,}\s*$/
+
+function escapeHtml(s: string): string {
+  return s.replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+interface ConvertedLine {
+  out: string
+  isBlock: boolean
+  isDivider: boolean
+}
+
+// Matches ATX heading lines: up to 3 leading spaces, then 1-6 # chars, then space/tab or EOL
+const ATX_HEADING_RE = /^[ ]{0,3}#{1,6}([ \t]|$)/
+
+function classifyLine(line: string): ConvertedLine {
+  if (line === '') return { out: '', isBlock: false, isDivider: false }
+  if (DIVIDER_RE.test(line)) return { out: '---', isBlock: false, isDivider: true }
+  if (MANUAL_LIST_RE.test(line)) return { out: escapeHtml(line), isBlock: true, isDivider: false }
+  // Escape leading # to prevent ATX heading interpretation
+  const escaped = ATX_HEADING_RE.test(line) ? '\\' + escapeHtml(line) : escapeHtml(line)
+  return { out: escaped, isBlock: false, isDivider: false }
+}
+
+export function convertPlainText(text: string): string {
+  if (text === '') return ''
+
+  const lines = text.split('\n').map(classifyLine)
+  const out: string[] = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const curr = lines[i]
+    const next = lines[i + 1]
+
+    if (curr.isDivider) {
+      // Insert a blank line before the divider when the previous output line is
+      // non-empty, so the Markdown parser sees a thematic break rather than a
+      // Setext heading underline.
+      if (out.length > 0 && out[out.length - 1] !== '') out.push('')
+      out.push('---')
+      continue
+    }
+
+    if (curr.out === '') {
+      out.push('')
+      continue
+    }
+
+    // Append \ only between two consecutive non-empty prose lines.
+    // Skip if the next line is a divider (a blank line will be inserted before it).
+    const hardBreak =
+      !curr.isBlock &&
+      next !== undefined &&
+      !next.isDivider &&
+      next.out !== '' &&
+      !next.isBlock
+
+    out.push(hardBreak ? curr.out + '\\' : curr.out)
+  }
+
+  return out.join('\n')
+}
+
 // ── receivedDate extraction ───────────────────────────────────────────────────
 
 export function extractReceivedDate(rawSource: Buffer | string): string {
@@ -181,7 +252,7 @@ export function assembleDocument(
   }
 
   if (!hasHtml && hasText) {
-    return frontmatter + '\n\n' + (parsed.text as string)
+    return frontmatter + '\n\n' + convertPlainText(parsed.text as string)
   }
 
   // Both HTML and plain text
@@ -191,7 +262,7 @@ export function assembleDocument(
     '\n\n' +
     htmlToMarkdown(parsed.html as string) +
     divider +
-    (parsed.text as string)
+    convertPlainText(parsed.text as string)
   )
 }
 
diff --git a/tests/unit/export.test.ts b/tests/unit/export.test.ts
index f0a408e..21d2eb9 100644
--- a/tests/unit/export.test.ts
+++ b/tests/unit/export.test.ts
@@ -10,6 +10,7 @@ import {
   extractReceivedDate,
   buildFrontmatter,
   assembleDocument,
+  convertPlainText,
   exportFolder,
   exportAccount,
 } from '../../src/core/export.js'
@@ -68,6 +69,134 @@ describe('htmlToMarkdown', () => {
   })
 })
 
+// ── convertPlainText ──────────────────────────────────────────────────────────
+
+describe('convertPlainText', () => {
+  it('returns empty string for empty input', () => {
+    expect(convertPlainText('')).toBe('')
+  })
+
+  it('adds trailing \\ between consecutive prose lines', () => {
+    const result = convertPlainText('Line one\nLine two\nLine three')
+    expect(result).toBe('Line one\\\nLine two\\\nLine three')
+  })
+
+  it('does not add \\ after the last line', () => {
+    const result = convertPlainText('Only line')
+    expect(result).toBe('Only line')
+  })
+
+  it('does not add \\ before a blank line', () => {
+    const result = convertPlainText('Para one\n\nPara two')
+    expect(result).toBe('Para one\n\nPara two')
+  })
+
+  it('does not add \\ to list items (- )', () => {
+    const result = convertPlainText('- item one\n- item two')
+    expect(result).toBe('- item one\n- item two')
+  })
+
+  it('does not add \\ to list items (* )', () => {
+    const result = convertPlainText('* item one\n* item two')
+    expect(result).toBe('* item one\n* item two')
+  })
+
+  it('does not add \\ to numbered list items', () => {
+    const result = convertPlainText('1. first\n2. second')
+    expect(result).toBe('1. first\n2. second')
+  })
+
+  it('does not add \\ to prose line followed by a list item', () => {
+    const result = convertPlainText('Intro text\n- item one')
+    expect(result).toBe('Intro text\n- item one')
+  })
+
+  it('does not add \\ to list item followed by prose', () => {
+    const result = convertPlainText('- item\nTrailing prose')
+    expect(result).toBe('- item\nTrailing prose')
+  })
+
+  it('handles mixed prose and list', () => {
+    const result = convertPlainText('Hello\nWorld\n\n- item\n\nFoo\nBar')
+    expect(result).toBe('Hello\\\nWorld\n\n- item\n\nFoo\\\nBar')
+  })
+
+  it('escapes < and > in prose', () => {
+    const result = convertPlainText('See <https://example.com>')
+    expect(result).toBe('See &lt;https://example.com&gt;')
+  })
+
+  it('escapes < and > in list items', () => {
+    const result = convertPlainText('- See <note>')
+    expect(result).toBe('- See &lt;note&gt;')
+  })
+
+  it('preserves indented list items (spaces)', () => {
+    const result = convertPlainText('  - nested item')
+    expect(result).toBe('  - nested item')
+  })
+
+  it('turns a dash divider directly under text into a thematic break (not a heading)', () => {
+    const result = convertPlainText('Some text\n----------')
+    expect(result).toBe('Some text\n\n---')
+  })
+
+  it('turns an equals divider directly under text into a thematic break', () => {
+    const result = convertPlainText('Some text\n==========')
+    expect(result).toBe('Some text\n\n---')
+  })
+
+  it('turns a standalone dash divider into a thematic break without extra blank line', () => {
+    // Divider not preceded by non-empty line — no extra blank line needed
+    const result = convertPlainText('----------')
+    expect(result).toBe('---')
+  })
+
+  it('handles divider between two prose paragraphs', () => {
+    const result = convertPlainText('Para one\n----------\nPara two')
+    expect(result).toBe('Para one\n\n---\nPara two')
+  })
+
+  it('does not add \\ to prose line immediately before a divider', () => {
+    const result = convertPlainText('Line one\n----------')
+    // "Line one" should NOT get a trailing \ even though it is followed by non-empty content
+    expect(result).not.toContain('\\')
+  })
+
+  it('normalises both 2-char and long dividers to ---', () => {
+    expect(convertPlainText('--')).toBe('---')
+    expect(convertPlainText('==================================================================')).toBe('---')
+  })
+
+  it('escapes # heading (h1)', () => {
+    expect(convertPlainText('# Hello')).toBe('\\# Hello')
+  })
+
+  it('escapes ## heading (h2)', () => {
+    expect(convertPlainText('## Section')).toBe('\\## Section')
+  })
+
+  it('escapes up to h6', () => {
+    expect(convertPlainText('###### tiny')).toBe('\\###### tiny')
+  })
+
+  it('escapes # with no following space (bare hash at EOL counts as heading)', () => {
+    expect(convertPlainText('#')).toBe('\\#')
+  })
+
+  it('does not escape # in the middle of a line', () => {
+    expect(convertPlainText('color: #ff0000')).toBe('color: #ff0000')
+  })
+
+  it('does not escape lines with 7+ # chars (not a heading)', () => {
+    expect(convertPlainText('####### not a heading')).toBe('####### not a heading')
+  })
+
+  it('escapes # with up to 3 leading spaces', () => {
+    expect(convertPlainText('   # indented')).toBe('\\   # indented')
+  })
+})
+
 // ── extractReceivedDate ───────────────────────────────────────────────────────
 
 describe('extractReceivedDate', () => {

From b931fcbe6b87dd3f1c5503cc25cbd7e4f7ab945b Mon Sep 17 00:00:00 2001
From: Jan Hapke <github@janhapke.com>
Date: Fri, 5 Jun 2026 01:05:15 +0200
Subject: [PATCH 08/18] feat(export): improve HTML and plain text Markdown
 quality

- Unwrap layout tables (no <th> / role="presentation") to prose; keep
  data tables as GFM pipe tables
- Strip invisible email spacer characters (soft hyphen, ZWS etc.) in
  preprocessHtml
- Post-process htmlToMarkdown output: replace Unicode non-breaking
  spaces, trim trailing whitespace per line, collapse 3+ newlines to 2,
  convert Turndown-escaped visual bullets (\* / \-) to real list items
- Plain text: keep > unchanged so quoted lines become Markdown
  blockquotes; classify blockquote lines as isBlock so they neither
  receive nor trigger hard-break markers

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/core/export.ts        | 130 +++++++++++++++++++++++++++++++---
 tests/unit/export.test.ts | 144 ++++++++++++++++++++++++++++++++++++--
 2 files changed, 260 insertions(+), 14 deletions(-)

diff --git a/src/core/export.ts b/src/core/export.ts
index 9eb43a3..5e65e86 100644
--- a/src/core/export.ts
+++ b/src/core/export.ts
@@ -32,8 +32,13 @@ export interface FolderExportResult {
 // ── HTML → Markdown ───────────────────────────────────────────────────────────
 
 export function preprocessHtml(html: string): string {
+  // Strip invisible filler characters used as spacers in HTML email
+  // (soft hyphen U+00AD, zero-width space U+200B, zero-width non-joiner U+200C,
+  //  zero-width joiner U+200D, BOM/zero-width no-break space U+FEFF)
+  let out = html.replace(/[\u00ad\u200b\u200c\u200d\ufeff]/g, '')
+
   // Strip <style> and <script> blocks
-  let out = html.replace(/<style[\s\S]*?<\/style>/gi, '')
+  out = out.replace(/<style[\s\S]*?<\/style>/gi, '')
   out = out.replace(/<script[\s\S]*?<\/script>/gi, '')
 
   // Strip tracking-pixel <img> tags: width/height attr ≤ 1 or inline style width:0/height:0
@@ -57,15 +62,119 @@ export function preprocessHtml(html: string): string {
   return out
 }
 
+// ── Smart table rules ─────────────────────────────────────────────────────────
+// Layout tables (no <th> in first row, or role="presentation") are unwrapped to
+// prose. Data tables (first row all <th>) are kept as GFM pipe tables.
+
+function tableHasHeadingRow(table: any): boolean {
+  if (typeof table.getAttribute === 'function' && table.getAttribute('role') === 'presentation') {
+    return false
+  }
+  if (!table.rows || table.rows.length === 0) return false
+  const firstRow = table.rows[0]
+  let cellCount = 0
+  for (const child of Array.from(firstRow.childNodes as Iterable<any>)) {
+    if (child.nodeType !== 1) continue
+    cellCount++
+    if (child.nodeName !== 'TH') return false
+  }
+  return cellCount > 0
+}
+
+function findAncestorTable(node: any): any {
+  for (let n = node.parentNode; n; n = n.parentNode) {
+    if (n.nodeName === 'TABLE') return n
+  }
+  return null
+}
+
+function gfmPipeCell(content: string, node: any): string {
+  const index = Array.prototype.indexOf.call(node.parentNode.childNodes, node)
+  return (index === 0 ? '| ' : ' ') + content + ' |'
+}
+
+function isFirstTbody(node: any): boolean {
+  const prev = node.previousSibling
+  return (
+    node.nodeName === 'TBODY' &&
+    (!prev || (prev.nodeName === 'THEAD' && /^\s*$/.test(prev.textContent || '')))
+  )
+}
+
+function isGfmHeadingRow(tr: any): boolean {
+  const parent = tr.parentNode
+  const allTh = Array.prototype.every.call(tr.childNodes, (n: any) => n.nodeName === 'TH')
+  return (
+    parent.nodeName === 'THEAD' ||
+    (parent.firstChild === tr &&
+      allTh &&
+      (parent.nodeName === 'TABLE' || isFirstTbody(parent)))
+  )
+}
+
+function configureSmartTableRules(service: TurndownService): void {
+  // These override GFM's rules by reusing the same key names, preserving rule
+  // priority order while replacing the implementation.
+
+  service.addRule('tableCell', {
+    filter: ['th', 'td'],
+    replacement(content: string, node: any): string {
+      const table = findAncestorTable(node)
+      if (!table || !tableHasHeadingRow(table)) {
+        const trimmed = content.trim()
+        return trimmed ? '\n\n' + trimmed + '\n\n' : ''
+      }
+      return gfmPipeCell(content, node)
+    },
+  })
+
+  service.addRule('tableRow', {
+    filter: 'tr',
+    replacement(content: string, node: any): string {
+      const table = findAncestorTable(node)
+      if (!table || !tableHasHeadingRow(table)) return content
+      if (isGfmHeadingRow(node)) {
+        let border = ''
+        for (const n of Array.from(node.childNodes as Iterable<any>)) {
+          if (n.nodeType === 1) border += gfmPipeCell('---', n)
+        }
+        return '\n' + content + '\n' + border
+      }
+      return '\n' + content
+    },
+  })
+
+  service.addRule('table', {
+    filter: 'table',
+    replacement(content: string, node: any): string {
+      if (!tableHasHeadingRow(node)) {
+        const prose = content.replace(/\n{2,}/g, '\n').trim()
+        return prose ? '\n\n' + prose + '\n\n' : ''
+      }
+      return '\n\n' + content + '\n\n'
+    },
+  })
+}
+
 export function htmlToMarkdown(html: string): string {
   const cleaned = preprocessHtml(html)
 
   const td = new TurndownService({ headingStyle: 'atx', codeBlockStyle: 'fenced' })
   td.use(gfm)
-  const md = td.turndown(cleaned)
-
-  // Collapse 3+ consecutive blank lines to 2
-  return md.replace(/\n{3,}/g, '\n\n')
+  configureSmartTableRules(td)
+  let md = td.turndown(cleaned)
+
+  // (a) Replace Unicode non-breaking / decorative spaces with plain space
+  md = md.replace(/[\u00a0\u1680\u2002\u2003\u2009\u200a\u202f]/g, ' ')
+  // (b) Trim trailing whitespace from every line
+  md = md.replace(/[ \t]+$/gm, '')
+  // (d) Convert Turndown-escaped visual bullets (\* / \-) to real list items.
+  //     Also strips leading whitespace so 4+-space indent doesn't trigger code blocks.
+  md = md.replace(/^[ \t]*\\([*-]) /gm, '- ')
+  // (c) Collapse 3+ consecutive newlines to 2
+  md = md.replace(/\n{3,}/g, '\n\n')
+
+  return md
 }
 
 // ── Plain text → Markdown ─────────────────────────────────────────────────────
@@ -79,7 +188,7 @@ const MANUAL_LIST_RE = /^[ ]*(?:[-*][ \t]|\d+\.[ \t])/
 const DIVIDER_RE = /^[-=]{2,}\s*$/
 
 function escapeHtml(s: string): string {
-  return s.replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  return s.replace(/</g, '&lt;')
 }
 
 interface ConvertedLine {
@@ -95,8 +204,13 @@ function classifyLine(line: string): ConvertedLine {
   if (line === '') return { out: '', isBlock: false, isDivider: false }
   if (DIVIDER_RE.test(line)) return { out: '---', isBlock: false, isDivider: true }
   if (MANUAL_LIST_RE.test(line)) return { out: escapeHtml(line), isBlock: true, isDivider: false }
-  // Escape leading # to prevent ATX heading interpretation
-  const escaped = ATX_HEADING_RE.test(line) ? '\\' + escapeHtml(line) : escapeHtml(line)
+  // Blockquote lines (email quote marker >) are treated as block elements so they
+  // neither receive nor trigger hard-break markers on adjacent lines.
+  if (line.startsWith('>')) return { out: escapeHtml(line), isBlock: true, isDivider: false }
+  // Escape the # to prevent ATX heading interpretation, preserving any leading spaces
+  const escaped = ATX_HEADING_RE.test(line)
+    ? escapeHtml(line).replace(/^([ ]{0,3})(#{1,6})/, '$1\\$2')
+    : escapeHtml(line)
   return { out: escaped, isBlock: false, isDivider: false }
 }
 
diff --git a/tests/unit/export.test.ts b/tests/unit/export.test.ts
index 21d2eb9..6ce2a9f 100644
--- a/tests/unit/export.test.ts
+++ b/tests/unit/export.test.ts
@@ -50,6 +50,14 @@ describe('preprocessHtml', () => {
     const html = '<img src="photo.jpg" width="800" height="600"><p>Text</p>'
     expect(preprocessHtml(html)).toContain('<img')
   })
+
+  it('strips soft hyphens and zero-width spaces used as email spacers', () => {
+    const html = '<td>­</td><td>Text</td><td>​</td>'
+    const result = preprocessHtml(html)
+    expect(result).not.toContain('­')
+    expect(result).not.toContain('​')
+    expect(result).toContain('Text')
+  })
 })
 
 // ── htmlToMarkdown ────────────────────────────────────────────────────────────
@@ -60,6 +68,41 @@ describe('htmlToMarkdown', () => {
     expect(result).toContain('**Hello**')
   })
 
+  it('replaces non-breaking spaces with regular spaces', () => {
+    const result = htmlToMarkdown('<p>Hello World</p>')
+    expect(result).not.toContain(' ')
+    expect(result).toContain('Hello World')
+  })
+
+  it('trims trailing whitespace from lines', () => {
+    const result = htmlToMarkdown('<p>Hello   </p><p>World</p>')
+    expect(result).not.toMatch(/[ \t]+\n/)
+    expect(result).not.toMatch(/[ \t]+$/)
+  })
+
+  it('collapses 3+ consecutive newlines to 2', () => {
+    const html = '<p>A</p><p></p><p></p><p></p><p>B</p>'
+    const result = htmlToMarkdown(html)
+    expect(result).not.toMatch(/\n{3,}/)
+  })
+
+  it('converts escaped visual bullets with leading spaces to real list items', () => {
+    // &nbsp;&nbsp;&nbsp;* text is a common email pattern for visual lists
+    const html = '<p>&nbsp;&nbsp;&nbsp;&nbsp;* Item one<br>&nbsp;&nbsp;&nbsp;&nbsp;* Item two</p>'
+    const result = htmlToMarkdown(html)
+    expect(result).not.toContain('\\*')
+    expect(result).toContain('- Item one')
+    expect(result).toContain('- Item two')
+  })
+
+  it('does not convert \\* in the middle of a line', () => {
+    // Only line-leading escaped bullets should become list items
+    const html = '<p>Price is 5 \\* 3 = 15</p>'
+    const result = htmlToMarkdown(html)
+    expect(result).toContain('5')
+    expect(result).toContain('3')
+  })
+
   it('collapses 4+ consecutive blank lines to 2', () => {
     // Force 4+ blank lines by injecting them after conversion
     // We test by passing content that will produce multiple blank lines
@@ -67,6 +110,74 @@ describe('htmlToMarkdown', () => {
     const result = htmlToMarkdown(html)
     expect(result).not.toMatch(/\n{4,}/)
   })
+
+  describe('table handling', () => {
+    it('unwraps a layout table (no <th>) to prose — no pipe characters', () => {
+      const html = `<table>
+        <tr><td>Hello</td><td>World</td></tr>
+        <tr><td>Foo</td><td>Bar</td></tr>
+      </table>`
+      const result = htmlToMarkdown(html)
+      expect(result).not.toContain('|')
+      expect(result).toContain('Hello')
+      expect(result).toContain('World')
+    })
+
+    it('unwraps a table with role="presentation" even if it has <th>', () => {
+      const html = `<table role="presentation">
+        <tr><th>Name</th><th>Value</th></tr>
+        <tr><td>foo</td><td>bar</td></tr>
+      </table>`
+      const result = htmlToMarkdown(html)
+      expect(result).not.toContain('|')
+      expect(result).toContain('Name')
+      expect(result).toContain('foo')
+    })
+
+    it('preserves a data table (first row all <th>) as a pipe table', () => {
+      const html = `<table>
+        <tr><th>Name</th><th>Value</th></tr>
+        <tr><td>foo</td><td>bar</td></tr>
+      </table>`
+      const result = htmlToMarkdown(html)
+      expect(result).toContain('| Name | Value |')
+      expect(result).toContain('| foo | bar |')
+      expect(result).toContain('---')
+    })
+
+    it('preserves inline formatting inside layout table cells', () => {
+      const html = `<table>
+        <tr><td><strong>Bold</strong> and <a href="/x">link</a></td></tr>
+      </table>`
+      const result = htmlToMarkdown(html)
+      expect(result).toContain('**Bold**')
+      expect(result).toContain('[link](/x)')
+    })
+
+    it('unwraps nested layout tables', () => {
+      const html = `<table>
+        <tr><td>
+          <table><tr><td>Inner</td></tr></table>
+        </td></tr>
+      </table>`
+      const result = htmlToMarkdown(html)
+      expect(result).not.toContain('|')
+      expect(result).toContain('Inner')
+    })
+
+    it('preserves a data table nested inside a layout table', () => {
+      const html = `<table>
+        <tr><td>
+          <table>
+            <tr><th>Col A</th><th>Col B</th></tr>
+            <tr><td>1</td><td>2</td></tr>
+          </table>
+        </td></tr>
+      </table>`
+      const result = htmlToMarkdown(html)
+      expect(result).toContain('| Col A | Col B |')
+    })
+  })
 })
 
 // ── convertPlainText ──────────────────────────────────────────────────────────
@@ -121,14 +232,35 @@ describe('convertPlainText', () => {
     expect(result).toBe('Hello\\\nWorld\n\n- item\n\nFoo\\\nBar')
   })
 
-  it('escapes < and > in prose', () => {
+  it('escapes < in prose (prevents HTML injection)', () => {
     const result = convertPlainText('See <https://example.com>')
-    expect(result).toBe('See &lt;https://example.com&gt;')
+    expect(result).toBe('See &lt;https://example.com>')
   })
 
-  it('escapes < and > in list items', () => {
+  it('escapes < in list items', () => {
     const result = convertPlainText('- See <note>')
-    expect(result).toBe('- See &lt;note&gt;')
+    expect(result).toBe('- See &lt;note>')
+  })
+
+  it('keeps > as-is so quoted lines become Markdown blockquotes', () => {
+    const text = '> Hello\n> World'
+    const result = convertPlainText(text)
+    expect(result).toContain('> Hello')
+    expect(result).toContain('> World')
+    expect(result).not.toContain('&gt;')
+  })
+
+  it('does not add hard-break \\ to blockquote lines', () => {
+    const text = '> Quoted line one\n> Quoted line two'
+    const result = convertPlainText(text)
+    expect(result).not.toContain('\\')
+  })
+
+  it('does not add hard-break \\ to prose line immediately before a blockquote', () => {
+    const text = 'Someone wrote:\n> Quoted text'
+    const result = convertPlainText(text)
+    expect(result).not.toMatch(/wrote:\\$/)
+    expect(result).toContain('> Quoted text')
   })
 
   it('preserves indented list items (spaces)', () => {
@@ -192,8 +324,8 @@ describe('convertPlainText', () => {
     expect(convertPlainText('####### not a heading')).toBe('####### not a heading')
   })
 
-  it('escapes # with up to 3 leading spaces', () => {
-    expect(convertPlainText('   # indented')).toBe('\\   # indented')
+  it('escapes # with up to 3 leading spaces, backslash right before #', () => {
+    expect(convertPlainText('   # indented')).toBe('   \\# indented')
   })
 })
 

From ec198a3f5e48fd514ff52c9f03d9a863f4abf853 Mon Sep 17 00:00:00 2001
From: Jan Hapke <github@janhapke.com>
Date: Fri, 5 Jun 2026 01:31:13 +0200
Subject: [PATCH 09/18] feat(export): add setext h1 subject heading between
 frontmatter and body

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/core/export.ts        | 15 +++++++++++----
 tests/unit/export.test.ts | 24 +++++++++++++++++++++---
 2 files changed, 32 insertions(+), 7 deletions(-)

diff --git a/src/core/export.ts b/src/core/export.ts
index 5e65e86..0ccc50b 100644
--- a/src/core/export.ts
+++ b/src/core/export.ts
@@ -347,6 +347,11 @@ export function assembleDocument(
 ): string {
   const frontmatter = buildFrontmatter(parsed, rawSource, folderPath)
 
+  const subject = parsed.subject ?? ''
+  const subjectHeading = subject.length > 0
+    ? subject + '\n' + '='.repeat(subject.length)
+    : ''
+
   // mailparser auto-generates text from html and vice versa — check the raw
   // content-type to determine which parts were explicitly present
   const unfolded = parseHeaderBlock(rawSource)
@@ -357,22 +362,24 @@ export function assembleDocument(
   const hasHtml = !isTopLevelTextOnly && typeof parsed.html === 'string' && parsed.html.length > 0
   const hasText = !isTopLevelHtmlOnly && typeof parsed.text === 'string' && parsed.text.length > 0
 
+  const header = subjectHeading ? frontmatter + '\n\n' + subjectHeading : frontmatter
+
   if (!hasHtml && !hasText) {
-    return frontmatter + '\n'
+    return header + '\n'
   }
 
   if (hasHtml && !hasText) {
-    return frontmatter + '\n\n' + htmlToMarkdown(parsed.html as string)
+    return header + '\n\n' + htmlToMarkdown(parsed.html as string)
   }
 
   if (!hasHtml && hasText) {
-    return frontmatter + '\n\n' + convertPlainText(parsed.text as string)
+    return header + '\n\n' + convertPlainText(parsed.text as string)
   }
 
   // Both HTML and plain text
   const divider = '\n\n---\n\n---\n\n---\n\n'
   return (
-    frontmatter +
+    header +
     '\n\n' +
     htmlToMarkdown(parsed.html as string) +
     divider +
diff --git a/tests/unit/export.test.ts b/tests/unit/export.test.ts
index 6ce2a9f..5f9ecc8 100644
--- a/tests/unit/export.test.ts
+++ b/tests/unit/export.test.ts
@@ -487,6 +487,21 @@ describe('assembleDocument', () => {
     expect(doc).toContain('Plain text here')
   })
 
+  it('includes setext h1 with subject between frontmatter and body', async () => {
+    const eml = 'From: foo@example.com\r\nSubject: Hello World\r\n\r\nBody text'
+    const parsed = await simpleParser(Buffer.from(eml))
+    const doc = assembleDocument(parsed, Buffer.from(eml), 'INBOX')
+    expect(doc).toContain('Hello World\n===========')
+  })
+
+  it('omits heading when subject is empty', async () => {
+    const eml = 'From: foo@example.com\r\n\r\nBody text'
+    const parsed = await simpleParser(Buffer.from(eml))
+    const doc = assembleDocument(parsed, Buffer.from(eml), 'INBOX')
+    // No setext underline in output
+    expect(doc).not.toMatch(/^=+$/m)
+  })
+
   it('pure-attachment: only frontmatter, no body content', async () => {
     const boundary = 'att123'
     const eml = [
@@ -504,9 +519,12 @@ describe('assembleDocument', () => {
     ].join('\r\n')
     const parsed = await simpleParser(Buffer.from(eml))
     const doc = assembleDocument(parsed, Buffer.from(eml), 'INBOX')
-    // Should end with --- (closing frontmatter delimiter) and newline, nothing else
-    const afterFm = doc.replace(/^---[\s\S]*?---\n/, '')
-    expect(afterFm.trim()).toBe('')
+    // Only frontmatter + optional subject heading, no body content
+    expect(doc).not.toContain('AAAA')
+    expect(doc).not.toContain('text/plain')
+    // No prose body after the heading
+    const afterHeading = doc.replace(/^---[\s\S]*?---\n(\n[\s\S]*?={3,}\n)?/, '')
+    expect(afterHeading.trim()).toBe('')
   })
 })
 

From 907df57c47a0cf9f59937a08692fe8612ebe9714 Mon Sep 17 00:00:00 2001
From: Jan Hapke <github@janhapke.com>
Date: Fri, 5 Jun 2026 01:34:31 +0200
Subject: [PATCH 10/18] feat(export): strip all non-attachment images from HTML
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Remove any <img> whose src is not a cid: URL — eliminates logos,
layout images, and tracking pixels. Inline attachments (cid:) are
preserved.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/core/export.ts        | 19 ++++---------------
 tests/unit/export.test.ts | 27 ++++++++++-----------------
 2 files changed, 14 insertions(+), 32 deletions(-)

diff --git a/src/core/export.ts b/src/core/export.ts
index 0ccc50b..0c21029 100644
--- a/src/core/export.ts
+++ b/src/core/export.ts
@@ -41,22 +41,11 @@ export function preprocessHtml(html: string): string {
   out = out.replace(/<style[\s\S]*?<\/style>/gi, '')
   out = out.replace(/<script[\s\S]*?<\/script>/gi, '')
 
-  // Strip tracking-pixel <img> tags: width/height attr ≤ 1 or inline style width:0/height:0
+  // Strip all <img> tags except inline attachments (src="cid:...").
+  // Logos, layout images, and tracking pixels from external URLs are all removed.
   out = out.replace(/<img\b[^>]*>/gi, (tag) => {
-    // Check width/height attributes
-    const widthAttr = tag.match(/\bwidth\s*=\s*["']?(\d+)["']?/i)
-    const heightAttr = tag.match(/\bheight\s*=\s*["']?(\d+)["']?/i)
-    if (widthAttr && parseInt(widthAttr[1]) <= 1) return ''
-    if (heightAttr && parseInt(heightAttr[1]) <= 1) return ''
-
-    // Check inline style for width:0 or height:0
-    const styleAttr = tag.match(/\bstyle\s*=\s*["']([^"']*)["']/i)
-    if (styleAttr) {
-      const style = styleAttr[1]
-      if (/width\s*:\s*0/.test(style) || /height\s*:\s*0/.test(style)) return ''
-    }
-
-    return tag
+    const src = tag.match(/\bsrc\s*=\s*["']([^"']*)["']/i)
+    return src && src[1].toLowerCase().startsWith('cid:') ? tag : ''
   })
 
   return out
diff --git a/tests/unit/export.test.ts b/tests/unit/export.test.ts
index 5f9ecc8..4f46bb3 100644
--- a/tests/unit/export.test.ts
+++ b/tests/unit/export.test.ts
@@ -30,25 +30,18 @@ describe('preprocessHtml', () => {
     expect(preprocessHtml(html)).toContain('<p>Text</p>')
   })
 
-  it('strips 1x1 tracking pixel img (width=1 height=1 attrs)', () => {
-    const html = '<img src="track.png" width="1" height="1"><p>Text</p>'
-    expect(preprocessHtml(html)).not.toContain('<img')
-    expect(preprocessHtml(html)).toContain('<p>Text</p>')
-  })
-
-  it('strips img with width=0 attribute', () => {
-    const html = '<img src="t.gif" width="0"><p>Text</p>'
-    expect(preprocessHtml(html)).not.toContain('<img')
-  })
-
-  it('strips img with style width:0', () => {
-    const html = '<img src="t.gif" style="width:0;height:0"><p>Text</p>'
-    expect(preprocessHtml(html)).not.toContain('<img')
+  it('strips external images (logos, layout, tracking pixels)', () => {
+    const html = '<img src="https://example.com/logo.png"><img src="track.gif" width="1" height="1"><p>Text</p>'
+    const result = preprocessHtml(html)
+    expect(result).not.toContain('<img')
+    expect(result).toContain('<p>Text</p>')
   })
 
-  it('preserves normal images', () => {
-    const html = '<img src="photo.jpg" width="800" height="600"><p>Text</p>'
-    expect(preprocessHtml(html)).toContain('<img')
+  it('preserves inline attachment images (cid: src)', () => {
+    const html = '<img src="cid:image001@example.com"><p>Text</p>'
+    const result = preprocessHtml(html)
+    expect(result).toContain('<img')
+    expect(result).toContain('cid:image001@example.com')
   })
 
   it('strips soft hyphens and zero-width spaces used as email spacers', () => {

From 83da8dd3d456f36d6e73c9c88af1cab8a62bf62a Mon Sep 17 00:00:00 2001
From: Jan Hapke <github@janhapke.com>
Date: Fri, 5 Jun 2026 01:34:58 +0200
Subject: [PATCH 11/18] docs: document export command in README

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/README.md b/README.md
index a699a6f..e2dc2d0 100644
--- a/README.md
+++ b/README.md
@@ -248,6 +248,50 @@ If a worktree for that reference already exists it is replaced.
 
 ---
 
+### `export`
+
+Export the archive as Markdown files — one `.md` per message — with YAML frontmatter and a human-readable body.
+
+```sh
+backmail export
+backmail export --only-folder INBOX --only-folder Sent
+backmail export --exclude-folder Spam --verbose
+```
+
+| Option | Description |
+|--------|-------------|
+| `--exclude-folder <name>` | Skip a folder (repeatable) |
+| `--only-folder <name>` | Restrict to a folder (repeatable) |
+| `--verbose` | Log one line per folder and per message |
+
+`--exclude-folder` and `--only-folder` are mutually exclusive.
+
+Output is written to `export/` next to `archive/`, mirroring the folder structure. Each file contains:
+
+- YAML frontmatter with `messageId`, `from`, `to`, `subject`, `receivedDate`, `folders`, and `attachments`
+- The subject as a top-level heading
+- HTML body converted to Markdown (layout tables unwrapped to prose, external images stripped, inline attachments preserved)
+- Plain text body appended after a triple horizontal-rule divider (when both parts are present)
+
+Running `export` again is idempotent — existing files are overwritten with identical content.
+
+Output:
+
+```
+export: =42 exported
+```
+
+If any message fails the export continues and the summary line is tagged `[partial]`:
+
+```
+export [partial]: =38 exported
+folder INBOX/Archive failed: read error
+```
+
+Exit code is non-zero when any folder fails.
+
+---
+
 ### `restore`
 
 Re-upload messages from a backup to an IMAP server. Useful for migrating to a new provider or recovering deleted mail.
@@ -290,6 +334,9 @@ archive/            # git repository
 worktrees/          # point-in-time checkouts (outside the git repo)
   2024-01-15/
   abc1234/
+export/             # Markdown export (created by `backmail export`)
+  INBOX/
+    2024-01-15_subject_aabbccdd.md
 ```
 
 Messages are content-addressed by Message-ID, so identical emails that appear in multiple IMAP folders (common with Gmail labels) are stored only once.

From 51bfcd4ccdc1f49366664e1f813fa19002ef115b Mon Sep 17 00:00:00 2001
From: Jan Hapke <github@janhapke.com>
Date: Fri, 5 Jun 2026 01:47:57 +0200
Subject: [PATCH 12/18] feat(export): strip preheader padding chars and empty
 links
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add U+034F (combining grapheme joiner) to invisible-char strip in
  preprocessHtml — used by newsletters to pad email preview text
- Remove Markdown links with empty text after conversion, which appear
  when stripped images were wrapped in <a> tags (tracking/logo anchors)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/core/export.ts        |  8 ++++++--
 tests/unit/export.test.ts | 15 +++++++++++++++
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/src/core/export.ts b/src/core/export.ts
index 0c21029..3845f26 100644
--- a/src/core/export.ts
+++ b/src/core/export.ts
@@ -34,8 +34,9 @@ export interface FolderExportResult {
 export function preprocessHtml(html: string): string {
   // Strip invisible filler characters used as spacers in HTML email
   // (soft hyphen U+00AD, zero-width space U+200B, zero-width non-joiner U+200C,
-  //  zero-width joiner U+200D, BOM/zero-width no-break space U+FEFF)
-  let out = html.replace(/[\u00ad\u200b\u200c\u200d\ufeff]/g, '')
+  //  zero-width joiner U+200D, BOM/zero-width no-break space U+FEFF,
+  //  combining grapheme joiner U+034F \u2014 used in preheader padding sequences)
+  let out = html.replace(/[\u034f\u00ad\u200b\u200c\u200d\ufeff]/g, '')
 
   // Strip <style> and <script> blocks
   out = out.replace(/<style[\s\S]*?<\/style>/gi, '')
@@ -157,6 +158,9 @@ export function htmlToMarkdown(html: string): string {
   md = md.replace(/[\u00a0\u1680\u2002\u2003\u2009\u200a\u202f]/g, ' ')
   // (b) Trim trailing whitespace from every line
   md = md.replace(/[ \t]+$/gm, '')
+  // (e) Remove links with empty or whitespace-only text \u2014 these come from <a> tags
+  //     that wrapped images or content we stripped (tracking links, logo anchors).
+  md = md.replace(/\[ *\]\([^)]*\)/g, '')
   // (d) Convert Turndown-escaped visual bullets (\* / \-) to real list items.
   //     Also strips leading whitespace so 4+-space indent doesn't trigger code blocks.
   md = md.replace(/^[ \t]*\\([*-]) /gm, '- ')
diff --git a/tests/unit/export.test.ts b/tests/unit/export.test.ts
index 4f46bb3..867d78c 100644
--- a/tests/unit/export.test.ts
+++ b/tests/unit/export.test.ts
@@ -51,6 +51,13 @@ describe('preprocessHtml', () => {
     expect(result).not.toContain('​')
     expect(result).toContain('Text')
   })
+
+  it('strips combining grapheme joiner (U+034F) used in preheader padding', () => {
+    const html = '<p>Preview text͏͏͏͏͏</p><p>Body</p>'
+    const result = preprocessHtml(html)
+    expect(result).not.toContain('͏')
+    expect(result).toContain('Preview text')
+  })
 })
 
 // ── htmlToMarkdown ────────────────────────────────────────────────────────────
@@ -96,6 +103,14 @@ describe('htmlToMarkdown', () => {
     expect(result).toContain('3')
   })
 
+  it('removes links with empty text (remnants of stripped images inside <a>)', () => {
+    const html = '<p>Before</p><a href="https://track.example.com/click"><img src="logo.png"></a><p>After</p>'
+    const result = htmlToMarkdown(html)
+    expect(result).not.toMatch(/\[\s*\]\(/)
+    expect(result).toContain('Before')
+    expect(result).toContain('After')
+  })
+
   it('collapses 4+ consecutive blank lines to 2', () => {
     // Force 4+ blank lines by injecting them after conversion
     // We test by passing content that will produce multiple blank lines

From f86c1f058ae9f4d31f8e3c440ffef855ed3871ee Mon Sep 17 00:00:00 2001
From: Jan Hapke <github@janhapke.com>
Date: Fri, 5 Jun 2026 01:50:39 +0200
Subject: [PATCH 13/18] feat(export): simplify frontmatter address and
 attachment format

- from/to use "Name <email>" strings instead of nested name/email objects
- attachments use "filename (N bytes)" strings instead of nested objects

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/core/export.ts        | 24 ++++++++++++++----------
 tests/unit/export.test.ts | 18 ++++++++----------
 2 files changed, 22 insertions(+), 20 deletions(-)

diff --git a/src/core/export.ts b/src/core/export.ts
index 3845f26..9c61f07 100644
--- a/src/core/export.ts
+++ b/src/core/export.ts
@@ -280,14 +280,21 @@ function yamlQuote(s: string): string {
   return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"'
 }
 
+function formatAddress(name: string | undefined, email: string | undefined): string {
+  const n = name?.trim() ?? ''
+  const e = email?.trim() ?? ''
+  if (n && e) return `${n} <${e}>`
+  return n || e
+}
+
 export function buildFrontmatter(
   parsed: ParsedMail,
   rawSource: Buffer | string,
   folderPath: string,
 ): string {
   const messageId = parsed.messageId ?? ''
-  const fromName = parsed.from?.value[0]?.name ?? ''
-  const fromEmail = parsed.from?.value[0]?.address ?? ''
+  const fromAddr = parsed.from?.value[0]
+  const fromStr = formatAddress(fromAddr?.name, fromAddr?.address)
   const toList = (parsed.to ? (Array.isArray(parsed.to) ? parsed.to : [parsed.to]) : [])
     .flatMap((a) => a.value)
   const subject = parsed.subject ?? ''
@@ -297,17 +304,14 @@ export function buildFrontmatter(
   const lines: string[] = []
   lines.push('---')
   lines.push(`messageId: ${yamlQuote(messageId)}`)
-  lines.push('from:')
-  lines.push(`  name: ${yamlQuote(fromName)}`)
-  lines.push(`  email: ${yamlQuote(fromEmail)}`)
+  lines.push(`from: ${yamlQuote(fromStr)}`)
 
   if (toList.length === 0) {
     lines.push('to: []')
   } else {
     lines.push('to:')
     for (const addr of toList) {
-      lines.push(`  - name: ${yamlQuote(addr.name ?? '')}`)
-      lines.push(`    email: ${yamlQuote(addr.address ?? '')}`)
+      lines.push(`  - ${yamlQuote(formatAddress(addr.name, addr.address))}`)
     }
   }
 
@@ -321,9 +325,9 @@ export function buildFrontmatter(
   } else {
     lines.push('attachments:')
     for (const att of attachments) {
-      lines.push(`  - filename: ${yamlQuote(att.filename ?? '')}`)
-      lines.push(`    contentType: ${yamlQuote(att.contentType)}`)
-      lines.push(`    size: ${att.size ?? 0}`)
+      const name = att.filename ?? ''
+      const size = att.size ?? 0
+      lines.push(`  - ${yamlQuote(name ? `${name} (${size} bytes)` : `(${size} bytes)`)}`)
     }
   }
 
diff --git a/tests/unit/export.test.ts b/tests/unit/export.test.ts
index 867d78c..5a59275 100644
--- a/tests/unit/export.test.ts
+++ b/tests/unit/export.test.ts
@@ -373,8 +373,7 @@ describe('buildFrontmatter', () => {
     const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX')
     expect(fm).toContain('messageId:')
     expect(fm).toContain('subject: "Hello World"')
-    expect(fm).toContain('name: "Jane Doe"')
-    expect(fm).toContain('email: "jane@example.com"')
+    expect(fm).toContain('from: "Jane Doe <jane@example.com>"')
     expect(fm).toContain('- "INBOX"')
   })
 
@@ -395,8 +394,8 @@ describe('buildFrontmatter', () => {
     ].join('\r\n')
     const parsed = await simpleParser(Buffer.from(eml))
     const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX')
-    expect(fm).toContain('email: "alice@example.com"')
-    expect(fm).toContain('email: "bob@example.com"')
+    expect(fm).toContain('"Alice <alice@example.com>"')
+    expect(fm).toContain('"Bob <bob@example.com>"')
   })
 
   it('sets subject to empty string when missing', async () => {
@@ -406,14 +405,14 @@ describe('buildFrontmatter', () => {
     expect(fm).toContain('subject: ""')
   })
 
-  it('sets from name to empty string when not present', async () => {
+  it('sets from to bare email when name is absent', async () => {
     const eml = 'From: foo@example.com\r\nSubject: Test\r\n\r\nBody'
     const parsed = await simpleParser(Buffer.from(eml))
     const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX')
-    expect(fm).toContain('name: ""')
+    expect(fm).toContain('from: "foo@example.com"')
   })
 
-  it('lists attachments with filename, contentType, size', async () => {
+  it('lists attachments as "filename (N bytes)" strings', async () => {
     const boundary = 'abc123boundary'
     const eml = [
       'From: foo@example.com',
@@ -434,9 +433,8 @@ describe('buildFrontmatter', () => {
     ].join('\r\n')
     const parsed = await simpleParser(Buffer.from(eml))
     const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX')
-    expect(fm).toContain('filename: "report.pdf"')
-    expect(fm).toContain('contentType: "application/pdf"')
-    expect(fm).toContain('size:')
+    expect(fm).toMatch(/- "report\.pdf \(\d+ bytes\)"/)
+    expect(fm).not.toContain('contentType:')
   })
 
   it('sets attachments: [] when no attachments', async () => {

From b73597d9e40311cd9e28737f7c9028bd26278103 Mon Sep 17 00:00:00 2001
From: Jan Hapke <github@janhapke.com>
Date: Fri, 5 Jun 2026 02:00:09 +0200
Subject: [PATCH 14/18] feat(export): treat <th> cells with block content as
 layout tables
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Newsletters often use <th> for multi-column image/text grids. A <th>
containing block-level elements (img, div, p, table, headings, etc.)
is a layout cell, not a data header — unwrap to prose instead of
forcing a broken GFM pipe table.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/core/export.ts        | 33 ++++++++++++++++++++++++++++++---
 tests/unit/export.test.ts | 25 +++++++++++++++++++++++++
 2 files changed, 55 insertions(+), 3 deletions(-)

diff --git a/src/core/export.ts b/src/core/export.ts
index 9c61f07..1930ba8 100644
--- a/src/core/export.ts
+++ b/src/core/export.ts
@@ -56,6 +56,26 @@ export function preprocessHtml(html: string): string {
 // Layout tables (no <th> in first row, or role="presentation") are unwrapped to
 // prose. Data tables (first row all <th>) are kept as GFM pipe tables.
 
+// Block-level tags that indicate a <th> is being used for layout rather than
+// as a data column header. A genuine header cell contains short inline text.
+const BLOCK_TAGS = new Set(['table', 'div', 'p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+  'ul', 'ol', 'blockquote', 'img', 'figure'])
+
+function cellHasBlockContent(cell: any): boolean {
+  function walk(node: any): boolean {
+    if (node.nodeType !== 1) return false
+    if (BLOCK_TAGS.has((node.nodeName as string).toLowerCase())) return true
+    for (const child of Array.from(node.childNodes as Iterable<any>)) {
+      if (walk(child)) return true
+    }
+    return false
+  }
+  for (const child of Array.from(cell.childNodes as Iterable<any>)) {
+    if (walk(child)) return true
+  }
+  return false
+}
+
 function tableHasHeadingRow(table: any): boolean {
   if (typeof table.getAttribute === 'function' && table.getAttribute('role') === 'presentation') {
     return false
@@ -67,6 +87,8 @@ function tableHasHeadingRow(table: any): boolean {
     if (child.nodeType !== 1) continue
     cellCount++
     if (child.nodeName !== 'TH') return false
+    // A <th> containing block-level elements is a layout cell, not a data header
+    if (cellHasBlockContent(child)) return false
   }
   return cellCount > 0
 }
@@ -154,9 +176,14 @@ export function htmlToMarkdown(html: string): string {
   configureSmartTableRules(td)
   let md = td.turndown(cleaned)
 
-  // (a) Replace Unicode non-breaking / decorative spaces with plain space
-  md = md.replace(/[\u00a0\u1680\u2002\u2003\u2009\u200a\u202f]/g, ' ')
-  // (b) Trim trailing whitespace from every line
+  // (a) Strip invisible characters that may have been decoded from HTML entities
+  //     by the DOM parser inside Turndown (e.g. &#847; \u2192 U+034F, &shy; \u2192 U+00AD).
+  //     Mirrors the preprocessHtml strip but catches entity-encoded variants.
+  md = md.replace(/[\u00ad\u034f\u200b\u200c\u200d\ufeff]/g, '')
+  // (b) Replace Unicode non-breaking / decorative spaces with plain space.
+  //     U+2007 FIGURE SPACE (&#8199;) is the main culprit in preheader padding divs.
+  md = md.replace(/[\u00a0\u1680\u2002\u2003\u2007\u2008\u2009\u200a\u202f\u205f\u3000]/g, ' ')
+  // (c) Trim trailing whitespace from every line (also collapses space-only lines to empty)
   md = md.replace(/[ \t]+$/gm, '')
   // (e) Remove links with empty or whitespace-only text \u2014 these come from <a> tags
   //     that wrapped images or content we stripped (tracking links, logo anchors).
diff --git a/tests/unit/export.test.ts b/tests/unit/export.test.ts
index 5a59275..3006de8 100644
--- a/tests/unit/export.test.ts
+++ b/tests/unit/export.test.ts
@@ -74,6 +74,16 @@ describe('htmlToMarkdown', () => {
     expect(result).toContain('Hello World')
   })
 
+  it('strips entity-encoded invisible chars and figure spaces that survive preprocessHtml', () => {
+    // &#8199; = U+2007 figure space, &#847; = U+034F CGJ, &shy; = U+00AD soft hyphen
+    const html = '<div>&#8199;&#847; &#8199;&#847; &shy; &shy;</div><p>Body</p>'
+    const result = htmlToMarkdown(html)
+    expect(result).not.toContain('\u2007')
+    expect(result).not.toContain('\u034f')
+    // The padding div should collapse to nothing, leaving only the body
+    expect(result.trim()).toBe('Body')
+  })
+
   it('trims trailing whitespace from lines', () => {
     const result = htmlToMarkdown('<p>Hello   </p><p>World</p>')
     expect(result).not.toMatch(/[ \t]+\n/)
@@ -173,6 +183,21 @@ describe('htmlToMarkdown', () => {
       expect(result).toContain('Inner')
     })
 
+    it('unwraps a layout table that uses <th> for layout (cells contain block content)', () => {
+      // Newsletters often use <th> for two-column grids — these are layout tables,
+      // not data tables, and should be unwrapped to prose, not rendered as pipe tables.
+      const html = `<table>
+        <tr>
+          <th><img src="cid:a.jpg" alt="A"><p>Left text</p></th>
+          <th><img src="cid:b.jpg" alt="B"><p>Right text</p></th>
+        </tr>
+      </table>`
+      const result = htmlToMarkdown(html)
+      expect(result).not.toContain('|')
+      expect(result).toContain('Left text')
+      expect(result).toContain('Right text')
+    })
+
     it('preserves a data table nested inside a layout table', () => {
       const html = `<table>
         <tr><td>

From cae848399cfe3e3658b44d4336f42757e499f6f5 Mon Sep 17 00:00:00 2001
From: Jan Hapke <github@janhapke.com>
Date: Fri, 5 Jun 2026 02:05:17 +0200
Subject: [PATCH 15/18] fix(export): treat whitespace-only lines as blank in
 convertPlainText

Tab-only lines used as separators were not classified as empty, causing
the preceding content line to receive a spurious hard-break marker \.
Also trims trailing whitespace from all non-empty plain text lines.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/core/export.ts        | 10 ++++++----
 tests/unit/export.test.ts | 16 ++++++++++++++++
 2 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/src/core/export.ts b/src/core/export.ts
index 1930ba8..471dc62 100644
--- a/src/core/export.ts
+++ b/src/core/export.ts
@@ -221,17 +221,19 @@ interface ConvertedLine {
 const ATX_HEADING_RE = /^[ ]{0,3}#{1,6}([ \t]|$)/
 
 function classifyLine(line: string): ConvertedLine {
-  if (line === '') return { out: '', isBlock: false, isDivider: false }
+  // Whitespace-only lines (tabs, spaces) count as blank lines — they must not
+  // trigger hard-break markers on the line before them.
+  if (line === '' || /^\s+$/.test(line)) return { out: '', isBlock: false, isDivider: false }
   if (DIVIDER_RE.test(line)) return { out: '---', isBlock: false, isDivider: true }
-  if (MANUAL_LIST_RE.test(line)) return { out: escapeHtml(line), isBlock: true, isDivider: false }
+  if (MANUAL_LIST_RE.test(line)) return { out: escapeHtml(line).trimEnd(), isBlock: true, isDivider: false }
   // Blockquote lines (email quote marker >) are treated as block elements so they
   // neither receive nor trigger hard-break markers on adjacent lines.
-  if (line.startsWith('>')) return { out: escapeHtml(line), isBlock: true, isDivider: false }
+  if (line.startsWith('>')) return { out: escapeHtml(line).trimEnd(), isBlock: true, isDivider: false }
   // Escape the # to prevent ATX heading interpretation, preserving any leading spaces
   const escaped = ATX_HEADING_RE.test(line)
     ? escapeHtml(line).replace(/^([ ]{0,3})(#{1,6})/, '$1\\$2')
     : escapeHtml(line)
-  return { out: escaped, isBlock: false, isDivider: false }
+  return { out: escaped.trimEnd(), isBlock: false, isDivider: false }
 }
 
 export function convertPlainText(text: string): string {
diff --git a/tests/unit/export.test.ts b/tests/unit/export.test.ts
index 3006de8..f5aed18 100644
--- a/tests/unit/export.test.ts
+++ b/tests/unit/export.test.ts
@@ -283,6 +283,22 @@ describe('convertPlainText', () => {
     expect(result).not.toContain('&gt;')
   })
 
+  it('treats whitespace-only lines as blank — does not add \\ to preceding line', () => {
+    // Plain-text emails often use tab-only lines as separators between content blocks.
+    // They should not trigger hard-break markers on the line before them.
+    const text = 'USA / New York\n\t\nLive dabei'
+    const result = convertPlainText(text)
+    expect(result).not.toContain('\\')
+    expect(result).toContain('USA / New York')
+    expect(result).toContain('Live dabei')
+  })
+
+  it('does not emit whitespace-only lines — collapses them to empty', () => {
+    const text = 'Line A\n\t\n\t\nLine B'
+    const result = convertPlainText(text)
+    expect(result).not.toMatch(/^\t/m)
+  })
+
   it('does not add hard-break \\ to blockquote lines', () => {
     const text = '> Quoted line one\n> Quoted line two'
     const result = convertPlainText(text)

From 6165b9ba8d475a7957acbc19b0e02b4f298f0d7a Mon Sep 17 00:00:00 2001
From: Jan Hapke <github@janhapke.com>
Date: Fri, 5 Jun 2026 02:33:31 +0200
Subject: [PATCH 16/18] feat(export): add hard line breaks to layout table
 prose lines

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/core/export.ts        | 32 ++++++++++++++++++++++++++++++++
 tests/unit/export.test.ts | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+)

diff --git a/src/core/export.ts b/src/core/export.ts
index 471dc62..c379f7b 100644
--- a/src/core/export.ts
+++ b/src/core/export.ts
@@ -193,10 +193,42 @@ export function htmlToMarkdown(html: string): string {
   md = md.replace(/^[ \t]*\\([*-]) /gm, '- ')
   // (c) Collapse 3+ consecutive newlines to 2
   md = md.replace(/\n{3,}/g, '\n\n')
+  // (f) Add hard line breaks between consecutive non-block prose lines so that
+  //     content extracted from layout tables (collapsed to single newlines) still
+  //     renders with visible line breaks in markdown.
+  md = addMarkdownHardBreaks(md)
 
   return md
 }
 
+// ── Markdown hard-break pass ──────────────────────────────────────────────────
+// Detects markdown structural lines that should not receive or trigger a hard-
+// break marker: headings, blockquotes, list items, indented/fenced code,
+// thematic breaks, setext underlines, and GFM table rows.
+const MD_BLOCK_RE =
+  /^(?:[ ]{0,3}#{1,6}[ \t]|>|[ ]{0,3}[-*+][ \t]|[ ]{0,3}\d+\.[ \t]|[ ]{4,}|\t|`{3,}|~{3,}|[=\-*_]{3,}\s*$|\|)/
+
+function addMarkdownHardBreaks(md: string): string {
+  const lines = md.split('\n')
+  const out: string[] = []
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const next = lines[i + 1]
+    const isEmpty = (s: string | undefined): boolean =>
+      s === undefined || s === '' || /^\s+$/.test(s)
+    const isBlock = (s: string): boolean => MD_BLOCK_RE.test(s)
+
+    const addBreak =
+      !isEmpty(line) &&
+      !isBlock(line) &&
+      !isEmpty(next) &&
+      !isBlock(next)
+
+    out.push(addBreak ? line + '\\' : line)
+  }
+  return out.join('\n')
+}
+
 // ── Plain text → Markdown ─────────────────────────────────────────────────────
 
 // Matches manually typed list lines: optional leading spaces, then "- " or "* " or "N. "
diff --git a/tests/unit/export.test.ts b/tests/unit/export.test.ts
index f5aed18..91c7534 100644
--- a/tests/unit/export.test.ts
+++ b/tests/unit/export.test.ts
@@ -210,6 +210,42 @@ describe('htmlToMarkdown', () => {
       const result = htmlToMarkdown(html)
       expect(result).toContain('| Col A | Col B |')
     })
+
+    it('adds hard line breaks between layout table cell lines so they render visibly', () => {
+      // Each cell ends up on its own line after table unwrapping; without \
+      // they would render as a single run-on paragraph in markdown.
+      const html = `<table>
+        <tr><td>First cell</td><td>Second cell</td></tr>
+        <tr><td>Third cell</td><td>Fourth cell</td></tr>
+      </table>`
+      const result = htmlToMarkdown(html)
+      // All prose lines except the last in a consecutive run should end with \
+      const lines = result.split('\n').filter((l) => l.trim() !== '')
+      for (let i = 0; i < lines.length - 1; i++) {
+        expect(lines[i]).toMatch(/\\$/)
+      }
+      expect(lines[lines.length - 1]).not.toMatch(/\\$/)
+    })
+
+    it('does not add hard breaks to lines already separated by blank lines', () => {
+      // Regular paragraphs are separated by \n\n and must NOT get \
+      const html = '<p>Paragraph one</p><p>Paragraph two</p>'
+      const result = htmlToMarkdown(html)
+      expect(result).not.toContain('\\')
+    })
+
+    it('does not add hard breaks to heading or list lines from layout tables', () => {
+      // When a layout table cell contains a heading or list, those lines are
+      // block elements and should not receive or trigger hard-break markers.
+      const html = `<table>
+        <tr><td><h2>Section title</h2></td></tr>
+        <tr><td><ul><li>item one</li><li>item two</li></ul></td></tr>
+      </table>`
+      const result = htmlToMarkdown(html)
+      // No line ending with \ should appear
+      expect(result).not.toMatch(/\\\n/)
+      expect(result).not.toMatch(/\\$/)
+    })
   })
 })
 

From 5aa2b840112e9554b7518c88d5a3edce27867e30 Mon Sep 17 00:00:00 2001
From: Jan Hapke <github@janhapke.com>
Date: Fri, 5 Jun 2026 03:00:01 +0200
Subject: [PATCH 17/18] refactor(export): restructure document layout and
 frontmatter fields

- Add formats list to frontmatter (plaintext, html, or both)
- Swap body order: plain text first (canonical), HTML conversion second
- Replace triple-divider with labelled separator block so AI agents and
  humans can identify the boundary and understand the HTML section is
  automatically converted
- Rename receivedDate frontmatter field to received

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/core/export.ts        | 47 ++++++++++++++++++++++++++++-----------
 tests/unit/export.test.ts | 42 +++++++++++++++++++++++++---------
 2 files changed, 66 insertions(+), 23 deletions(-)

diff --git a/src/core/export.ts b/src/core/export.ts
index c379f7b..148f1b1 100644
--- a/src/core/export.ts
+++ b/src/core/export.ts
@@ -352,6 +352,7 @@ export function buildFrontmatter(
   parsed: ParsedMail,
   rawSource: Buffer | string,
   folderPath: string,
+  formats: string[],
 ): string {
   const messageId = parsed.messageId ?? ''
   const fromAddr = parsed.from?.value[0]
@@ -377,10 +378,19 @@ export function buildFrontmatter(
   }
 
   lines.push(`subject: ${yamlQuote(subject)}`)
-  lines.push(`receivedDate: ${yamlQuote(receivedDate)}`)
+  lines.push(`received: ${yamlQuote(receivedDate)}`)
   lines.push('folders:')
   lines.push(`  - ${yamlQuote(folderPath)}`)
 
+  if (formats.length === 0) {
+    lines.push('formats: []')
+  } else {
+    lines.push('formats:')
+    for (const fmt of formats) {
+      lines.push(`  - ${yamlQuote(fmt)}`)
+    }
+  }
+
   if (attachments.length === 0) {
     lines.push('attachments: []')
   } else {
@@ -398,18 +408,19 @@ export function buildFrontmatter(
 
 // ── Document assembler ────────────────────────────────────────────────────────
 
+// Separator used when both plain text and HTML body parts are present.
+// Three thematic breaks frame a bold label so AI agents and humans can
+// unambiguously identify the boundary and understand what follows.
+const HTML_BODY_SEPARATOR =
+  '\n\n---\n---\n---\n\n' +
+  '**[html-body below - automatically converted from HTML; may contain formatting loss or artifacts]**' +
+  '\n\n---\n---\n---\n\n'
+
 export function assembleDocument(
   parsed: ParsedMail,
   rawSource: Buffer | string,
   folderPath: string,
 ): string {
-  const frontmatter = buildFrontmatter(parsed, rawSource, folderPath)
-
-  const subject = parsed.subject ?? ''
-  const subjectHeading = subject.length > 0
-    ? subject + '\n' + '='.repeat(subject.length)
-    : ''
-
   // mailparser auto-generates text from html and vice versa — check the raw
   // content-type to determine which parts were explicitly present
   const unfolded = parseHeaderBlock(rawSource)
@@ -420,6 +431,17 @@ export function assembleDocument(
   const hasHtml = !isTopLevelTextOnly && typeof parsed.html === 'string' && parsed.html.length > 0
   const hasText = !isTopLevelHtmlOnly && typeof parsed.text === 'string' && parsed.text.length > 0
 
+  const formats: string[] = []
+  if (hasText) formats.push('plaintext')
+  if (hasHtml) formats.push('html')
+
+  const frontmatter = buildFrontmatter(parsed, rawSource, folderPath, formats)
+
+  const subject = parsed.subject ?? ''
+  const subjectHeading = subject.length > 0
+    ? subject + '\n' + '='.repeat(subject.length)
+    : ''
+
   const header = subjectHeading ? frontmatter + '\n\n' + subjectHeading : frontmatter
 
   if (!hasHtml && !hasText) {
@@ -434,14 +456,13 @@ export function assembleDocument(
     return header + '\n\n' + convertPlainText(parsed.text as string)
   }
 
-  // Both HTML and plain text
-  const divider = '\n\n---\n\n---\n\n---\n\n'
+  // Both present: plain text first (canonical), then HTML conversion
   return (
     header +
     '\n\n' +
-    htmlToMarkdown(parsed.html as string) +
-    divider +
-    convertPlainText(parsed.text as string)
+    convertPlainText(parsed.text as string) +
+    HTML_BODY_SEPARATOR +
+    htmlToMarkdown(parsed.html as string)
   )
 }
 
diff --git a/tests/unit/export.test.ts b/tests/unit/export.test.ts
index 91c7534..35488f9 100644
--- a/tests/unit/export.test.ts
+++ b/tests/unit/export.test.ts
@@ -447,7 +447,7 @@ describe('buildFrontmatter', () => {
       'Body text',
     ].join('\r\n')
     const parsed = await simpleParser(Buffer.from(eml))
-    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX')
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX', [])
     expect(fm).toContain('messageId:')
     expect(fm).toContain('subject: "Hello World"')
     expect(fm).toContain('from: "Jane Doe <jane@example.com>"')
@@ -457,7 +457,7 @@ describe('buildFrontmatter', () => {
   it('produces to: [] when To header is absent', async () => {
     const eml = 'From: foo@example.com\r\nSubject: Test\r\n\r\nBody'
     const parsed = await simpleParser(Buffer.from(eml))
-    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX')
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX', [])
     expect(fm).toContain('to: []')
   })
 
@@ -470,7 +470,7 @@ describe('buildFrontmatter', () => {
       'Body',
     ].join('\r\n')
     const parsed = await simpleParser(Buffer.from(eml))
-    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX')
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX', [])
     expect(fm).toContain('"Alice <alice@example.com>"')
     expect(fm).toContain('"Bob <bob@example.com>"')
   })
@@ -478,14 +478,14 @@ describe('buildFrontmatter', () => {
   it('sets subject to empty string when missing', async () => {
     const eml = 'From: foo@example.com\r\n\r\nBody'
     const parsed = await simpleParser(Buffer.from(eml))
-    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX')
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX', [])
     expect(fm).toContain('subject: ""')
   })
 
   it('sets from to bare email when name is absent', async () => {
     const eml = 'From: foo@example.com\r\nSubject: Test\r\n\r\nBody'
     const parsed = await simpleParser(Buffer.from(eml))
-    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX')
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX', [])
     expect(fm).toContain('from: "foo@example.com"')
   })
 
@@ -509,7 +509,7 @@ describe('buildFrontmatter', () => {
       `--${boundary}--`,
     ].join('\r\n')
     const parsed = await simpleParser(Buffer.from(eml))
-    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX')
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX', [])
     expect(fm).toMatch(/- "report\.pdf \(\d+ bytes\)"/)
     expect(fm).not.toContain('contentType:')
   })
@@ -517,9 +517,25 @@ describe('buildFrontmatter', () => {
   it('sets attachments: [] when no attachments', async () => {
     const eml = 'From: foo@example.com\r\nSubject: Test\r\n\r\nBody'
     const parsed = await simpleParser(Buffer.from(eml))
-    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX')
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX', [])
     expect(fm).toContain('attachments: []')
   })
+
+  it('includes formats list in frontmatter', async () => {
+    const eml = 'From: foo@example.com\r\nSubject: Test\r\n\r\nBody'
+    const parsed = await simpleParser(Buffer.from(eml))
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX', ['plaintext', 'html'])
+    expect(fm).toContain('formats:')
+    expect(fm).toContain('  - "plaintext"')
+    expect(fm).toContain('  - "html"')
+  })
+
+  it('includes formats: [] when no formats given', async () => {
+    const eml = 'From: foo@example.com\r\nSubject: Test\r\n\r\nBody'
+    const parsed = await simpleParser(Buffer.from(eml))
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX', [])
+    expect(fm).toContain('formats: []')
+  })
 })
 
 // ── assembleDocument ──────────────────────────────────────────────────────────
@@ -536,7 +552,7 @@ describe('assembleDocument', () => {
     const parsed = await simpleParser(Buffer.from(eml))
     const doc = assembleDocument(parsed, Buffer.from(eml), 'INBOX')
     expect(doc).toContain('**Hello**')
-    expect(doc).not.toContain('\n\n---\n\n---\n\n---\n\n')
+    expect(doc).not.toContain('html-body below')
   })
 
   it('plain-text-only: body is plain text, no conversion', async () => {
@@ -546,7 +562,7 @@ describe('assembleDocument', () => {
     expect(doc).toContain('Hello plain world')
   })
 
-  it('HTML + plain text: three-divider block present', async () => {
+  it('HTML + plain text: separator present, plain text before HTML', async () => {
     const boundary = 'div123'
     const eml = [
       'From: foo@example.com',
@@ -565,9 +581,15 @@ describe('assembleDocument', () => {
     ].join('\r\n')
     const parsed = await simpleParser(Buffer.from(eml))
     const doc = assembleDocument(parsed, Buffer.from(eml), 'INBOX')
-    expect(doc).toContain('\n\n---\n\n---\n\n---\n\n')
+    expect(doc).toContain('**[html-body below - automatically converted from HTML; may contain formatting loss or artifacts]**')
     expect(doc).toContain('HTML here')
     expect(doc).toContain('Plain text here')
+    // Plain text section must come before the HTML section
+    expect(doc.indexOf('Plain text here')).toBeLessThan(doc.indexOf('HTML here'))
+    // Frontmatter must list both formats
+    expect(doc).toContain('formats:')
+    expect(doc).toContain('"plaintext"')
+    expect(doc).toContain('"html"')
   })
 
   it('includes setext h1 with subject between frontmatter and body', async () => {

From 016c18aa0624c66d03cf6a7bf7f26f4ce82efd37 Mon Sep 17 00:00:00 2001
From: Jan Hapke <github@janhapke.com>
Date: Fri, 5 Jun 2026 03:05:56 +0200
Subject: [PATCH 18/18] docs: update export command docs for new frontmatter
 fields and body order

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index e2dc2d0..08de960 100644
--- a/README.md
+++ b/README.md
@@ -268,10 +268,10 @@ backmail export --exclude-folder Spam --verbose
 
 Output is written to `export/` next to `archive/`, mirroring the folder structure. Each file contains:
 
-- YAML frontmatter with `messageId`, `from`, `to`, `subject`, `receivedDate`, `folders`, and `attachments`
+- YAML frontmatter with `messageId`, `from`, `to`, `subject`, `received`, `folders`, `formats`, and `attachments`
 - The subject as a top-level heading
-- HTML body converted to Markdown (layout tables unwrapped to prose, external images stripped, inline attachments preserved)
-- Plain text body appended after a triple horizontal-rule divider (when both parts are present)
+- Plain text body (when present)
+- HTML body converted to Markdown, preceded by a labelled separator block (when both parts are present — layout tables are unwrapped to prose, external images stripped, inline attachments preserved)
 
 Running `export` again is idempotent — existing files are overwritten with identical content.