@emailens/engine 0.3.1 → 0.5.0

package/dist/index.d.cts

@@ -0,0 +1,273 @@
+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 SpamAnalysisOptions, d as SpamReport, L as LinkReport, e as AccessibilityReport, I as ImageReport } from './react-email-BQljgXbo.cjs';
+export { f as AccessibilityIssue, g as CompileError, h as CompileReactEmailOptions, i as EstimateOptions, j as ExportScope, k as FixType, l as ImageInfo, m as ImageIssue, n as InputFormat, o as LinkIssue, P as PreviewResult, p as SandboxStrategy, q as SpamIssue, r as SupportLevel, s as TokenEstimate, t as TokenEstimateWithWarnings, u as estimateAiFixTokens, v as generateFixPrompt, w as heuristicTokenCount } from './react-email-BQljgXbo.cjs';
+
+declare const EMAIL_CLIENTS: EmailClient[];
+declare function getClient(id: string): EmailClient | undefined;
+
+declare function transformForClient(html: string, clientId: string, framework?: Framework): TransformResult;
+declare function transformForAllClients(html: string, framework?: Framework): TransformResult[];
+
+/**
+ * Analyze an HTML email and return CSS compatibility warnings
+ * 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
+ * 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.
+ */
+declare function analyzeEmail(html: string, framework?: Framework): CSSWarning[];
+/**
+ * Generate a summary of CSS compatibility for the email.
+ */
+declare function generateCompatibilityScore(warnings: CSSWarning[]): Record<string, {
+    score: number;
+    errors: number;
+    warnings: number;
+    info: number;
+}>;
+/** Filter warnings for a specific client. */
+declare function warningsForClient(warnings: CSSWarning[], clientId: string): CSSWarning[];
+/** Get only error-severity warnings. */
+declare function errorWarnings(warnings: CSSWarning[]): CSSWarning[];
+/** Get only structural fix warnings. */
+declare function structuralWarnings(warnings: CSSWarning[]): CSSWarning[];
+
+/**
+ * Simulate dark mode rendering for an email.
+ * Email clients apply dark mode differently:
+ * - Some invert colors (Gmail Android)
+ * - Some use prefers-color-scheme media query (Apple Mail)
+ * - Some do partial inversion (Outlook.com)
+ */
+declare function simulateDarkMode(html: string, clientId: string): {
+    html: string;
+    warnings: CSSWarning[];
+};
+
+/**
+ * Look up a code fix for a given property, client, and optional framework.
+ * Returns undefined if no fix snippet exists.
+ *
+ * Resolution order (most specific to least specific):
+ * 1. property::clientPrefix::framework  (e.g. "display:flex::outlook::jsx")
+ * 2. property::framework                (e.g. "display:grid::jsx")
+ * 3. property::clientPrefix             (e.g. "border-radius::outlook")
+ * 4. property                           (generic fix)
+ */
+declare function getCodeFix(property: string, clientId: string, framework?: Framework): CodeFix | undefined;
+/**
+ * Look up a suggestion string for a given property, client, and optional framework.
+ *
+ * Resolution order mirrors `getCodeFix()`:
+ * 1. property::clientPrefix::framework
+ * 2. property::framework
+ * 3. property::clientPrefix
+ * 4. property (generic)
+ *
+ * `isGenericFallback` is true when a framework was specified but no
+ * framework-specific entry was found (resolution fell through to tiers 3–4).
+ */
+declare function getSuggestion(property: string, clientId: string, framework?: Framework): {
+    text: string;
+    isGenericFallback: boolean;
+};
+
+/**
+ * Compare two sets of analysis results to show what improved,
+ * what regressed, and what stayed the same.
+ */
+declare function diffResults(before: {
+    scores: Record<string, {
+        score: number;
+        errors: number;
+        warnings: number;
+        info: number;
+    }>;
+    warnings: CSSWarning[];
+}, after: {
+    scores: Record<string, {
+        score: number;
+        errors: number;
+        warnings: number;
+        info: number;
+    }>;
+    warnings: CSSWarning[];
+}): DiffResult[];
+
+interface GenerateAiFixOptions extends ExportPromptOptions {
+    /** Callback that sends a prompt to an LLM and returns the response text. */
+    provider: AiProvider;
+    /**
+     * Maximum input tokens for the prompt. If the estimated prompt exceeds
+     * this, warnings are intelligently truncated (info first, then CSS-only
+     * duplicates). Defaults to 16000.
+     */
+    maxInputTokens?: number;
+}
+/**
+ * Generate an AI-powered fix for email compatibility issues.
+ *
+ * This uses the deterministic engine's analysis (warnings, scores, fix snippets)
+ * 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`
+ * callback (Anthropic SDK, Vercel AI SDK, OpenRouter, etc.).
+ *
+ * @example
+ * ```ts
+ * import Anthropic from "@anthropic-ai/sdk";
+ * import { analyzeEmail, generateCompatibilityScore, generateAiFix } from "@emailens/engine";
+ *
+ * const anthropic = new Anthropic();
+ * const warnings = analyzeEmail(html, "jsx");
+ * const scores = generateCompatibilityScore(warnings);
+ *
+ * // 1. Check cost before calling
+ * const estimate = await estimateAiFixTokens({
+ *   originalHtml: html, warnings, scores, scope: "all", format: "jsx",
+ * });
+ * console.log(`~${estimate.inputTokens} input tokens`);
+ *
+ * // 2. Generate the fix
+ * const result = await generateAiFix({
+ *   originalHtml: html, warnings, scores, scope: "all", format: "jsx",
+ *   provider: async (prompt) => {
+ *     const msg = await anthropic.messages.create({
+ *       model: "claude-sonnet-4-6",
+ *       max_tokens: 8192,
+ *       system: AI_FIX_SYSTEM_PROMPT,
+ *       messages: [{ role: "user", content: prompt }],
+ *     });
+ *     return msg.content[0].type === "text" ? msg.content[0].text : "";
+ *   },
+ * });
+ * ```
+ */
+declare function generateAiFix(options: GenerateAiFixOptions): Promise<AiFixResult>;
+/**
+ * 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- 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.";
+
+/**
+ * Properties that require HTML structural changes (not just CSS swaps)
+ * to fix. These cannot be solved by replacing one CSS value with another.
+ */
+declare const STRUCTURAL_FIX_PROPERTIES: Set<string>;
+
+/**
+ * Analyze an HTML email for spam indicators.
+ *
+ * Returns a 0-100 score (100 = clean, 0 = very spammy) and an array
+ * of issues found. Uses heuristic rules modeled after common spam
+ * filter triggers (CAN-SPAM, GDPR, SpamAssassin patterns).
+ */
+declare function analyzeSpam(html: string, options?: SpamAnalysisOptions): SpamReport;
+
+/**
+ * Extract and validate all links from an HTML email.
+ *
+ * Performs static analysis only (no network requests). Checks for
+ * empty/placeholder hrefs, javascript: protocol, insecure HTTP,
+ * generic link text, accessibility issues, and more.
+ */
+declare function validateLinks(html: string): LinkReport;
+
+/**
+ * Audit an HTML email for accessibility issues.
+ *
+ * Checks for missing lang attributes, image alt text, small fonts,
+ * layout table roles, link accessibility, heading hierarchy, and
+ * color contrast. Returns a 0–100 score and detailed issues.
+ */
+declare function checkAccessibility(html: string): AccessibilityReport;
+
+/**
+ * Analyze images in an HTML email for best practices.
+ *
+ * Checks for missing dimensions, oversized data URIs, missing alt
+ * attributes, unsupported formats (WebP, SVG), tracking pixels,
+ * missing display:block, and overall image heaviness.
+ */
+declare function analyzeImages(html: string): ImageReport;
+
+interface AuditOptions {
+    framework?: Framework;
+    /** Options for spam analysis */
+    spam?: SpamAnalysisOptions;
+    /** Skip specific checks */
+    skip?: Array<"spam" | "links" | "accessibility" | "images" | "compatibility">;
+}
+interface AuditReport {
+    compatibility: {
+        warnings: CSSWarning[];
+        scores: Record<string, {
+            score: number;
+            errors: number;
+            warnings: number;
+            info: number;
+        }>;
+    };
+    spam: SpamReport;
+    links: LinkReport;
+    accessibility: AccessibilityReport;
+    images: ImageReport;
+}
+/**
+ * Run all email analysis checks in a single call.
+ *
+ * Returns a unified report with compatibility warnings + scores,
+ * spam analysis, link validation, accessibility audit, and image analysis.
+ * Use the `skip` option to omit checks you don't need.
+ */
+declare function auditEmail(html: string, options?: AuditOptions): AuditReport;
+
+/**
+ * Shared constants used across the engine.
+ */
+/** Maximum HTML input size: 2MB. Inputs exceeding this are rejected early. */
+declare const MAX_HTML_SIZE: number;
+declare const GENERIC_LINK_TEXT: Set<string>;
+
+/**
+ * WCAG 2.1 color parsing, luminance, and contrast utilities.
+ *
+ * Handles hex (#fff, #ffffff, #rrggbbaa), rgb()/rgba(), 148 named CSS colors,
+ * and `transparent`. Returns null for unresolvable values like var(), inherit,
+ * currentColor.
+ */
+interface RGBA {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+type WcagGrade = "AAA" | "AA" | "AA Large" | "Fail";
+/**
+ * Parse a CSS color value to RGBA. Returns null for unresolvable values.
+ */
+declare function parseColor(value: string): RGBA | null;
+/**
+ * Compute WCAG 2.1 relative luminance for an sRGB color.
+ * Input values 0-255.
+ */
+declare function relativeLuminance(r: number, g: number, b: number): number;
+/**
+ * Compute the WCAG contrast ratio between two relative luminances.
+ */
+declare function contrastRatio(l1: number, l2: number): number;
+/**
+ * Determine WCAG 2.1 conformance grade for a contrast ratio.
+ */
+declare function wcagGrade(ratio: number): WcagGrade;
+/**
+ * Alpha-blend a foreground RGBA onto an opaque background (r, g, b 0-255).
+ * Returns the flattened [r, g, b] as 0-255 values.
+ */
+declare function alphaBlend(fg: RGBA, bgR: number, bgG: number, bgB: number): [number, number, number];
+
+export { AI_FIX_SYSTEM_PROMPT, AccessibilityReport, AiFixResult, AiProvider, type AuditOptions, type AuditReport, CSSWarning, CodeFix, DiffResult, EMAIL_CLIENTS, EmailClient, ExportPromptOptions, Framework, GENERIC_LINK_TEXT, type GenerateAiFixOptions, ImageReport, LinkReport, MAX_HTML_SIZE, type RGBA, STRUCTURAL_FIX_PROPERTIES, SpamAnalysisOptions, SpamReport, TransformResult, type WcagGrade, alphaBlend, analyzeEmail, analyzeImages, analyzeSpam, auditEmail, checkAccessibility, contrastRatio, diffResults, errorWarnings, generateAiFix, generateCompatibilityScore, getClient, getCodeFix, getSuggestion, parseColor, relativeLuminance, simulateDarkMode, structuralWarnings, transformForAllClients, transformForClient, validateLinks, warningsForClient, wcagGrade };

package/dist/index.d.ts

@@ -1,233 +1,5 @@
-type ExportScope = "all" | "current";
-interface ExportPromptOptions {
-    originalHtml: string;
-    warnings: CSSWarning[];
-    scores: Record<string, {
-        score: number;
-        errors: number;
-        warnings: number;
-        info: number;
-    }>;
-    scope: ExportScope;
-    selectedClientId?: string;
-    format?: "html" | "jsx" | "mjml" | "maizzle";
-}
-declare function generateFixPrompt(options: ExportPromptOptions): string;
-
-interface TokenEstimate {
-    /** Estimated input tokens (prompt + system prompt) */
-    inputTokens: number;
-    /** Estimated output tokens (fixed code response) */
-    estimatedOutputTokens: number;
-    /** Raw character count of the prompt */
-    promptCharacters: number;
-    /** Character count of just the HTML being fixed */
-    htmlCharacters: number;
-    /** Total warnings included in the prompt */
-    warningCount: number;
-    /** How many warnings are structural (need HTML changes) */
-    structuralCount: number;
-    /** Whether warnings were truncated to fit within limits */
-    truncated: boolean;
-    /** Number of warnings removed during truncation */
-    warningsRemoved: number;
-}
-/**
- * Extended return type from `estimateAiFixTokens()` that includes both the
- * token metrics AND the (potentially truncated) warnings list. The `warnings`
- * field is used internally by `generateAiFix()` to build the prompt with the
- * truncated set, but is NOT exposed in `AiFixResult.tokenEstimate` to keep
- * the public API clean.
- */
-interface TokenEstimateWithWarnings extends TokenEstimate {
-    /** The warnings after smart truncation (may be shorter than the input list) */
-    warnings: CSSWarning[];
-}
-interface EstimateOptions extends Omit<ExportPromptOptions, "warnings"> {
-    warnings: CSSWarning[];
-    /**
-     * Maximum input tokens to target. If the estimated prompt exceeds
-     * this, warnings will be truncated (info first, then duplicates).
-     * Defaults to 16000 (~56KB of prompt text).
-     */
-    maxInputTokens?: number;
-    /**
-     * Optional precise token counter. If provided, it will be called
-     * with the final prompt text for an exact count. Consumers can wire
-     * this to `anthropic.messages.countTokens()`.
-     */
-    tokenCounter?: (text: string) => Promise<number> | number;
-    /**
-     * Token count for the system prompt. Added to the input token estimate
-     * since the system prompt counts against the context window. Defaults
-     * to 250 (matching the built-in AI_FIX_SYSTEM_PROMPT). Set to 0 if
-     * not using a system prompt, or override for custom system prompts.
-     */
-    systemPromptTokens?: number;
-}
-/**
- * Estimate tokens for an AI fix prompt BEFORE making the API call.
- * Use this to show cost estimates, check limits, and decide whether
- * to proceed.
- *
- * @example
- * ```ts
- * const estimate = await estimateAiFixTokens({
- *   originalHtml: html,
- *   warnings,
- *   scores,
- *   scope: "all",
- *   format: "jsx",
- * });
- *
- * console.log(`~${estimate.inputTokens} input tokens`);
- * console.log(`~${estimate.estimatedOutputTokens} output tokens`);
- * console.log(`Truncated: ${estimate.truncated}`);
- * ```
- */
-declare function estimateAiFixTokens(options: EstimateOptions): Promise<TokenEstimateWithWarnings>;
-/**
- * Quick synchronous heuristic token count. No deps, no API calls.
- * Accuracy: within ~10-15% of real Claude tokenizer for code/HTML.
- */
-declare function heuristicTokenCount(text: string): number;
-
-type SupportLevel = "supported" | "partial" | "unsupported" | "unknown";
-type Framework = "jsx" | "mjml" | "maizzle";
-type InputFormat = "html" | Framework;
-interface EmailClient {
-    id: string;
-    name: string;
-    category: "webmail" | "desktop" | "mobile";
-    engine: string;
-    darkModeSupport: boolean;
-    icon: string;
-}
-interface CodeFix {
-    before: string;
-    after: string;
-    language: "html" | "css" | "jsx" | "mjml" | "maizzle";
-    description: string;
-}
-type FixType = "css" | "structural";
-interface CSSWarning {
-    severity: "error" | "warning" | "info";
-    client: string;
-    property: string;
-    message: string;
-    suggestion?: string;
-    fix?: CodeFix;
-    fixIsGenericFallback?: boolean;
-    fixType?: FixType;
-    line?: number;
-    selector?: string;
-}
-/**
- * Callback that sends a prompt to an LLM and returns the text response.
- * Consumers bring their own AI provider (Anthropic SDK, Vercel AI, etc.).
- */
-type AiProvider = (prompt: string) => Promise<string>;
-interface AiFixResult {
-    /** The fixed email code returned by the AI */
-    code: string;
-    /** The raw prompt that was sent to the AI */
-    prompt: string;
-    /** Number of warnings the fix was targeting */
-    targetedWarnings: number;
-    /** How many of those had fixType: "structural" */
-    structuralCount: number;
-    /** Token estimate for the AI call */
-    tokenEstimate: TokenEstimate;
-}
-interface TransformResult {
-    clientId: string;
-    html: string;
-    warnings: CSSWarning[];
-}
-interface PreviewResult {
-    id: string;
-    originalHtml: string;
-    transforms: TransformResult[];
-    cssReport: CSSWarning[];
-    createdAt: string;
-}
-interface DiffResult {
-    clientId: string;
-    scoreBefore: number;
-    scoreAfter: number;
-    scoreDelta: number;
-    fixed: CSSWarning[];
-    introduced: CSSWarning[];
-    unchanged: CSSWarning[];
-}
-interface SpamIssue {
-    rule: string;
-    severity: "error" | "warning" | "info";
-    message: string;
-    detail?: string;
-}
-interface SpamReport {
-    score: number;
-    level: "low" | "medium" | "high";
-    issues: SpamIssue[];
-}
-interface SpamAnalysisOptions {
-    /** Value of the List-Unsubscribe header, if present */
-    listUnsubscribeHeader?: string;
-    /** Type of email — transactional emails are exempt from unsubscribe requirements */
-    emailType?: "marketing" | "transactional";
-}
-interface LinkIssue {
-    severity: "error" | "warning" | "info";
-    rule: string;
-    message: string;
-    href?: string;
-    text?: string;
-}
-interface LinkReport {
-    totalLinks: number;
-    issues: LinkIssue[];
-    breakdown: {
-        https: number;
-        http: number;
-        mailto: number;
-        tel: number;
-        anchor: number;
-        other: number;
-    };
-}
-interface AccessibilityIssue {
-    severity: "error" | "warning" | "info";
-    rule: string;
-    message: string;
-    element?: string;
-    details?: string;
-}
-interface AccessibilityReport {
-    score: number;
-    issues: AccessibilityIssue[];
-}
-interface ImageIssue {
-    rule: string;
-    severity: "error" | "warning" | "info";
-    message: string;
-    src?: string;
-}
-interface ImageInfo {
-    src: string;
-    alt: string | null;
-    width: string | null;
-    height: string | null;
-    isTrackingPixel: boolean;
-    dataUriBytes: number;
-    issues: string[];
-}
-interface ImageReport {
-    total: number;
-    totalDataUriBytes: number;
-    issues: ImageIssue[];
-    images: ImageInfo[];
-}
+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 SpamAnalysisOptions, d as SpamReport, L as LinkReport, e as AccessibilityReport, I as ImageReport } from './react-email-BQljgXbo.js';
+export { f as AccessibilityIssue, g as CompileError, h as CompileReactEmailOptions, i as EstimateOptions, j as ExportScope, k as FixType, l as ImageInfo, m as ImageIssue, n as InputFormat, o as LinkIssue, P as PreviewResult, p as SandboxStrategy, q as SpamIssue, r as SupportLevel, s as TokenEstimate, t as TokenEstimateWithWarnings, u as estimateAiFixTokens, v as generateFixPrompt, w as heuristicTokenCount } from './react-email-BQljgXbo.js';
 
 declare const EMAIL_CLIENTS: EmailClient[];
 declare function getClient(id: string): EmailClient | undefined;
