@emailens/engine 0.1.0 → 0.3.0

package/README.md

@@ -218,9 +218,107 @@ Look up a client by ID.
 | HEY Mail | `hey-mail` | Webmail | WebKit | Yes |
 | Superhuman | `superhuman` | Desktop | Blink | Yes |
 
+## AI-Powered Fixes (v0.2.0)
+
+The engine classifies every warning as either `css` (CSS-only swap) or `structural` (requires HTML restructuring — tables, VML, conditionals). For structural issues that static snippets can't solve, the engine can generate a structured prompt and delegate to an LLM.
+
+The engine is **provider-agnostic** — you bring your own AI provider via a simple callback.
+
+### `generateAiFix(options): Promise<AiFixResult>`
+
+Builds a fix prompt from the engine's analysis, sends it to your AI provider, and extracts the fixed code.
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+import {
+  analyzeEmail,
+  generateCompatibilityScore,
+  generateAiFix,
+  AI_FIX_SYSTEM_PROMPT,
+} from "@emailens/engine";
+
+const anthropic = new Anthropic();
+const warnings = analyzeEmail(html, "jsx");
+const scores = generateCompatibilityScore(warnings);
+
+const result = await generateAiFix({
+  originalHtml: html,
+  warnings,
+  scores,
+  scope: "all",        // or "current" with selectedClientId
+  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 : "";
+  },
+});
+
+console.log(result.code);              // Fixed email code
+console.log(result.targetedWarnings);  // 23
+console.log(result.structuralCount);   // 5
+```
+
+### `estimateAiFixTokens(options): Promise<TokenEstimate>`
+
+Estimate tokens **before** making an API call. Use for cost estimates, limit checks, and UI feedback.
+
+```typescript
+import { estimateAiFixTokens } from "@emailens/engine";
+
+const estimate = await estimateAiFixTokens({
+  originalHtml: html,
+  warnings,
+  scores,
+  scope: "all",
+  format: "jsx",
+  maxInputTokens: 16000,  // optional, triggers smart truncation
+});
+
+console.log(`~${estimate.inputTokens} input tokens`);
+console.log(`~${estimate.estimatedOutputTokens} output tokens`);
+console.log(`${estimate.warningCount} warnings (${estimate.structuralCount} structural)`);
+console.log(`Truncated: ${estimate.truncated}`);
+```
+
+**Smart truncation** kicks in when the prompt exceeds `maxInputTokens`:
+1. Deduplicates warnings (same property × severity)
+2. Removes `info`-level warnings
+3. Removes CSS-only warnings (keeps structural + errors)
+4. Trims long fix snippets
+
+### `heuristicTokenCount(text): number`
+
+Instant synchronous token estimate (~3.5 chars/token). Within ~10-15% of real Claude tokenizer for HTML/CSS.
+
+```typescript
+import { heuristicTokenCount } from "@emailens/engine";
+const tokens = heuristicTokenCount(html); // instant, no deps
+```
+
+### `AI_FIX_SYSTEM_PROMPT`
+
+Expert system prompt for email compatibility fixes. Pass as the `system` parameter to your LLM call for best results. Includes structural fix patterns (table layouts, VML, MSO conditionals).
+
+### `STRUCTURAL_FIX_PROPERTIES`
+
+`Set<string>` of CSS properties that require HTML restructuring (not just CSS swaps). Includes `display:flex`, `display:grid`, `word-break`, `position`, `border-radius` (Outlook), `background-image` (Outlook), and more.
+
+```typescript
+import { STRUCTURAL_FIX_PROPERTIES } from "@emailens/engine";
+STRUCTURAL_FIX_PROPERTIES.has("word-break"); // true
+STRUCTURAL_FIX_PROPERTIES.has("color");      // false
+```
+
 ## CSS Support Matrix
 
-The engine includes a comprehensive CSS support matrix (`src/rules/css-support.ts`) covering 30+ CSS properties and HTML elements across all 12 clients. Data sourced from [caniemail.com](https://www.caniemail.com/) with inferred values for HEY Mail and Superhuman based on their rendering engines.
+The engine includes a comprehensive CSS support matrix (`src/rules/css-support.ts`) covering 45+ CSS properties and HTML elements across all 12 clients. Data sourced from [caniemail.com](https://www.caniemail.com/) with inferred values for HEY Mail and Superhuman based on their rendering engines.
+
+Properties added in v0.2.0: `word-break`, `overflow-wrap`, `white-space`, `text-overflow`, `vertical-align`, `border-spacing`, `min-width`, `min-height`, `max-height`, `text-shadow`, `background-size`, `background-position`.
 
 ## Types
 
@@ -228,6 +326,8 @@ The engine includes a comprehensive CSS support matrix (`src/rules/css-support.t
 type SupportLevel = "supported" | "partial" | "unsupported" | "unknown";
 type Framework = "jsx" | "mjml" | "maizzle";
 type InputFormat = "html" | Framework;
