@ultimat3/mail 1.0.0

package/src/index.js

@@ -0,0 +1,13 @@
+// Single responsibility: the public API of @ultimat3/mail. Explicit named exports only —
+// other packages call `defineMail`, `send` and the driver seam, and nothing else.
+export { blocks } from './blocks';
+export { MAIL_CATALOG, MAIL_CATALOG_SOURCE, registerMailCatalog } from './catalog';
+export { createLogDriver, createMemoryDriver, createResendDriver, createSmtpDriver, mailDriver, messageHeaders, resetMailDriver, setMailDriver, tryMailDriver, } from './driver';
+export { driverUnavailable, layoutUnknown, localeMissing, MAIL_ERROR_CODES, MAIL_ERROR_TITLES, MailError, mailDuplicate, templateUnknown, textMissing, transportNotImplemented, } from './errors';
+export { escapeHtml, safeUrl } from './html';
+export { mailIdempotencyKey, mailMessageSchema, sendMailJob } from './job';
+export { BASE_LAYOUT, baseLayout, DARK_RULES, darkModeCss, layoutFor, MAIL_FONT_STACK, MAIL_TOKENS, MAIL_WIDTH_PX, registeredLayouts, registerLayout, token, } from './layout';
+export { defineMail, mailFor, registeredMailIds, registeredMails, renderMessage, resetMails, send, sendById, } from './mail';
+export { FOOTER_KEYS, renderMail, textOf, UNSUBSCRIBE_KEY } from './render';
+export { FRAMEWORK_MAILS, inviteInput, inviteMail, MFA_METHODS, mfaEnrolledInput, mfaEnrolledMail, resetPasswordInput, resetPasswordMail, securityAlertInput, securityAlertMail, verifyEmailInput, verifyEmailMail, welcomeInput, welcomeMail, } from './templates';
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,kFAAkF;AAGlF,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAUnF,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,eAAe,EACf,aAAa,EACb,aAAa,GACd,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,aAAa,EACb,eAAe,EACf,WAAW,EACX,uBAAuB,GACxB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAE7C,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAS3E,OAAO,EACL,WAAW,EACX,UAAU,EACV,UAAU,EACV,WAAW,EACX,SAAS,EACT,eAAe,EACf,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,KAAK,GACN,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,UAAU,EACV,OAAO,EACP,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,UAAU,EACV,IAAI,EACJ,QAAQ,GACT,MAAM,QAAQ,CAAC;AAEhB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAE5E,OAAO,EACL,eAAe,EAEf,WAAW,EACX,UAAU,EACV,WAAW,EAEX,gBAAgB,EAChB,eAAe,EAEf,kBAAkB,EAClB,iBAAiB,EAEjB,kBAAkB,EAClB,iBAAiB,EAEjB,gBAAgB,EAChB,eAAe,EAEf,YAAY,EACZ,WAAW,GACZ,MAAM,aAAa,CAAC"}

package/src/index.ts

