@emailens/engine 0.10.4 → 0.11.1

package/dist/index.d.cts

@@ -1,6 +1,7 @@
-import { E as EmailClient, F as Framework, T as TransformResult, C as CSSWarning, a as CodeFix, D as DiffResult, b as ExportPromptOptions, A as AiProvider, c as AiFixResult, S as SupportLevel, d as SpamAnalysisOptions, e as SpamReport, L as LinkReport, f as AccessibilityReport, I as ImageReport, g as InboxPreview, h as SizeReport, i as TemplateReport, O as OverflowReport, V as VisualReport, j as DeliverabilityReport } from './types-BLR3-Fzo.cjs';
-export { k as AccessibilityIssue, B as BaseIssue, l as ClientTruncation, m as DeliverabilityCheck, n as DeliverabilityIssue, o as EstimateOptions, p as ExportScope, q as FixType, r as ImageInfo, s as ImageIssue, t as InboxPreviewIssue, u as InputFormat, v as LinkIssue, w as OverflowIssue, P as PreviewResult, x as Severity, y as SizeIssue, z as SourceLocation, G as SpamIssue, H as TemplateIssue, J as TokenEstimate, K as TokenEstimateWithWarnings, M as VisualIssue, N as estimateAiFixTokens, Q as generateFixPrompt, R as heuristicTokenCount } from './types-BLR3-Fzo.cjs';
-export { C as CompileError, a as CompileReactEmailOptions, S as SandboxStrategy } from './react-email-DTzVpGgB.cjs';
+import { E as EmailClient, F as Framework, T as TransformResult, C as CSSWarning, a as CodeFix, D as DiffResult, b as ExportPromptOptions, A as AiProvider, c as AiFixResult, S as SupportLevel, d as SpamAnalysisOptions, e as SpamReport, L as LinkReport, f as AccessibilityReport, g as AccessibilityIssue, I as ImageReport, h as InboxPreview, i as SizeReport, j as TemplateReport, O as OverflowReport, V as VmlReport, k as VisualReport, l as DesignReport, m as DeliverabilityReport } from './types-bvGDId6f.cjs';
+export { B as BaseIssue, n as ClientTruncation, o as DeliverabilityCheck, p as DeliverabilityIssue, q as DesignIssue, r as EstimateOptions, s as ExportScope, t as FixType, u as ImageInfo, v as ImageIssue, w as InboxPreviewIssue, x as InputFormat, y as LinkIssue, z as OverflowIssue, P as PreviewResult, G as Severity, H as SizeIssue, J as SourceLocation, K as SpamIssue, M as TemplateIssue, N as TokenEstimate, Q as TokenEstimateWithWarnings, R as VisualIssue, U as VmlIssue, W as estimateAiFixTokens, X as generateFixPrompt, Y as heuristicTokenCount } from './types-bvGDId6f.cjs';
+import * as cheerio from 'cheerio';
+export { C as CompileError, a as CompileReactEmailOptions, S as SandboxStrategy } from './react-email-DuZAgJtw.cjs';
 
 declare const EMAIL_CLIENTS: EmailClient[];
 declare function getClient(id: string): EmailClient | undefined;
