@emailens/engine 0.11.1 → 0.11.3

package/dist/index.d.cts

@@ -390,6 +390,55 @@ declare function checkVml(html: string, options?: {
     positions?: boolean;
 }): VmlReport;
 
+/**
+ * Resolve the Outlook branch of an email and translate its VML into CSS a
+ * browser can draw.
+ *
+ * Every preview of a Word-engine Outlook has, until now, rendered the wrong
+ * half of the email: the `<!--[if mso]>` blocks stayed commented and the
+ * `<!--[if !mso]>` fallback stayed live, so the screenshot showed precisely
+ * what Outlook does *not* render and hid what it does.
+ *
+ * Resolving the branch alone makes that worse rather than better. VML has been
+ * dead in browsers since IE9, so `<v:rect>` parses as an HTMLUnknownElement:
+ * `display:inline`, no box, no fill. The content inside would render as bare
+ * inline text. Resolution and translation therefore ship together and are not
+ * useful apart.
+ *
+ * ponytail: a mapping for the two shapes that occur in practice, not a VML
+ * renderer. Measured across a reported production email and MJML's output,
+ * `roundrect` and `rect` are the whole surface. Anything else is left alone
+ * rather than approximated.
+ *
+ * Deliberately NOT emulated: how Word *mis*-renders a nested shape. That is a
+ * real and confirmed failure (the container disappears and text stops drawing
+ * further down the document), but reproducing it means perturbing Chromium's
+ * layout into a picture that is wrong in a third way, different from both the
+ * correct render and Outlook's. `checkVml` reports it with a line number
+ * instead, which is more useful and cannot mislead.
+ */
+/**
+ * `arcsize` is a VgFraction: a proportion of *half the shape's shorter side*,
+ * where 0% is square and 100% fully circular. Values outside that are clamped
+ * rather than rejected, which is why 120% and 100% draw the identical corner.
+ * Verified against Outlook Classic.
+ */
+declare function arcsizeToRadius(arcsize: string, width: number, height: number): number;
+/**
+ * Uncomment the Outlook-only blocks and delete the downlevel-revealed branch,
+ * leaving the markup a Word-engine client actually parses.
+ */
+declare function resolveMsoBranch(html: string): string;
+/** Translate the VML shapes a browser cannot draw into divs it can. */
+declare function vmlToCss(html: string): string;
+/**
+ * Render the branch a Word-engine Outlook actually sees.
+ *
+ * Returns the input unchanged when there is nothing Outlook-only in it, so an
+ * email without conditional comments is never rewritten for no reason.
+ */
+declare function renderOutlookBranch(html: string): string;
+
 /**
  * Detect probable visual bugs in a stylized email: background images/gradients
  * with no colour fallback, and font stacks with no web-safe fallback. Each
@@ -674,4 +723,4 @@ declare function colorDistance(a: RGBA, b: RGBA): number;
  */
 declare function downlevelCSS(html: string): string;
 
-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 };
+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, arcsizeToRadius, 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, renderOutlookBranch, resolveMsoBranch, rgbToOklab, simulateDarkMode, structuralWarnings, toPlainText, transformForAllClients, transformForClient, validateLinks, vmlToCss, warningsForClient, wcagGrade };

package/dist/index.d.ts

@@ -390,6 +390,55 @@ declare function checkVml(html: string, options?: {
     positions?: boolean;
 }): VmlReport;
 
