@emailens/engine 0.11.0 → 0.11.2

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { E as EmailClient, F as Framework, T as TransformResult, C as CSSWarning, a as CodeFix, D as DiffResult, b as ExportPromptOptions, A as AiProvider, c as AiFixResult, S as SupportLevel, d as SpamAnalysisOptions, e as SpamReport, L as LinkReport, f as AccessibilityReport, g as AccessibilityIssue, I as ImageReport, h as InboxPreview, i as SizeReport, j as TemplateReport, O as OverflowReport, V as VisualReport, k as DesignReport, l as DeliverabilityReport } from './types-BFhPXh3c.cjs';
-export { B as BaseIssue, m as ClientTruncation, n as DeliverabilityCheck, o as DeliverabilityIssue, p as DesignIssue, q as EstimateOptions, r as ExportScope, s as FixType, t as ImageInfo, u as ImageIssue, v as InboxPreviewIssue, w as InputFormat, x as LinkIssue, y as OverflowIssue, P as PreviewResult, z as Severity, G as SizeIssue, H as SourceLocation, J as SpamIssue, K as TemplateIssue, M as TokenEstimate, N as TokenEstimateWithWarnings, Q as VisualIssue, R as estimateAiFixTokens, U as generateFixPrompt, W as heuristicTokenCount } from './types-BFhPXh3c.cjs';
+import { E as EmailClient, F as Framework, T as TransformResult, C as CSSWarning, a as CodeFix, D as DiffResult, b as ExportPromptOptions, A as AiProvider, c as AiFixResult, S as SupportLevel, d as SpamAnalysisOptions, e as SpamReport, L as LinkReport, f as AccessibilityReport, g as AccessibilityIssue, I as ImageReport, h as InboxPreview, i as SizeReport, j as TemplateReport, O as OverflowReport, V as VmlReport, k as VisualReport, l as DesignReport, m as DeliverabilityReport } from './types-bvGDId6f.cjs';
+export { B as BaseIssue, n as ClientTruncation, o as DeliverabilityCheck, p as DeliverabilityIssue, q as DesignIssue, r as EstimateOptions, s as ExportScope, t as FixType, u as ImageInfo, v as ImageIssue, w as InboxPreviewIssue, x as InputFormat, y as LinkIssue, z as OverflowIssue, P as PreviewResult, G as Severity, H as SizeIssue, J as SourceLocation, K as SpamIssue, M as TemplateIssue, N as TokenEstimate, Q as TokenEstimateWithWarnings, R as VisualIssue, U as VmlIssue, W as estimateAiFixTokens, X as generateFixPrompt, Y as heuristicTokenCount } from './types-bvGDId6f.cjs';
 import * as cheerio from 'cheerio';
-export { C as CompileError, a as CompileReactEmailOptions, S as SandboxStrategy } from './react-email-BWIfwG7U.cjs';
+export { C as CompileError, a as CompileReactEmailOptions, S as SandboxStrategy } from './react-email-DuZAgJtw.cjs';
 
 declare const EMAIL_CLIENTS: EmailClient[];
 declare function getClient(id: string): EmailClient | undefined;
@@ -372,6 +372,73 @@ declare function checkTemplateVariables(html: string, options?: ParseOptions): T
  */
 declare function checkOverflow(html: string, options?: ParseOptions): OverflowReport;
 
+/**
+ * Check hand-written VML for the mistakes Outlook punishes.
+ *
+ * This is the one part of an email the DOM analyzers structurally cannot see:
+ * VML lives inside `<!--[if mso]>` conditional comments, so to every HTML
+ * parser it is a comment node, and to a headless-Chromium screenshot it does
+ * not exist at all. An email can therefore lint clean and preview perfectly
+ * while the branch Outlook actually renders is broken.
+ *
+ * ponytail: a tag-sequence checker, not a VML renderer. It validates structure
+ * and attribute values, which is where the reported breakages cluster. It does
+ * not resolve geometry, so it can say Outlook will misplace a nested shape but
+ * not where the shape lands.
+ */
+declare function checkVml(html: string, options?: {
+    positions?: boolean;
+}): VmlReport;
+
+/**
+ * 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
@@ -390,7 +457,7 @@ interface AuditOptions extends ParseOptions {
     /** Options for spam analysis */
     spam?: SpamAnalysisOptions;
     /** Skip specific checks */
