@meith/mail 0.16.0

package/LICENSE.md

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@meith/mail",
+  "version": "0.16.0",
+  "license": "LGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meith-dev/meith.git",
+    "directory": "packages/mail"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.type-test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@meith/i18n": "0.16.0",
+    "@meith/markdown": "0.16.0",
+    "@meith/theme-kit": "0.16.0",
+    "@meith/settings": "0.16.0"
+  }
+}

package/src/brand.ts

@@ -0,0 +1,82 @@
+import { isLogoKey, type LogoScheme, logoFormat, logoPath } from '@meith/settings'
+
+import { FALLBACK_PALETTE, type MailPalette, mailPalette, type ThemeTokenSet } from './palette'
+
+export interface MailLogo {
+  readonly src: string
+  readonly darkSrc: string | null
+  readonly alt: string
+}
+
+export interface MailBrand {
+  readonly boardName: string
+  readonly fromName?: string
+  readonly boardUrl: string
+  readonly logo: MailLogo | null
+  readonly palette: MailPalette
+}
+
+const UNRENDERABLE_IN_MAIL: readonly string[] = ['svg']
+
+export function normaliseBoardUrl(value: string): string {
+  const trimmed = value.trim().replace(/\/+$/, '')
+  return /^https?:\/\/[^\s/]+$/i.test(trimmed) ? trimmed : ''
+}
+
+export function absoluteUrl(boardUrl: string, path: string | null): string | null {
+  if (boardUrl === '' || path === null || !path.startsWith('/')) return null
+  return `${boardUrl}${path}`
+}
+
+function renderable(key: string): boolean {
+  const format = logoFormat(key)
+  return format !== null && !UNRENDERABLE_IN_MAIL.includes(format)
+}
+
+function usableKey(value: string): string | null {
+  return isLogoKey(value) && renderable(value) ? value : null
+}
+
+export function mailLogo(input: {
+  readonly boardUrl: string
+  readonly lightKey: string
+  readonly darkKey: string
+  readonly alt: string
+}): MailLogo | null {
+  const boardUrl = normaliseBoardUrl(input.boardUrl)
+  if (boardUrl === '' || input.alt.trim() === '') return null
+
+  const light = usableKey(input.lightKey)
+  const dark = usableKey(input.darkKey)
+  if (light === null && dark === null) return null
+
+  const source = (scheme: LogoScheme, key: string): string => `${boardUrl}${logoPath(scheme, key)}`
+
+  const lightSrc = light === null ? source('dark', dark!) : source('light', light)
+  const darkSrc = dark === null ? source('light', light!) : source('dark', dark)
+
+  return { src: lightSrc, darkSrc: darkSrc === lightSrc ? null : darkSrc, alt: input.alt.trim() }
+}
+
+export function buildMailBrand(input: {
+  readonly boardName: string
+  readonly fromName?: string
+  readonly boardUrl: string
+  readonly tokens?: ThemeTokenSet | null
+  readonly logo?: {
+    readonly lightKey: string
+    readonly darkKey: string
+    readonly alt: string
+  }
+}): MailBrand {
+  const boardUrl = normaliseBoardUrl(input.boardUrl)
+  const fromName = (input.fromName ?? '').trim()
+
+  return {
+    boardName: input.boardName.trim(),
+    ...(fromName === '' ? {} : { fromName }),
+    boardUrl,
+    logo: input.logo === undefined ? null : mailLogo({ boardUrl, ...input.logo }),
+    palette: input.tokens === undefined ? FALLBACK_PALETTE : mailPalette(input.tokens),
+  }
+}

package/src/document.ts