+/**
+ * Resolve the Outlook branch of an email and translate its VML into CSS a
+ * browser can draw.
+ *
+ * Every preview of a Word-engine Outlook has, until now, rendered the wrong
+ * half of the email: the `<!--[if mso]>` blocks stayed commented and the
+ * `<!--[if !mso]>` fallback stayed live, so the screenshot showed precisely
+ * what Outlook does *not* render and hid what it does.
+ *
+ * Resolving the branch alone makes that worse rather than better. VML has been
+ * dead in browsers since IE9, so `<v:rect>` parses as an HTMLUnknownElement:
+ * `display:inline`, no box, no fill. The content inside would render as bare
+ * inline text. Resolution and translation therefore ship together and are not
+ * useful apart.
+ *
+ * ponytail: a mapping for the two shapes that occur in practice, not a VML
+ * renderer. Measured across a reported production email and MJML's output,
+ * `roundrect` and `rect` are the whole surface. Anything else is left alone
+ * rather than approximated.
+ *
+ * Deliberately NOT emulated: how Word *mis*-renders a nested shape. That is a
+ * real and confirmed failure (the container disappears and text stops drawing
+ * further down the document), but reproducing it means perturbing Chromium's
+ * layout into a picture that is wrong in a third way, different from both the
+ * correct render and Outlook's. `checkVml` reports it with a line number
+ * instead, which is more useful and cannot mislead.
+ */
+/**
+ * `arcsize` is a VgFraction: a proportion of *half the shape's shorter side*,
+ * where 0% is square and 100% fully circular. Values outside that are clamped
+ * rather than rejected, which is why 120% and 100% draw the identical corner.
+ * Verified against Outlook Classic.
+ */
+declare function arcsizeToRadius(arcsize: string, width: number, height: number): number;
+/**
+ * Uncomment the Outlook-only blocks and delete the downlevel-revealed branch,
+ * leaving the markup a Word-engine client actually parses.
+ */
+declare function resolveMsoBranch(html: string): string;
+/** Translate the VML shapes a browser cannot draw into divs it can. */
+declare function vmlToCss(html: string): string;
+/**
+ * Render the branch a Word-engine Outlook actually sees.
+ *
+ * Returns the input unchanged when there is nothing Outlook-only in it, so an
+ * email without conditional comments is never rewritten for no reason.
+ */
+declare function renderOutlookBranch(html: string): string;
+
 /**
  * Detect probable visual bugs in a stylized email: background images/gradients
  * with no colour fallback, and font stacks with no web-safe fallback. Each
@@ -674,4 +723,4 @@ declare function colorDistance(a: RGBA, b: RGBA): number;
  */
 declare function downlevelCSS(html: string): string;
 
-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 };
+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, arcsizeToRadius, 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, renderOutlookBranch, resolveMsoBranch, rgbToOklab, simulateDarkMode, structuralWarnings, toPlainText, transformForAllClients, transformForClient, validateLinks, vmlToCss, warningsForClient, wcagGrade };

package/dist/index.js

@@ -9740,6 +9740,114 @@ function downlevelCSS(html) {
   return $.html();
 }
 
