@emailens/engine 0.5.2 → 0.7.0

package/dist/index.cjs

@@ -71,10 +71,14 @@ __export(index_exports, {
   analyzeSpam: () => analyzeSpam,
   auditEmail: () => auditEmail,
   checkAccessibility: () => checkAccessibility,
+  checkSize: () => checkSize,
+  checkTemplateVariables: () => checkTemplateVariables,
   contrastRatio: () => contrastRatio,
+  createSession: () => createSession,
   diffResults: () => diffResults,
   errorWarnings: () => errorWarnings,
   estimateAiFixTokens: () => estimateAiFixTokens,
+  extractInboxPreview: () => extractInboxPreview,
   generateAiFix: () => generateAiFix,
   generateCompatibilityScore: () => generateCompatibilityScore,
   generateFixPrompt: () => generateFixPrompt,
@@ -2836,6 +2840,43 @@ var GENERIC_LINK_TEXT = /* @__PURE__ */ new Set([
   "tap here",
   "this"
 ]);
+var GMAIL_CLIP_THRESHOLD = 102 * 1024;
+var GMAIL_CLIP_WARNING_THRESHOLD = 90 * 1024;
+var CLIENT_DISPLAY_LIMITS = [
+  { client: "Gmail (Web)", subjectLimit: 70, preheaderLimit: 90 },
+  { client: "Gmail (Mobile)", subjectLimit: 40, preheaderLimit: 90 },
+  { client: "Outlook (Web)", subjectLimit: 60, preheaderLimit: 35 },
+  { client: "Outlook (Desktop)", subjectLimit: 55, preheaderLimit: 35 },
+  { client: "Apple Mail (macOS)", subjectLimit: 78, preheaderLimit: 140 },
+  { client: "Apple Mail (iOS)", subjectLimit: 35, preheaderLimit: 90 },
+  { client: "Yahoo Mail", subjectLimit: 46, preheaderLimit: 100 },
+  { client: "Samsung Email", subjectLimit: 40, preheaderLimit: 70 }
+];
+var TEMPLATE_VARIABLE_PATTERNS = [
+  [/\{\{[\s\S]*?\}\}/g, "Handlebars/Mustache"],
+  // {{var}}
+  [/\$\{[^}]+\}/g, "ES template literal"],
+  // ${var}
+  [/<%=?\s*[^%]+%>/g, "ERB/EJS"],
+  // <% %> / <%= %>
+  [/\*\|[A-Z_][A-Z0-9_]*\|\*/g, "Mailchimp merge tag"],
+  // *|TAG|*
+  [/%%[A-Za-z_][A-Za-z0-9_]*%%/g, "Salesforce AMPscript"],
+  // %%tag%%
+  [/\{[A-Za-z_][A-Za-z0-9_.]{2,}\}/g, "Single-brace merge field"]
+  // {merge_field} (3+ char names)
+];
+var EMPTY_SPAM = { score: 100, level: "low", issues: [] };
+var EMPTY_LINKS = {
+  totalLinks: 0,
+  issues: [],
+  breakdown: { https: 0, http: 0, mailto: 0, tel: 0, anchor: 0, javascript: 0, protocolRelative: 0, other: 0 }
+};
+var EMPTY_ACCESSIBILITY = { score: 100, issues: [] };
+var EMPTY_IMAGES = { total: 0, totalDataUriBytes: 0, issues: [], images: [] };
+var EMPTY_INBOX_PREVIEW = { subject: null, preheader: null, subjectLength: 0, preheaderLength: 0, truncation: [], issues: [] };
+var EMPTY_SIZE = { htmlBytes: 0, humanSize: "0 B", clipped: false, issues: [] };
+var EMPTY_TEMPLATE = { unresolvedCount: 0, issues: [] };
 
 // src/transform.ts
 function inlineStyles($) {
@@ -3344,15 +3385,8 @@ function transformForAllClients(html, framework) {
 // src/analyze.ts
 var cheerio2 = __toESM(require("cheerio"), 1);
 var csstree2 = __toESM(require("css-tree"), 1);
-function analyzeEmail(html, framework) {
+function analyzeEmailFromDom($, framework) {
   var _a, _b, _c, _d, _e, _f, _g;
-  if (!html || !html.trim()) {
-    return [];
-  }
-  if (html.length > MAX_HTML_SIZE) {
-    throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
-  }
-  const $ = cheerio2.load(html);
   const warnings = [];
   const seenWarnings = /* @__PURE__ */ new Set();
   function addWarning(w) {
@@ -3597,6 +3631,16 @@ function analyzeEmail(html, framework) {
   warnings.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
   return warnings;
 }
+function analyzeEmail(html, framework) {
+  if (!html || !html.trim()) {
+    return [];
+  }
+  if (html.length > MAX_HTML_SIZE) {
+    throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
+  }
+  const $ = cheerio2.load(html);
+  return analyzeEmailFromDom($, framework);
+}
 function getFixType(prop) {
   return STRUCTURAL_FIX_PROPERTIES.has(prop) ? "structural" : "css";
 }
@@ -4495,7 +4539,9 @@ var WEIGHTS = {
   "image-only": 20,
   "high-image-ratio": 10,
   "deceptive-link": 15,
-  "all-caps-subject": 10
+  "all-caps-subject": 10,
+  "missing-physical-address": 8,
+  "missing-one-click-unsubscribe": 5
 };
 function extractVisibleText($) {
   const clone = $.root().clone();
@@ -4712,6 +4758,47 @@ Href: ${href}`
   });
   return issues;
 }
+var STREET_ADDRESS_PATTERN = /\b\d{1,5}\s+[A-Za-z]+\s+(St(reet)?|Ave(nue)?|Blvd|Boulevard|Dr(ive)?|Rd|Road|Ln|Lane|Way|Ct|Court|Pl(ace)?|Pkwy|Parkway|Cir(cle)?|Terr(ace)?|Loop)\b/i;
+var PO_BOX_PATTERN = /\bP\.?\s*O\.?\s*Box\s+\d+/i;
+var ZIP_CODE_PATTERN = /\b\d{5}(-\d{4})?\b/;
+var ADDRESS_CLASS_PATTERN = /address|mailing|postal|footer-address|physical-address/i;
+function checkPhysicalAddress($, text, options) {
+  if ((options == null ? void 0 : options.emailType) === "transactional") return null;
+  if (STREET_ADDRESS_PATTERN.test(text) && ZIP_CODE_PATTERN.test(text)) return null;
+  if (PO_BOX_PATTERN.test(text) && ZIP_CODE_PATTERN.test(text)) return null;
+  let foundByClass = false;
+  $("[class]").each((_, el) => {
+    const cls = $(el).attr("class") || "";
+    if (ADDRESS_CLASS_PATTERN.test(cls)) {
+      const elText = $(el).text().trim();
+      if (elText.length > 5) {
+        foundByClass = true;
+        return false;
+      }
+    }
+  });
+  if (foundByClass) return null;
+  if ($("address").length > 0 && $("address").text().trim().length > 5) return null;
+  return {
+    rule: "missing-physical-address",
+    severity: "warning",
+    message: "No physical mailing address detected \u2014 required by CAN-SPAM for marketing emails.",
+    detail: "Include a street address or P.O. Box in the email footer."
+  };
+}
+function checkOneClickUnsubscribe(options) {
+  var _a, _b;
+  if (!((_a = options == null ? void 0 : options.listUnsubscribeHeader) == null ? void 0 : _a.trim())) return null;
+  if (!((_b = options == null ? void 0 : options.listUnsubscribePostHeader) == null ? void 0 : _b.trim())) {
+    return {
+      rule: "missing-one-click-unsubscribe",
+      severity: "warning",
+      message: "List-Unsubscribe header present but missing List-Unsubscribe-Post header (RFC 8058). Gmail and Yahoo require one-click unsubscribe.",
+      detail: 'Add "List-Unsubscribe-Post: List-Unsubscribe=One-Click" header.'
+    };
+  }
+  return null;
+}
 function checkAllCapsTitle($) {
   const title = $("title").text().trim();
   if (title.length > 5 && title === title.toUpperCase() && /[A-Z]/.test(title)) {
@@ -4723,14 +4810,7 @@ function checkAllCapsTitle($) {
   }
   return null;
 }
-function analyzeSpam(html, options) {
-  if (!html || !html.trim()) {
-    return { score: 100, level: "low", issues: [] };
-  }
-  if (html.length > MAX_HTML_SIZE) {
-    throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
-  }
-  const $ = cheerio4.load(html);
+function analyzeSpamFromDom($, options) {
   const text = extractVisibleText($);
   const issues = [];
   const capsIssue = checkCapsRatio(text);
@@ -4748,6 +4828,10 @@ function analyzeSpam(html, options) {
   issues.push(...checkDeceptiveLinks($));
   const capsTitle = checkAllCapsTitle($);
   if (capsTitle) issues.push(capsTitle);
+  const addressIssue = checkPhysicalAddress($, text, options);
+  if (addressIssue) issues.push(addressIssue);
+  const oneClickIssue = checkOneClickUnsubscribe(options);
+  if (oneClickIssue) issues.push(oneClickIssue);
   let penalty = 0;
   const seenRules = /* @__PURE__ */ new Map();
   for (const issue of issues) {
@@ -4768,6 +4852,16 @@ function analyzeSpam(html, options) {
   const level = score >= 70 ? "low" : score >= 40 ? "medium" : "high";
   return { score, level, issues };
 }
+function analyzeSpam(html, options) {
+  if (!html || !html.trim()) {
+    return { score: 100, level: "low", issues: [] };
+  }
+  if (html.length > MAX_HTML_SIZE) {
+    throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
+  }
+  const $ = cheerio4.load(html);
+  return analyzeSpamFromDom($, options);
+}
 
 // src/link-validator.ts
 var cheerio5 = __toESM(require("cheerio"), 1);
@@ -4787,18 +4881,7 @@ function isPlaceholderHref(href) {
   const h = href.trim().toLowerCase();
   return h === "#" || h === "" || h === "javascript:void(0)" || h === "javascript:;";
 }
-function validateLinks(html) {
-  if (!html || !html.trim()) {
-    return {
-      totalLinks: 0,
-      issues: [],
-      breakdown: { https: 0, http: 0, mailto: 0, tel: 0, anchor: 0, javascript: 0, protocolRelative: 0, other: 0 }
-    };
-  }
-  if (html.length > MAX_HTML_SIZE) {
-    throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
-  }
-  const $ = cheerio5.load(html);
+function validateLinksFromDom($) {
   const issues = [];
   const breakdown = { https: 0, http: 0, mailto: 0, tel: 0, anchor: 0, javascript: 0, protocolRelative: 0, other: 0 };
   const links = $("a");
@@ -4937,6 +5020,23 @@ function validateLinks(html) {
       });
     }
   });
+  links.each((_, el) => {
+    const href = $(el).attr("href") || "";
+    const trimmed = href.trim();
+    if (trimmed.startsWith("#") && trimmed.length > 1) {
+      const targetId = trimmed.slice(1);
+      const target = $(`[id="${targetId}"]`);
+      if (target.length === 0) {
+        issues.push({
+          severity: "error",
+          rule: "broken-anchor",
+          message: `Anchor link "${trimmed}" points to an element that does not exist`,
+          href: trimmed,
+          text: $(el).text().trim().slice(0, 80) || "(no text)"
+        });
+      }
+    }
+  });
   for (const [href, count] of hrefCounts) {
     if (count > 5) {
       issues.push({
@@ -4949,6 +5049,20 @@ function validateLinks(html) {
   }
   return { totalLinks, issues, breakdown };
 }
+function validateLinks(html) {
+  if (!html || !html.trim()) {
+    return {
+      totalLinks: 0,
+      issues: [],
+      breakdown: { https: 0, http: 0, mailto: 0, tel: 0, anchor: 0, javascript: 0, protocolRelative: 0, other: 0 }
+    };
+  }
+  if (html.length > MAX_HTML_SIZE) {
+    throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
+  }
+  const $ = cheerio5.load(html);
+  return validateLinksFromDom($);
+}
 
 // src/accessibility-checker.ts
 var cheerio6 = __toESM(require("cheerio"), 1);
@@ -5176,6 +5290,21 @@ function checkTextSizeAndContrast($) {
   }
   return issues;
 }
+function checkCharsetDeclaration($) {
+  const metaCharset = $("meta[charset]");
+  if (metaCharset.length > 0) return null;
+  const httpEquiv = $('meta[http-equiv="Content-Type"]');
+  if (httpEquiv.length > 0) {
+    const content = httpEquiv.attr("content") || "";
+    if (/charset\s*=/i.test(content)) return null;
+  }
+  return {
+    severity: "warning",
+    rule: "missing-charset",
+    message: "Missing charset declaration",
+    details: 'Add <meta charset="utf-8"> in <head> to prevent encoding issues across email clients.'
+  };
+}
 function checkSemanticStructure($) {
   const issues = [];
   const headings = [];
@@ -5197,14 +5326,7 @@ function checkSemanticStructure($) {
   }
   return issues;
 }
-function checkAccessibility(html) {
-  if (!html || !html.trim()) {
-    return { score: 100, issues: [] };
-  }
-  if (html.length > MAX_HTML_SIZE) {
-    throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
-  }
-  const $ = cheerio6.load(html);
+function checkAccessibilityFromDom($) {
   const issues = [];
   const langIssue = checkLangAttribute($);
   if (langIssue) issues.push(langIssue);
@@ -5215,6 +5337,8 @@ function checkAccessibility(html) {
   issues.push(...checkTableAccessibility($));
   issues.push(...checkTextSizeAndContrast($));
   issues.push(...checkSemanticStructure($));
+  const charsetIssue = checkCharsetDeclaration($);
+  if (charsetIssue) issues.push(charsetIssue);
   let penalty = 0;
   const seenRules = /* @__PURE__ */ new Map();
   for (const issue of issues) {
@@ -5237,6 +5361,16 @@ function checkAccessibility(html) {
   const score = Math.max(0, 100 - penalty);
   return { score, issues };
 }
+function checkAccessibility(html) {
+  if (!html || !html.trim()) {
+    return { score: 100, issues: [] };
+  }
+  if (html.length > MAX_HTML_SIZE) {
+    throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
+  }
+  const $ = cheerio6.load(html);
+  return checkAccessibilityFromDom($);
+}
 
 // src/image-analyzer.ts
 var cheerio7 = __toESM(require("cheerio"), 1);
@@ -5270,14 +5404,7 @@ function truncateSrc(src, max = 60) {
   }
   return src.length > max ? src.slice(0, max - 3) + "..." : src;
 }
-function analyzeImages(html) {
-  if (!html || !html.trim()) {
-    return { total: 0, totalDataUriBytes: 0, issues: [], images: [] };
-  }
-  if (html.length > MAX_HTML_SIZE) {
-    throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
-  }
-  const $ = cheerio7.load(html);
+function analyzeImagesFromDom($) {
   const issues = [];
   const images = [];
   let totalDataUriBytes = 0;
@@ -5403,16 +5530,318 @@ function analyzeImages(html) {
   }
   return { total: images.length, totalDataUriBytes, issues, images };
 }
+function analyzeImages(html) {
+  if (!html || !html.trim()) {
+    return { total: 0, totalDataUriBytes: 0, issues: [], images: [] };
+  }
+  if (html.length > MAX_HTML_SIZE) {
+    throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
+  }
+  const $ = cheerio7.load(html);
+  return analyzeImagesFromDom($);
+}
+
+// src/inbox-preview.ts
+var cheerio8 = __toESM(require("cheerio"), 1);
+var MAX_SUBJECT_LENGTH = 60;
+var MAX_PREHEADER_LENGTH = 100;
+var MIN_PREHEADER_LENGTH = 30;
+var EMOJI_PATTERN = /[\u{1F600}-\u{1F64F}\u{1F300}-\u{1F5FF}\u{1F680}-\u{1F6FF}\u{1F1E0}-\u{1F1FF}\u{2600}-\u{26FF}\u{2700}-\u{27BF}\u{2B50}-\u{2B55}\u{FE00}-\u{FE0F}\u{1F900}-\u{1F9FF}\u{1FA00}-\u{1FA6F}\u{1FA70}-\u{1FAFF}\u{200D}\u{20E3}\u{E0020}-\u{E007F}]/u;
+var ZWNJ_PADDING_PATTERN = /(\u200C\s*(&nbsp;|\u00A0)\s*){2,}|(&zwnj;\s*&nbsp;\s*){2,}/;
+function extractInboxPreview(html) {
+  if (!html || !html.trim()) {
+    return {
+      subject: null,
+      preheader: null,
+      subjectLength: 0,
+      preheaderLength: 0,
+      truncation: [],
+      issues: [{ rule: "missing-subject", severity: "warning", message: "No <title> tag found. Most email clients use this as the subject line." }]
+    };
+  }
+  if (html.length > MAX_HTML_SIZE) {
+    throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
+  }
+  const $ = cheerio8.load(html);
+  return extractInboxPreviewFromDom($);
+}
+function extractInboxPreviewFromDom($) {
+  var _a, _b;
+  const issues = [];
+  const titleEl = $("title");
+  const subject = titleEl.length > 0 ? titleEl.first().text().trim() || null : null;
+  const subjectLength = (_a = subject == null ? void 0 : subject.length) != null ? _a : 0;
+  if (!subject) {
+    issues.push({
+      rule: "missing-subject",
+      severity: "warning",
+      message: "No <title> tag found. Most email clients use this as the subject line."
+    });
+  } else if (subjectLength > MAX_SUBJECT_LENGTH) {
+    issues.push({
+      rule: "subject-too-long",
+      severity: "warning",
+      message: `Subject is ${subjectLength} characters \u2014 may be truncated in inboxes (recommended: ${MAX_SUBJECT_LENGTH} or fewer).`
+    });
+  }
+  const preheader = extractPreheaderText($);
+  const preheaderLength = (_b = preheader == null ? void 0 : preheader.length) != null ? _b : 0;
+  if (!preheader) {
+    issues.push({
+      rule: "missing-preheader",
+      severity: "info",
+      message: "No preheader text detected. Adding preview text improves open rates in crowded inboxes."
+    });
+  } else if (preheaderLength < MIN_PREHEADER_LENGTH) {
+    issues.push({
+      rule: "preheader-too-short",
+      severity: "warning",
+      message: `Preheader is only ${preheaderLength} characters \u2014 email clients may backfill with body text (recommended: ${MIN_PREHEADER_LENGTH}+).`
+    });
+  } else if (preheaderLength > MAX_PREHEADER_LENGTH) {
+    issues.push({
+      rule: "preheader-too-long",
+      severity: "info",
+      message: `Preheader is ${preheaderLength} characters \u2014 most clients show 40\u2013100 characters. Text beyond that is hidden.`
+    });
+  }
+  if (hasZwnjPadding($)) {
+    issues.push({
+      rule: "zwnj-padding",
+      severity: "info",
+      message: "Preheader uses &zwnj;&nbsp; padding hack \u2014 works in most clients but may show garbled text in some."
+    });
+  }
+  if (subject && EMOJI_PATTERN.test(subject)) {
+    issues.push({
+      rule: "emoji-in-subject",
+      severity: "info",
+      message: "Subject line contains emoji \u2014 renders inconsistently across email clients and may trigger spam filters."
+    });
+  }
+  const truncation = computeTruncation(subject, preheader);
+  return {
+    subject,
+    preheader,
+    subjectLength,
+    preheaderLength,
+    truncation,
+    issues
+  };
+}
+function computeTruncation(subject, preheader) {
+  return CLIENT_DISPLAY_LIMITS.map((limit) => {
+    const truncatedSubject = subject && subject.length > limit.subjectLimit ? subject.slice(0, limit.subjectLimit - 1) + "\u2026" : subject;
+    const truncatedPreheader = preheader && preheader.length > limit.preheaderLimit ? preheader.slice(0, limit.preheaderLimit - 1) + "\u2026" : preheader;
+    return {
+      client: limit.client,
+      subjectLimit: limit.subjectLimit,
+      preheaderLimit: limit.preheaderLimit,
+      truncatedSubject: truncatedSubject != null ? truncatedSubject : null,
+      truncatedPreheader: truncatedPreheader != null ? truncatedPreheader : null,
+      subjectTruncated: !!subject && subject.length > limit.subjectLimit,
+      preheaderTruncated: !!preheader && preheader.length > limit.preheaderLimit
+    };
+  });
+}
+function hasZwnjPadding($) {
+  const body = $("body");
+  if (!body.length) return false;
+  const hiddenSelectors = [
+    'div[style*="display:none"]',
+    'div[style*="display: none"]',
+    'span[style*="display:none"]',
+    'span[style*="display: none"]',
+    'div[style*="max-height:0"]',
+    'div[style*="max-height: 0"]',
+    'span[style*="max-height:0"]',
+    'span[style*="max-height: 0"]',
+    '[class*="preheader"]',
+    '[class*="preview-text"]',
+    '[class*="previewText"]'
+  ];
+  for (const sel of hiddenSelectors) {
+    const el = body.find(sel).first();
+    if (el.length) {
+      const rawHtml = el.html() || "";
+      if (ZWNJ_PADDING_PATTERN.test(rawHtml)) return true;
+    }
+  }
+  return false;
+}
+function extractPreheaderText($) {
+  const body = $("body");
+  if (!body.length) return null;
+  const hiddenSelectors = [
+    'div[style*="display:none"]',
+    'div[style*="display: none"]',
+    'span[style*="display:none"]',
+    'span[style*="display: none"]',
+    'div[style*="visibility:hidden"]',
+    'div[style*="visibility: hidden"]',
+    'span[style*="visibility:hidden"]',
+    'span[style*="visibility: hidden"]',
+    'div[style*="max-height:0"]',
+    'div[style*="max-height: 0"]',
+    'span[style*="max-height:0"]',
+    'span[style*="max-height: 0"]',
+    'div[style*="mso-hide:all"]',
+    'div[style*="mso-hide: all"]'
+  ];
+  for (const sel of hiddenSelectors) {
+    const el = body.find(sel).first();
+    if (el.length) {
+      const text = el.text().trim();
+      if (text) return text;
+    }
+  }
+  const preheaderClasses = body.find(
+    '[class*="preheader"], [class*="preview-text"], [class*="previewText"]'
+  ).first();
+  if (preheaderClasses.length) {
+    const text = preheaderClasses.text().trim();
+    if (text) return text;
+  }
+  const firstText = getFirstVisibleText($, body);
+  return firstText || null;
+}
+function getFirstVisibleText($, body) {
+  const skipTags = /* @__PURE__ */ new Set(["style", "script", "head", "title"]);
+  let result = null;
+  body.find("*").each((_, el) => {
+    var _a;
+    if (result) return false;
+    const tagName = (_a = el.tagName) == null ? void 0 : _a.toLowerCase();
+    if (skipTags.has(tagName)) return;
+    const style = $(el).attr("style") || "";
+    if (style.includes("display:none") || style.includes("display: none") || style.includes("visibility:hidden") || style.includes("visibility: hidden")) {
+      return;
+    }
+    const directText = $(el).contents().filter((_2, node) => node.type === "text").text().trim();
+    if (directText && directText.length > 1) {
+      const cleaned = directText.replace(/[\u200B\u00A0\s]+/g, " ").trim();
+      if (cleaned.length > 1) {
+        result = cleaned;
+        return false;
+      }
+    }
+  });
+  return result;
+}
+
+// src/size-checker.ts
+var cheerio9 = __toESM(require("cheerio"), 1);
+function humanizeBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  const kb = bytes / 1024;
+  if (kb < 1024) return `${kb.toFixed(1)} KB`;
+  const mb = kb / 1024;
+  return `${mb.toFixed(2)} MB`;
+}
+function checkSizeFromDom(_$, html) {
+  const htmlBytes = new TextEncoder().encode(html).length;
+  const humanSize = humanizeBytes(htmlBytes);
+  const issues = [];
+  let clipped = false;
+  if (htmlBytes > GMAIL_CLIP_THRESHOLD) {
+    clipped = true;
+    issues.push({
+      rule: "gmail-clipped",
+      severity: "error",
+      message: `Email is ${humanSize} \u2014 Gmail will clip it at ~102 KB. Recipients see a "View entire message" link instead of your content.`,
+      detail: `${htmlBytes} bytes exceeds the ${GMAIL_CLIP_THRESHOLD} byte threshold.`
+    });
+  } else if (htmlBytes > GMAIL_CLIP_WARNING_THRESHOLD) {
+    issues.push({
+      rule: "gmail-clip-warning",
+      severity: "warning",
+      message: `Email is ${humanSize} \u2014 approaching Gmail's ~102 KB clip threshold. Consider trimming.`,
+      detail: `${htmlBytes} bytes is within ${GMAIL_CLIP_THRESHOLD - htmlBytes} bytes of the clip threshold.`
+    });
+  }
+  return { htmlBytes, humanSize, clipped, issues };
+}
+function checkSize(html) {
+  if (!html || !html.trim()) {
+    return { htmlBytes: 0, humanSize: "0 B", clipped: false, issues: [] };
+  }
+  if (html.length > MAX_HTML_SIZE) {
+    throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
+  }
+  const $ = cheerio9.load(html);
+  return checkSizeFromDom($, html);
+}
+
+// src/template-checker.ts
+var cheerio10 = __toESM(require("cheerio"), 1);
+function checkTemplateVariablesFromDom($) {
+  const issues = [];
+  const seen = /* @__PURE__ */ new Set();
+  const textContent = extractTextContent($);
+  for (const [pattern, label] of TEMPLATE_VARIABLE_PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(textContent)) !== null) {
+      const variable = match[0];
+      const key = `text:${variable}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      issues.push({
+        rule: "unresolved-variable",
+        severity: "error",
+        message: `Unresolved ${label} variable "${variable}" found in text content.`,
+        variable,
+        location: "text"
+      });
+    }
+  }
+  const attrSelectors = ["[href]", "[src]", "[alt]"];
+  for (const sel of attrSelectors) {
+    $(sel).each((_, el) => {
+      const attrs = ["href", "src", "alt"];
+      for (const attr of attrs) {
+        const value = $(el).attr(attr);
+        if (!value) continue;
+        for (const [pattern, label] of TEMPLATE_VARIABLE_PATTERNS) {
+          pattern.lastIndex = 0;
+          let match;
+          while ((match = pattern.exec(value)) !== null) {
+            const variable = match[0];
+            const key = `attr:${attr}:${variable}`;
+            if (seen.has(key)) continue;
+            seen.add(key);
+            issues.push({
+              rule: "unresolved-variable",
+              severity: "error",
+              message: `Unresolved ${label} variable "${variable}" found in ${attr} attribute.`,
+              variable,
+              location: "attribute"
+            });
+          }
+        }
+      }
+    });
+  }
+  return { unresolvedCount: issues.length, issues };
+}
+function extractTextContent($) {
+  const clone = $.root().clone();
+  clone.find("style, script, head").remove();
+  return clone.text();
+}
+function checkTemplateVariables(html) {
+  if (!html || !html.trim()) {
+    return { unresolvedCount: 0, issues: [] };
+  }
+  if (html.length > MAX_HTML_SIZE) {
+    throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
+  }
+  const $ = cheerio10.load(html);
+  return checkTemplateVariablesFromDom($);
+}
 
 // src/audit.ts
-var EMPTY_SPAM = { score: 100, level: "low", issues: [] };
-var EMPTY_LINKS = {
-  totalLinks: 0,
-  issues: [],
-  breakdown: { https: 0, http: 0, mailto: 0, tel: 0, anchor: 0, javascript: 0, protocolRelative: 0, other: 0 }
-};
-var EMPTY_ACCESSIBILITY = { score: 100, issues: [] };
-var EMPTY_IMAGES = { total: 0, totalDataUriBytes: 0, issues: [], images: [] };
+var cheerio11 = __toESM(require("cheerio"), 1);
 function auditEmail(html, options) {
   var _a;
   if (!html || !html.trim()) {
@@ -5421,7 +5850,10 @@ function auditEmail(html, options) {
       spam: EMPTY_SPAM,
       links: EMPTY_LINKS,
       accessibility: EMPTY_ACCESSIBILITY,
-      images: EMPTY_IMAGES
+      images: EMPTY_IMAGES,
+      inboxPreview: EMPTY_INBOX_PREVIEW,
+      size: EMPTY_SIZE,
+      templateVariables: EMPTY_TEMPLATE
     };
   }
   if (html.length > MAX_HTML_SIZE) {
@@ -5429,13 +5861,111 @@ function auditEmail(html, options) {
   }
   const framework = options == null ? void 0 : options.framework;
   const skip = new Set((_a = options == null ? void 0 : options.skip) != null ? _a : []);
-  const warnings = skip.has("compatibility") ? [] : analyzeEmail(html, framework);
+  const $ = cheerio11.load(html);
+  const warnings = skip.has("compatibility") ? [] : analyzeEmailFromDom($, framework);
   const scores = skip.has("compatibility") ? {} : generateCompatibilityScore(warnings);
-  const spam = skip.has("spam") ? EMPTY_SPAM : analyzeSpam(html, options == null ? void 0 : options.spam);
-  const links = skip.has("links") ? EMPTY_LINKS : validateLinks(html);
-  const accessibility = skip.has("accessibility") ? EMPTY_ACCESSIBILITY : checkAccessibility(html);
-  const images = skip.has("images") ? EMPTY_IMAGES : analyzeImages(html);
-  return { compatibility: { warnings, scores }, spam, links, accessibility, images };
+  const spam = skip.has("spam") ? EMPTY_SPAM : analyzeSpamFromDom($, options == null ? void 0 : options.spam);
+  const links = skip.has("links") ? EMPTY_LINKS : validateLinksFromDom($);
+  const accessibility = skip.has("accessibility") ? EMPTY_ACCESSIBILITY : checkAccessibilityFromDom($);
+  const images = skip.has("images") ? EMPTY_IMAGES : analyzeImagesFromDom($);
+  const inboxPreview = skip.has("inboxPreview") ? EMPTY_INBOX_PREVIEW : extractInboxPreviewFromDom($);
+  const size = skip.has("size") ? EMPTY_SIZE : checkSizeFromDom($, html);
+  const templateVariables = skip.has("templateVariables") ? EMPTY_TEMPLATE : checkTemplateVariablesFromDom($);
+  return { compatibility: { warnings, scores }, spam, links, accessibility, images, inboxPreview, size, templateVariables };
+}
+
+// src/session.ts
+var cheerio12 = __toESM(require("cheerio"), 1);
+function createSession(html, options) {
+  if (!html || !html.trim()) {
+    const fw = options == null ? void 0 : options.framework;
+    return {
+      html: html || "",
+      framework: fw,
+      audit: () => ({
+        compatibility: { warnings: [], scores: {} },
+        spam: EMPTY_SPAM,
+        links: EMPTY_LINKS,
+        accessibility: EMPTY_ACCESSIBILITY,
+        images: EMPTY_IMAGES,
+        inboxPreview: EMPTY_INBOX_PREVIEW,
+        size: EMPTY_SIZE,
+        templateVariables: EMPTY_TEMPLATE
+      }),
+      analyze: () => [],
+      score: () => ({}),
+      analyzeSpam: () => EMPTY_SPAM,
+      validateLinks: () => EMPTY_LINKS,
+      checkAccessibility: () => EMPTY_ACCESSIBILITY,
+      analyzeImages: () => EMPTY_IMAGES,
+      extractInboxPreview: () => EMPTY_INBOX_PREVIEW,
+      checkSize: () => EMPTY_SIZE,
+      checkTemplateVariables: () => EMPTY_TEMPLATE,
+      transformForClient: (clientId) => ({ clientId, html: html || "", warnings: [] }),
+      transformForAllClients: () => [],
+      simulateDarkMode: (clientId) => ({ html: html || "", warnings: [] })
+    };
+  }
+  if (html.length > MAX_HTML_SIZE) {
+    throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
+  }
+  const $ = cheerio12.load(html);
+  const framework = options == null ? void 0 : options.framework;
+  return {
+    html,
+    framework,
+    audit(opts) {
+      var _a;
+      const skip = new Set((_a = opts == null ? void 0 : opts.skip) != null ? _a : []);
+      const warnings = skip.has("compatibility") ? [] : analyzeEmailFromDom($, framework);
+      const scores = skip.has("compatibility") ? {} : generateCompatibilityScore(warnings);
+      const spam = skip.has("spam") ? EMPTY_SPAM : analyzeSpamFromDom($, opts == null ? void 0 : opts.spam);
+      const links = skip.has("links") ? EMPTY_LINKS : validateLinksFromDom($);
+      const accessibility = skip.has("accessibility") ? EMPTY_ACCESSIBILITY : checkAccessibilityFromDom($);
+      const images = skip.has("images") ? EMPTY_IMAGES : analyzeImagesFromDom($);
+      const inboxPreview = skip.has("inboxPreview") ? EMPTY_INBOX_PREVIEW : extractInboxPreviewFromDom($);
+      const size = skip.has("size") ? EMPTY_SIZE : checkSizeFromDom($, html);
+      const templateVariables = skip.has("templateVariables") ? EMPTY_TEMPLATE : checkTemplateVariablesFromDom($);
+      return { compatibility: { warnings, scores }, spam, links, accessibility, images, inboxPreview, size, templateVariables };
+    },
+    analyze() {
+      return analyzeEmailFromDom($, framework);
+    },
+    score(warnings) {
+      return generateCompatibilityScore(warnings);
+    },
+    analyzeSpam(opts) {
+      return analyzeSpamFromDom($, opts);
+    },
+    validateLinks() {
+      return validateLinksFromDom($);
+    },
+    checkAccessibility() {
+      return checkAccessibilityFromDom($);
+    },
+    analyzeImages() {
+      return analyzeImagesFromDom($);
+    },
+    extractInboxPreview() {
+      return extractInboxPreviewFromDom($);
+    },
+    checkSize() {
+      return checkSizeFromDom($, html);
+    },
+    checkTemplateVariables() {
+      return checkTemplateVariablesFromDom($);
+    },
+    // Transforms create isolated copies since they mutate the DOM
+    transformForClient(clientId) {
+      return transformForClient(html, clientId, framework);
+    },
+    transformForAllClients() {
+      return transformForAllClients(html, framework);
+    },
+    simulateDarkMode(clientId) {
+      return simulateDarkMode(html, clientId);
+    }
+  };
 }
 
 // src/compile/errors.ts
@@ -5461,10 +5991,14 @@ var CompileError = class extends Error {
   analyzeSpam,
   auditEmail,
   checkAccessibility,
+  checkSize,
+  checkTemplateVariables,
   contrastRatio,
+  createSession,
   diffResults,
   errorWarnings,
   estimateAiFixTokens,
+  extractInboxPreview,
   generateAiFix,
   generateCompatibilityScore,
   generateFixPrompt,