@novacraft-engineering/mailbox 0.4.27 → 0.4.29

package/lib/color-scheme.ts

@@ -0,0 +1,233 @@
+// Mail is styled inline, and only a stylesheet rule marked !important can override an inline
+// colour, so the other scheme is a prefers-color-scheme block of per-element classes. Gmail
+// drops that block and keeps inverting the inline styles itself.
+
+type Rgb = [number, number, number]
+type Hsl = [number, number, number]
+export type SchemeBase = 'light' | 'dark'
+
+const NAMED: Record<string, Rgb> = { white: [255, 255, 255], black: [0, 0, 0] }
+const VOID = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr'])
+const RAW_TEXT = new Set(['style', 'script', 'title', 'textarea'])
+const COLOR_TOKEN = /#[0-9a-f]{6}\b|#[0-9a-f]{3}\b|rgba?\([^)]*\)|\b(?:white|black)\b/i
+const SURFACE: Record<SchemeBase, Rgb> = { light: [28, 28, 30], dark: [255, 255, 255] }
+
+function parseColor(value: string | undefined): Rgb | null {
+  if (!value) return null
+  const raw = value.trim().toLowerCase().replace(/\s*!important$/, '')
+  if (NAMED[raw]) return NAMED[raw]
+  const hex = raw.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/)
+  if (hex) {
+    const full = hex[1].length === 3 ? [...hex[1]].map(digit => digit + digit).join('') : hex[1]
+    return [0, 2, 4].map(offset => parseInt(full.slice(offset, offset + 2), 16)) as Rgb
+  }
+  const rgb = raw.match(/^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)$/)
+  if (rgb && (rgb[4] === undefined || Number(rgb[4]) >= 0.9)) return [rgb[1], rgb[2], rgb[3]].map(Number) as Rgb
+  return null
+}
+
+const toHex = (color: Rgb) => `#${color.map(channel => Math.round(channel).toString(16).padStart(2, '0')).join('')}`
+
+function luminance(color: Rgb): number {
+  const [red, green, blue] = color.map(channel => {
+    const scaled = channel / 255
+    return scaled <= 0.03928 ? scaled / 12.92 : ((scaled + 0.055) / 1.055) ** 2.4
+  })
+  return 0.2126 * red + 0.7152 * green + 0.0722 * blue
+}
+
+function contrast(first: Rgb, second: Rgb): number {
+  const [high, low] = [luminance(first), luminance(second)].sort((left, right) => right - left)
+  return (high + 0.05) / (low + 0.05)
+}
+
+function toHsl([red, green, blue]: Rgb): Hsl {
+  const [scaledRed, scaledGreen, scaledBlue] = [red / 255, green / 255, blue / 255]
+  const max = Math.max(scaledRed, scaledGreen, scaledBlue)
+  const min = Math.min(scaledRed, scaledGreen, scaledBlue)
+  const lightness = (max + min) / 2
+  if (max === min) return [0, 0, lightness]
+  const delta = max - min
+  const saturation = lightness > 0.5 ? delta / (2 - max - min) : delta / (max + min)
+  const hue =
+    max === scaledRed ? (scaledGreen - scaledBlue) / delta + (scaledGreen < scaledBlue ? 6 : 0)
+    : max === scaledGreen ? (scaledBlue - scaledRed) / delta + 2
+    : (scaledRed - scaledGreen) / delta + 4
+  return [hue / 6, saturation, lightness]
+}
+
+function fromHsl([hue, saturation, lightness]: Hsl): Rgb {
+  if (!saturation) return [lightness * 255, lightness * 255, lightness * 255]
+  const upper = lightness < 0.5 ? lightness * (1 + saturation) : lightness + saturation - lightness * saturation
+  const lower = 2 * lightness - upper
+  const channel = (offset: number) => {
+    let tint = hue + offset
+    if (tint < 0) tint += 1
+    if (tint > 1) tint -= 1
+    if (tint < 1 / 6) return lower + (upper - lower) * 6 * tint
+    if (tint < 1 / 2) return upper
+    if (tint < 2 / 3) return lower + (upper - lower) * (2 / 3 - tint) * 6
+    return lower
+  }
+  return [channel(1 / 3) * 255, channel(0) * 255, channel(-1 / 3) * 255]
+}
+
+const withLightness = (color: Rgb, lightness: number, saturationScale = 1): Rgb => {
+  const [hue, saturation] = toHsl(color)
+  return fromHsl([hue, saturation * saturationScale, Math.min(1, Math.max(0, lightness))])
+}
+
+function flipSurface(color: Rgb, base: SchemeBase, kind: 'fill' | 'border'): Rgb {
+  const lightness = toHsl(color)[2]
+  if (base === 'light') {
+    if (lightness <= 0.75) return color
+    return withLightness(color, (1 - lightness) * 0.6 + (kind === 'fill' ? 0.06 : 0.2), 0.7)
+  }
+  if (lightness >= 0.25) return color
+  return withLightness(color, kind === 'fill' ? 0.94 + lightness * 0.6 : 0.9 - lightness * 0.6)
+}
+
+function fitText(color: Rgb, surface: Rgb): Rgb {
+  if (contrast(color, surface) >= 4.5) return color
+  const towardLight = luminance(surface) < 0.18
+  let lightness = 1 - toHsl(color)[2]
+  let candidate = withLightness(color, lightness)
+  while (contrast(candidate, surface) < 4.5 && lightness > 0 && lightness < 1) {
+    lightness += towardLight ? 0.02 : -0.02
+    candidate = withLightness(color, lightness)
+  }
+  return candidate
+}
+
+const sameColor = (first: Rgb, second: Rgb) => toHex(first) === toHex(second)
+
+function declarations(style: string): Map<string, string> {
+  const found = new Map<string, string>()
+  let depth = 0
+  let start = 0
+  const take = (end: number) => {
+    const part = style.slice(start, end)
+    const colon = part.indexOf(':')
+    if (colon > 0) found.set(part.slice(0, colon).trim().toLowerCase(), part.slice(colon + 1).trim())
+    start = end + 1
+  }
+  for (let index = 0; index < style.length; index++) {
+    const char = style[index]
+    if (char === '(') depth++
+    else if (char === ')') depth = Math.max(0, depth - 1)
+    else if (char === ';' && !depth) take(index)
+  }
+  take(style.length)
+  return found
+}
+
+function attribute(attrs: string, name: string): string | undefined {
+  const match = attrs.match(new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, 'i'))
+  return match ? (match[1] ?? match[2] ?? match[3]) : undefined
+}
+
+function colorsOf(tag: string, attrs: string) {
+  const style = declarations((attribute(attrs, 'style') ?? '').replace(/&quot;/g, '"'))
+  const backgroundShorthand = style.get('background')
+  const fill =
+    parseColor(style.get('background-color')) ??
+    (backgroundShorthand && !/url\(/i.test(backgroundShorthand)
+      ? parseColor(backgroundShorthand) ?? parseColor(backgroundShorthand.match(COLOR_TOKEN)?.[0])
+      : null) ??
+    parseColor(attribute(attrs, 'bgcolor'))
+  const borderValue = ['border-color', 'border', 'border-top', 'border-right', 'border-bottom', 'border-left']
+    .map(name => style.get(name))
+    .find(value => value && COLOR_TOKEN.test(value))
+  return {
+    text: parseColor(style.get('color')) ?? (tag === 'font' ? parseColor(attribute(attrs, 'color')) : null),
+    fill,
+    border: parseColor(borderValue?.match(COLOR_TOKEN)?.[0]),
+  }
+}
+
+type Frame = { tag: string; sourceText: Rgb; targetText: Rgb; targetFill: Rgb }
+
+export function designsForDark(html: string): boolean {
+  return /prefers-color-scheme\s*:\s*dark/i.test(html)
+}
+
+export function adaptiveEmail(html: string, base: SchemeBase = 'light'): string {
+  if (!html.trim() || /prefers-color-scheme/i.test(html)) return html
+  const other = base === 'light' ? 'dark' : 'light'
+  const rules = new Map<string, string>()
+  const root: Frame = {
+    tag: '#root',
+    sourceText: [0, 0, 0],
+    targetText: fitText([0, 0, 0], SURFACE[base]),
+    targetFill: SURFACE[base],
+  }
+  const stack: Frame[] = [root]
+  const tagPattern = /<!--[\s\S]*?-->|<(\/?)([a-zA-Z][a-zA-Z0-9]*)((?:\s(?:[^>"']|"[^"]*"|'[^']*')*)?)\s*(\/?)>/g
+  let output = ''
+  let cursor = 0
+  let match: RegExpExecArray | null
+  while ((match = tagPattern.exec(html))) {
+    const [whole, closing, rawTag, attrs = '', selfClosing] = match
+    output += html.slice(cursor, match.index)
+    cursor = match.index + whole.length
+    if (!rawTag) {
+      output += whole
+      continue
+    }
+    const tag = rawTag.toLowerCase()
+    if (closing) {
+      const depth = stack.map(frame => frame.tag).lastIndexOf(tag)
+      if (depth > 0) stack.length = depth
+      output += whole
+      continue
+    }
+    if (RAW_TEXT.has(tag)) {
+      const end = html.toLowerCase().indexOf(`</${tag}`, cursor)
+      const stop = end === -1 ? html.length : end
+      output += whole + html.slice(cursor, stop)
+      cursor = stop
+      tagPattern.lastIndex = stop
+      continue
+    }
+    const parent = stack[stack.length - 1]
+    const own = colorsOf(tag, attrs)
+    const sourceText = own.text ?? parent.sourceText
+    const targetFill = own.fill ? flipSurface(own.fill, base, 'fill') : parent.targetFill
+    const targetText = fitText(sourceText, targetFill)
+    const shownWithoutRule = own.text ?? parent.targetText
+    const declarationsForOther = [
+      !sameColor(targetText, shownWithoutRule) && `color:${toHex(targetText)}!important`,
+      own.fill && !sameColor(targetFill, own.fill) && `background-color:${toHex(targetFill)}!important`,
+      own.border && !sameColor(flipSurface(own.border, base, 'border'), own.border) &&
+        `border-color:${toHex(flipSurface(own.border, base, 'border'))}!important`,
+    ].filter(Boolean).join(';')
+
+    let tagHtml = whole
+    if (declarationsForOther) {
+      const name = rules.get(declarationsForOther) ?? `nc-${other[0]}${rules.size}`
+      rules.set(declarationsForOther, name)
+      const existing = attrs.match(/\sclass\s*=\s*(?:"([^"]*)"|'([^']*)')/i)
+      tagHtml = existing
+        ? whole.replace(existing[0], ` class="${`${existing[1] ?? existing[2] ?? ''} ${name}`.trim()}"`)
+        : whole.replace(/^<[a-zA-Z0-9]+/, opening => `${opening} class="${name}"`)
+    }
+    output += tagHtml
+    if (!selfClosing && !/\/\s*$/.test(attrs) && !VOID.has(tag)) stack.push({ tag, sourceText, targetText, targetFill })
+  }
+  output += html.slice(cursor)
+
+  const css = [...rules].map(([body, name]) => `.${name}{${body}}`).join('')
+  const head =
+    '<meta name="color-scheme" content="light dark"><meta name="supported-color-schemes" content="light dark">' +
+    `<style>:root{color-scheme:light dark;supported-color-schemes:light dark}@media (prefers-color-scheme: ${other}){${css}}</style>`
+  if (/<head[\s>]/i.test(output)) return output.replace(/<head([^>]*)>/i, `<head$1>${head}`)
+  if (/<html[\s>]/i.test(output)) return output.replace(/<html([^>]*)>/i, `<html$1><head>${head}</head>`)
+  return `<!doctype html><html><head><meta charset="utf-8">${head}</head><body>${output}</body></html>`
+}
+
+// The reader's theme decides, not the device's: a dark app on a light device still gets the dark design.
+export function pinColorScheme(html: string, dark: boolean): string {
+  return html.replace(/\(\s*prefers-color-scheme\s*:\s*(dark|light)\s*\)/gi, (_, scheme: string) =>
+    (scheme.toLowerCase() === 'dark') === dark ? '(min-width:0px)' : '(max-width:0px)',
+  )
+}

package/lib/emails/index.ts

@@ -1,4 +1,5 @@
 import { BRAND } from '../brand'
+import { adaptiveEmail } from '../color-scheme'
 /**
  * Tiny email-template runtime.
  *
@@ -88,13 +89,13 @@ export function renderNotificationEmail(
   mode: EmailMode,
   fields: EmailField[],
 ): string {
-  return render(TPL_NOTIFICATION, {
+  return adaptiveEmail(render(TPL_NOTIFICATION, {
     title:
       mode === 'academy' ? 'New Academy Registration' : 'New Project Inquiry',
     host: BRAND_HOST,
     date: new Date().toUTCString(),
     rows: renderRows(fields, 'notification'),
-  })
+  }), 'dark')
 }
 
 export function notificationSubject(mode: EmailMode, email: string): string {
@@ -108,7 +109,7 @@ export function renderAutoReplyEmail(
   fields: EmailField[],
 ): string {
   const isAcademy = mode === 'academy'
-  return render(TPL_AUTO_REPLY, {
+  return adaptiveEmail(render(TPL_AUTO_REPLY, {
     headline: isAcademy ? 'Your spot is reserved.' : 'We got your brief.',
     kicker: isAcademy ? 'Academy' : 'Studio',
     lead: isAcademy
@@ -117,7 +118,7 @@ export function renderAutoReplyEmail(
     rows: renderRows(fields, 'reply'),
     brandUrl: BRAND_URL,
     brandHost: BRAND_HOST,
-  })
+  }), 'dark')
 }
 
 export function autoReplySubject(mode: EmailMode): string {
@@ -150,7 +151,7 @@ export type AcademyFollowupVars = {
 }
 
 export function renderAcademyFollowupEmail(vars: AcademyFollowupVars): string {
-  return render(TPL_ACADEMY_FOLLOWUP, {
+  return adaptiveEmail(render(TPL_ACADEMY_FOLLOWUP, {
     logoUrl: vars.logoUrl ?? BRAND.logoUrl,
     headline: escapeHtml(vars.headline ?? 'Your cohort details are here.'),
     firstName: escapeHtml(vars.firstName),
@@ -188,7 +189,7 @@ export function renderAcademyFollowupEmail(vars: AcademyFollowupVars): string {
     signatureRole: escapeHtml(vars.signatureRole ?? `${BRAND.name} Academy`),
     brandUrl: BRAND_URL,
     brandHost: BRAND_HOST,
-  })
+  }), 'dark')
 }
 
 export function academyFollowupSubject(courses: string): string {
@@ -239,7 +240,7 @@ function renderAcademySection(vars: ContactFollowupVars): string {
 }
 
 export function renderContactFollowupEmail(vars: ContactFollowupVars): string {
-  return render(TPL_CONTACT_FOLLOWUP, {
+  return adaptiveEmail(render(TPL_CONTACT_FOLLOWUP, {
     logoUrl: vars.logoUrl ?? BRAND.logoUrl,
     headline: escapeHtml(vars.headline ?? 'A few quick questions about your project.'),
     firstName: escapeHtml(vars.firstName),
@@ -274,7 +275,7 @@ export function renderContactFollowupEmail(vars: ContactFollowupVars): string {
     signatureRole: escapeHtml(vars.signatureRole ?? 'Engineering Studio'),
     brandUrl: BRAND_URL,
     brandHost: BRAND_HOST,
-  })
+  }), 'dark')
 }
 
 export function contactFollowupSubject(projectType: string): string {
@@ -294,7 +295,7 @@ export type ActionEmailVars = {
 
 /** One-button transactional mail — resets, invites — in the tenant's own accent. */
 export function renderActionEmail(vars: ActionEmailVars): string {
-  return render(TPL_ACTION, {
+  return adaptiveEmail(render(TPL_ACTION, {
     eyebrow: escapeHtml(vars.eyebrow),
     accent: escapeHtml(vars.accent),
     title: escapeHtml(vars.title),
@@ -303,5 +304,5 @@ export function renderActionEmail(vars: ActionEmailVars): string {
     actionUrl: escapeHtml(vars.actionUrl),
     expiry: escapeHtml(vars.expiry),
     footer: escapeHtml(vars.footer),
-  })
+  }), 'dark')
 }

package/lib/inbox-filters.test.ts

@@ -0,0 +1,54 @@
+import assert from 'node:assert/strict'
+import { DatabaseSync } from 'node:sqlite'
+import { DEFAULT_INBOX_FILTERS, inboxFiltersSql, matchesInboxFilters, normalizeInboxFilters, type InboxFilter } from './inbox-filters.ts'
+
+assert.deepEqual(normalizeInboxFilters(undefined), DEFAULT_INBOX_FILTERS, 'untouched settings get the defaults')
+assert.deepEqual(normalizeInboxFilters([]), [], 'an emptied list stays empty')
+assert.deepEqual(
+  normalizeInboxFilters([
+    { kind: 'senderDomain', value: ' @Example.COM ' },
+    { kind: 'senderDomain', value: 'example.com' },
+    { kind: 'bogus', value: 'x' },
+    { kind: 'subjectPrefix', value: '   ' },
+  ]),
+  [{ kind: 'senderDomain', value: 'example.com' }],
+  'sender values are lowercased, duplicates and junk dropped',
+)
+
+const threads = [
+  { id: 'dmarc', senders: ['DMARC <dmarcreport@microsoft.com>'], subject: '[Preview] Report Domain: example.com', snippet: 'This is a DMARC report' },
+  { id: 'dmarc-joined', senders: ['dmarcreport@microsoft.com', 'Ada <ada@example.org>'], subject: 'Re: report', snippet: 'Thanks' },
+  { id: 'newsletter', senders: ['news@mail.example.net'], subject: 'Weekly: what shipped', snippet: '\n  Unsubscribe any time' },
+  { id: 'person', senders: ['Ada <ada@example.org>'], subject: 'Lunch 50% off?', snippet: 'Hi' },
+]
+
+const db = new DatabaseSync(':memory:')
+db.exec('CREATE TABLE mail_threads (thread_id TEXT, senders TEXT, subject TEXT, snippet TEXT)')
+const insert = db.prepare('INSERT INTO mail_threads VALUES (?, ?, ?, ?)')
+for (const thread of threads) insert.run(thread.id, JSON.stringify(thread.senders), thread.subject, thread.snippet)
+
+const viaSql = (filters: InboxFilter[]) => {
+  const clause = inboxFiltersSql(filters)
+  if (!clause) return []
+  return db.prepare(`SELECT thread_id FROM mail_threads t WHERE ${clause.sql} ORDER BY thread_id`).all(...clause.args).map(row => String(row.thread_id))
+}
+const viaJs = (filters: InboxFilter[]) =>
+  threads.filter(thread => matchesInboxFilters(filters, { senders: thread.senders, subject: thread.subject, text: thread.snippet })).map(thread => thread.id).sort()
+
+const cases: Array<[InboxFilter[], string[]]> = [
+  [DEFAULT_INBOX_FILTERS, ['dmarc']],
+  [[{ kind: 'senderDomain', value: 'example.net' }], ['newsletter']],
+  [[{ kind: 'senderDomain', value: 'microsoft.com' }], ['dmarc']],
+  [[{ kind: 'subjectPrefix', value: 'weekly:' }], ['newsletter']],
+  [[{ kind: 'subjectContains', value: '50%' }], ['person']],
+  [[{ kind: 'subjectContains', value: '0%' }], ['person']],
+  [[{ kind: 'messagePrefix', value: 'unsubscribe' }], ['newsletter']],
+  [[{ kind: 'senderPrefix', value: 'dmarcreport' }, { kind: 'senderPrefix', value: 'ada' }], ['dmarc', 'dmarc-joined', 'person']],
+]
+for (const [filters, expected] of cases) {
+  assert.deepEqual(viaSql(filters), expected, `sql ${JSON.stringify(filters)}`)
+  assert.deepEqual(viaJs(filters), expected, `js ${JSON.stringify(filters)}`)
+}
+assert.equal(inboxFiltersSql([]), null)
+
+console.log('inbox-filters: ok')

package/lib/inbox-filters.ts

@@ -0,0 +1,111 @@
+export type InboxFilterKind = 'senderPrefix' | 'senderDomain' | 'subjectPrefix' | 'subjectContains' | 'messagePrefix'
+export type InboxFilter = { kind: InboxFilterKind; value: string }
+
+export const INBOX_FILTER_KINDS: Array<{ kind: InboxFilterKind; label: string; placeholder: string }> = [
+  { kind: 'senderPrefix', label: 'Sender starts with', placeholder: 'dmarcreport' },
+  { kind: 'senderDomain', label: 'Sender domain', placeholder: 'example.com' },
+  { kind: 'subjectPrefix', label: 'Subject starts with', placeholder: 'Report Domain:' },
+  { kind: 'subjectContains', label: 'Subject contains', placeholder: 'newsletter' },
+  { kind: 'messagePrefix', label: 'Message starts with', placeholder: 'This is an automated' },
+]
+
+export const DEFAULT_INBOX_FILTERS: InboxFilter[] = [{ kind: 'senderPrefix', value: 'dmarcreport' }]
+
+const MAX_FILTERS = 40
+const MAX_VALUE = 200
+const SENDER_KINDS = new Set<InboxFilterKind>(['senderPrefix', 'senderDomain'])
+
+/** A person who never touched the list gets the defaults; one who emptied it gets none. */
+export function normalizeInboxFilters(raw: unknown): InboxFilter[] {
+  if (!Array.isArray(raw)) return DEFAULT_INBOX_FILTERS
+  const seen = new Set<string>()
+  const filters: InboxFilter[] = []
+  for (const entry of raw) {
+    const kind = (entry as InboxFilter)?.kind
+    if (!INBOX_FILTER_KINDS.some(option => option.kind === kind)) continue
+    let value = String((entry as InboxFilter).value ?? '').replace(/\s+/g, ' ').trim().slice(0, MAX_VALUE)
+    if (SENDER_KINDS.has(kind)) value = value.toLowerCase().replace(/^@/, '')
+    const key = `${kind}:${value.toLowerCase()}`
+    if (!value || seen.has(key)) continue
+    seen.add(key)
+    filters.push({ kind, value })
+    if (filters.length === MAX_FILTERS) break
+  }
+  return filters
+}
+
+const likeEscape = (value: string) => value.replace(/[\\%_]/g, match => `\\${match}`)
+
+function senderAddress(raw: string): string {
+  const angled = raw.match(/<([^>]*)>?/)
+  return (angled ? angled[1] : raw).trim().toLowerCase()
+}
+
+const ADDRESS_SQL = "lower(trim(rtrim(CASE WHEN instr(value, '<') > 0 THEN substr(value, instr(value, '<') + 1) ELSE value END, '> ')))"
+const SNIPPET_SQL = "ltrim(coalesce(t.snippet, ''), ' ' || char(9, 10, 13))"
+
+/**
+ * The rules as one SQL condition over a mail_threads row aliased `t`. Sender rules hold only
+ * when every sender in the conversation matches, so a person replying into a filtered
+ * thread brings it back; subject and message rules read the latest message.
+ */
+export function inboxFiltersSql(filters: InboxFilter[]): { sql: string; args: string[] } | null {
+  if (!filters.length) return null
+  const senderRules: string[] = []
+  const senderArgs: string[] = []
+  const rules: string[] = []
+  const args: string[] = []
+  for (const filter of filters) {
+    const value = likeEscape(filter.value)
+    if (filter.kind === 'senderPrefix') {
+      senderRules.push(`${ADDRESS_SQL} LIKE ? ESCAPE '\\'`)
+      senderArgs.push(`${value.toLowerCase()}%`)
+    } else if (filter.kind === 'senderDomain') {
+      senderRules.push(`(${ADDRESS_SQL} LIKE ? ESCAPE '\\' OR ${ADDRESS_SQL} LIKE ? ESCAPE '\\')`)
+      senderArgs.push(`%@${value.toLowerCase()}`, `%.${value.toLowerCase()}`)
+    } else if (filter.kind === 'subjectPrefix') {
+      rules.push(`coalesce(t.subject, '') LIKE ? ESCAPE '\\'`)
+      args.push(`${value}%`)
+    } else if (filter.kind === 'subjectContains') {
+      rules.push(`coalesce(t.subject, '') LIKE ? ESCAPE '\\'`)
+      args.push(`%${value}%`)
+    } else {
+      rules.push(`${SNIPPET_SQL} LIKE ? ESCAPE '\\'`)
+      args.push(`${value}%`)
+    }
+  }
+  const parts = [...rules]
+  if (senderRules.length) {
+    parts.unshift(
+      `(json_array_length(coalesce(t.senders, '[]')) > 0 AND NOT EXISTS (SELECT 1 FROM json_each(coalesce(t.senders, '[]')) WHERE NOT (${senderRules.join(' OR ')})))`,
+    )
+  }
+  return { sql: `(${parts.join(' OR ')})`, args: [...senderArgs, ...args] }
+}
+
+/** The same rules for one message, for the paths that never reach SQL — a push, say. */
+export function matchesInboxFilters(
+  filters: InboxFilter[],
+  message: { senders: string[]; subject: string | null | undefined; text: string | null | undefined },
+): boolean {
+  const addresses = message.senders.filter(Boolean).map(senderAddress)
+  const subject = (message.subject ?? '').toLowerCase()
+  const text = (message.text ?? '').trimStart().toLowerCase()
+  const senderMatches = (address: string) =>
+    filters.some(filter => {
+      if (filter.kind === 'senderPrefix') return address.startsWith(filter.value.toLowerCase())
+      if (filter.kind === 'senderDomain') {
+        const domain = filter.value.toLowerCase()
+        return address.endsWith(`@${domain}`) || address.endsWith(`.${domain}`)
+      }
+      return false
+    })
+  if (filters.some(filter => SENDER_KINDS.has(filter.kind)) && addresses.length && addresses.every(senderMatches)) return true
+  return filters.some(filter => {
+    const value = filter.value.toLowerCase()
+    if (filter.kind === 'subjectPrefix') return subject.startsWith(value)
+    if (filter.kind === 'subjectContains') return subject.includes(value)
+    if (filter.kind === 'messagePrefix') return text.startsWith(value)
+    return false
+  })
+}

package/lib/mail-provider.ts

@@ -176,8 +176,10 @@ async function sendViaSes(payload: SendPayload): Promise<SendResult> {
  * here ever sees it. Skipped when the archive is already a recipient, so a message never
  * arrives twice, and skipped for anything a person wrote — their Sent folder already has it.
  */
+export const archiveAddress = () => (process.env.MAIL_ARCHIVE_BCC ?? '').trim().toLowerCase()
+
 function withArchive(payload: SendPayload): SendPayload {
-  const archive = (process.env.MAIL_ARCHIVE_BCC ?? '').trim().toLowerCase()
+  const archive = archiveAddress()
   if (!archive || payload.skipArchive) return payload
   const already = [...payload.to, ...(payload.cc ?? []), ...(payload.bcc ?? [])]
     .some(entry => entry.toLowerCase().includes(archive))

package/lib/mailbox.ts

@@ -13,6 +13,7 @@ import { hashPassword } from './password'
 import { duration, type ParsedQuery } from '@/app/mail/search'
 import { turso, tursoBatch, tursoQuery } from './turso'
 import { subjectKey, threadIdFor, THREAD_GAP_MS } from './threads'
+import { inboxFiltersSql, normalizeInboxFilters, type InboxFilter } from './inbox-filters'
 
 export type InboundAttachment = { filename: string; contentType?: string; size?: number; shareId?: string }
 
@@ -1183,13 +1184,23 @@ async function rethreadAfterChange(id: string, previousOwner?: string | null, pr
   }
 }
 
-export type ThreadFolder = 'inbox' | 'archive' | 'trash' | 'starred' | 'snoozed' | 'spam'
+export type ThreadFolder = 'inbox' | 'archive' | 'trash' | 'starred' | 'snoozed' | 'spam' | 'filtered'
 
 /** The newest conversations in a folder: one row each, already summarised. */
 export type ThreadPage = { rows: ThreadRow[]; nextCursor: string | null }
 
-export async function listThreads(ownerRaw: string | null, folder: ThreadFolder, limit: number, cursorRaw?: string | null): Promise<ThreadPage> {
-  await ensureMailSchema()
+export async function listThreads(
+  ownerRaw: string | null,
+  folder: ThreadFolder,
+  limit: number,
+  cursorRaw?: string | null,
+  filters: InboxFilter[] = [],
+): Promise<ThreadPage> {
+  await ensureMailSchema()
+  const filterSql = folder === 'inbox' || folder === 'filtered' ? inboxFiltersSql(filters) : null
+  if (folder === 'filtered' && !filterSql) return { rows: [], nextCursor: null }
+  const filterClause = filterSql ? (folder === 'filtered' ? filterSql.sql : `NOT ${filterSql.sql}`) : ''
+  const filterArgs = filterSql?.args ?? []
   const owner = ownerRaw === null ? null : ownerRaw.toLowerCase()
   const nowIso = new Date().toISOString()
   const predicate =
@@ -1201,7 +1212,7 @@ export async function listThreads(ownerRaw: string | null, folder: ThreadFolder,
     : 'inbox_count > 0 AND (snoozed_until IS NULL OR snoozed_until <= ?)'
   // Both snooze predicates carry one bound timestamp; the others carry none, and the
   // cursor's arguments have to follow whatever the predicate used.
-  const folderArgs = folder === 'snoozed' || folder === 'inbox' ? [nowIso] : []
+  const folderArgs = folder === 'snoozed' || folder === 'inbox' || folder === 'filtered' ? [nowIso] : []
   const cursor = decodeCursor(cursorRaw)
   const cursorClause = cursor ? '(latest_at < ? OR (latest_at = ? AND thread_id < ?))' : ''
   const cursorArgs = cursor ? [cursor.receivedAt, cursor.receivedAt, cursor.id] : []
@@ -1209,25 +1220,28 @@ export async function listThreads(ownerRaw: string | null, folder: ThreadFolder,
   // conversation back together. SQLite fills a bare column from whichever row matched the
   // MAX in the same select, which is how subject, snippet and senders come from the latest
   // message rather than an arbitrary one.
+  const outer = [filterClause, cursorClause].filter(Boolean).join(' AND ')
   const rows = owner === null
     ? await tagged(db(), `
-        SELECT thread_id, subject, MIN(first_at) AS first_at, MAX(latest_at) AS latest_at, latest_id,
-          SUM(count) AS count, SUM(unread_count) AS unread_count, SUM(starred_count) AS starred_count,
-          SUM(inbox_count) AS inbox_count, SUM(archived_count) AS archived_count,
-          SUM(trashed_count) AS trashed_count, SUM(spam_count) AS spam_count, SUM(attach_count) AS attach_count,
-          senders, snippet, labels, snoozed_until, addressed, risk
-        FROM mail_threads
-        GROUP BY thread_id
-        HAVING ${predicate}${cursorClause ? ` AND ${cursorClause}` : ''}
+        SELECT * FROM (
+          SELECT thread_id, subject, MIN(first_at) AS first_at, MAX(latest_at) AS latest_at, latest_id,
+            SUM(count) AS count, SUM(unread_count) AS unread_count, SUM(starred_count) AS starred_count,
+            SUM(inbox_count) AS inbox_count, SUM(archived_count) AS archived_count,
+            SUM(trashed_count) AS trashed_count, SUM(spam_count) AS spam_count, SUM(attach_count) AS attach_count,
+            senders, snippet, labels, snoozed_until, addressed, risk
+          FROM mail_threads
+          GROUP BY thread_id
+          HAVING ${predicate}
+        ) t${outer ? ` WHERE ${outer}` : ''}
         ORDER BY latest_at DESC, thread_id DESC LIMIT ?`,
-        [...folderArgs, ...cursorArgs, limit])
+        [...folderArgs, ...filterArgs, ...cursorArgs, limit])
     : await tagged(db(), `
         SELECT thread_id, subject, first_at, latest_at, latest_id, count, unread_count, starred_count,
           inbox_count, archived_count, trashed_count, spam_count, attach_count, senders, snippet, labels, snoozed_until, addressed, risk
-        FROM mail_threads WHERE owner = ? AND ${predicate}
-          ${cursorClause ? `AND ${cursorClause}` : ''}
+        FROM mail_threads t WHERE owner = ? AND ${predicate}
+          ${outer ? `AND ${outer}` : ''}
         ORDER BY latest_at DESC, thread_id DESC LIMIT ?`,
-        [owner, ...folderArgs, ...cursorArgs, limit])
+        [owner, ...folderArgs, ...filterArgs, ...cursorArgs, limit])
   const last = rows[rows.length - 1]
   const nextCursor = rows.length === limit && last ? encodeCursor(String(last.latest_at), String(last.thread_id)) : null
   const mapped = rows.map(row => ({
@@ -1254,6 +1268,27 @@ export async function listThreads(ownerRaw: string | null, folder: ThreadFolder,
   return { rows: mapped, nextCursor }
 }
 
+/** Inbox conversations the rules hold out, and how many of those have unread mail. */
+export async function countFilteredThreads(ownerRaw: string | null, filters: InboxFilter[]): Promise<{ total: number; unread: number }> {
+  const filterSql = inboxFiltersSql(filters)
+  if (!filterSql) return { total: 0, unread: 0 }
+  await ensureMailSchema()
+  const nowIso = new Date().toISOString()
+  const inbox = 'inbox_count > 0 AND (snoozed_until IS NULL OR snoozed_until <= ?)'
+  const rows = ownerRaw === null
+    ? await tagged(db(), `
+        SELECT COUNT(*) AS total, SUM(CASE WHEN unread_count > 0 THEN 1 ELSE 0 END) AS unread FROM (
+          SELECT thread_id, SUM(unread_count) AS unread_count, SUM(inbox_count) AS inbox_count, snoozed_until, senders, subject, snippet, MAX(latest_at)
+          FROM mail_threads GROUP BY thread_id HAVING ${inbox}
+        ) t WHERE ${filterSql.sql}`,
+        [nowIso, ...filterSql.args])
+    : await tagged(db(), `
+        SELECT COUNT(*) AS total, SUM(CASE WHEN unread_count > 0 THEN 1 ELSE 0 END) AS unread
+        FROM mail_threads t WHERE owner = ? AND ${inbox} AND ${filterSql.sql}`,
+        [ownerRaw.toLowerCase(), nowIso, ...filterSql.args])
+  return { total: Number(rows[0]?.total ?? 0), unread: Number(rows[0]?.unread ?? 0) }
+}
+
 /**
  * Backfill, phase one: give every message a thread id, oldest first so the thirty-day
  * rule holds for history. Summaries are left for the second phase, so each thread is
@@ -1786,7 +1821,8 @@ export async function inboundExists(ids: string[]): Promise<Set<string>> {
   for (let i = 0; i < ids.length; i += 200) {
     const chunk = ids.slice(i, i + 200)
     if (!chunk.length) break
-    const rows = await tagged(db(), `SELECT id FROM mail_inbox WHERE id IN (${chunk.map(() => '?').join(',')})`, chunk)
+    const marks = chunk.map(() => '?').join(',')
+    const rows = await tagged(db(), `SELECT id FROM mail_inbox WHERE id IN (${marks}) UNION SELECT id FROM mail_sent WHERE id IN (${marks})`, [...chunk, ...chunk])
     for (const row of rows) found.add(String(row.id))
   }
   return found
@@ -1905,6 +1941,10 @@ export async function getSettings(owner: string): Promise<Record<string, unknown
   return parseJson<Record<string, unknown>>(rows[0]?.data, {})
 }
 
+export async function inboxFiltersFor(login: string): Promise<InboxFilter[]> {
+  return normalizeInboxFilters((await getSettings(login)).inboxFilters)
+}
+
 export async function setSettings(owner: string, data: Record<string, unknown>): Promise<void> {
   await ensureMailSchema()
   const sql = db()