+// src/vml-render.ts
+function px(value) {
+  if (!value) return void 0;
+  const m = value.trim().match(/^(-?[\d.]+)(?:px)?$/i);
+  return m ? parseFloat(m[1]) : void 0;
+}
+function styleProps(style) {
+  const out = {};
+  for (const decl of style.split(";")) {
+    const i = decl.indexOf(":");
+    if (i > 0) out[decl.slice(0, i).trim().toLowerCase()] = decl.slice(i + 1).trim();
+  }
+  return out;
+}
+function attrs(raw) {
+  var _a, _b;
+  const out = {};
+  for (const m of raw.matchAll(/([\w:-]+)\s*=\s*"([^"]*)"|([\w:-]+)\s*=\s*'([^']*)'/g)) {
+    out[((_a = m[1]) != null ? _a : m[3]).toLowerCase()] = (_b = m[2]) != null ? _b : m[4];
+  }
+  return out;
+}
+function arcsizeToRadius(arcsize, width, height) {
+  const raw = arcsize.trim();
+  const pct = raw.endsWith("%") ? parseFloat(raw) : parseFloat(raw) * 100;
+  if (!Number.isFinite(pct)) return 0;
+  return Math.min(100, Math.max(0, pct)) / 100 * (Math.min(width, height) / 2);
+}
+function resolveMsoBranch(html) {
+  return html.replace(/<!--\[if\s*!\s*(?:mso|vml)[^\]]*\]><!-->([\s\S]*?)<!--<!\[endif\]-->/gi, "").replace(/<!--\[if[^\]]*(?:mso|vml)[^\]]*\]>([\s\S]*?)<!\[endif\]-->/gi, "$1");
+}
+function vmlToCss(html) {
+  let out = html;
+  out = out.replace(
+    /<v:roundrect([^>]*)>([\s\S]*?)<\/v:roundrect>/gi,
+    (_m, rawAttrs, inner) => {
+      var _a, _b, _c, _d, _e, _f;
+      const a = attrs(rawAttrs);
+      const s = styleProps((_a = a.style) != null ? _a : "");
+      const w = (_b = px(s.width)) != null ? _b : 0;
+      const h = (_c = px(s.height)) != null ? _c : 0;
+      const radius = a.arcsize ? arcsizeToRadius(a.arcsize, w, h) : 0.2 * (Math.min(w, h) / 2);
+      const fill = (_d = a.fillcolor) != null ? _d : "transparent";
+      const stroked = !(a.stroke === "f" || a.stroke === "false");
+      const middle = /middle/i.test((_e = s["v-text-anchor"]) != null ? _e : "");
+      const label = inner.replace(/<\/?(?:w:anchorlock|center)[^>]*>/gi, "").trim();
+      const box = [
+        w ? `width:${w}px` : "",
+        h ? `height:${h}px` : "",
+        `border-radius:${radius}px`,
+        `background:${fill}`,
+        stroked ? `border:1px solid ${(_f = a.strokecolor) != null ? _f : "#000"}` : "border:none",
+        "display:inline-flex",
+        "justify-content:center",
+        `align-items:${middle ? "center" : "flex-start"}`,
+        "overflow:hidden",
+        "text-align:center"
+      ].filter(Boolean).join(";");
+      const href = a.href ? ` data-href="${a.href}"` : "";
+      return `<div data-vml="roundrect"${href} style="${box}">${label}</div>`;
+    }
+  );
+  out = out.replace(
+    /<v:rect([^>]*)>([\s\S]*?)<\/v:rect>/gi,
+    (_m, rawAttrs, inner) => {
+      var _a, _b, _c, _d, _e, _f;
+      const a = attrs(rawAttrs);
+      const s = styleProps((_a = a.style) != null ? _a : "");
+      const w = px(s.width);
+      const h = px(s.height);
+      const fillTag = inner.match(/<v:fill([^>]*?)\/?>/i);
+      const f = fillTag ? attrs(fillTag[1]) : {};
+      const type = ((_b = f.type) != null ? _b : "solid").toLowerCase();
+      let background = "";
+      if (f.src && type === "tile") {
+        background = `background-image:url('${f.src}');background-repeat:repeat;`;
+      } else if (f.src) {
+        background = `background-image:url('${f.src}');background-size:cover;background-position:center;`;
+      } else if (type === "gradient" || type === "gradientradial") {
+        const from = (_d = (_c = f.color) != null ? _c : a.fillcolor) != null ? _d : "transparent";
+        const to = (_e = f.color2) != null ? _e : from;
+        const angle = f.angle ? `${parseFloat(f.angle)}deg` : "180deg";
+        background = type === "gradientradial" ? `background-image:radial-gradient(${from},${to});` : `background-image:linear-gradient(${angle},${from},${to});`;
+      }
+      const solid = (_f = f.color) != null ? _f : a.fillcolor;
+      const tb = inner.match(/<v:textbox([^>]*)>([\s\S]*?)<\/v:textbox>/i);
+      const inset = tb ? attrs(tb[1]).inset : void 0;
+      const padding = inset ? inset.split(",").map((p) => {
+        var _a2;
+        return `${(_a2 = px(p.trim())) != null ? _a2 : 0}px`;
+      }).join(" ") : "0";
+      const content = tb ? tb[2] : inner.replace(/<v:fill[^>]*?\/?>/gi, "");
+      const box = [
+        w !== void 0 ? `width:${w}px` : "",
+        h !== void 0 ? `height:${h}px` : "",
+        solid ? `background-color:${solid}` : "",
+        `padding:${padding}`
+      ].filter(Boolean).join(";");
+      return `<div data-vml="rect" style="${background}${box}">${content}</div>`;
+    }
+  );
+  return out.replace(/<\/?v:(?:fill|textbox|stroke|shadow|imagedata|path|formulas|handles)[^>]*?\/?>/gi, "");
+}
+function renderOutlookBranch(html) {
+  if (!/<!--\[if/i.test(html)) return html;
+  return vmlToCss(resolveMsoBranch(html));
+}
+
 // src/constants.ts
 var MAX_HTML_SIZE = 2 * 1024 * 1024;
 var MAX_WARNING_LOCATIONS = 100;
@@ -10463,7 +10571,8 @@ function transformForClient(html, clientId, framework) {
       ]
     };
   }