@@ -255,6 +27,12 @@ declare function generateCompatibilityScore(warnings: CSSWarning[]): Record<stri
     warnings: number;
     info: number;
 }>;
+/** Filter warnings for a specific client. */
+declare function warningsForClient(warnings: CSSWarning[], clientId: string): CSSWarning[];
+/** Get only error-severity warnings. */
+declare function errorWarnings(warnings: CSSWarning[]): CSSWarning[];
+/** Get only structural fix warnings. */
+declare function structuralWarnings(warnings: CSSWarning[]): CSSWarning[];
 
 /**
  * Simulate dark mode rendering for an email.
@@ -417,4 +195,79 @@ declare function checkAccessibility(html: string): AccessibilityReport;
  */
 declare function analyzeImages(html: string): ImageReport;
 
-export { AI_FIX_SYSTEM_PROMPT, type AccessibilityIssue, type AccessibilityReport, type AiFixResult, type AiProvider, type CSSWarning, type CodeFix, type DiffResult, EMAIL_CLIENTS, type EmailClient, type EstimateOptions, type ExportPromptOptions, type ExportScope, type FixType, type Framework, type GenerateAiFixOptions, type ImageInfo, type ImageIssue, type ImageReport, type InputFormat, type LinkIssue, type LinkReport, type PreviewResult, STRUCTURAL_FIX_PROPERTIES, type SpamAnalysisOptions, type SpamIssue, type SpamReport, type SupportLevel, type TokenEstimate, type TokenEstimateWithWarnings, type TransformResult, analyzeEmail, analyzeImages, analyzeSpam, checkAccessibility, diffResults, estimateAiFixTokens, generateAiFix, generateCompatibilityScore, generateFixPrompt, getClient, getCodeFix, getSuggestion, heuristicTokenCount, simulateDarkMode, transformForAllClients, transformForClient, validateLinks };
+interface AuditOptions {
+    framework?: Framework;
+    /** Options for spam analysis */
+    spam?: SpamAnalysisOptions;
+    /** Skip specific checks */
+    skip?: Array<"spam" | "links" | "accessibility" | "images" | "compatibility">;
+}
+interface AuditReport {
+    compatibility: {
+        warnings: CSSWarning[];
+        scores: Record<string, {
+            score: number;
+            errors: number;
+            warnings: number;
+            info: number;
+        }>;
+    };
+    spam: SpamReport;
+    links: LinkReport;
+    accessibility: AccessibilityReport;
+    images: ImageReport;
+}
+/**
+ * Run all email analysis checks in a single call.
+ *
+ * Returns a unified report with compatibility warnings + scores,
+ * spam analysis, link validation, accessibility audit, and image analysis.
+ * Use the `skip` option to omit checks you don't need.
+ */
+declare function auditEmail(html: string, options?: AuditOptions): AuditReport;
+
+/**
+ * Shared constants used across the engine.
+ */
+/** Maximum HTML input size: 2MB. Inputs exceeding this are rejected early. */
+declare const MAX_HTML_SIZE: number;
+declare const GENERIC_LINK_TEXT: Set<string>;
+
+/**
+ * WCAG 2.1 color parsing, luminance, and contrast utilities.
+ *
+ * Handles hex (#fff, #ffffff, #rrggbbaa), rgb()/rgba(), 148 named CSS colors,
+ * and `transparent`. Returns null for unresolvable values like var(), inherit,
+ * currentColor.
+ */
+interface RGBA {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+type WcagGrade = "AAA" | "AA" | "AA Large" | "Fail";
+/**
+ * Parse a CSS color value to RGBA. Returns null for unresolvable values.
+ */
+declare function parseColor(value: string): RGBA | null;
+/**
+ * Compute WCAG 2.1 relative luminance for an sRGB color.
+ * Input values 0-255.
+ */
+declare function relativeLuminance(r: number, g: number, b: number): number;
+/**
+ * Compute the WCAG contrast ratio between two relative luminances.
+ */
+declare function contrastRatio(l1: number, l2: number): number;
+/**
+ * Determine WCAG 2.1 conformance grade for a contrast ratio.
+ */
+declare function wcagGrade(ratio: number): WcagGrade;
+/**
+ * Alpha-blend a foreground RGBA onto an opaque background (r, g, b 0-255).
+ * Returns the flattened [r, g, b] as 0-255 values.
+ */
+declare function alphaBlend(fg: RGBA, bgR: number, bgG: number, bgB: number): [number, number, number];
+
+export { AI_FIX_SYSTEM_PROMPT, AccessibilityReport, AiFixResult, AiProvider, type AuditOptions, type AuditReport, CSSWarning, CodeFix, DiffResult, EMAIL_CLIENTS, EmailClient, ExportPromptOptions, Framework, GENERIC_LINK_TEXT, type GenerateAiFixOptions, ImageReport, LinkReport, MAX_HTML_SIZE, type RGBA, STRUCTURAL_FIX_PROPERTIES, SpamAnalysisOptions, SpamReport, TransformResult, type WcagGrade, alphaBlend, analyzeEmail, analyzeImages, analyzeSpam, auditEmail, checkAccessibility, contrastRatio, diffResults, errorWarnings, generateAiFix, generateCompatibilityScore, getClient, getCodeFix, getSuggestion, parseColor, relativeLuminance, simulateDarkMode, structuralWarnings, transformForAllClients, transformForClient, validateLinks, warningsForClient, wcagGrade };