-    skip?: Array<"spam" | "links" | "accessibility" | "images" | "compatibility" | "inboxPreview" | "size" | "templateVariables" | "overflow" | "visual" | "darkContrast" | "mobileContrast" | "design">;
+    skip?: Array<"spam" | "links" | "accessibility" | "images" | "compatibility" | "inboxPreview" | "size" | "templateVariables" | "overflow" | "visual" | "darkContrast" | "mobileContrast" | "design" | "vml">;
 }
 interface AuditReport {
     compatibility: {
@@ -411,6 +478,8 @@ interface AuditReport {
     templateVariables: TemplateReport;
     overflow: OverflowReport;
     visual: VisualReport;
+    /** Structural faults in Outlook-only VML, which lives inside conditional comments. */
+    vml: VmlReport;
     /** Contrast failures present only once a client inverts colours. */
     darkContrast: AccessibilityIssue[];
     /** Contrast failures present only below the email's mobile breakpoint. */
@@ -654,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, type WcagGrade, alphaBlend, analyzeEmail, analyzeImages, analyzeSpam, auditEmail, caveatApplies, checkAccessibility, checkDarkModeContrast, checkDarkStylesContrastFromDom, checkDesignConsistency, checkMobileContrast, checkOverflow, checkSize, checkTemplateVariables, checkVisual, 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

@@ -1,7 +1,7 @@
-import { E as EmailClient, F as Framework, T as TransformResult, C as CSSWarning, a as CodeFix, D as DiffResult, b as ExportPromptOptions, A as AiProvider, c as AiFixResult, S as SupportLevel, d as SpamAnalysisOptions, e as SpamReport, L as LinkReport, f as AccessibilityReport, g as AccessibilityIssue, I as ImageReport, h as InboxPreview, i as SizeReport, j as TemplateReport, O as OverflowReport, V as VisualReport, k as DesignReport, l as DeliverabilityReport } from './types-BFhPXh3c.js';
-export { B as BaseIssue, m as ClientTruncation, n as DeliverabilityCheck, o as DeliverabilityIssue, p as DesignIssue, q as EstimateOptions, r as ExportScope, s as FixType, t as ImageInfo, u as ImageIssue, v as InboxPreviewIssue, w as InputFormat, x as LinkIssue, y as OverflowIssue, P as PreviewResult, z as Severity, G as SizeIssue, H as SourceLocation, J as SpamIssue, K as TemplateIssue, M as TokenEstimate, N as TokenEstimateWithWarnings, Q as VisualIssue, R as estimateAiFixTokens, U as generateFixPrompt, W as heuristicTokenCount } from './types-BFhPXh3c.js';
+import { E as EmailClient, F as Framework, T as TransformResult, C as CSSWarning, a as CodeFix, D as DiffResult, b as ExportPromptOptions, A as AiProvider, c as AiFixResult, S as SupportLevel, d as SpamAnalysisOptions, e as SpamReport, L as LinkReport, f as AccessibilityReport, g as AccessibilityIssue, I as ImageReport, h as InboxPreview, i as SizeReport, j as TemplateReport, O as OverflowReport, V as VmlReport, k as VisualReport, l as DesignReport, m as DeliverabilityReport } from './types-bvGDId6f.js';
+export { B as BaseIssue, n as ClientTruncation, o as DeliverabilityCheck, p as DeliverabilityIssue, q as DesignIssue, r as EstimateOptions, s as ExportScope, t as FixType, u as ImageInfo, v as ImageIssue, w as InboxPreviewIssue, x as InputFormat, y as LinkIssue, z as OverflowIssue, P as PreviewResult, G as Severity, H as SizeIssue, J as SourceLocation, K as SpamIssue, M as TemplateIssue, N as TokenEstimate, Q as TokenEstimateWithWarnings, R as VisualIssue, U as VmlIssue, W as estimateAiFixTokens, X as generateFixPrompt, Y as heuristicTokenCount } from './types-bvGDId6f.js';
 import * as cheerio from 'cheerio';
-export { C as CompileError, a as CompileReactEmailOptions, S as SandboxStrategy } from './react-email-D24HkW2Z.js';
+export { C as CompileError, a as CompileReactEmailOptions, S as SandboxStrategy } from './react-email-BROBcC8u.js';
 
 declare const EMAIL_CLIENTS: EmailClient[];
 declare function getClient(id: string): EmailClient | undefined;
@@ -372,6 +372,73 @@ declare function checkTemplateVariables(html: string, options?: ParseOptions): T
  */
 declare function checkOverflow(html: string, options?: ParseOptions): OverflowReport;
 
+/**
+ * Check hand-written VML for the mistakes Outlook punishes.
+ *
+ * This is the one part of an email the DOM analyzers structurally cannot see:
+ * VML lives inside `<!--[if mso]>` conditional comments, so to every HTML
+ * parser it is a comment node, and to a headless-Chromium screenshot it does
+ * not exist at all. An email can therefore lint clean and preview perfectly
+ * while the branch Outlook actually renders is broken.
+ *
+ * ponytail: a tag-sequence checker, not a VML renderer. It validates structure
+ * and attribute values, which is where the reported breakages cluster. It does
+ * not resolve geometry, so it can say Outlook will misplace a nested shape but
+ * not where the shape lands.
+ */
+declare function checkVml(html: string, options?: {
+    positions?: boolean;
+}): VmlReport;
+
+/**
+ * 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
@@ -390,7 +457,7 @@ interface AuditOptions extends ParseOptions {
     /** Options for spam analysis */
     spam?: SpamAnalysisOptions;
     /** Skip specific checks */
-    skip?: Array<"spam" | "links" | "accessibility" | "images" | "compatibility" | "inboxPreview" | "size" | "templateVariables" | "overflow" | "visual" | "darkContrast" | "mobileContrast" | "design">;
+    skip?: Array<"spam" | "links" | "accessibility" | "images" | "compatibility" | "inboxPreview" | "size" | "templateVariables" | "overflow" | "visual" | "darkContrast" | "mobileContrast" | "design" | "vml">;
 }
 interface AuditReport {
     compatibility: {
@@ -411,6 +478,8 @@ interface AuditReport {
     templateVariables: TemplateReport;
     overflow: OverflowReport;
     visual: VisualReport;
+    /** Structural faults in Outlook-only VML, which lives inside conditional comments. */
+    vml: VmlReport;
     /** Contrast failures present only once a client inverts colours. */
     darkContrast: AccessibilityIssue[];
     /** Contrast failures present only below the email's mobile breakpoint. */
@@ -654,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, type WcagGrade, alphaBlend, analyzeEmail, analyzeImages, analyzeSpam, auditEmail, caveatApplies, checkAccessibility, checkDarkModeContrast, checkDarkStylesContrastFromDom, checkDesignConsistency, checkMobileContrast, checkOverflow, checkSize, checkTemplateVariables, checkVisual, 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 };