@@ -0,0 +1,110 @@
+// Single responsibility: the public API of @ultimat3/mail. Explicit named exports only —
+// other packages call `defineMail`, `send` and the driver seam, and nothing else.
+
+/** Re-exported so a `defineMail` file needs one import, not two. Same object as schema's. */
+export type { Infer } from '@ultimat3/schema';
+export { t } from '@ultimat3/schema';
+export type { CalloutTone, MailBlock, MailTemplate, TemplateArgs } from './blocks';
+export { blocks } from './blocks';
+
+export { MAIL_CATALOG, MAIL_CATALOG_SOURCE, registerMailCatalog } from './catalog';
+export type {
+  MailDriver,
+  MailMessage,
+  MemoryMailDriver,
+  SendResult,
+  SentMail,
+} from './driver';
+export {
+  createLogDriver,
+  createMemoryDriver,
+  envelopeRecipients,
+  isMemoryDriver,
+  mailDriver,
+  messageHeaders,
+  resetMailDriver,
+  setMailDriver,
+  tryMailDriver,
+} from './driver';
+export type { MailEnvironment, MailSelection } from './driver-env';
+export { MAIL_ENV_KEYS, selectMailDriver } from './driver-env';
+export type { MailFetch, ResendDriverOptions } from './driver-resend';
+export { createResendDriver, RESEND_BASE_URL } from './driver-resend';
+export type { SmtpDriverOptions } from './driver-smtp';
+export { createSmtpDriver } from './driver-smtp';
+export type { MailErrorCode, MailErrorInit, SendFailure, SendStage } from './errors';
+export {
+  driverUnavailable,
+  layoutUnknown,
+  localeMissing,
+  MAIL_ERROR_CODES,
+  MAIL_ERROR_TITLES,
+  MailError,
+  mailDuplicate,
+  sendFailed,
+  templateUnknown,
+  textMissing,
+} from './errors';
+
+export { escapeHtml, safeUrl } from './html';
+
+export { mailIdempotencyKey } from './idempotency';
+export { mailMessageSchema, sendMailJob } from './job';
+export type {
+  ColorScheme,
+  DarkRule,
+  LayoutInput,
+  MailLayout,
+  MailToken,
+  UnsubscribeSlot,
+} from './layout';
+export {
+  BASE_LAYOUT,
+  baseLayout,
+  DARK_RULES,
+  darkModeCss,
+  layoutFor,
+  MAIL_FONT_STACK,
+  MAIL_TOKENS,
+  MAIL_WIDTH_PX,
+  registeredLayouts,
+  registerLayout,
+  token,
+} from './layout';
+export type { AnyMailDefinition, MailDefinition, MailInit, SendOptions } from './mail';
+export {
+  defineMail,
+  mailFor,
+  registeredMailIds,
+  registeredMails,
+  renderMessage,
+  resetMails,
+  send,
+  sendById,
+} from './mail';
+export type { RenderableMail, RenderedMail, RenderOptions } from './render';
+export { FOOTER_KEYS, renderMail, textOf, UNSUBSCRIBE_KEY } from './render';
+export type { SmtpConnector, SmtpStream } from './smtp-client';
+
+export {
+  FRAMEWORK_MAILS,
+  type InviteInput,
+  inviteInput,
+  inviteMail,
+  MFA_METHODS,
+  type MfaEnrolledInput,
+  mfaEnrolledInput,
+  mfaEnrolledMail,
+  type ResetPasswordInput,
+  resetPasswordInput,
+  resetPasswordMail,
+  type SecurityAlertInput,
+  securityAlertInput,
+  securityAlertMail,
+  type VerifyEmailInput,
+  verifyEmailInput,
+  verifyEmailMail,
+  type WelcomeInput,
+  welcomeInput,
+  welcomeMail,
+} from './templates';

package/src/job.d.ts

@@ -0,0 +1,17 @@
+import { type JobHandle } from '@ultimat3/jobs';
+import { type StandardSchemaV1 } from '@ultimat3/schema';
+import { type MailMessage } from './driver';
+/** The queue payload is the already-rendered envelope: rendering happens once, at send time. */
+export declare const mailMessageSchema: StandardSchemaV1<unknown, MailMessage>;
+/**
+ * `(mailId, recipients, hash(rendered payload))`, or the caller's key when supplied.
+ * Content-derived on purpose: a retry of the same request produces the same key, while an
+ * intentional resend with different content produces a different one.
+ */
+export declare function mailIdempotencyKey(message: MailMessage): string;
+/**
+ * Five attempts with exponential backoff: transient 4xx/greylisting clears in minutes, and a
+ * hard bounce still lands in the dead-letter queue where `x jobs dead --json` can show it.
+ */
+export declare const sendMailJob: JobHandle<MailMessage>;
+//# sourceMappingURL=job.d.ts.map