@@ -13,7 +14,7 @@ interface ParseOptions {
     /**
      * Record source positions so issues carry a `loc`. Costs a little parse time
      * (parse5 tracks a location record per node and per attribute), so it is
-     * opt-in for callers that need to point at the source — editors, CI
+     * opt-in for callers that need to point at the source: editors, CI
      * annotations, agents.
      */
     positions?: boolean;
@@ -24,7 +25,7 @@ interface ParseOptions {
  * for all target email clients.
  *
  * The `framework` parameter controls which fix snippets are attached
- * to warnings — it does NOT change which warnings fire. Analysis always
+ * to warnings; it does NOT change which warnings fire. Analysis always
  * runs on compiled HTML (what email clients actually receive). Fix
  * snippets reference source-level constructs so users know how to
  * modify their framework source code.
@@ -128,7 +129,7 @@ interface GenerateAiFixOptions extends ExportPromptOptions {
  * to build a structured prompt, then delegates to an LLM for context-aware
  * structural fixes that static snippets cannot handle.
  *
- * The engine stays provider-agnostic — consumers pass their own `AiProvider`
+ * The engine stays provider-agnostic: consumers pass their own `AiProvider`
  * callback (Anthropic SDK, Vercel AI SDK, OpenRouter, etc.).
  *
  * @example
@@ -166,10 +167,10 @@ declare function generateAiFix(options: GenerateAiFixOptions): Promise<AiFixResu
  * System prompt for the AI fix provider. Consumers should pass this as
  * the `system` parameter to their LLM call for best results.
  */
-declare const AI_FIX_SYSTEM_PROMPT = "You are an expert email developer specializing in cross-client HTML email compatibility. You fix emails to render correctly across all email clients.\n\nRules:\n- Return ONLY the fixed code inside a single code fence. No explanations before or after.\n- Preserve all existing content, text, links, and visual design.\n- For structural issues (fixType: \"structural\"), you MUST restructure the HTML \u2014 CSS-only changes will not work.\n- Common structural patterns:\n  - word-break/overflow-wrap unsupported \u2192 wrap text in <table><tr><td> with constrained width\n  - display:flex/grid \u2192 convert to <table> layout (match the original column count and proportions)\n  - border-radius in Outlook \u2192 use VML <v:roundrect> with <!--[if mso]> conditionals\n  - background-image in Outlook \u2192 use VML <v:rect> with <v:fill>\n  - max-width in Outlook \u2192 wrap in <!--[if mso]><table width=\"N\"> conditional\n  - position:absolute \u2192 use <table> cells for layout\n  - <svg> \u2192 replace with <img> pointing to a hosted PNG\n- For CSS-only issues (fixType: \"css\"), swap properties or add fallbacks.\n- For \"Layout & Visual Issues\", apply the provided Fix directly: add the background-color fallback beneath a gradient/image, append a web-safe font to the stack, and constrain fixed widths wider than the frame to width:100% with max-width.\n- Apply ALL fixes from the issues list \u2014 do not skip any.\n- Use the framework syntax specified (JSX/MJML/Maizzle/HTML).\n- For JSX: use camelCase style props, React Email components, and proper TypeScript types.\n- For MJML: use mj-* elements and attributes.\n- For Maizzle: use Tailwind CSS classes.";
+declare const AI_FIX_SYSTEM_PROMPT = "You are an expert email developer specializing in cross-client HTML email compatibility. You fix emails to render correctly across all email clients.\n\nRules:\n- Return ONLY the fixed code inside a single code fence. No explanations before or after.\n- Preserve all existing content, text, links, and visual design.\n- For structural issues (fixType: \"structural\"), you MUST restructure the HTML; CSS-only changes will not work.\n- Common structural patterns:\n  - word-break/overflow-wrap unsupported \u2192 wrap text in <table><tr><td> with constrained width\n  - display:flex/grid \u2192 convert to <table> layout (match the original column count and proportions)\n  - border-radius in Outlook \u2192 use VML <v:roundrect> with <!--[if mso]> conditionals\n  - background-image in Outlook \u2192 use VML <v:rect> with <v:fill>\n  - max-width in Outlook \u2192 wrap in <!--[if mso]><table width=\"N\"> conditional\n  - position:absolute \u2192 use <table> cells for layout\n  - <svg> \u2192 replace with <img> pointing to a hosted PNG\n- For CSS-only issues (fixType: \"css\"), swap properties or add fallbacks.\n- For \"Layout & Visual Issues\", apply the provided Fix directly: add the background-color fallback beneath a gradient/image, append a web-safe font to the stack, and constrain fixed widths wider than the frame to width:100% with max-width.\n- Apply ALL fixes from the issues list: do not skip any.\n- Use the framework syntax specified (JSX/MJML/Maizzle/HTML).\n- For JSX: use camelCase style props, React Email components, and proper TypeScript types.\n- For MJML: use mj-* elements and attributes.\n- For Maizzle: use Tailwind CSS classes.";
 
 /**
- * CSS/HTML feature support matrix — auto-generated from caniemail.com.
+ * CSS/HTML feature support matrix, auto-generated from caniemail.com.
  * Last synced: 2026-07-28
  * caniemail last updated: 2026-07-20 09:56:37 +0000
  *
@@ -186,11 +187,11 @@ declare const AI_FIX_SYSTEM_PROMPT = "You are an expert email developer speciali
  * - hey-mail: caniemail.com (WebKit-based)
  * - superhuman: Manual overrides (Chromium/Blink-based, best-effort estimates)
  *
- * DO NOT EDIT — regenerate with: bun run sync:caniemail
+ * DO NOT EDIT; regenerate with: bun run sync:caniemail
  */
 declare const CSS_SUPPORT: Record<string, Record<string, SupportLevel>>;
 /**
- * Caveat notes per (feature, client) from caniemail — the "why" behind a
+ * Caveat notes per (feature, client) from caniemail: the "why" behind a
  * partial/buggy/unsupported rating. Sparse: only cells with a note appear.
  */
 declare const CSS_SUPPORT_NOTES: Record<string, Record<string, string[]>>;
@@ -212,10 +213,10 @@ declare const CSS_FUNCTION_FEATURES: readonly ["calc", "clamp", "conic-gradient"
  * caniemail's page for each feature, for a diagnostic's `codeDescription`.
  *
  * 250 of 255 features. The rest have no caniemail entry of
- * their own and get no link, which is the honest outcome — a link to a 404
+ * their own and get no link, which is the honest outcome: a link to a 404
  * is worse than none.
  *
- * DO NOT EDIT — regenerate with: bun run sync:feature-urls
+ * DO NOT EDIT; regenerate with: bun run sync:feature-urls
  */
 declare const FEATURE_URLS: Record<string, string>;
 /** Where to read about a rule, when there is somewhere. */
@@ -239,7 +240,7 @@ declare const VALUE_CAVEAT_PROPS: ReadonlySet<string>;
  * applies if either does.
  *
  * Returns true (report it) for a property that isn't value-gated, and for one
- * where we never saw a value — an at-rule, a pseudo-class, a detected CSS
+ * where we never saw a value: an at-rule, a pseudo-class, a detected CSS
  * function.
  */
 declare function caveatApplies(prop: string, values: readonly string[] | undefined, notes: string[] | undefined): boolean;
@@ -267,6 +268,20 @@ declare function analyzeSpam(html: string, options?: SpamAnalysisOptions): SpamR
  */
 declare function validateLinks(html: string, options?: ParseOptions): LinkReport;
 
+/**
+ * The render a cascade is being resolved for.
+ *
+ * An email has more than one correct answer: the same CSS produces a different
+ * palette on a phone and in dark mode, and a contrast bug can live in only one
+ * of them. Resolving against an explicit context is what lets the same
+ * machinery grade all three.
+ */
+interface RenderContext {
+    /** Viewport width in px, for width media queries. */
+    width: number;
+    /** Whether `prefers-color-scheme: dark` matches. */
+    dark: boolean;
+}
 /**
  * Audit an HTML email for accessibility issues.
  *
@@ -275,6 +290,43 @@ declare function validateLinks(html: string, options?: ParseOptions): LinkReport
  * color contrast. Returns a 0–100 score and detailed issues.
  */
 declare function checkAccessibility(html: string, options?: ParseOptions): AccessibilityReport;
+/**
+ * Contrast failures inside the email's own `@media (prefers-color-scheme: dark)`
+ * styles.
+ *
+ * This is the other half of dark mode, and the half the author actually
+ * controls: Apple Mail, Superhuman, Thunderbird and friends do not invert
+ * anything, they just apply the dark block as written. A dark background
+ * paired with body text that was never re-coloured is invisible there, and no
+ * amount of inversion analysis finds it; the bug is in the CSS, not in what
+ * the client does to it.
+ *
+ * Free to run: same DOM, resolved against a dark render, so positions stay
+ * valid. Emails with no dark block resolve identically to the light pass and
+ * report nothing.
+ */
+declare function checkDarkStylesContrastFromDom($: cheerio.CheerioAPI, lightIssues?: AccessibilityIssue[]): AccessibilityIssue[];
+/**
+ * Contrast failures that only appear at mobile width. See
+ * {@link checkMobileContrastFromDom}.
+ */
+declare function checkMobileContrast(html: string, options?: ParseOptions): AccessibilityIssue[];
+/**
+ * Contrast failures an email has *only* in dark mode.
+ *
+ * Clients that invert colours do it selectively, so a palette that passes in
+ * light mode can collapse to unreadable once inverted, mid-tone text left
+ * alone on a background repainted near-black. This runs the ordinary contrast
+ * check over the simulated dark render and reports what is new there.
+ *
+ * Pass `lightIssues` when the light-mode report is already in hand (the audit
+ * has it) to skip re-running the light pass.
+ *
+ * ponytail: deduped by the element description, so two genuinely identical
+ * elements collapse into one report. Track them individually only if the
+ * per-element count turns out to matter.
+ */
+declare function checkDarkModeContrast(html: string, lightIssues?: AccessibilityIssue[]): AccessibilityIssue[];
 
 /**
  * Analyze images in an HTML email for best practices.
@@ -320,6 +372,24 @@ declare function checkTemplateVariables(html: string, options?: ParseOptions): T
  */
 declare function checkOverflow(html: string, options?: ParseOptions): OverflowReport;
 
+/**
+ * Check hand-written VML for the mistakes Outlook punishes.
+ *
+ * This is the one part of an email the DOM analyzers structurally cannot see:
+ * VML lives inside `<!--[if mso]>` conditional comments, so to every HTML
+ * parser it is a comment node, and to a headless-Chromium screenshot it does
+ * not exist at all. An email can therefore lint clean and preview perfectly
+ * while the branch Outlook actually renders is broken.
+ *
+ * ponytail: a tag-sequence checker, not a VML renderer. It validates structure
+ * and attribute values, which is where the reported breakages cluster. It does
+ * not resolve geometry, so it can say Outlook will misplace a nested shape but
+ * not where the shape lands.
+ */
+declare function checkVml(html: string, options?: {
+    positions?: boolean;
+}): VmlReport;
+
 /**
  * Detect probable visual bugs in a stylized email: background images/gradients
  * with no colour fallback, and font stacks with no web-safe fallback. Each
@@ -327,12 +397,18 @@ declare function checkOverflow(html: string, options?: ParseOptions): OverflowRe
  */
 declare function checkVisual(html: string, options?: ParseOptions): VisualReport;
 
+/**
+ * Report design drift in an HTML email: near-identical colours, and properties
+ * carrying more distinct values than a design system would.
+ */
+declare function checkDesignConsistency(html: string, options?: ParseOptions): DesignReport;
+
 interface AuditOptions extends ParseOptions {
     framework?: Framework;
     /** Options for spam analysis */
     spam?: SpamAnalysisOptions;
     /** Skip specific checks */
-    skip?: Array<"spam" | "links" | "accessibility" | "images" | "compatibility" | "inboxPreview" | "size" | "templateVariables" | "overflow" | "visual">;
+    skip?: Array<"spam" | "links" | "accessibility" | "images" | "compatibility" | "inboxPreview" | "size" | "templateVariables" | "overflow" | "visual" | "darkContrast" | "mobileContrast" | "design" | "vml">;
 }
 interface AuditReport {
     compatibility: {
@@ -353,6 +429,14 @@ interface AuditReport {
     templateVariables: TemplateReport;
     overflow: OverflowReport;
     visual: VisualReport;
+    /** Structural faults in Outlook-only VML, which lives inside conditional comments. */
+    vml: VmlReport;
+    /** Contrast failures present only once a client inverts colours. */
+    darkContrast: AccessibilityIssue[];
+    /** Contrast failures present only below the email's mobile breakpoint. */
+    mobileContrast: AccessibilityIssue[];
+    /** Design drift: near-identical colours, and properties with no system left. */
+    design: DesignReport;
 }
 /**
  * Run all email analysis checks in a single call.
@@ -453,7 +537,7 @@ interface EmailSession {
      * Simulate dark mode for a specific client.
      *
      * Creates an isolated DOM copy per call (simulation mutates the DOM).
-     * Operates on the **original** HTML — if you need dark mode on
+     * Operates on the **original** HTML, if you need dark mode on
      * already-transformed HTML, use the standalone `simulateDarkMode()` instead.
      */
     simulateDarkMode(clientId: string): {
@@ -466,7 +550,7 @@ interface EmailSession {
  * DOM across all read-only analysis operations.
  *
  * Use this when you need to call multiple analysis functions on the
- * same HTML — it eliminates redundant `cheerio.load()` calls.
+ * same HTML: it eliminates redundant `cheerio.load()` calls.
  *
  * @example
  * ```typescript
@@ -548,6 +632,21 @@ declare function wcagGrade(ratio: number): WcagGrade;
  * Returns the flattened [r, g, b] as 0-255 values.
  */
 declare function alphaBlend(fg: RGBA, bgR: number, bgG: number, bgB: number): [number, number, number];
+/**
+ * Convert sRGB to OKLab.
+ *
+ * OKLab is built so that straight-line distance between two points matches how
+ * different the colours look, which sRGB emphatically does not: `#333` and
+ * `#343434` are far apart in RGB terms and identical to a reader.
+ */
+declare function rgbToOklab(rgba: RGBA): [number, number, number];
+/**
+ * Perceptual distance between two colours, as OKLab delta-E.
+ *
+ * Roughly: under ~0.02 the two are the same colour to a reader, and around
+ * ~0.1 they are clearly different.
+ */
+declare function colorDistance(a: RGBA, b: RGBA): number;
 
 /**
  * Downlevel modern CSS in HTML emails to maximize email client compatibility.
@@ -575,4 +674,4 @@ declare function alphaBlend(fg: RGBA, bgR: number, bgG: number, bgB: number): [n
  */
 declare function downlevelCSS(html: string): string;
 
-export { AI_FIX_SYSTEM_PROMPT, AT_RULE_FEATURES, AccessibilityReport, AiFixResult, AiProvider, type AuditOptions, type AuditReport, COMPOUND_VALUE_FEATURES, CSSWarning, CSS_FUNCTION_FEATURES, CSS_SUPPORT, CSS_SUPPORT_NOTES, CodeFix, type CreateSessionOptions, DeliverabilityReport, DiffResult, EMAIL_CLIENTS, EMPTY_DELIVERABILITY, EmailClient, type EmailSession, ExportPromptOptions, FEATURE_URLS, Framework, GENERIC_LINK_TEXT, type GenerateAiFixOptions, HTML_ELEMENT_FEATURES, ImageReport, InboxPreview, LinkReport, MAX_HTML_SIZE, MAX_WARNING_LOCATIONS, OverflowReport, type ParseOptions, type RGBA, STRUCTURAL_FIX_PROPERTIES, SizeReport, SpamAnalysisOptions, SpamReport, SupportLevel, TemplateReport, TransformResult, VALUE_CAVEAT_PROPS, VisualReport, type WcagGrade, alphaBlend, analyzeEmail, analyzeImages, analyzeSpam, auditEmail, caveatApplies, checkAccessibility, checkOverflow, checkSize, checkTemplateVariables, checkVisual, contrastRatio, createSession, diffResults, downlevelCSS, errorWarnings, extractInboxPreview, featureUrl, formatRgb, generateAiFix, generateCompatibilityScore, getClient, getCodeFix, getSuggestion, parseColor, relativeLuminance, simulateDarkMode, structuralWarnings, toPlainText, transformForAllClients, transformForClient, validateLinks, warningsForClient, wcagGrade };
+export { AI_FIX_SYSTEM_PROMPT, AT_RULE_FEATURES, AccessibilityIssue, AccessibilityReport, AiFixResult, AiProvider, type AuditOptions, type AuditReport, COMPOUND_VALUE_FEATURES, CSSWarning, CSS_FUNCTION_FEATURES, CSS_SUPPORT, CSS_SUPPORT_NOTES, CodeFix, type CreateSessionOptions, DeliverabilityReport, DesignReport, DiffResult, EMAIL_CLIENTS, EMPTY_DELIVERABILITY, EmailClient, type EmailSession, ExportPromptOptions, FEATURE_URLS, Framework, GENERIC_LINK_TEXT, type GenerateAiFixOptions, HTML_ELEMENT_FEATURES, ImageReport, InboxPreview, LinkReport, MAX_HTML_SIZE, MAX_WARNING_LOCATIONS, OverflowReport, type ParseOptions, type RGBA, type RenderContext, STRUCTURAL_FIX_PROPERTIES, SizeReport, SpamAnalysisOptions, SpamReport, SupportLevel, TemplateReport, TransformResult, VALUE_CAVEAT_PROPS, VisualReport, VmlReport, type WcagGrade, alphaBlend, analyzeEmail, analyzeImages, analyzeSpam, auditEmail, caveatApplies, checkAccessibility, checkDarkModeContrast, checkDarkStylesContrastFromDom, checkDesignConsistency, checkMobileContrast, checkOverflow, checkSize, checkTemplateVariables, checkVisual, checkVml, colorDistance, contrastRatio, createSession, diffResults, downlevelCSS, errorWarnings, extractInboxPreview, featureUrl, formatRgb, generateAiFix, generateCompatibilityScore, getClient, getCodeFix, getSuggestion, parseColor, relativeLuminance, rgbToOklab, simulateDarkMode, structuralWarnings, toPlainText, transformForAllClients, transformForClient, validateLinks, warningsForClient, wcagGrade };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import { E as EmailClient, F as Framework, T as TransformResult, C as CSSWarning, a as CodeFix, D as DiffResult, b as ExportPromptOptions, A as AiProvider, c as AiFixResult, S as SupportLevel, d as SpamAnalysisOptions, e as SpamReport, L as LinkReport, f as AccessibilityReport, I as ImageReport, g as InboxPreview, h as SizeReport, i as TemplateReport, O as OverflowReport, V as VisualReport, j as DeliverabilityReport } from './types-BLR3-Fzo.js';
-export { k as AccessibilityIssue, B as BaseIssue, l as ClientTruncation, m as DeliverabilityCheck, n as DeliverabilityIssue, o as EstimateOptions, p as ExportScope, q as FixType, r as ImageInfo, s as ImageIssue, t as InboxPreviewIssue, u as InputFormat, v as LinkIssue, w as OverflowIssue, P as PreviewResult, x as Severity, y as SizeIssue, z as SourceLocation, G as SpamIssue, H as TemplateIssue, J as TokenEstimate, K as TokenEstimateWithWarnings, M as VisualIssue, N as estimateAiFixTokens, Q as generateFixPrompt, R as heuristicTokenCount } from './types-BLR3-Fzo.js';
-export { C as CompileError, a as CompileReactEmailOptions, S as SandboxStrategy } from './react-email-DwBWB2kr.js';
+import { E as EmailClient, F as Framework, T as TransformResult, C as CSSWarning, a as CodeFix, D as DiffResult, b as ExportPromptOptions, A as AiProvider, c as AiFixResult, S as SupportLevel, d as SpamAnalysisOptions, e as SpamReport, L as LinkReport, f as AccessibilityReport, g as AccessibilityIssue, I as ImageReport, h as InboxPreview, i as SizeReport, j as TemplateReport, O as OverflowReport, V as VmlReport, k as VisualReport, l as DesignReport, m as DeliverabilityReport } from './types-bvGDId6f.js';
+export { B as BaseIssue, n as ClientTruncation, o as DeliverabilityCheck, p as DeliverabilityIssue, q as DesignIssue, r as EstimateOptions, s as ExportScope, t as FixType, u as ImageInfo, v as ImageIssue, w as InboxPreviewIssue, x as InputFormat, y as LinkIssue, z as OverflowIssue, P as PreviewResult, G as Severity, H as SizeIssue, J as SourceLocation, K as SpamIssue, M as TemplateIssue, N as TokenEstimate, Q as TokenEstimateWithWarnings, R as VisualIssue, U as VmlIssue, W as estimateAiFixTokens, X as generateFixPrompt, Y as heuristicTokenCount } from './types-bvGDId6f.js';
+import * as cheerio from 'cheerio';
+export { C as CompileError, a as CompileReactEmailOptions, S as SandboxStrategy } from './react-email-BROBcC8u.js';
 
 declare const EMAIL_CLIENTS: EmailClient[];
 declare function getClient(id: string): EmailClient | undefined;
@@ -13,7 +14,7 @@ interface ParseOptions {
     /**
      * Record source positions so issues carry a `loc`. Costs a little parse time
      * (parse5 tracks a location record per node and per attribute), so it is
-     * opt-in for callers that need to point at the source — editors, CI
+     * opt-in for callers that need to point at the source: editors, CI
      * annotations, agents.
      */
     positions?: boolean;
@@ -24,7 +25,7 @@ interface ParseOptions {
  * for all target email clients.
  *
  * The `framework` parameter controls which fix snippets are attached
- * to warnings — it does NOT change which warnings fire. Analysis always
+ * to warnings; it does NOT change which warnings fire. Analysis always
  * runs on compiled HTML (what email clients actually receive). Fix
  * snippets reference source-level constructs so users know how to
  * modify their framework source code.
@@ -128,7 +129,7 @@ interface GenerateAiFixOptions extends ExportPromptOptions {
  * to build a structured prompt, then delegates to an LLM for context-aware
  * structural fixes that static snippets cannot handle.
  *
- * The engine stays provider-agnostic — consumers pass their own `AiProvider`
+ * The engine stays provider-agnostic: consumers pass their own `AiProvider`
  * callback (Anthropic SDK, Vercel AI SDK, OpenRouter, etc.).
  *
  * @example
@@ -166,10 +167,10 @@ declare function generateAiFix(options: GenerateAiFixOptions): Promise<AiFixResu
  * System prompt for the AI fix provider. Consumers should pass this as
  * the `system` parameter to their LLM call for best results.
  */
-declare const AI_FIX_SYSTEM_PROMPT = "You are an expert email developer specializing in cross-client HTML email compatibility. You fix emails to render correctly across all email clients.\n\nRules:\n- Return ONLY the fixed code inside a single code fence. No explanations before or after.\n- Preserve all existing content, text, links, and visual design.\n- For structural issues (fixType: \"structural\"), you MUST restructure the HTML \u2014 CSS-only changes will not work.\n- Common structural patterns:\n  - word-break/overflow-wrap unsupported \u2192 wrap text in <table><tr><td> with constrained width\n  - display:flex/grid \u2192 convert to <table> layout (match the original column count and proportions)\n  - border-radius in Outlook \u2192 use VML <v:roundrect> with <!--[if mso]> conditionals\n  - background-image in Outlook \u2192 use VML <v:rect> with <v:fill>\n  - max-width in Outlook \u2192 wrap in <!--[if mso]><table width=\"N\"> conditional\n  - position:absolute \u2192 use <table> cells for layout\n  - <svg> \u2192 replace with <img> pointing to a hosted PNG\n- For CSS-only issues (fixType: \"css\"), swap properties or add fallbacks.\n- For \"Layout & Visual Issues\", apply the provided Fix directly: add the background-color fallback beneath a gradient/image, append a web-safe font to the stack, and constrain fixed widths wider than the frame to width:100% with max-width.\n- Apply ALL fixes from the issues list \u2014 do not skip any.\n- Use the framework syntax specified (JSX/MJML/Maizzle/HTML).\n- For JSX: use camelCase style props, React Email components, and proper TypeScript types.\n- For MJML: use mj-* elements and attributes.\n- For Maizzle: use Tailwind CSS classes.";
+declare const AI_FIX_SYSTEM_PROMPT = "You are an expert email developer specializing in cross-client HTML email compatibility. You fix emails to render correctly across all email clients.\n\nRules:\n- Return ONLY the fixed code inside a single code fence. No explanations before or after.\n- Preserve all existing content, text, links, and visual design.\n- For structural issues (fixType: \"structural\"), you MUST restructure the HTML; CSS-only changes will not work.\n- Common structural patterns:\n  - word-break/overflow-wrap unsupported \u2192 wrap text in <table><tr><td> with constrained width\n  - display:flex/grid \u2192 convert to <table> layout (match the original column count and proportions)\n  - border-radius in Outlook \u2192 use VML <v:roundrect> with <!--[if mso]> conditionals\n  - background-image in Outlook \u2192 use VML <v:rect> with <v:fill>\n  - max-width in Outlook \u2192 wrap in <!--[if mso]><table width=\"N\"> conditional\n  - position:absolute \u2192 use <table> cells for layout\n  - <svg> \u2192 replace with <img> pointing to a hosted PNG\n- For CSS-only issues (fixType: \"css\"), swap properties or add fallbacks.\n- For \"Layout & Visual Issues\", apply the provided Fix directly: add the background-color fallback beneath a gradient/image, append a web-safe font to the stack, and constrain fixed widths wider than the frame to width:100% with max-width.\n- Apply ALL fixes from the issues list: do not skip any.\n- Use the framework syntax specified (JSX/MJML/Maizzle/HTML).\n- For JSX: use camelCase style props, React Email components, and proper TypeScript types.\n- For MJML: use mj-* elements and attributes.\n- For Maizzle: use Tailwind CSS classes.";
 
 /**
- * CSS/HTML feature support matrix — auto-generated from caniemail.com.
+ * CSS/HTML feature support matrix, auto-generated from caniemail.com.
  * Last synced: 2026-07-28
  * caniemail last updated: 2026-07-20 09:56:37 +0000
  *
@@ -186,11 +187,11 @@ declare const AI_FIX_SYSTEM_PROMPT = "You are an expert email developer speciali
  * - hey-mail: caniemail.com (WebKit-based)
  * - superhuman: Manual overrides (Chromium/Blink-based, best-effort estimates)
  *
- * DO NOT EDIT — regenerate with: bun run sync:caniemail
+ * DO NOT EDIT; regenerate with: bun run sync:caniemail
  */
 declare const CSS_SUPPORT: Record<string, Record<string, SupportLevel>>;
 /**
- * Caveat notes per (feature, client) from caniemail — the "why" behind a
+ * Caveat notes per (feature, client) from caniemail: the "why" behind a
  * partial/buggy/unsupported rating. Sparse: only cells with a note appear.
  */
 declare const CSS_SUPPORT_NOTES: Record<string, Record<string, string[]>>;
@@ -212,10 +213,10 @@ declare const CSS_FUNCTION_FEATURES: readonly ["calc", "clamp", "conic-gradient"
  * caniemail's page for each feature, for a diagnostic's `codeDescription`.
  *
  * 250 of 255 features. The rest have no caniemail entry of
- * their own and get no link, which is the honest outcome — a link to a 404
+ * their own and get no link, which is the honest outcome: a link to a 404
  * is worse than none.
  *
- * DO NOT EDIT — regenerate with: bun run sync:feature-urls
+ * DO NOT EDIT; regenerate with: bun run sync:feature-urls
  */
 declare const FEATURE_URLS: Record<string, string>;
 /** Where to read about a rule, when there is somewhere. */
@@ -239,7 +240,7 @@ declare const VALUE_CAVEAT_PROPS: ReadonlySet<string>;
  * applies if either does.
  *
  * Returns true (report it) for a property that isn't value-gated, and for one
- * where we never saw a value — an at-rule, a pseudo-class, a detected CSS
+ * where we never saw a value: an at-rule, a pseudo-class, a detected CSS
  * function.
  */
 declare function caveatApplies(prop: string, values: readonly string[] | undefined, notes: string[] | undefined): boolean;
@@ -267,6 +268,20 @@ declare function analyzeSpam(html: string, options?: SpamAnalysisOptions): SpamR
  */
 declare function validateLinks(html: string, options?: ParseOptions): LinkReport;
 
+/**
+ * The render a cascade is being resolved for.
+ *
+ * An email has more than one correct answer: the same CSS produces a different
+ * palette on a phone and in dark mode, and a contrast bug can live in only one
+ * of them. Resolving against an explicit context is what lets the same
+ * machinery grade all three.
+ */
+interface RenderContext {
+    /** Viewport width in px, for width media queries. */
+    width: number;
+    /** Whether `prefers-color-scheme: dark` matches. */
+    dark: boolean;
+}
 /**
  * Audit an HTML email for accessibility issues.
  *
@@ -275,6 +290,43 @@ declare function validateLinks(html: string, options?: ParseOptions): LinkReport
  * color contrast. Returns a 0–100 score and detailed issues.
  */
 declare function checkAccessibility(html: string, options?: ParseOptions): AccessibilityReport;
+/**
+ * Contrast failures inside the email's own `@media (prefers-color-scheme: dark)`
+ * styles.
+ *
+ * This is the other half of dark mode, and the half the author actually
+ * controls: Apple Mail, Superhuman, Thunderbird and friends do not invert
+ * anything, they just apply the dark block as written. A dark background
+ * paired with body text that was never re-coloured is invisible there, and no
+ * amount of inversion analysis finds it; the bug is in the CSS, not in what
+ * the client does to it.
+ *
+ * Free to run: same DOM, resolved against a dark render, so positions stay
+ * valid. Emails with no dark block resolve identically to the light pass and
+ * report nothing.
+ */
+declare function checkDarkStylesContrastFromDom($: cheerio.CheerioAPI, lightIssues?: AccessibilityIssue[]): AccessibilityIssue[];
+/**
+ * Contrast failures that only appear at mobile width. See
+ * {@link checkMobileContrastFromDom}.
+ */
+declare function checkMobileContrast(html: string, options?: ParseOptions): AccessibilityIssue[];
+/**
+ * Contrast failures an email has *only* in dark mode.
+ *
+ * Clients that invert colours do it selectively, so a palette that passes in
+ * light mode can collapse to unreadable once inverted, mid-tone text left
+ * alone on a background repainted near-black. This runs the ordinary contrast
+ * check over the simulated dark render and reports what is new there.
+ *
+ * Pass `lightIssues` when the light-mode report is already in hand (the audit
+ * has it) to skip re-running the light pass.
+ *
+ * ponytail: deduped by the element description, so two genuinely identical
+ * elements collapse into one report. Track them individually only if the
+ * per-element count turns out to matter.
+ */
+declare function checkDarkModeContrast(html: string, lightIssues?: AccessibilityIssue[]): AccessibilityIssue[];
 
 /**
  * Analyze images in an HTML email for best practices.
@@ -320,6 +372,24 @@ declare function checkTemplateVariables(html: string, options?: ParseOptions): T
  */
 declare function checkOverflow(html: string, options?: ParseOptions): OverflowReport;
 
+/**
+ * Check hand-written VML for the mistakes Outlook punishes.
+ *
+ * This is the one part of an email the DOM analyzers structurally cannot see:
+ * VML lives inside `<!--[if mso]>` conditional comments, so to every HTML
+ * parser it is a comment node, and to a headless-Chromium screenshot it does
+ * not exist at all. An email can therefore lint clean and preview perfectly
+ * while the branch Outlook actually renders is broken.
+ *
+ * ponytail: a tag-sequence checker, not a VML renderer. It validates structure
+ * and attribute values, which is where the reported breakages cluster. It does
+ * not resolve geometry, so it can say Outlook will misplace a nested shape but
+ * not where the shape lands.
+ */
+declare function checkVml(html: string, options?: {
+    positions?: boolean;
+}): VmlReport;
+
 /**
  * Detect probable visual bugs in a stylized email: background images/gradients
  * with no colour fallback, and font stacks with no web-safe fallback. Each
@@ -327,12 +397,18 @@ declare function checkOverflow(html: string, options?: ParseOptions): OverflowRe
  */
 declare function checkVisual(html: string, options?: ParseOptions): VisualReport;
 
+/**
+ * Report design drift in an HTML email: near-identical colours, and properties
+ * carrying more distinct values than a design system would.
+ */
+declare function checkDesignConsistency(html: string, options?: ParseOptions): DesignReport;
+
 interface AuditOptions extends ParseOptions {
     framework?: Framework;
     /** Options for spam analysis */
     spam?: SpamAnalysisOptions;
     /** Skip specific checks */
-    skip?: Array<"spam" | "links" | "accessibility" | "images" | "compatibility" | "inboxPreview" | "size" | "templateVariables" | "overflow" | "visual">;
+    skip?: Array<"spam" | "links" | "accessibility" | "images" | "compatibility" | "inboxPreview" | "size" | "templateVariables" | "overflow" | "visual" | "darkContrast" | "mobileContrast" | "design" | "vml">;
 }
 interface AuditReport {
     compatibility: {
@@ -353,6 +429,14 @@ interface AuditReport {
     templateVariables: TemplateReport;
     overflow: OverflowReport;
     visual: VisualReport;
+    /** Structural faults in Outlook-only VML, which lives inside conditional comments. */
+    vml: VmlReport;
+    /** Contrast failures present only once a client inverts colours. */
+    darkContrast: AccessibilityIssue[];
+    /** Contrast failures present only below the email's mobile breakpoint. */
+    mobileContrast: AccessibilityIssue[];
+    /** Design drift: near-identical colours, and properties with no system left. */
+    design: DesignReport;
 }
 /**
  * Run all email analysis checks in a single call.
@@ -453,7 +537,7 @@ interface EmailSession {
      * Simulate dark mode for a specific client.
      *
      * Creates an isolated DOM copy per call (simulation mutates the DOM).
-     * Operates on the **original** HTML — if you need dark mode on
+     * Operates on the **original** HTML, if you need dark mode on
      * already-transformed HTML, use the standalone `simulateDarkMode()` instead.
      */
     simulateDarkMode(clientId: string): {
@@ -466,7 +550,7 @@ interface EmailSession {
  * DOM across all read-only analysis operations.
  *
  * Use this when you need to call multiple analysis functions on the
- * same HTML — it eliminates redundant `cheerio.load()` calls.
+ * same HTML: it eliminates redundant `cheerio.load()` calls.
  *
  * @example
  * ```typescript
@@ -548,6 +632,21 @@ declare function wcagGrade(ratio: number): WcagGrade;
  * Returns the flattened [r, g, b] as 0-255 values.
  */
 declare function alphaBlend(fg: RGBA, bgR: number, bgG: number, bgB: number): [number, number, number];
+/**
+ * Convert sRGB to OKLab.
+ *
+ * OKLab is built so that straight-line distance between two points matches how
+ * different the colours look, which sRGB emphatically does not: `#333` and
+ * `#343434` are far apart in RGB terms and identical to a reader.
+ */
+declare function rgbToOklab(rgba: RGBA): [number, number, number];
+/**
+ * Perceptual distance between two colours, as OKLab delta-E.
+ *
+ * Roughly: under ~0.02 the two are the same colour to a reader, and around
+ * ~0.1 they are clearly different.
+ */
+declare function colorDistance(a: RGBA, b: RGBA): number;
 
 /**
  * Downlevel modern CSS in HTML emails to maximize email client compatibility.
@@ -575,4 +674,4 @@ declare function alphaBlend(fg: RGBA, bgR: number, bgG: number, bgB: number): [n
  */
 declare function downlevelCSS(html: string): string;
 
-export { AI_FIX_SYSTEM_PROMPT, AT_RULE_FEATURES, AccessibilityReport, AiFixResult, AiProvider, type AuditOptions, type AuditReport, COMPOUND_VALUE_FEATURES, CSSWarning, CSS_FUNCTION_FEATURES, CSS_SUPPORT, CSS_SUPPORT_NOTES, CodeFix, type CreateSessionOptions, DeliverabilityReport, DiffResult, EMAIL_CLIENTS, EMPTY_DELIVERABILITY, EmailClient, type EmailSession, ExportPromptOptions, FEATURE_URLS, Framework, GENERIC_LINK_TEXT, type GenerateAiFixOptions, HTML_ELEMENT_FEATURES, ImageReport, InboxPreview, LinkReport, MAX_HTML_SIZE, MAX_WARNING_LOCATIONS, OverflowReport, type ParseOptions, type RGBA, STRUCTURAL_FIX_PROPERTIES, SizeReport, SpamAnalysisOptions, SpamReport, SupportLevel, TemplateReport, TransformResult, VALUE_CAVEAT_PROPS, VisualReport, type WcagGrade, alphaBlend, analyzeEmail, analyzeImages, analyzeSpam, auditEmail, caveatApplies, checkAccessibility, checkOverflow, checkSize, checkTemplateVariables, checkVisual, contrastRatio, createSession, diffResults, downlevelCSS, errorWarnings, extractInboxPreview, featureUrl, formatRgb, generateAiFix, generateCompatibilityScore, getClient, getCodeFix, getSuggestion, parseColor, relativeLuminance, simulateDarkMode, structuralWarnings, toPlainText, transformForAllClients, transformForClient, validateLinks, warningsForClient, wcagGrade };
+export { AI_FIX_SYSTEM_PROMPT, AT_RULE_FEATURES, AccessibilityIssue, AccessibilityReport, AiFixResult, AiProvider, type AuditOptions, type AuditReport, COMPOUND_VALUE_FEATURES, CSSWarning, CSS_FUNCTION_FEATURES, CSS_SUPPORT, CSS_SUPPORT_NOTES, CodeFix, type CreateSessionOptions, DeliverabilityReport, DesignReport, DiffResult, EMAIL_CLIENTS, EMPTY_DELIVERABILITY, EmailClient, type EmailSession, ExportPromptOptions, FEATURE_URLS, Framework, GENERIC_LINK_TEXT, type GenerateAiFixOptions, HTML_ELEMENT_FEATURES, ImageReport, InboxPreview, LinkReport, MAX_HTML_SIZE, MAX_WARNING_LOCATIONS, OverflowReport, type ParseOptions, type RGBA, type RenderContext, STRUCTURAL_FIX_PROPERTIES, SizeReport, SpamAnalysisOptions, SpamReport, SupportLevel, TemplateReport, TransformResult, VALUE_CAVEAT_PROPS, VisualReport, VmlReport, type WcagGrade, alphaBlend, analyzeEmail, analyzeImages, analyzeSpam, auditEmail, caveatApplies, checkAccessibility, checkDarkModeContrast, checkDarkStylesContrastFromDom, checkDesignConsistency, checkMobileContrast, checkOverflow, checkSize, checkTemplateVariables, checkVisual, checkVml, colorDistance, contrastRatio, createSession, diffResults, downlevelCSS, errorWarnings, extractInboxPreview, featureUrl, formatRgb, generateAiFix, generateCompatibilityScore, getClient, getCodeFix, getSuggestion, parseColor, relativeLuminance, rgbToOklab, simulateDarkMode, structuralWarnings, toPlainText, transformForAllClients, transformForClient, validateLinks, warningsForClient, wcagGrade };