@@ -0,0 +1,290 @@
+import type { Translator } from '@meith/i18n'
+import { escapeAttribute, escapeHtml } from '@meith/markdown'
+
+import type { MailBrand } from './brand'
+import type { MailScheme } from './palette'
+
+export interface MailLink {
+  readonly label: string
+  readonly href: string
+}
+
+export interface MailFooterLine {
+  readonly text: string
+  readonly href?: string | null
+}
+
+export interface MailBody {
+  readonly title: string
+  readonly greeting?: string | null
+  readonly paragraphs: readonly string[]
+  readonly action?: MailLink | null
+  readonly note?: string | null
+  readonly footer?: readonly MailFooterLine[]
+}
+
+export interface RenderedMail {
+  readonly subject: string
+  readonly text: string
+  readonly html: string
+}
+
+const CARD_WIDTH = 600
+
+const LOGO_HEIGHT = 36
+
+export function safeHref(value: string | null | undefined): string | null {
+  if (typeof value !== 'string') return null
+
+  const trimmed = value.trim()
+  if (!/^https?:\/\/[^\s<>\x22\x27]+$/i.test(trimmed)) return null
+
+  return trimmed
+}
+
+function paragraphs(body: MailBody): readonly string[] {
+  return body.paragraphs.filter((paragraph) => paragraph.trim() !== '')
+}
+
+function footerLines(body: MailBody): readonly MailFooterLine[] {
+  return (body.footer ?? []).filter((line) => line.text.trim() !== '')
+}
+
+function preheader(body: MailBody): string {
+  return (paragraphs(body)[0] ?? body.title).replace(/\s+/g, ' ').slice(0, 140)
+}
+
+export function renderMailText(input: {
+  readonly brand: MailBrand
+  readonly body: MailBody
+  readonly boardName: string
+}): string {
+  const { body } = input
+  const lines: string[] = []
+
+  if (typeof body.greeting === 'string' && body.greeting.trim() !== '') {
+    lines.push(body.greeting, '')
+  }
+  lines.push(body.title)
+
+  for (const paragraph of paragraphs(body)) lines.push('', paragraph)
+
+  const action = body.action === null || body.action === undefined ? null : body.action
+  const actionHref = action === null ? null : safeHref(action.href)
+  if (action !== null && actionHref !== null) lines.push('', `${action.label}: ${actionHref}`)
+
+  if (typeof body.note === 'string' && body.note.trim() !== '') lines.push('', body.note)
+
+  const footer = footerLines(body)
+  if (footer.length > 0) {
+    lines.push('', '--')
+    for (const line of footer) {
+      const href = safeHref(line.href)
+      lines.push(href === null ? line.text : `${line.text}: ${href}`)
+    }
+  }
+
+  return lines.join('\n')
+}
+
+function styleSheet(dark: MailScheme): string {
+  return [
+    `.m-page{margin:0;padding:0;width:100%!important}`,
+    `img{border:0;outline:none;text-decoration:none;-ms-interpolation-mode:bicubic}`,
+    `a{text-decoration:none}`,
+    `.m-logo-dark{display:none}`,
+    `@media (max-width:620px){`,
+    `.m-pad{padding-left:20px!important;padding-right:20px!important}`,
+    `}`,
+    `@media (prefers-color-scheme:dark){`,
+    `.m-page,.m-page-cell{background-color:${dark.page}!important}`,
+    `.m-card{background-color:${dark.card}!important;border-color:${dark.border}!important}`,
+    `.m-band{background-color:${dark.band}!important;border-color:${dark.border}!important}`,
+    `.m-title,.m-text,.m-wordmark{color:${dark.text}!important}`,
+    `.m-muted,.m-foot,.m-foot a{color:${dark.muted}!important}`,
+    `.m-rule{border-color:${dark.border}!important}`,
+    `.m-action{background-color:${dark.primary}!important}`,
+    `.m-action a,.m-action-label{color:${dark.primaryText}!important}`,
+    `.m-link{color:${dark.text}!important;text-decoration-color:${dark.primary}!important}`,
+    `.m-accent{background-color:${dark.primary}!important}`,
+    `.m-logo-light{display:none!important}`,
+    `.m-logo-dark{display:inline-block!important}`,
+    `}`,
+  ].join('')
+}
+
+function masthead(brand: MailBrand, boardName: string, light: MailScheme, font: string): string {
+  const home = safeHref(brand.boardUrl)
+  const wordmark =
+    `<span class="m-wordmark" style="font-family:${font};font-size:19px;` +
+    `font-weight:700;letter-spacing:-0.01em;color:${light.text}">${escapeHtml(boardName)}</span>`
+
+  const inner =
+    brand.logo === null
+      ? wordmark
+      : logoImage(brand.logo.src, brand.logo.alt, `m-logo-light`) +
+        (brand.logo.darkSrc === null
+          ? ''
+          : logoImage(brand.logo.darkSrc, brand.logo.alt, `m-logo-dark`))
+
+  return home === null
+    ? inner
+    : `<a href="${escapeAttribute(home)}" style="text-decoration:none">${inner}</a>`
+}
+
+function logoImage(src: string, alt: string, className: string): string {
+  const href = safeHref(src)
+  if (href === null) return ''
+
+  return (
+    `<img src="${escapeAttribute(href)}" alt="${escapeAttribute(alt)}" height="${LOGO_HEIGHT}" ` +
+    `class="${className}" style="display:inline-block;height:${LOGO_HEIGHT}px;` +
+    `max-height:${LOGO_HEIGHT}px;width:auto;border:0">`
+  )
+}
+
+function actionButton(
+  action: MailLink,
+  href: string,
+  light: MailScheme,
+  font: string,
+  radius: number,
+): string {
+  return (
+    `<table role="presentation" border="0" cellpadding="0" cellspacing="0">` +
+    `<tr><td class="m-action" align="center" ` +
+    `style="background-color:${light.primary};border-radius:${radius}px">` +
+    `<a href="${escapeAttribute(href)}" class="m-action-label" ` +
+    `style="display:inline-block;padding:13px 26px;font-family:${font};font-size:15px;` +
+    `font-weight:600;line-height:1;color:${light.primaryText};text-decoration:none">` +
+    `${escapeHtml(action.label)}</a></td></tr></table>`
+  )
+}
+
+export function renderMailHtml(input: {
+  readonly brand: MailBrand
+  readonly body: MailBody
+  readonly boardName: string
+  readonly subject: string
+  readonly t: Translator
+}): string {
+  const { brand, body, boardName, t } = input
+  const { light, bodyFont, headingFont, radius } = {
+    light: brand.palette.light,
+    bodyFont: brand.palette.bodyFont,
+    headingFont: brand.palette.headingFont,
+    radius: brand.palette.radius,
+  }
+
+  const text = `font-family:${bodyFont};font-size:15px;line-height:1.6;color:${light.text}`
+  const parts: string[] = []
+
+  parts.push(
+    `<!doctype html><html lang="${escapeAttribute(t.locale)}">`,
+    `<head><meta charset="utf-8">`,
+    `<meta name="viewport" content="width=device-width,initial-scale=1">`,
+    `<meta name="color-scheme" content="light dark">`,
+    `<meta name="supported-color-schemes" content="light dark">`,
+    `<title>${escapeHtml(input.subject)}</title>`,
+    `<style>${styleSheet(brand.palette.dark)}</style></head>`,
+    `<body class="m-page" style="margin:0;padding:0;background-color:${light.page};${text}">`,
+    `<div style="display:none;max-height:0;overflow:hidden;opacity:0">`,
+    `${escapeHtml(preheader(body))}</div>`,
+    `<table role="presentation" width="100%" border="0" cellpadding="0" cellspacing="0" `,
+    `style="background-color:${light.page}"><tr>`,
+    `<td class="m-page-cell" align="center" style="padding:32px 12px;background-color:${light.page}">`,
+    `<table role="presentation" class="m-card" width="${CARD_WIDTH}" border="0" cellpadding="0" `,
+    `cellspacing="0" style="width:100%;max-width:${CARD_WIDTH}px;background-color:${light.card};`,
+    `border:1px solid ${light.border};border-radius:${radius + 4}px;overflow:hidden">`,
+    `<tr><td class="m-accent" style="height:4px;line-height:4px;font-size:0;`,
+    `background-color:${light.primary}">&nbsp;</td></tr>`,
+    `<tr><td class="m-band m-pad" align="left" style="padding:20px 32px;`,
+    `background-color:${light.band};border-bottom:1px solid ${light.border}">`,
+    `${masthead(brand, boardName, light, headingFont)}</td></tr>`,
+    `<tr><td class="m-pad" style="padding:32px">`,
+    `<h1 class="m-title" style="margin:0 0 20px;font-family:${headingFont};font-size:21px;`,
+    `line-height:1.3;font-weight:700;color:${light.text}">${escapeHtml(body.title)}</h1>`,
+  )
+
+  if (typeof body.greeting === 'string' && body.greeting.trim() !== '') {
+    parts.push(`<p class="m-text" style="margin:0 0 16px;${text}">`)
+    parts.push(`${escapeHtml(body.greeting)}</p>`)
+  }
+
+  for (const paragraph of paragraphs(body)) {
+    parts.push(
+      `<p class="m-text" style="margin:0 0 16px;${text}">`,
+      `${escapeHtml(paragraph).replace(/\n/g, `<br>`)}</p>`,
+    )
+  }
+
+  const action = body.action ?? null
+  const actionHref = action === null ? null : safeHref(action.href)
+
+  if (action !== null && actionHref !== null) {
+    parts.push(
+      `<div style="margin:24px 0 20px">`,
+      actionButton(action, actionHref, light, bodyFont, radius),
+      `</div>`,
+      `<p class="m-muted" style="margin:0;font-size:13px;line-height:1.6;color:${light.muted};`,
+      `word-break:break-all">${escapeHtml(t.t('mail.action.fallback'))}<br>`,
+      `<a href="${escapeAttribute(actionHref)}" class="m-link" `,
+      `style="color:${light.text};text-decoration:underline;`,
+      `text-decoration-color:${light.primary}">${escapeHtml(actionHref)}</a></p>`,
+    )
+  }
+
+  if (typeof body.note === 'string' && body.note.trim() !== '') {
+    parts.push(
+      `<p class="m-muted" style="margin:20px 0 0;font-size:13px;line-height:1.6;`,
+      `color:${light.muted}">${escapeHtml(body.note)}</p>`,
+    )
+  }
+
+  parts.push(`</td></tr></table>`)
+
+  const footer = footerLines(body)
+  if (footer.length > 0) {
+    parts.push(
+      `<table role="presentation" width="${CARD_WIDTH}" border="0" cellpadding="0" `,
+      `cellspacing="0" style="width:100%;max-width:${CARD_WIDTH}px"><tr>`,
+      `<td class="m-foot m-pad" align="center" style="padding:20px 32px 0;font-family:${bodyFont};`,
+      `font-size:12px;line-height:1.7;color:${light.muted}">`,
+    )
+
+    for (const line of footer) {
+      const href = safeHref(line.href)
+      parts.push(
+        `<p style="margin:0">`,
+        href === null
+          ? escapeHtml(line.text)
+          : `<a href="${escapeAttribute(href)}" style="color:${light.muted};` +
+              `text-decoration:underline">${escapeHtml(line.text)}</a>`,
+        `</p>`,
+      )
+    }
+
+    parts.push(`</td></tr></table>`)
+  }
+
+  parts.push(`</td></tr></table></body></html>`)
+
+  return parts.join('')
+}
+
+export function renderMail(input: {
+  readonly brand: MailBrand
+  readonly body: MailBody
+  readonly t: Translator
+}): RenderedMail {
+  const boardName =
+    input.brand.boardName === '' ? input.t.t('mail.boardFallback') : input.brand.boardName
+
+  const subject = `[${boardName}] ${input.body.title}`
+
+  return {
+    subject,
+    text: renderMailText({ brand: input.brand, body: input.body, boardName }),
+    html: renderMailHtml({ ...input, boardName, subject }),
+  }
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+export {
+  absoluteUrl,
+  buildMailBrand,
+  type MailBrand,
+  type MailLogo,
+  mailLogo,
+  normaliseBoardUrl,
+} from './brand'
+export {
+  type MailBody,
+  type MailFooterLine,
+  type MailLink,
+  type RenderedMail,
+  renderMail,
+  renderMailHtml,
+  renderMailText,
+  safeHref,
+} from './document'
+export {
+  FALLBACK_PALETTE,
+  type MailPalette,
+  type MailScheme,
+  mailPalette,
+  mergeTokenOverrides,
+  type ThemeTokenSet,
+  type TokenRecord,
+} from './palette'

package/src/palette.ts

@@ -0,0 +1,166 @@
+import { colourToHex } from '@meith/theme-kit'
+
+export type TokenRecord = Readonly<Record<string, string>>
+
+export interface ThemeTokenSet {
+  readonly light: TokenRecord
+  readonly dark: TokenRecord
+}
+
+export interface MailScheme {
+  readonly page: string
+  readonly card: string
+  readonly band: string
+  readonly border: string
+  readonly text: string
+  readonly muted: string
+  readonly primary: string
+  readonly primaryText: string
+}
+
+export interface MailPalette {
+  readonly light: MailScheme
+  readonly dark: MailScheme
+  readonly bodyFont: string
+  readonly headingFont: string
+  readonly radius: number
+}
+
+const FALLBACK: { readonly light: MailScheme; readonly dark: MailScheme } = {
+  light: {
+    page: '#f4f4f4',
+    card: '#ffffff',
+    band: '#ebebeb',
+    border: '#dfdfdf',
+    text: '#171717',
+    muted: '#616161',
+    primary: '#047857',
+    primaryText: '#fafafa',
+  },
+  dark: {
+    page: '#0b0b0b',
+    card: '#151515',
+    band: '#0f0f0f',
+    border: '#303030',
+    text: '#f4f4f4',
+    muted: '#9f9f9f',
+    primary: '#35d399',
+    primaryText: '#04160f',
+  },
+}
+
+const SANS_FALLBACK = "ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Arial, sans-serif"
+
+const MAX_RADIUS = 20
+
+const ROOT_FONT_PX = 16
+
+const VAR_REFERENCE = /^var\(\s*--([\w-]+)\s*\)$/
+
+function dereference(tokens: TokenRecord, name: string, depth = 0): string {
+  const value = tokens[name]
+  if (value === undefined || depth > 4) return ''
+
+  const reference = VAR_REFERENCE.exec(value.trim())
+  return reference === null ? value.trim() : dereference(tokens, reference[1]!, depth + 1)
+}
+
+function colour(tokens: TokenRecord, names: readonly string[], fallback: string): string {
+  for (const name of names) {
+    const hex = colourToHex(dereference(tokens, name))
+    if (hex !== null) return hex
+  }
+  return fallback
+}
+
+function fontStack(tokens: TokenRecord, name: string): string {
+  const declared = dereference(tokens, name)
+    .split(',')
+    .map((segment) => segment.trim())
+    .map((segment) => segment.replace(/\x22/g, '\x27'))
+    .filter((segment) => segment !== '' && !segment.includes('var(') && !/[;{}<>]/.test(segment))
+
+  const fallbacks = SANS_FALLBACK.split(',').map((segment) => segment.trim())
+  const seen = new Set<string>()
+
+  return [...declared, ...fallbacks]
+    .filter((segment) => {
+      const key = segment.toLowerCase()
+      if (seen.has(key)) return false
+      seen.add(key)
+      return true
+    })
+    .join(', ')
+}
+
+function radiusPx(tokens: TokenRecord): number {
+  const declared = dereference(tokens, 'radius')
+  const match = /^([\d.]+)(rem|px)$/.exec(declared)
+  if (match === null) return 8
+
+  const value = Number(match[1]) * (match[2] === 'rem' ? ROOT_FONT_PX : 1)
+  return Number.isFinite(value) ? Math.round(Math.min(MAX_RADIUS, Math.max(0, value))) : 8
+}
+
+function scheme(tokens: TokenRecord, fallback: MailScheme): MailScheme {
+  return {
+    page: colour(tokens, ['background'], fallback.page),
+    card: colour(tokens, ['card', 'background'], fallback.card),
+    band: colour(tokens, ['surface', 'muted', 'card'], fallback.band),
+    border: colour(tokens, ['border'], fallback.border),
+    text: colour(tokens, ['card-foreground', 'foreground'], fallback.text),
+    muted: colour(tokens, ['muted-foreground', 'foreground'], fallback.muted),
+    primary: colour(tokens, ['primary'], fallback.primary),
+    primaryText: colour(tokens, ['primary-foreground'], fallback.primaryText),
+  }
+}
+
+export function mergeTokenOverrides(baseline: ThemeTokenSet, overrides: unknown): ThemeTokenSet {
+  if (overrides === null || typeof overrides !== 'object' || Array.isArray(overrides)) {
+    return baseline
+  }
+
+  const record = overrides as Record<string, unknown>
+  const shaped =
+    Object.keys(record).length > 0 &&
+    Object.keys(record).every((key) => key === 'light' || key === 'dark')
+
+  const flat = shaped ? {} : strings(record)
+
+  return {
+    light: { ...baseline.light, ...flat, ...(shaped ? strings(record.light) : {}) },
+    dark: { ...baseline.dark, ...flat, ...(shaped ? strings(record.dark) : {}) },
+  }
+}
+
+function strings(value: unknown): TokenRecord {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return {}
+
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>).filter(
+      (entry): entry is [string, string] => typeof entry[1] === 'string' && entry[1].trim() !== '',
+    ),
+  )
+}
+
+export function mailPalette(tokens: ThemeTokenSet | null): MailPalette {
+  if (tokens === null) {
+    return {
+      light: FALLBACK.light,
+      dark: FALLBACK.dark,
+      bodyFont: SANS_FALLBACK,
+      headingFont: SANS_FALLBACK,
+      radius: 8,
+    }
+  }
+
+  return {
+    light: scheme(tokens.light, FALLBACK.light),
+    dark: scheme(tokens.dark, FALLBACK.dark),
+    bodyFont: fontStack(tokens.light, 'font-sans-stack'),
+    headingFont: fontStack(tokens.light, 'font-heading-stack'),
+    radius: radiusPx(tokens.light),
+  }
+}
+
+export const FALLBACK_PALETTE: MailPalette = mailPalette(null)