-  const downleveled = downlevelCSS(html);
+  const source = clientId === "outlook-windows-legacy" ? renderOutlookBranch(html) : html;
+  const downleveled = downlevelCSS(source);
   return applyTransform(downleveled, config, framework);
 }
 function transformForAllClients(html, framework) {
@@ -10478,8 +10587,13 @@ function transformForAllClients(html, framework) {
     throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
   }
   const downleveled = downlevelCSS(html);
+  const outlookSource = /<!--\[if/i.test(html) ? downlevelCSS(renderOutlookBranch(html)) : downleveled;
   return Object.keys(CLIENT_CONFIGS).map(
-    (clientId) => applyTransform(downleveled, CLIENT_CONFIGS[clientId], framework)
+    (clientId) => applyTransform(
+      clientId === "outlook-windows-legacy" ? outlookSource : downleveled,
+      CLIENT_CONFIGS[clientId],
+      framework
+    )
   );
 }
 
@@ -13201,9 +13315,9 @@ function mediaApplies(prelude, ctx) {
   const scheme = text.match(/prefers-color-scheme\s*:\s*(dark|light)/);
   if (scheme && scheme[1] === "dark" !== ctx.dark) return false;
   for (const m of text.matchAll(/(max|min)-width\s*:\s*([^)]+)/g)) {
-    const px = mediaPx(m[2]);
-    if (px === null) continue;
-    if (m[1] === "max" ? ctx.width > px : ctx.width < px) return false;
+    const px2 = mediaPx(m[2]);
+    if (px2 === null) continue;
+    if (m[1] === "max" ? ctx.width > px2 : ctx.width < px2) return false;
   }
   return true;
 }
@@ -13424,10 +13538,10 @@ function resolveBackground($, el, cascade) {
 function isLargeText(size, weight) {
   const match = size == null ? void 0 : size.match(/^(\d+(?:\.\d+)?)(px|pt)/i);
   if (!match) return false;
-  const px = match[2].toLowerCase() === "pt" ? parseFloat(match[1]) * 1.333 : parseFloat(match[1]);
+  const px2 = match[2].toLowerCase() === "pt" ? parseFloat(match[1]) * 1.333 : parseFloat(match[1]);
   const w = weight == null ? void 0 : weight.trim().toLowerCase();
   const bold = w === "bold" || w === "bolder" || !!w && parseInt(w, 10) >= 700;
-  return px >= 18 || px >= 14 && bold;
+  return px2 >= 18 || px2 >= 14 && bold;
 }
 function inherited($, el, cascade, prop) {
   var _a, _b;
@@ -14148,8 +14262,8 @@ function checkTemplateVariablesFromDom($, source) {
   const attrSelectors = ["[href]", "[src]", "[alt]"];
   for (const sel of attrSelectors) {
     $(sel).each((_, el) => {
-      const attrs = ["href", "src", "alt"];
-      for (const attr2 of attrs) {
+      const attrs2 = ["href", "src", "alt"];
+      for (const attr2 of attrs2) {
         const value = $(el).attr(attr2);
         if (!value) continue;
         for (const [pattern, label] of TEMPLATE_VARIABLE_PATTERNS) {
@@ -14389,9 +14503,9 @@ function locAt(source, offset, length) {
     length
   };
 }
-function attr(attrs, name) {
+function attr(attrs2, name) {
   var _a;
-  const m = attrs.match(
+  const m = attrs2.match(
     new RegExp(`(?:^|\\s)${name}\\s*=\\s*"([^"]*)"|(?:^|\\s)${name}\\s*=\\s*'([^']*)'`, "i")
   );
   return m ? (_a = m[1]) != null ? _a : m[2] : void 0;
@@ -14699,8 +14813,8 @@ function radiusLengths(value) {
   return lengths.filter((v) => {
     if (/^0(?:px|rem|em|%)?$/.test(v)) return false;
     if (v === "50%") return false;
-    const px = parseFloat(v);
-    return !(v.endsWith("px") && Number.isFinite(px) && px >= 500);
+    const px2 = parseFloat(v);
+    return !(v.endsWith("px") && Number.isFinite(px2) && px2 >= 500);
   });
 }
 function collect($) {
@@ -15095,6 +15209,7 @@ export {
   analyzeEmail,
   analyzeImages,
   analyzeSpam,
+  arcsizeToRadius,
   auditEmail,
   caveatApplies,
   checkAccessibility,
@@ -15126,6 +15241,8 @@ export {
   heuristicTokenCount,
   parseColor,
   relativeLuminance,
+  renderOutlookBranch,
+  resolveMsoBranch,
   rgbToOklab,
   simulateDarkMode,
   structuralWarnings,
@@ -15133,6 +15250,7 @@ export {
   transformForAllClients,
   transformForClient,
   validateLinks,
+  vmlToCss,
   warningsForClient,
   wcagGrade
 };