package/src/job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.d.ts","sourceRoot":"","sources":["job.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,SAAS,EAAO,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,KAAK,gBAAgB,EAAK,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,KAAK,WAAW,EAA+B,MAAM,UAAU,CAAC;AAEzE,gGAAgG;AAChG,eAAO,MAAM,iBAAiB,EAAE,gBAAgB,CAAC,OAAO,EAAE,WAAW,CAanE,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAiB/D;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,CAAC,WAAW,CAM7C,CAAC"}

package/src/job.js

@@ -0,0 +1,79 @@
+// Single responsibility: delivering a rendered message is background work, never request work.
+// A slow SMTP host must not hold a request open, and at-least-once delivery must not mean two
+// welcome emails — so the send is a `job` with a content-derived idempotency key.
+import { job } from '@ultimat3/jobs';
+import { t } from '@ultimat3/schema';
+import { mailDriver } from './driver';
+/** The queue payload is the already-rendered envelope: rendering happens once, at send time. */
+export const mailMessageSchema = t.object({
+    mailId: t.string,
+    to: t.array(t.email),
+    subject: t.string,
+    html: t.string,
+    text: t.string,
+    locale: t.locale,
+    tz: t.timezone,
+    replyTo: t.email.optional(),
+    cc: t.array(t.email).optional(),
+    bcc: t.array(t.email).optional(),
+    unsubscribeUrl: t.url.optional(),
+    idempotencyKey: t.string.optional(),
+});
+/**
+ * `(mailId, recipients, hash(rendered payload))`, or the caller's key when supplied.
+ * Content-derived on purpose: a retry of the same request produces the same key, while an
+ * intentional resend with different content produces a different one.
+ */
+export function mailIdempotencyKey(message) {
+    const explicit = message.idempotencyKey;
+    if (explicit !== undefined && explicit !== '')
+        return `mail:${explicit}`;
+    const recipients = [...message.to].map((address) => address.toLowerCase()).sort();
+    const digest = fnv1a32(stableStringify({
+        subject: message.subject,
+        html: message.html,
+        text: message.text,
+        cc: message.cc ?? [],
+        bcc: message.bcc ?? [],
+        locale: message.locale,
+        tz: message.tz,
+        unsubscribeUrl: message.unsubscribeUrl ?? '',
+    }));
+    return `mail:${message.mailId}:${recipients.join(',')}:${digest}`;
+}
+/**
+ * Five attempts with exponential backoff: transient 4xx/greylisting clears in minutes, and a
+ * hard bounce still lands in the dead-letter queue where `x jobs dead --json` can show it.
+ */
+export const sendMailJob = job({
+    name: 'mail.send',
+    input: mailMessageSchema,
+    idempotencyKey: mailIdempotencyKey,
+    retry: { attempts: 5, backoff: 'exponential' },
+    run: ({ input }) => mailDriver().send(input),
+});
+/** Key order is normalised so two structurally equal payloads hash identically. */
+function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    if (value !== null && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`);
+        return `{${entries.join(',')}}`;
+    }
+    if (value === undefined)
+        return 'null';
+    return JSON.stringify(value);
+}
+/** FNV-1a, 32-bit. Not a security hash — a short, dependency-free, stable content id. */
+function fnv1a32(input) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < input.length; index += 1) {
+        hash ^= input.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, '0');
+}
+//# sourceMappingURL=job.js.map

package/src/job.js.map

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

package/src/job.ts

@@ -0,0 +1,36 @@
+// Single responsibility: delivering a rendered message is background work, never request work.
+// A slow SMTP host must not hold a request open, and at-least-once delivery must not mean two
+// welcome emails — so the send is a `job` keyed by the content-derived idempotency key.
+
+import { type JobHandle, job } from '@ultimat3/jobs';
+import { type StandardSchemaV1, t } from '@ultimat3/schema';
+import { type MailMessage, mailDriver, type SendResult } from './driver';
+import { mailIdempotencyKey } from './idempotency';
+
+/** The queue payload is the already-rendered envelope: rendering happens once, at send time. */
+export const mailMessageSchema: StandardSchemaV1<unknown, MailMessage> = t.object({
+  mailId: t.string,
+  to: t.array(t.email),
+  subject: t.string,
+  html: t.string,
+  text: t.string,
+  locale: t.locale,
+  tz: t.timezone,
+  replyTo: t.email.optional(),
+  cc: t.array(t.email).optional(),
+  bcc: t.array(t.email).optional(),
+  unsubscribeUrl: t.url.optional(),
+  idempotencyKey: t.string.optional(),
+});
+
+/**
+ * Five attempts with exponential backoff: transient 4xx/greylisting clears in minutes, and a
+ * hard bounce still lands in the dead-letter queue where `x jobs dead --json` can show it.
+ */
+export const sendMailJob: JobHandle<MailMessage> = job<MailMessage>({
+  name: 'mail.send',
+  input: mailMessageSchema,
+  idempotencyKey: mailIdempotencyKey,
+  retry: { attempts: 5, backoff: 'exponential' },
+  run: ({ input }): Promise<SendResult> => mailDriver().send(input),
+});

package/src/layout.d.ts

@@ -0,0 +1,41 @@
+export type ColorScheme = 'light' | 'dark';
+export type MailToken = 'pageBg' | 'surfaceBg' | 'textPrimary' | 'textMuted' | 'borderSubtle' | 'accentBg' | 'accentText' | 'linkText' | 'calloutInfoBg' | 'calloutInfoText' | 'calloutDangerBg' | 'calloutDangerText';
+export declare const MAIL_TOKENS: Readonly<Record<MailToken, Readonly<Record<ColorScheme, string>>>>;
+/** Resolve a token to a hex value. The only function in the package that returns a colour. */
+export declare function token(name: MailToken, scheme?: ColorScheme): string;
+export declare const MAIL_FONT_STACK = "-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica,Arial,sans-serif";
+export declare const MAIL_WIDTH_PX = 600;
+/** A node's dark-mode role: which CSS property takes which token when the client is dark. */
+export type DarkRule = readonly [role: string, declarations: readonly [string, MailToken][]];
+/**
+ * Dark overrides key off short `data-x` role codes rather than class names: base styling
+ * stays fully inlined for the clients that strip <style>, and the codes are deliberately
+ * not token names, so nothing leaks the design vocabulary into delivered HTML.
+ */
+export declare const DARK_RULES: readonly DarkRule[];
+/** The one `prefers-color-scheme` block. Clients that ignore it keep the inlined light theme. */
+export declare function darkModeCss(): string;
+export interface UnsubscribeSlot {
+    /** Already translated — the layout never touches a catalog. */
+    readonly label: string;
+    readonly url: string;
+}
+export interface LayoutInput {
+    readonly subject: string;
+    /** Hidden preview text. Clients show it next to the subject in the inbox list. */
+    readonly preheader: string;
+    /** Rendered block HTML. */
+    readonly content: string;
+    readonly footer: readonly string[];
+    readonly unsubscribe?: UnsubscribeSlot | undefined;
+    readonly locale: string;
+    readonly direction: 'ltr' | 'rtl';
+}
+export type MailLayout = (input: LayoutInput) => string;
+export declare const BASE_LAYOUT = "base";
+/** The framework's only layout. Apps register their own with `registerLayout`. */
+export declare const baseLayout: MailLayout;
+export declare function registerLayout(name: string, layout: MailLayout): void;
+export declare function layoutFor(name: string): MailLayout | undefined;
+export declare function registeredLayouts(): readonly string[];
+//# sourceMappingURL=layout.d.ts.map

package/src/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["layout.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3C,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,WAAW,GACX,aAAa,GACb,WAAW,GACX,cAAc,GACd,UAAU,GACV,YAAY,GACZ,UAAU,GACV,eAAe,GACf,iBAAiB,GACjB,iBAAiB,GACjB,mBAAmB,CAAC;AAExB,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC,CAcvF,CAAC;AAEL,8FAA8F;AAC9F,wBAAgB,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,GAAE,WAAqB,GAAG,MAAM,CAE5E;AAED,eAAO,MAAM,eAAe,gFACmD,CAAC;AAEhF,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC,6FAA6F;AAC7F,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC;AAE7F;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAmCzC,CAAC;AAEF,iGAAiG;AACjG,wBAAgB,WAAW,IAAI,MAAM,CAQpC;AAED,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,KAAK,GAAG,KAAK,CAAC;CACnC;AAED,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,MAAM,CAAC;AAExD,eAAO,MAAM,WAAW,SAAS,CAAC;AA6ClC,kFAAkF;AAClF,eAAO,MAAM,UAAU,EAAE,UAwBjB,CAAC;AAeT,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAErE;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAE9D;AAED,wBAAgB,iBAAiB,IAAI,SAAS,MAAM,EAAE,CAErD"}

package/src/layout.js

@@ -0,0 +1,160 @@
+// Single responsibility: the base email layout and the semantic colour tokens every block
+// resolves through. Colours are declared once here (light + dark) and inlined by the
+// renderer, because email clients drop <style> and templates must never carry a raw hex.
+// Table-based and 600px wide: Outlook still renders with Word's HTML engine.
+import { escapeHtml, safeUrl, styleAttr } from './html';
+export const MAIL_TOKENS = Object.freeze({
+    pageBg: { light: '#f4f5f7', dark: '#0b0d10' },
+    surfaceBg: { light: '#ffffff', dark: '#14181d' },
+    textPrimary: { light: '#16191d', dark: '#e7eaee' },
+    textMuted: { light: '#5c6470', dark: '#9aa4b1' },
+    borderSubtle: { light: '#e2e6ea', dark: '#262c33' },
+    accentBg: { light: '#2f6df6', dark: '#4f86ff' },
+    accentText: { light: '#ffffff', dark: '#0b0d10' },
+    linkText: { light: '#2f6df6', dark: '#7aa7ff' },
+    calloutInfoBg: { light: '#eef3ff', dark: '#141c2c' },
+    calloutInfoText: { light: '#1f3f8f', dark: '#b9cdfb' },
+    calloutDangerBg: { light: '#fdeceb', dark: '#2a1416' },
+    calloutDangerText: { light: '#8c2118', dark: '#f5b3ad' },
+});
+/** Resolve a token to a hex value. The only function in the package that returns a colour. */
+export function token(name, scheme = 'light') {
+    return MAIL_TOKENS[name][scheme];
+}
+export const MAIL_FONT_STACK = '-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica,Arial,sans-serif';
+export const MAIL_WIDTH_PX = 600;
+/**
+ * Dark overrides key off short `data-x` role codes rather than class names: base styling
+ * stays fully inlined for the clients that strip <style>, and the codes are deliberately
+ * not token names, so nothing leaks the design vocabulary into delivered HTML.
+ */
+export const DARK_RULES = [
+    ['page', [['background-color', 'pageBg']]],
+    [
+        'card',
+        [
+            ['background-color', 'surfaceBg'],
+            ['border-color', 'borderSubtle'],
+        ],
+    ],
+    ['h', [['color', 'textPrimary']]],
+    ['p', [['color', 'textPrimary']]],
+    ['mut', [['color', 'textMuted']]],
+    [
+        'btn',
+        [
+            ['background-color', 'accentBg'],
+            ['color', 'accentText'],
+        ],
+    ],
+    ['hr', [['border-top-color', 'borderSubtle']]],
+    ['a', [['color', 'linkText']]],
+    [
+        'ci',
+        [
+            ['background-color', 'calloutInfoBg'],
+            ['color', 'calloutInfoText'],
+        ],
+    ],
+    [
+        'cd',
+        [
+            ['background-color', 'calloutDangerBg'],
+            ['color', 'calloutDangerText'],
+        ],
+    ],
+];
+/** The one `prefers-color-scheme` block. Clients that ignore it keep the inlined light theme. */
+export function darkModeCss() {
+    const rules = DARK_RULES.map(([role, declarations]) => {
+        const body = declarations
+            .map(([property, name]) => `${property}:${token(name, 'dark')}!important`)
+            .join(';');
+        return `[data-x="${role}"]{${body}}`;
+    });
+    return `@media (prefers-color-scheme:dark){${rules.join('')}}`;
+}
+export const BASE_LAYOUT = 'base';
+const BODY_STYLE = styleAttr([
+    'margin:0',
+    'padding:0',
+    'width:100%',
+    `background-color:${token('pageBg')}`,
+    `font-family:${MAIL_FONT_STACK}`,
+    `color:${token('textPrimary')}`,
+    '-webkit-font-smoothing:antialiased',
+]);
+const PREHEADER_STYLE = styleAttr([
+    'display:none',
+    'font-size:1px',
+    'line-height:1px',
+    'max-height:0',
+    'max-width:0',
+    'opacity:0',
+    'overflow:hidden',
+    'mso-hide:all',
+]);
+const PAGE_STYLE = styleAttr([`background-color:${token('pageBg')}`, 'width:100%']);
+const GUTTER_STYLE = styleAttr(['padding:24px 12px']);
+const SHELL_STYLE = styleAttr([`width:${MAIL_WIDTH_PX}px`, 'max-width:100%']);
+const CARD_STYLE = styleAttr([
+    `background-color:${token('surfaceBg')}`,
+    `border:1px solid ${token('borderSubtle')}`,
+    'border-radius:12px',
+    'padding:32px',
+]);
+const FOOTER_STYLE = styleAttr([
+    `color:${token('textMuted')}`,
+    'font-size:12px',
+    'line-height:18px',
+    'padding:16px 8px 32px 8px',
+]);
+const UNSUBSCRIBE_STYLE = styleAttr([`color:${token('textMuted')}`, 'text-decoration:underline']);
+const TABLE_ATTRS = 'role="presentation" cellpadding="0" cellspacing="0" border="0"';
+/** The framework's only layout. Apps register their own with `registerLayout`. */
+export const baseLayout = (input) => `<!doctype html>
+<html lang="${escapeHtml(input.locale)}" dir="${input.direction}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta http-equiv="x-ua-compatible" content="ie=edge">
+<meta name="color-scheme" content="light dark">
+<meta name="supported-color-schemes" content="light dark">
+<meta name="format-detection" content="telephone=no,date=no,address=no,email=no">
+<meta name="x-apple-disable-message-reformatting">
+<title>${escapeHtml(input.subject)}</title>
+<style>${darkModeCss()}</style>
+</head>
+<body ${BODY_STYLE} data-x="page">
+<div ${PREHEADER_STYLE}>${escapeHtml(input.preheader)}</div>
+<table ${TABLE_ATTRS} width="100%" data-x="page" ${PAGE_STYLE}>
+<tr><td align="center" ${GUTTER_STYLE}>
+<table ${TABLE_ATTRS} width="${MAIL_WIDTH_PX}" ${SHELL_STYLE}>
+<tr><td data-x="card" ${CARD_STYLE}>${input.content}</td></tr>
+<tr><td data-x="mut" ${FOOTER_STYLE}>${footerHtml(input)}</td></tr>
+</table>
+</td></tr>
+</table>
+</body>
+</html>`;
+function footerHtml(input) {
+    const lines = input.footer.map((line) => `<div>${escapeHtml(line)}</div>`);
+    const slot = input.unsubscribe;
+    if (slot !== undefined) {
+        const href = escapeHtml(safeUrl(slot.url));
+        const label = escapeHtml(slot.label);
+        lines.push(`<div><a data-x="a" href="${href}" ${UNSUBSCRIBE_STYLE}>${label}</a></div>`);
+    }
+    return lines.join('');
+}
+const layouts = new Map([[BASE_LAYOUT, baseLayout]]);
+export function registerLayout(name, layout) {
+    layouts.set(name, layout);
+}
+export function layoutFor(name) {
+    return layouts.get(name);
+}
+export function registeredLayouts() {
+    return [...layouts.keys()].sort();
+}
+//# sourceMappingURL=layout.js.map

package/src/layout.js.map

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