+type FixType = "css" | "structural";
+type AiProvider = (prompt: string) => Promise<string>;
 
 interface EmailClient {
   id: string;
@@ -246,6 +346,7 @@ interface CSSWarning {
   suggestion?: string;
   fix?: CodeFix;
   fixIsGenericFallback?: boolean;
+  fixType?: FixType;           // "css" or "structural" (v0.2.0)
 }
 
 interface CodeFix {
@@ -255,6 +356,25 @@ interface CodeFix {
   description: string;
 }
 
+interface AiFixResult {
+  code: string;
+  prompt: string;
+  targetedWarnings: number;
+  structuralCount: number;
+  tokenEstimate: TokenEstimate;
+}
+
+interface TokenEstimate {
+  inputTokens: number;
+  estimatedOutputTokens: number;
+  promptCharacters: number;
+  htmlCharacters: number;
+  warningCount: number;
+  structuralCount: number;
+  truncated: boolean;
+  warningsRemoved: number;
+}
+
 interface TransformResult {
   clientId: string;
   html: string;
@@ -278,7 +398,7 @@ interface DiffResult {
 bun test
 ```
 
-95 tests covering analysis, transformation, dark mode simulation, framework-aware fixes, edge cases, and accuracy benchmarks against real-world email templates.
+166 tests covering analysis, transformation, dark mode simulation, framework-aware fixes, AI fix generation, token estimation, smart truncation, fixType classification, and accuracy benchmarks against real-world email templates.
 
 ## License
 

package/dist/index.d.ts

@@ -1,3 +1,97 @@
+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;
@@ -15,6 +109,7 @@ interface CodeFix {
     language: "html" | "css" | "jsx" | "mjml" | "maizzle";
     description: string;
 }
+type FixType = "css" | "structural";
 interface CSSWarning {
     severity: "error" | "warning" | "info";
     client: string;
@@ -23,9 +118,27 @@ interface CSSWarning {
     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;
@@ -47,6 +160,68 @@ interface DiffResult {
     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 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[];
+}
 
 declare const EMAIL_CLIENTS: EmailClient[];
 declare function getClient(id: string): EmailClient | undefined;
@@ -137,20 +312,103 @@ declare function diffResults(before: {
     warnings: CSSWarning[];
 }): DiffResult[];
 
-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";
+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;
 }
-declare function generateFixPrompt(options: ExportPromptOptions): string;
+/**
+ * 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): 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;
 
-export { type CSSWarning, type CodeFix, type DiffResult, EMAIL_CLIENTS, type EmailClient, type ExportPromptOptions, type ExportScope, type Framework, type InputFormat, type PreviewResult, type SupportLevel, type TransformResult, analyzeEmail, diffResults, generateCompatibilityScore, generateFixPrompt, getClient, getCodeFix, getSuggestion, simulateDarkMode, transformForAllClients, transformForClient };
+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 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 };