@emailens/engine 0.10.1 → 0.10.2

package/dist/{react-email-B1Rd5itD.d.cts → react-email-DTzVpGgB.d.cts}

@@ -1,4 +1,4 @@
-import { u as InputFormat } from './types-DEAn3IiX.cjs';
+import { u as InputFormat } from './types-BLR3-Fzo.cjs';
 
 /**
  * Unified error class for all email compilation failures.

package/dist/{react-email-D4XyNztP.d.ts → react-email-DwBWB2kr.d.ts}

@@ -1,4 +1,4 @@
-import { u as InputFormat } from './types-DEAn3IiX.js';
+import { u as InputFormat } from './types-BLR3-Fzo.js';
 
 /**
  * Unified error class for all email compilation failures.

package/dist/server.d.cts

@@ -1,5 +1,5 @@
 import { promises } from 'node:dns';
-import { j as DeliverabilityReport } from './types-DEAn3IiX.cjs';
+import { j as DeliverabilityReport } from './types-BLR3-Fzo.cjs';
 
 /**
  * DNS-based email deliverability checker.

package/dist/server.d.ts

@@ -1,5 +1,5 @@
 import { promises } from 'node:dns';
-import { j as DeliverabilityReport } from './types-DEAn3IiX.js';
+import { j as DeliverabilityReport } from './types-BLR3-Fzo.js';
 
 /**
  * DNS-based email deliverability checker.

package/dist/{types-DEAn3IiX.d.cts → types-BLR3-Fzo.d.cts}

@@ -111,11 +111,42 @@ interface EmailClient {
     deprecated?: string;
 }
 type Severity = "error" | "warning" | "info";
+/**
+ * Where an issue lives in the analyzed HTML.
+ *
+ * Lines and columns are 1-based; `offset` is a 0-based character index into
+ * the HTML string. Populated only when the analysis ran with `positions: true`
+ * — and only for findings that belong to a specific node, so document-level
+ * findings (email size, aggregate spam signals) leave it undefined.
+ */
+interface SourceLocation {
+    /** 1-based line in the original HTML string. */
+    line: number;
+    /** 1-based column. */
+    column: number;
+    endLine: number;
+    endColumn: number;
+    /** 0-based character offset, for consumers that prefer offsets. */
+    offset: number;
+    length: number;
+}
 /** Shared shape for every analyzer's issue objects. */
 interface BaseIssue {
     rule: string;
     severity: Severity;
     message: string;
+    /** Position of the first occurrence in the source HTML. Requires `positions: true`. */
+    loc?: SourceLocation;
+    /**
+     * Every occurrence, in document order — `loc` is the first of them.
+     *
+     * Present on analyzers that report one issue per *kind* of problem rather
+     * than one per element (overflow, visual). Analyzers that already emit an
+     * issue per element carry `loc` alone. Capped at {@link MAX_WARNING_LOCATIONS}.
+     */
+    locs?: SourceLocation[];
+    /** `locs` hit the cap and does not list every occurrence. */
+    locsTruncated?: boolean;
 }
 interface CodeFix {
     before: string;
@@ -133,8 +164,34 @@ interface CSSWarning {
     fix?: CodeFix;
     fixIsGenericFallback?: boolean;
     fixType?: FixType;
+    /**
+     * @deprecated Use `loc`. Without `positions: true` this is the line within
+     * the `<style>` block that declared the property (and is absent for inline
+     * styles); with positions on it is `loc.line`, i.e. absolute in the document.
+     */
     line?: number;
     selector?: string;
+    /** Position of the first occurrence in the source HTML. Requires `positions: true`. */
+    loc?: SourceLocation;
+    /**
+     * Every occurrence, in document order — `loc` is the first of them.
+     *
+     * Warnings are deduplicated per client, property, severity and `selector`,
+     * so twelve elements the analyzer describes the same way collapse into one
+     * warning — this is how a consumer reaches the other eleven. Elements
+     * described differently (`div.card` vs `span`) still produce separate
+     * warnings for the same property, so a consumer that wants every place a
+     * property breaks should union `locs` across the warnings for that property.
+     * Ordered by position, capped at {@link MAX_WARNING_LOCATIONS}.
+     */
+    locs?: SourceLocation[];
+    /**
+     * `locs` hit the cap and does not list every occurrence.
+     *
+     * A consumer that acts on all of them (an editor applying a fix everywhere)
+     * needs to know the list is partial rather than infer it from the length.
+     */
+    locsTruncated?: boolean;
 }
 /**
  * Callback that sends a prompt to an LLM and returns the text response.
@@ -303,4 +360,4 @@ interface DeliverabilityIssue extends BaseIssue {
     detail?: string;
 }
 
-export { type AiProvider as A, type BaseIssue as B, type CSSWarning as C, type DiffResult as D, type EmailClient as E, type Framework as F, type TemplateIssue as G, type TokenEstimate as H, type ImageReport as I, type TokenEstimateWithWarnings as J, type VisualIssue as K, type LinkReport as L, estimateAiFixTokens as M, generateFixPrompt as N, type OverflowReport as O, type PreviewResult as P, heuristicTokenCount as Q, type SupportLevel as S, type TransformResult as T, type VisualReport as V, type CodeFix as a, type ExportPromptOptions as b, type AiFixResult as c, type SpamAnalysisOptions as d, type SpamReport as e, type AccessibilityReport as f, type InboxPreview as g, type SizeReport as h, type TemplateReport as i, type DeliverabilityReport as j, type AccessibilityIssue as k, type ClientTruncation as l, type DeliverabilityCheck as m, type DeliverabilityIssue as n, type EstimateOptions as o, type ExportScope as p, type FixType as q, type ImageInfo as r, type ImageIssue as s, type InboxPreviewIssue as t, type InputFormat as u, type LinkIssue as v, type OverflowIssue as w, type Severity as x, type SizeIssue as y, type SpamIssue as z };
+export { type AiProvider as A, type BaseIssue as B, type CSSWarning as C, type DiffResult as D, type EmailClient as E, type Framework as F, type SpamIssue as G, type TemplateIssue as H, type ImageReport as I, type TokenEstimate as J, type TokenEstimateWithWarnings as K, type LinkReport as L, type VisualIssue as M, estimateAiFixTokens as N, type OverflowReport as O, type PreviewResult as P, generateFixPrompt as Q, heuristicTokenCount as R, type SupportLevel as S, type TransformResult as T, type VisualReport as V, type CodeFix as a, type ExportPromptOptions as b, type AiFixResult as c, type SpamAnalysisOptions as d, type SpamReport as e, type AccessibilityReport as f, type InboxPreview as g, type SizeReport as h, type TemplateReport as i, type DeliverabilityReport as j, type AccessibilityIssue as k, type ClientTruncation as l, type DeliverabilityCheck as m, type DeliverabilityIssue as n, type EstimateOptions as o, type ExportScope as p, type FixType as q, type ImageInfo as r, type ImageIssue as s, type InboxPreviewIssue as t, type InputFormat as u, type LinkIssue as v, type OverflowIssue as w, type Severity as x, type SizeIssue as y, type SourceLocation as z };

package/dist/{types-DEAn3IiX.d.ts → types-BLR3-Fzo.d.ts}

@@ -111,11 +111,42 @@ interface EmailClient {
     deprecated?: string;
 }
 type Severity = "error" | "warning" | "info";
+/**
+ * Where an issue lives in the analyzed HTML.
+ *
+ * Lines and columns are 1-based; `offset` is a 0-based character index into
+ * the HTML string. Populated only when the analysis ran with `positions: true`
+ * — and only for findings that belong to a specific node, so document-level
+ * findings (email size, aggregate spam signals) leave it undefined.
+ */
+interface SourceLocation {
+    /** 1-based line in the original HTML string. */
+    line: number;
+    /** 1-based column. */
+    column: number;
+    endLine: number;
+    endColumn: number;
+    /** 0-based character offset, for consumers that prefer offsets. */
+    offset: number;
+    length: number;
+}
 /** Shared shape for every analyzer's issue objects. */
 interface BaseIssue {
     rule: string;
     severity: Severity;
     message: string;
+    /** Position of the first occurrence in the source HTML. Requires `positions: true`. */
+    loc?: SourceLocation;
+    /**
+     * Every occurrence, in document order — `loc` is the first of them.
+     *
+     * Present on analyzers that report one issue per *kind* of problem rather
+     * than one per element (overflow, visual). Analyzers that already emit an
+     * issue per element carry `loc` alone. Capped at {@link MAX_WARNING_LOCATIONS}.
+     */
+    locs?: SourceLocation[];
+    /** `locs` hit the cap and does not list every occurrence. */
+    locsTruncated?: boolean;
 }
 interface CodeFix {
     before: string;
@@ -133,8 +164,34 @@ interface CSSWarning {
     fix?: CodeFix;
     fixIsGenericFallback?: boolean;
     fixType?: FixType;
+    /**
+     * @deprecated Use `loc`. Without `positions: true` this is the line within
+     * the `<style>` block that declared the property (and is absent for inline
+     * styles); with positions on it is `loc.line`, i.e. absolute in the document.
+     */
     line?: number;
     selector?: string;
+    /** Position of the first occurrence in the source HTML. Requires `positions: true`. */
+    loc?: SourceLocation;
+    /**
+     * Every occurrence, in document order — `loc` is the first of them.
+     *
+     * Warnings are deduplicated per client, property, severity and `selector`,
+     * so twelve elements the analyzer describes the same way collapse into one
+     * warning — this is how a consumer reaches the other eleven. Elements
+     * described differently (`div.card` vs `span`) still produce separate
+     * warnings for the same property, so a consumer that wants every place a
+     * property breaks should union `locs` across the warnings for that property.
+     * Ordered by position, capped at {@link MAX_WARNING_LOCATIONS}.
+     */
+    locs?: SourceLocation[];
+    /**
+     * `locs` hit the cap and does not list every occurrence.
+     *
+     * A consumer that acts on all of them (an editor applying a fix everywhere)
+     * needs to know the list is partial rather than infer it from the length.
+     */
+    locsTruncated?: boolean;
 }
 /**
  * Callback that sends a prompt to an LLM and returns the text response.
@@ -303,4 +360,4 @@ interface DeliverabilityIssue extends BaseIssue {
     detail?: string;
 }
 
-export { type AiProvider as A, type BaseIssue as B, type CSSWarning as C, type DiffResult as D, type EmailClient as E, type Framework as F, type TemplateIssue as G, type TokenEstimate as H, type ImageReport as I, type TokenEstimateWithWarnings as J, type VisualIssue as K, type LinkReport as L, estimateAiFixTokens as M, generateFixPrompt as N, type OverflowReport as O, type PreviewResult as P, heuristicTokenCount as Q, type SupportLevel as S, type TransformResult as T, type VisualReport as V, type CodeFix as a, type ExportPromptOptions as b, type AiFixResult as c, type SpamAnalysisOptions as d, type SpamReport as e, type AccessibilityReport as f, type InboxPreview as g, type SizeReport as h, type TemplateReport as i, type DeliverabilityReport as j, type AccessibilityIssue as k, type ClientTruncation as l, type DeliverabilityCheck as m, type DeliverabilityIssue as n, type EstimateOptions as o, type ExportScope as p, type FixType as q, type ImageInfo as r, type ImageIssue as s, type InboxPreviewIssue as t, type InputFormat as u, type LinkIssue as v, type OverflowIssue as w, type Severity as x, type SizeIssue as y, type SpamIssue as z };
+export { type AiProvider as A, type BaseIssue as B, type CSSWarning as C, type DiffResult as D, type EmailClient as E, type Framework as F, type SpamIssue as G, type TemplateIssue as H, type ImageReport as I, type TokenEstimate as J, type TokenEstimateWithWarnings as K, type LinkReport as L, type VisualIssue as M, estimateAiFixTokens as N, type OverflowReport as O, type PreviewResult as P, generateFixPrompt as Q, heuristicTokenCount as R, type SupportLevel as S, type TransformResult as T, type VisualReport as V, type CodeFix as a, type ExportPromptOptions as b, type AiFixResult as c, type SpamAnalysisOptions as d, type SpamReport as e, type AccessibilityReport as f, type InboxPreview as g, type SizeReport as h, type TemplateReport as i, type DeliverabilityReport as j, type AccessibilityIssue as k, type ClientTruncation as l, type DeliverabilityCheck as m, type DeliverabilityIssue as n, type EstimateOptions as o, type ExportScope as p, type FixType as q, type ImageInfo as r, type ImageIssue as s, type InboxPreviewIssue as t, type InputFormat as u, type LinkIssue as v, type OverflowIssue as w, type Severity as x, type SizeIssue as y, type SourceLocation as z };

package/package.json

@@ -1,123 +1,124 @@
-{
-  "name": "@emailens/engine",
-  "version": "0.10.1",
-  "description": "Email compatibility engine — transforms CSS per email client, scores compatibility, simulates dark mode, suggests fixes, and runs spam, accessibility, link, and image quality analysis.",
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    },
-    "./compile": {
-      "types": "./dist/compile/index.d.ts",
-      "import": "./dist/compile/index.js",
-      "require": "./dist/compile/index.cjs"
-    },
-    "./server": {
-      "types": "./dist/server.d.ts",
-      "import": "./dist/server.js",
-      "require": "./dist/server.cjs"
-    }
-  },
-  "types": "./dist/index.d.ts",
-  "sideEffects": false,
-  "engines": {
-    "node": ">=18"
-  },
-  "files": [
-    "dist",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "sync:caniemail": "bun run scripts/sync-caniemail.ts",
-    "check:freshness": "bun run scripts/check-data-freshness.ts",
-    "test": "bun test",
-    "test:render": "RENDER_TESTS=1 bun test src/__tests__/render.e2e.test.ts",
-    "prepublishOnly": "bun run build"
-  },
-  "dependencies": {
-    "cheerio": "^1.2.0",
-    "css-tree": "^3.1.0"
-  },
-  "peerDependencies": {
-    "@maizzle/framework": ">=5.0.0",
-    "@react-email/components": ">=0.0.36",
-    "@react-email/render": ">=1.0.0",
-    "isolated-vm": ">=5.0.0",
-    "mjml": ">=4.0.0",
-    "quickjs-emscripten": ">=0.29.0",
-    "react": "^18.0.0 || ^19.0.0",
-    "sucrase": "^3.35.0"
-  },
-  "peerDependenciesMeta": {
-    "sucrase": {
-      "optional": true
-    },
-    "react": {
-      "optional": true
-    },
-    "@react-email/components": {
-      "optional": true
-    },
-    "@react-email/render": {
-      "optional": true
-    },
-    "mjml": {
-      "optional": true
-    },
-    "@maizzle/framework": {
-      "optional": true
-    },
-    "isolated-vm": {
-      "optional": true
-    },
-    "quickjs-emscripten": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@maizzle/framework": "^5.0.0",
-    "@react-email/components": "^0.0.36",
-    "@react-email/render": "^1.0.6",
-    "@types/bun": "^1.3.9",
-    "@types/css-tree": "^2.3.11",
-    "@types/mjml": "^4.7.4",
-    "@types/node": "^25.3.0",
-    "@types/react": "^19.2.14",
-    "bun-types": "^1.3.9",
-    "mjml": "^4.15.0",
-    "playwright": "^1.62.0",
-    "react": "^19.0.0",
-    "sucrase": "^3.35.0",
-    "tsup": "^8.4.0",
-    "typescript": "^5.9.3"
-  },
-  "keywords": [
-    "email",
-    "html-email",
-    "css",
-    "compatibility",
-    "gmail",
-    "outlook",
-    "apple-mail",
-    "dark-mode",
-    "email-testing",
-    "spam-scoring",
-    "accessibility",
-    "link-validation",
-    "image-analysis"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/emailens/engine.git"
-  },
-  "homepage": "https://github.com/emailens/engine#readme",
-  "bugs": {
-    "url": "https://github.com/emailens/engine/issues"
-  }
-}
+{
+  "name": "@emailens/engine",
+  "version": "0.10.2",
+  "description": "Email compatibility engine — transforms CSS per email client, scores compatibility, simulates dark mode, suggests fixes, and runs spam, accessibility, link, and image quality analysis.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./compile": {
+      "types": "./dist/compile/index.d.ts",
+      "import": "./dist/compile/index.js",
+      "require": "./dist/compile/index.cjs"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "require": "./dist/server.cjs"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "sync:caniemail": "bun run scripts/sync-caniemail.ts",
+    "check:freshness": "bun run scripts/check-data-freshness.ts",
+    "bench:positions": "bun run scripts/bench-positions.ts",
+    "test": "bun test",
+    "test:render": "RENDER_TESTS=1 bun test src/__tests__/render.e2e.test.ts",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "cheerio": "^1.2.0",
+    "css-tree": "^3.1.0"
+  },
+  "peerDependencies": {
+    "@maizzle/framework": ">=5.0.0 <6.0.0",
+    "@react-email/components": ">=0.0.36",
+    "@react-email/render": ">=1.0.0",
+    "isolated-vm": ">=5.0.0",
+    "mjml": ">=4.0.0",
+    "quickjs-emscripten": ">=0.29.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "sucrase": "^3.35.0"
+  },
+  "peerDependenciesMeta": {
+    "sucrase": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "@react-email/components": {
+      "optional": true
+    },
+    "@react-email/render": {
+      "optional": true
+    },
+    "mjml": {
+      "optional": true
+    },
+    "@maizzle/framework": {
+      "optional": true
+    },
+    "isolated-vm": {
+      "optional": true
+    },
+    "quickjs-emscripten": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@maizzle/framework": "^5.5.0",
+    "@react-email/components": "^1.0.12",
+    "@react-email/render": "^2.1.0",
+    "@types/bun": "^1.3.9",
+    "@types/css-tree": "^2.3.11",
+    "@types/mjml": "^5.0.0",
+    "@types/node": "^25.3.0",
+    "@types/react": "^19.2.14",
+    "bun-types": "^1.3.9",
+    "mjml": "^5.4.0",
+    "playwright": "^1.62.0",
+    "react": "^19.0.0",
+    "sucrase": "^3.35.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [
+    "email",
+    "html-email",
+    "css",
+    "compatibility",
+    "gmail",
+    "outlook",
+    "apple-mail",
+    "dark-mode",
+    "email-testing",
+    "spam-scoring",
+    "accessibility",
+    "link-validation",
+    "image-analysis"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emailens/engine.git"
+  },
+  "homepage": "https://github.com/emailens/engine#readme",
+  "bugs": {
+    "url": "https://github.com/emailens/engine/issues"
+  }
+}