@emailens/engine 0.11.9 → 0.12.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. package/README.md +264 -264
  2. package/dist/{chunk-PW6EUG2G.js → chunk-OA6VNA5L.js} +16 -4
  3. package/dist/chunk-OA6VNA5L.js.map +1 -0
  4. package/dist/compile/index.cjs +16 -4
  5. package/dist/compile/index.cjs.map +1 -1
  6. package/dist/compile/index.d.cts +2 -21
  7. package/dist/compile/index.d.ts +2 -21
  8. package/dist/compile/index.js +2 -2
  9. package/dist/index.cjs +5011 -2202
  10. package/dist/index.cjs.map +1 -1
  11. package/dist/index.d.cts +16 -56
  12. package/dist/index.d.ts +16 -56
  13. package/dist/index.js +5000 -2202
  14. package/dist/index.js.map +1 -1
  15. package/dist/maizzle-R5KU3HHZ.js +11 -0
  16. package/dist/{react-email-B82A1R_K.d.ts → react-email-CDNfg8Ta.d.ts} +1 -1
  17. package/dist/{react-email-DRkmpgX-.d.cts → react-email-eJhDK8a5.d.cts} +1 -1
  18. package/dist/server.d.cts +1 -1
  19. package/dist/server.d.ts +1 -1
  20. package/dist/{types-DiseE-UH.d.cts → types-hQYXbiqj.d.cts} +109 -2
  21. package/dist/{types-DiseE-UH.d.ts → types-hQYXbiqj.d.ts} +109 -2
  22. package/package.json +1 -1
  23. package/dist/chunk-PW6EUG2G.js.map +0 -1
  24. package/dist/maizzle-KKJF7XY7.js +0 -9
  25. /package/dist/{maizzle-KKJF7XY7.js.map → maizzle-R5KU3HHZ.js.map} +0 -0
package/README.md CHANGED
@@ -1,264 +1,264 @@
1
- <div align="center">
2
-
3
- <picture>
4
- <source media="(prefers-color-scheme: dark)" srcset="./docs/wordmark-dark.svg">
5
- <img src="./docs/wordmark-light.svg" alt="emailens / engine" width="515">
6
- </picture>
7
-
8
- **The rendering linter for email**
9
-
10
- [![CI](https://github.com/emailens/engine/actions/workflows/ci.yml/badge.svg)](https://github.com/emailens/engine/actions/workflows/ci.yml)
11
- [![npm](https://img.shields.io/npm/v/@emailens/engine)](https://www.npmjs.com/package/@emailens/engine)
12
- [![license](https://img.shields.io/npm/l/@emailens/engine)](./LICENSE)
13
- [![tests](https://img.shields.io/badge/tests-1108%20passing-brightgreen)]()
14
- [![node](https://img.shields.io/node/v/@emailens/engine)](https://nodejs.org/)
15
- [![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://github.com/emailens/mcp)
16
- [![GitHub stars](https://img.shields.io/github/stars/emailens/engine?style=flat)](https://github.com/emailens/engine/stargazers)
17
-
18
- [Quick Start](#quick-start) · [What It Catches](#what-it-catches) · [Why Emailens](#why-emailens) · [Supported Clients](#supported-email-clients) · [API Docs](./docs/API.md) · [The State of Email CSS](https://emailens.dev/email-css/report)
19
-
20
- </div>
21
-
22
- **Your email looks perfect in Apple Mail. Gmail strips half the CSS. Outlook renders it in Word.**
23
-
24
- `@emailens/engine` analyzes your email against 255 CSS and HTML features across 21 email clients, scores compatibility, and shows you exactly what to fix: before you hit send.
25
-
26
- Write it however you like. **HTML, MJML, Maizzle and React Email** all go in the front: the engine compiles the template with your own compiler and lints the HTML that actually gets sent, which is the only version your reader sees.
27
-
28
- Our data says you need this: of those 255 features, **only 6 are fully supported in every major email client**. See [The State of Email CSS](https://emailens.dev/email-css/report).
29
-
30
- ![emailens lint output showing errors and warnings across email clients](./docs/lint-demo.png)
31
-
32
- > **[emailens.dev](https://emailens.dev)**: Try the hosted version. Paste HTML, get a full audit in seconds.
33
-
34
- ## Quick Start
35
-
36
- No install, no project setup, lint any email right now:
37
-
38
- ```bash
39
- npx @emailens/cli lint email.html
40
- ```
41
-
42
- Or use the engine as a library:
43
-
44
- ```bash
45
- npm install @emailens/engine
46
- ```
47
-
48
- ```typescript
49
- import { auditEmail } from "@emailens/engine";
50
-
51
- // Flexbox + gap + box-shadow — all Outlook killers
52
- const html = `<html lang="en">
53
- <head><title>Weekly Update</title>
54
- <style>
55
- .card { border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
56
- </style>
57
- </head>
58
- <body>
59
- <div class="card" style="display: flex; gap: 16px;">
60
- <div>Column A</div>
61
- <div>Column B</div>
62
- </div>
63
- </body>
64
- </html>`;
65
-
66
- const report = auditEmail(html, { framework: "jsx" });
67
-
68
- console.log(report.compatibility.scores["outlook-windows"]);
69
- // { score: 30, errors: 3, warnings: 3, info: 1 }
70
- // ↑ Outlook uses Word — flexbox, gap, box-shadow, border-radius all break
71
-
72
- console.log(report.compatibility.scores["gmail-web"]);
73
- // { score: 75, errors: 0, warnings: 5, info: 0 }
74
-
75
- console.log(report.spam.score); // 100 (clean)
76
- console.log(report.accessibility.score); // 88
77
- console.log(report.size.clipped); // false (under Gmail's 102KB limit)
78
- ```
79
-
80
- ## Score too low? Fix it
81
-
82
- Score too low? Fix it automatically:
83
-
84
- ```typescript
85
- import { generateAiFix, AI_FIX_SYSTEM_PROMPT } from "@emailens/engine";
86
-
87
- const { code } = await generateAiFix({
88
- originalHtml: html,
89
- warnings: report.compatibility.warnings,
90
- scores: report.compatibility.scores,
91
- scope: "outlook-windows",
92
- format: "jsx",
93
- provider: async (prompt) => {
94
- // Any LLM — Claude, GPT, etc.
95
- const msg = await anthropic.messages.create({
96
- model: "claude-sonnet-4-6",
97
- max_tokens: 8192,
98
- system: AI_FIX_SYSTEM_PROMPT,
99
- messages: [{ role: "user", content: prompt }],
100
- });
101
- return msg.content[0].type === "text" ? msg.content[0].text : "";
102
- },
103
- });
104
- // code → JSX with <Table> layout, VML roundrects, inline fallbacks
105
- ```
106
-
107
- ## What It Catches
108
-
109
- 14 analysis engines, one `auditEmail()` call.
110
-
111
- - **CSS compatibility**: 255 CSS and HTML features tested across 21 email clients, with fix snippets and AI-powered auto-fix
112
- - **Outlook VML**: structural faults in the Outlook-only markup inside `<!--[if mso]>` conditional comments — the one part of an email a DOM analyzer structurally cannot see, since to every HTML parser it is a comment node and to a screenshot it does not exist
113
- - **Content overflow**: fixed widths wider than the email frame and unbreakable strings that force horizontal scrolling
114
- - **Visual bugs**: gradients/background images with no color fallback (invisible content in Outlook) and fonts with no web-safe fallback, each with a concrete fix
115
- - **Design consistency**: colours that differ as values but not to a reader (OKLab distance), and runaway cardinality in type sizes, families and corner radii
116
- - **Dark and mobile contrast**: the two renders nobody checks — what a client's forced inversion does, what the email's own `prefers-color-scheme` block does, and what changes below the mobile breakpoint
117
- - **Spam scoring**: 45+ signals modeled after SpamAssassin, CAN-SPAM, and GDPR
118
- - **Accessibility**: WCAG contrast ratios, alt text, semantic structure, heading hierarchy
119
- - **Link validation**: broken hrefs, insecure HTTP, `javascript:` protocols, deceptive URLs
120
- - **Image analysis**: missing dimensions, oversized data URIs, tracking pixels, WebP/SVG format
121
- - **Inbox preview**: subject/preheader truncation per client, Gmail clipping detection
122
- - **Domain authentication**: SPF, DKIM, DMARC, MX, and BIMI DNS record validation
123
- - **Template variables**: unresolved merge tags across 6 template systems (Handlebars, ERB, Mailchimp, etc.)
124
-
125
- Every finding can carry its **source position**: line, column and offset, plus
126
- every place it occurs, so a result can be pointed at, annotated on a pull
127
- request, or fixed in place:
128
-
129
- ```typescript
130
- const report = auditEmail(html, { positions: true });
131
- const w = report.compatibility.warnings[0];
132
- `${file}:${w.loc.line}:${w.loc.column}`; // emails/welcome.html:42:8
133
- w.locs.length; // every element it breaks on
134
- ```
135
-
136
- ## Installation
137
-
138
- ```bash
139
- npm install @emailens/engine
140
- ```
141
-
142
- Three entry points:
143
-
144
- | Import | Description |
145
- |---|---|
146
- | `@emailens/engine` | Core analysis: CSS, spam, a11y, links, images, inbox preview, size, templates, AI fix |
147
- | `@emailens/engine/compile` | JSX / MJML / Maizzle → HTML compilers |
148
- | `@emailens/engine/server` | Node-only: DNS deliverability checks, SpamAssassin integration |
149
-
150
- ## Why Emailens?
151
-
152
- - **Offline-first**: runs entirely locally, no network calls required (except DNS deliverability checks)
153
- - **Unified audit**: one function call returns CSS compatibility, spam, accessibility, links, images, inbox preview, size, and template checks
154
- - **Framework-aware**: fix snippets tailored to React Email (JSX), MJML, and Maizzle
155
- - **AI-ready**: structural issues get LLM-powered auto-fix with any provider (Claude, GPT, etc.)
156
- - **Programmable**: a TypeScript API, not a GUI. Drops into CI, editors, or build pipelines
157
-
158
- | | @emailens/engine | Litmus | Email on Acid | caniemail.com |
159
- |---|---|---|---|---|
160
- | Local/offline | Yes | No | No | Data only |
161
- | Programmatic API | Yes | Limited | No | No |
162
- | CSS + Spam + A11y | Yes | Separate tools | Separate tools | CSS only |
163
- | AI auto-fix | Yes | No | No | No |
164
- | Open source | MIT | No | No | Yes (data) |
165
-
166
- ### vs other email libraries
167
-
168
- `@emailens/engine` sits in the **QA / lint / scoring** slot: it analyzes finished HTML. It's complementary to (not a replacement for) composition and inlining libraries.
169
-
170
- | | @emailens/engine | [juice](https://github.com/automattic/juice) | [email-comb](https://github.com/codsen/email-comb) | [mjml](https://mjml.io/) | [maizzle](https://maizzle.com/) |
171
- |---|---|---|---|---|---|
172
- | Purpose | QA / lint / score | CSS inliner | Unused CSS pruner | MJML → HTML | Tailwind → HTML |
173
- | Per-client compatibility scoring | Yes | No | No | No | No |
174
- | Spam / a11y / link / image analysis | Yes | No | No | No | No |
175
- | AI-powered fix generation | Yes | No | No | No | No |
176
- | Compose emails | Reads only | Reads only | Reads only | Yes | Yes |
177
- | CSS inlining | No (pair with juice) | Yes | No | Yes (built-in) | Yes (built-in) |
178
-
179
- A typical pipeline: write in **mjml** or **maizzle** → inline with **juice** → audit with **@emailens/engine** → ship.
180
-
181
- ## Supported Email Clients
182
-
183
- | Client | ID | Category | Engine | Dark Mode |
184
- |---|---|---|---|---|
185
- | Gmail | `gmail-web` | Webmail | Gmail Web | Yes |
186
- | Gmail Android | `gmail-android` | Mobile | Gmail Mobile | Yes |
187
- | Gmail iOS | `gmail-ios` | Mobile | Gmail Mobile | Yes |
188
- | Outlook 365 | `outlook-web` | Webmail | Outlook Web | Yes |
189
- | Outlook (New) | `outlook-windows` | Desktop | Outlook Web | Yes |
190
- | Outlook Classic | `outlook-windows-legacy` | Desktop | Microsoft Word | Yes |
191
- | Outlook iOS | `outlook-ios` | Mobile | Outlook Mobile | Yes |
192
- | Outlook Android | `outlook-android` | Mobile | Outlook Mobile | Yes |
193
- | Outlook for Mac | `outlook-macos` | Desktop | WebKit | Yes |
194
- | Apple Mail | `apple-mail-macos` | Desktop | WebKit | Yes |
195
- | Apple Mail iOS | `apple-mail-ios` | Mobile | WebKit | Yes |
196
- | Yahoo Mail | `yahoo-mail` | Webmail | Yahoo | Yes |
197
- | Yahoo Mail Android | `yahoo-mail-android` | Mobile | Yahoo | Yes |
198
- | Yahoo Mail iOS | `yahoo-mail-ios` | Mobile | Yahoo | Yes |
199
- | Samsung Mail | `samsung-mail` | Mobile | Samsung | Yes |
200
- | Thunderbird | `thunderbird` | Desktop | Gecko | No |
201
- | HEY Mail | `hey-mail` | Webmail | WebKit | Yes |
202
- | Proton Mail | `protonmail` | Webmail | Proton | Yes |
203
- | AOL Mail | `aol` | Webmail | AOL | Yes |
204
- | Fastmail | `fastmail` | Webmail | Fastmail | Yes |
205
- | Superhuman | `superhuman` | Desktop | Blink | Yes |
206
-
207
- ## API Documentation
208
-
209
- Full API reference: **[docs/API.md](./docs/API.md)**
210
-
211
- Covers:
212
- - `auditEmail` and `createSession`: core analysis
213
- - Standalone analyzers (CSS, VML, spam, links, accessibility, images, inbox preview, size, templates)
214
- - DNS deliverability and SpamAssassin integration
215
- - Client transforms and dark mode simulation
216
- - Compile module (JSX, MJML, Maizzle)
217
- - AI-powered fixes and token estimation
218
- - Performance optimization guide
219
- - Security considerations
220
- - Full TypeScript type definitions
221
-
222
- ## Roadmap
223
-
224
- See [ROADMAP.md](./ROADMAP.md) for the full picture (shipped items + items under consideration with rationale).
225
-
226
- **Shipped:** Outlook VML structural validation (`checkVml`, verified against the Word engine) · automated caniemail.com data sync · GitHub Actions integration via `@emailens/cli` and the [Marketplace Action](https://github.com/marketplace/actions/emailens-email-preview-check) · AI-powered fix generation · compile module for JSX/MJML/Maizzle.
227
-
228
- **Considering:** Outlook VML auto-generation · plugin system for custom analyzers · MJML/Maizzle source-level linting · ESLint plugin · spam corpus tuning · dark-mode accuracy tests.
229
-
230
- Concrete bugs go in [Issues](https://github.com/emailens/engine/issues). Open-ended ideas live in the roadmap.
231
-
232
- ## Contributing
233
-
234
- Contributions are welcome! See **[CONTRIBUTING.md](./CONTRIBUTING.md)** for architecture overview, setup instructions, and PR guidelines.
235
-
236
- ```bash
237
- bun install && bun test # 719 tests
238
- ```
239
-
240
- Optional real-render validation: renders engine output in a real browser engine (free, no Litmus/Email on Acid needed). Off by default; needs a browser-capable machine:
241
-
242
- ```bash
243
- bunx playwright install chromium
244
- bun run test:render
245
- ```
246
-
247
- ### Data Maintenance
248
-
249
- CSS support data is auto-synced from [caniemail.com](https://www.caniemail.com/). Other data (dark mode behavior, display limits, Superhuman overrides) is manually curated and tracked with verification dates.
250
-
251
- ```bash
252
- bun run sync:caniemail # Refresh CSS support matrix from caniemail.com
253
- bun run check:freshness # Flag stale data sources (exits 1 if any overdue)
254
- ```
255
-
256
- See [CONTRIBUTING.md](./CONTRIBUTING.md#data-sources-and-freshness) for full details on data sources and verification procedures.
257
-
258
- ## License
259
-
260
- MIT, Copyright 2025 [Emailens](https://emailens.dev)
261
-
262
- ---
263
-
264
- If this saved you from an Outlook surprise, [a star](https://github.com/emailens/engine) helps other email developers find it.
1
+ <div align="center">
2
+
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="./docs/wordmark-dark.svg">
5
+ <img src="./docs/wordmark-light.svg" alt="emailens / engine" width="515">
6
+ </picture>
7
+
8
+ **The rendering linter for email**
9
+
10
+ [![CI](https://github.com/emailens/engine/actions/workflows/ci.yml/badge.svg)](https://github.com/emailens/engine/actions/workflows/ci.yml)
11
+ [![npm](https://img.shields.io/npm/v/@emailens/engine)](https://www.npmjs.com/package/@emailens/engine)
12
+ [![license](https://img.shields.io/npm/l/@emailens/engine)](./LICENSE)
13
+ [![tests](https://img.shields.io/badge/tests-1108%20passing-brightgreen)]()
14
+ [![node](https://img.shields.io/node/v/@emailens/engine)](https://nodejs.org/)
15
+ [![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://github.com/emailens/mcp)
16
+ [![GitHub stars](https://img.shields.io/github/stars/emailens/engine?style=flat)](https://github.com/emailens/engine/stargazers)
17
+
18
+ [Quick Start](#quick-start) · [What It Catches](#what-it-catches) · [Why Emailens](#why-emailens) · [Supported Clients](#supported-email-clients) · [API Docs](./docs/API.md) · [The State of Email CSS](https://emailens.dev/email-css/report)
19
+
20
+ </div>
21
+
22
+ **Your email looks perfect in Apple Mail. Gmail strips half the CSS. Outlook renders it in Word.**
23
+
24
+ `@emailens/engine` analyzes your email against 298 CSS and HTML features (plus 14 image formats) across 21 email clients, scores compatibility, and shows you exactly what to fix: before you hit send.
25
+
26
+ Write it however you like. **HTML, MJML, Maizzle and React Email** all go in the front: the engine compiles the template with your own compiler and lints the HTML that actually gets sent, which is the only version your reader sees.
27
+
28
+ Our data says you need this: of those 298 features, **only 6 are fully supported in every one of the 21 clients**. See [The State of Email CSS](https://emailens.dev/email-css/report).
29
+
30
+ ![emailens lint output showing errors and warnings across email clients](./docs/lint-demo.png)
31
+
32
+ > **[emailens.dev](https://emailens.dev)**: Try the hosted version. Paste HTML, get a full audit in seconds.
33
+
34
+ ## Quick Start
35
+
36
+ No install, no project setup, lint any email right now:
37
+
38
+ ```bash
39
+ npx @emailens/cli lint email.html
40
+ ```
41
+
42
+ Or use the engine as a library:
43
+
44
+ ```bash
45
+ npm install @emailens/engine
46
+ ```
47
+
48
+ ```typescript
49
+ import { auditEmail } from "@emailens/engine";
50
+
51
+ // Flexbox + gap + box-shadow — all Outlook killers
52
+ const html = `<html lang="en">
53
+ <head><title>Weekly Update</title>
54
+ <style>
55
+ .card { border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
56
+ </style>
57
+ </head>
58
+ <body>
59
+ <div class="card" style="display: flex; gap: 16px;">
60
+ <div>Column A</div>
61
+ <div>Column B</div>
62
+ </div>
63
+ </body>
64
+ </html>`;
65
+
66
+ const report = auditEmail(html, { framework: "jsx" });
67
+
68
+ console.log(report.compatibility.scores["outlook-windows"]);
69
+ // { score: 30, errors: 3, warnings: 3, info: 1 }
70
+ // ↑ Outlook uses Word — flexbox, gap, box-shadow, border-radius all break
71
+
72
+ console.log(report.compatibility.scores["gmail-web"]);
73
+ // { score: 75, errors: 0, warnings: 5, info: 0 }
74
+
75
+ console.log(report.spam.score); // 100 (clean)
76
+ console.log(report.accessibility.score); // 88
77
+ console.log(report.size.clipped); // false (under Gmail's 102KB limit)
78
+ ```
79
+
80
+ ## Score too low? Fix it
81
+
82
+ Score too low? Fix it automatically:
83
+
84
+ ```typescript
85
+ import { generateAiFix, AI_FIX_SYSTEM_PROMPT } from "@emailens/engine";
86
+
87
+ const { code } = await generateAiFix({
88
+ originalHtml: html,
89
+ warnings: report.compatibility.warnings,
90
+ scores: report.compatibility.scores,
91
+ scope: "outlook-windows",
92
+ format: "jsx",
93
+ provider: async (prompt) => {
94
+ // Any LLM — Claude, GPT, etc.
95
+ const msg = await anthropic.messages.create({
96
+ model: "claude-sonnet-4-6",
97
+ max_tokens: 8192,
98
+ system: AI_FIX_SYSTEM_PROMPT,
99
+ messages: [{ role: "user", content: prompt }],
100
+ });
101
+ return msg.content[0].type === "text" ? msg.content[0].text : "";
102
+ },
103
+ });
104
+ // code → JSX with <Table> layout, VML roundrects, inline fallbacks
105
+ ```
106
+
107
+ ## What It Catches
108
+
109
+ 14 analysis engines, one `auditEmail()` call.
110
+
111
+ - **CSS compatibility**: 298 CSS and HTML features tested across 21 email clients, with fix snippets and AI-powered auto-fix
112
+ - **Outlook VML**: structural faults in the Outlook-only markup inside `<!--[if mso]>` conditional comments — the one part of an email a DOM analyzer structurally cannot see, since to every HTML parser it is a comment node and to a screenshot it does not exist
113
+ - **Content overflow**: fixed widths wider than the email frame and unbreakable strings that force horizontal scrolling
114
+ - **Visual bugs**: gradients/background images with no color fallback (invisible content in Outlook) and fonts with no web-safe fallback, each with a concrete fix
115
+ - **Design consistency**: colours that differ as values but not to a reader (OKLab distance), and runaway cardinality in type sizes, families and corner radii
116
+ - **Dark and mobile contrast**: the two renders nobody checks — what a client's forced inversion does, what the email's own `prefers-color-scheme` block does, and what changes below the mobile breakpoint
117
+ - **Spam scoring**: 45+ signals modeled after SpamAssassin, CAN-SPAM, and GDPR
118
+ - **Accessibility**: WCAG contrast ratios, alt text, semantic structure, heading hierarchy
119
+ - **Link validation**: broken hrefs, insecure HTTP, `javascript:` protocols, deceptive URLs
120
+ - **Image analysis**: missing dimensions, oversized data URIs, tracking pixels, WebP/SVG format
121
+ - **Inbox preview**: subject/preheader truncation per client, Gmail clipping detection
122
+ - **Domain authentication**: SPF, DKIM, DMARC, MX, and BIMI DNS record validation
123
+ - **Template variables**: unresolved merge tags across 6 template systems (Handlebars, ERB, Mailchimp, etc.)
124
+
125
+ Every finding can carry its **source position**: line, column and offset, plus
126
+ every place it occurs, so a result can be pointed at, annotated on a pull
127
+ request, or fixed in place:
128
+
129
+ ```typescript
130
+ const report = auditEmail(html, { positions: true });
131
+ const w = report.compatibility.warnings[0];
132
+ `${file}:${w.loc.line}:${w.loc.column}`; // emails/welcome.html:42:8
133
+ w.locs.length; // every element it breaks on
134
+ ```
135
+
136
+ ## Installation
137
+
138
+ ```bash
139
+ npm install @emailens/engine
140
+ ```
141
+
142
+ Three entry points:
143
+
144
+ | Import | Description |
145
+ |---|---|
146
+ | `@emailens/engine` | Core analysis: CSS, spam, a11y, links, images, inbox preview, size, templates, AI fix |
147
+ | `@emailens/engine/compile` | JSX / MJML / Maizzle → HTML compilers |
148
+ | `@emailens/engine/server` | Node-only: DNS deliverability checks, SpamAssassin integration |
149
+
150
+ ## Why Emailens?
151
+
152
+ - **Offline-first**: runs entirely locally, no network calls required (except DNS deliverability checks)
153
+ - **Unified audit**: one function call returns CSS compatibility, spam, accessibility, links, images, inbox preview, size, and template checks
154
+ - **Framework-aware**: fix snippets tailored to React Email (JSX), MJML, and Maizzle
155
+ - **AI-ready**: structural issues get LLM-powered auto-fix with any provider (Claude, GPT, etc.)
156
+ - **Programmable**: a TypeScript API, not a GUI. Drops into CI, editors, or build pipelines
157
+
158
+ | | @emailens/engine | Litmus | Email on Acid | caniemail.com |
159
+ |---|---|---|---|---|
160
+ | Local/offline | Yes | No | No | Data only |
161
+ | Programmatic API | Yes | Limited | No | No |
162
+ | CSS + Spam + A11y | Yes | Separate tools | Separate tools | CSS only |
163
+ | AI auto-fix | Yes | No | No | No |
164
+ | Open source | MIT | No | No | Yes (data) |
165
+
166
+ ### vs other email libraries
167
+
168
+ `@emailens/engine` sits in the **QA / lint / scoring** slot: it analyzes finished HTML. It's complementary to (not a replacement for) composition and inlining libraries.
169
+
170
+ | | @emailens/engine | [juice](https://github.com/automattic/juice) | [email-comb](https://github.com/codsen/email-comb) | [mjml](https://mjml.io/) | [maizzle](https://maizzle.com/) |
171
+ |---|---|---|---|---|---|
172
+ | Purpose | QA / lint / score | CSS inliner | Unused CSS pruner | MJML → HTML | Tailwind → HTML |
173
+ | Per-client compatibility scoring | Yes | No | No | No | No |
174
+ | Spam / a11y / link / image analysis | Yes | No | No | No | No |
175
+ | AI-powered fix generation | Yes | No | No | No | No |
176
+ | Compose emails | Reads only | Reads only | Reads only | Yes | Yes |
177
+ | CSS inlining | No (pair with juice) | Yes | No | Yes (built-in) | Yes (built-in) |
178
+
179
+ A typical pipeline: write in **mjml** or **maizzle** → inline with **juice** → audit with **@emailens/engine** → ship.
180
+
181
+ ## Supported Email Clients
182
+
183
+ | Client | ID | Category | Engine | Dark Mode |
184
+ |---|---|---|---|---|
185
+ | Gmail | `gmail-web` | Webmail | Gmail Web | Yes |
186
+ | Gmail Android | `gmail-android` | Mobile | Gmail Mobile | Yes |
187
+ | Gmail iOS | `gmail-ios` | Mobile | Gmail Mobile | Yes |
188
+ | Outlook 365 | `outlook-web` | Webmail | Outlook Web | Yes |
189
+ | Outlook (New) | `outlook-windows` | Desktop | Outlook Web | Yes |
190
+ | Outlook Classic | `outlook-windows-legacy` | Desktop | Microsoft Word | Yes |
191
+ | Outlook iOS | `outlook-ios` | Mobile | Outlook Mobile | Yes |
192
+ | Outlook Android | `outlook-android` | Mobile | Outlook Mobile | Yes |
193
+ | Outlook for Mac | `outlook-macos` | Desktop | WebKit | Yes |
194
+ | Apple Mail | `apple-mail-macos` | Desktop | WebKit | Yes |
195
+ | Apple Mail iOS | `apple-mail-ios` | Mobile | WebKit | Yes |
196
+ | Yahoo Mail | `yahoo-mail` | Webmail | Yahoo | Yes |
197
+ | Yahoo Mail Android | `yahoo-mail-android` | Mobile | Yahoo | Yes |
198
+ | Yahoo Mail iOS | `yahoo-mail-ios` | Mobile | Yahoo | Yes |
199
+ | Samsung Mail | `samsung-mail` | Mobile | Samsung | Yes |
200
+ | Thunderbird | `thunderbird` | Desktop | Gecko | No |
201
+ | HEY Mail | `hey-mail` | Webmail | WebKit | Yes |
202
+ | Proton Mail | `protonmail` | Webmail | Proton | Yes |
203
+ | AOL Mail | `aol` | Webmail | AOL | Yes |
204
+ | Fastmail | `fastmail` | Webmail | Fastmail | Yes |
205
+ | Superhuman | `superhuman` | Desktop | Blink | Yes |
206
+
207
+ ## API Documentation
208
+
209
+ Full API reference: **[docs/API.md](./docs/API.md)**
210
+
211
+ Covers:
212
+ - `auditEmail` and `createSession`: core analysis
213
+ - Standalone analyzers (CSS, VML, spam, links, accessibility, images, inbox preview, size, templates)
214
+ - DNS deliverability and SpamAssassin integration
215
+ - Client transforms and dark mode simulation
216
+ - Compile module (JSX, MJML, Maizzle)
217
+ - AI-powered fixes and token estimation
218
+ - Performance optimization guide
219
+ - Security considerations
220
+ - Full TypeScript type definitions
221
+
222
+ ## Roadmap
223
+
224
+ See [ROADMAP.md](./ROADMAP.md) for the full picture (shipped items + items under consideration with rationale).
225
+
226
+ **Shipped:** Outlook VML structural validation (`checkVml`, verified against the Word engine) · automated caniemail.com data sync · GitHub Actions integration via `@emailens/cli` and the [Marketplace Action](https://github.com/marketplace/actions/emailens-email-preview-check) · AI-powered fix generation · compile module for JSX/MJML/Maizzle.
227
+
228
+ **Considering:** Outlook VML auto-generation · plugin system for custom analyzers · MJML/Maizzle source-level linting · ESLint plugin · spam corpus tuning · dark-mode accuracy tests.
229
+
230
+ Concrete bugs go in [Issues](https://github.com/emailens/engine/issues). Open-ended ideas live in the roadmap.
231
+
232
+ ## Contributing
233
+
234
+ Contributions are welcome! See **[CONTRIBUTING.md](./CONTRIBUTING.md)** for architecture overview, setup instructions, and PR guidelines.
235
+
236
+ ```bash
237
+ bun install && bun test # 719 tests
238
+ ```
239
+
240
+ Optional real-render validation: renders engine output in a real browser engine (free, no Litmus/Email on Acid needed). Off by default; needs a browser-capable machine:
241
+
242
+ ```bash
243
+ bunx playwright install chromium
244
+ bun run test:render
245
+ ```
246
+
247
+ ### Data Maintenance
248
+
249
+ CSS support data is auto-synced from [caniemail.com](https://www.caniemail.com/). Other data (dark mode behavior, display limits, Superhuman overrides) is manually curated and tracked with verification dates.
250
+
251
+ ```bash
252
+ bun run sync:caniemail # Refresh CSS support matrix from caniemail.com
253
+ bun run check:freshness # Flag stale data sources (exits 1 if any overdue)
254
+ ```
255
+
256
+ See [CONTRIBUTING.md](./CONTRIBUTING.md#data-sources-and-freshness) for full details on data sources and verification procedures.
257
+
258
+ ## License
259
+
260
+ MIT, Copyright 2025 [Emailens](https://emailens.dev)
261
+
262
+ ---
263
+
264
+ If this saved you from an Outlook surprise, [a star](https://github.com/emailens/engine) helps other email developers find it.
package/dist/{chunk-PW6EUG2G.js → chunk-OA6VNA5L.js} RENAMED
@@ -6,6 +6,9 @@ import {
6
6
  var MAX_SOURCE_SIZE = 512e3;
7
7
  var COMPILE_TIMEOUT_MS = 15e3;
8
8
  var DANGEROUS_DIRECTIVE_RE = /<\s*(?:extends|component|fetch|include|module|slot|fill|raw|block|yield)\b/i;
9
+ function isMaizzle6(mod) {
10
+ return "createRenderer" in mod;
11
+ }
9
12
  async function compileMaizzle(source) {
10
13
  if (!source || !source.trim()) {
11
14
  throw new CompileError("Maizzle source must not be empty.", "maizzle", "validation");
@@ -25,16 +28,24 @@ async function compileMaizzle(source) {
25
28
  );
26
29
  }
27
30
  let maizzleRender;
31
+ let maizzle;
28
32
  try {
29
- const maizzle = await import("@maizzle/framework");
30
- maizzleRender = maizzle.render;
33
+ maizzle = await import("@maizzle/framework");
31
34
  } catch (e) {
32
35
  throw new CompileError(
33
- 'Maizzle compilation requires "@maizzle/framework". Install it:\n npm install @maizzle/framework',
36
+ 'Maizzle compilation requires "@maizzle/framework". Install it:\n npm install @maizzle/framework@5',
37
+ "maizzle",
38
+ "compile"
39
+ );
40
+ }
41
+ if (isMaizzle6(maizzle)) {
42
+ throw new CompileError(
43
+ "Maizzle 6 is installed, and this engine compiles Maizzle 5 templates.\nMaizzle 6 renders Vue single-file components rather than HTML, so an\nHTML template is not something it can read. Install the supported major:\n npm install @maizzle/framework@5",
34
44
  "maizzle",
35
45
  "compile"
36
46
  );
37
47
  }
48
+ maizzleRender = maizzle.render;
38
49
  const compilePromise = maizzleRender(source, {
39
50
  css: {
40
51
  inline: {
@@ -73,6 +84,7 @@ async function compileMaizzle(source) {
73
84
  }
74
85
 
75
86
  export {
87
+ isMaizzle6,
76
88
  compileMaizzle
77
89
  };
78
- //# sourceMappingURL=chunk-PW6EUG2G.js.map
90
+ //# sourceMappingURL=chunk-OA6VNA5L.js.map
package/dist/chunk-OA6VNA5L.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/compile/maizzle.ts"],"sourcesContent":["import { CompileError } from \"./errors.js\";\r\n\r\n/** Maximum Maizzle source size: 512KB */\r\nconst MAX_SOURCE_SIZE = 512_000;\r\n\r\n/** Compilation timeout: 15 seconds */\r\nconst COMPILE_TIMEOUT_MS = 15_000;\r\n\r\n/**\r\n * PostHTML directives that perform file-system reads or network fetches.\r\n *\r\n * Maizzle's PostHTML pipeline resolves these at compile time: a template\r\n * like `<extends src=\"/etc/passwd\">` causes the server to read that path\r\n * and include the content in rendered output (server-side file read). We\r\n * reject any input containing these directives rather than stripping them,\r\n * because stripping is error-prone with nested or malformed markup.\r\n *\r\n * Affected plugins: posthtml-extend, posthtml-fetch, posthtml-components,\r\n * posthtml-include, posthtml-modules.\r\n */\r\nconst DANGEROUS_DIRECTIVE_RE =\r\n /<\\s*(?:extends|component|fetch|include|module|slot|fill|raw|block|yield)\\b/i;\r\n\r\n/**\r\n * Compile a Maizzle template string into an HTML email string.\r\n *\r\n * Pipeline:\r\n * 1. Validate input (size, basic structure check)\r\n * 2. Reject inputs containing PostHTML file-access directives\r\n * 3. Compile using @maizzle/framework\r\n *\r\n * Security:\r\n * - PostHTML file-system directives are rejected at validation time\r\n * to prevent server-side file reads and SSRF.\r\n * - Template expressions ({{ expr }}) are evaluated by posthtml-expressions\r\n * with empty `locals`, so unknown identifiers like `process` or `require`\r\n * return the literal string '{local}' rather than accessing Node.js globals.\r\n * - A hard timeout prevents pathological PostCSS/Tailwind inputs from\r\n * hanging indefinitely.\r\n *\r\n * Requires peer dependency: @maizzle/framework\r\n */\r\n/**\r\n * Is this the Maizzle 6 module?\r\n *\r\n * Maizzle 6 replaced the HTML template with a Vue single-file component, and\r\n * its `render` resolves a string argument as a path rather than as source.\r\n * Handed a template it reports `Failed to load url <!DOCTYPE html>…`, which\r\n * describes nothing an author can act on, so the caller checks first and says\r\n * what actually happened.\r\n *\r\n * `createRenderer` is the discriminator: exported by every v6 release and by\r\n * no v5 one. The module carries no version to read, so a capability probe is\r\n * what there is.\r\n */\r\nexport function isMaizzle6(mod: object): boolean {\r\n return \"createRenderer\" in mod;\r\n}\r\n\r\nexport async function compileMaizzle(source: string): Promise<string> {\r\n // ── 1. Validate ──────────────────────────────────────────────────────\r\n if (!source || !source.trim()) {\r\n throw new CompileError(\"Maizzle source must not be empty.\", \"maizzle\", \"validation\");\r\n }\r\n\r\n if (source.length > MAX_SOURCE_SIZE) {\r\n throw new CompileError(\r\n `Maizzle source exceeds ${MAX_SOURCE_SIZE / 1000}KB limit.`,\r\n \"maizzle\",\r\n \"validation\",\r\n );\r\n }\r\n\r\n // ── 2. Block file-system and network PostHTML directives ─────────────\r\n if (DANGEROUS_DIRECTIVE_RE.test(source)) {\r\n throw new CompileError(\r\n \"Maizzle templates may not use <extends>, <component>, <fetch>, <include>, \" +\r\n \"<module>, <slot>, <fill>, <raw>, <block>, or <yield> directives. These directives \" +\r\n \"access the server file system at compile time. Use inline HTML and Tailwind utility classes instead.\",\r\n \"maizzle\",\r\n \"validation\",\r\n );\r\n }\r\n\r\n // ── 3. Load peer dependency ──────────────────────────────────────────\r\n let maizzleRender: (\r\n input: string,\r\n options: Record<string, unknown>,\r\n ) => Promise<{ html: string }>;\r\n\r\n let maizzle: Record<string, unknown>;\r\n try {\r\n maizzle = (await import(\"@maizzle/framework\")) as unknown as Record<string, unknown>;\r\n } catch {\r\n throw new CompileError(\r\n 'Maizzle compilation requires \"@maizzle/framework\". Install it:\\n' +\r\n \" npm install @maizzle/framework@5\",\r\n \"maizzle\",\r\n \"compile\",\r\n );\r\n }\r\n\r\n if (isMaizzle6(maizzle)) {\r\n throw new CompileError(\r\n \"Maizzle 6 is installed, and this engine compiles Maizzle 5 templates.\\n\" +\r\n \"Maizzle 6 renders Vue single-file components rather than HTML, so an\\n\" +\r\n \"HTML template is not something it can read. Install the supported major:\\n\" +\r\n \" npm install @maizzle/framework@5\",\r\n \"maizzle\",\r\n \"compile\",\r\n );\r\n }\r\n maizzleRender = maizzle.render as typeof maizzleRender;\r\n\r\n // ── 4. Compile with timeout ──────────────────────────────────────────\r\n const compilePromise = maizzleRender(source, {\r\n css: {\r\n inline: {\r\n removeInlinedSelectors: true,\r\n applyWidthAttributes: true,\r\n applyHeightAttributes: true,\r\n },\r\n shorthand: true,\r\n sixHex: true,\r\n },\r\n locals: {},\r\n });\r\n\r\n const timeoutPromise = new Promise<never>((_, reject) => {\r\n const t = setTimeout(() => {\r\n reject(\r\n new CompileError(\r\n `Maizzle compilation timed out after ${COMPILE_TIMEOUT_MS / 1000}s.`,\r\n \"maizzle\",\r\n \"compile\",\r\n ),\r\n );\r\n }, COMPILE_TIMEOUT_MS);\r\n if (typeof t.unref === \"function\") t.unref();\r\n });\r\n\r\n try {\r\n const { html } = await Promise.race([compilePromise, timeoutPromise]);\r\n\r\n if (!html) {\r\n throw new CompileError(\"Maizzle compilation produced empty output.\", \"maizzle\", \"compile\");\r\n }\r\n\r\n return html;\r\n } catch (err: unknown) {\r\n if (err instanceof CompileError) throw err;\r\n const message = err instanceof Error ? err.message : \"Unknown Maizzle compilation error\";\r\n throw new CompileError(`Maizzle compilation failed: ${message}`, \"maizzle\", \"compile\");\r\n }\r\n}\r\n"],"mappings":";;;;;AAGA,IAAM,kBAAkB;AAGxB,IAAM,qBAAqB;AAc3B,IAAM,yBACJ;AAkCK,SAAS,WAAW,KAAsB;AAC/C,SAAO,oBAAoB;AAC7B;AAEA,eAAsB,eAAe,QAAiC;AAEpE,MAAI,CAAC,UAAU,CAAC,OAAO,KAAK,GAAG;AAC7B,UAAM,IAAI,aAAa,qCAAqC,WAAW,YAAY;AAAA,EACrF;AAEA,MAAI,OAAO,SAAS,iBAAiB;AACnC,UAAM,IAAI;AAAA,MACR,0BAA0B,kBAAkB,GAAI;AAAA,MAChD;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAGA,MAAI,uBAAuB,KAAK,MAAM,GAAG;AACvC,UAAM,IAAI;AAAA,MACR;AAAA,MAGA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAGA,MAAI;AAKJ,MAAI;AACJ,MAAI;AACF,cAAW,MAAM,OAAO,oBAAoB;AAAA,EAC9C,SAAQ;AACN,UAAM,IAAI;AAAA,MACR;AAAA,MAEA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAEA,MAAI,WAAW,OAAO,GAAG;AACvB,UAAM,IAAI;AAAA,MACR;AAAA,MAIA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACA,kBAAgB,QAAQ;AAGxB,QAAM,iBAAiB,cAAc,QAAQ;AAAA,IAC3C,KAAK;AAAA,MACH,QAAQ;AAAA,QACN,wBAAwB;AAAA,QACxB,sBAAsB;AAAA,QACtB,uBAAuB;AAAA,MACzB;AAAA,MACA,WAAW;AAAA,MACX,QAAQ;AAAA,IACV;AAAA,IACA,QAAQ,CAAC;AAAA,EACX,CAAC;AAED,QAAM,iBAAiB,IAAI,QAAe,CAAC,GAAG,WAAW;AACvD,UAAM,IAAI,WAAW,MAAM;AACzB;AAAA,QACE,IAAI;AAAA,UACF,uCAAuC,qBAAqB,GAAI;AAAA,UAChE;AAAA,UACA;AAAA,QACF;AAAA,MACF;AAAA,IACF,GAAG,kBAAkB;AACrB,QAAI,OAAO,EAAE,UAAU,WAAY,GAAE,MAAM;AAAA,EAC7C,CAAC;AAED,MAAI;AACF,UAAM,EAAE,KAAK,IAAI,MAAM,QAAQ,KAAK,CAAC,gBAAgB,cAAc,CAAC;AAEpE,QAAI,CAAC,MAAM;AACT,YAAM,IAAI,aAAa,8CAA8C,WAAW,SAAS;AAAA,IAC3F;AAEA,WAAO;AAAA,EACT,SAAS,KAAc;AACrB,QAAI,eAAe,aAAc,OAAM;AACvC,UAAM,UAAU,eAAe,QAAQ,IAAI,UAAU;AACrD,UAAM,IAAI,aAAa,+BAA+B,OAAO,IAAI,WAAW,SAAS;AAAA,EACvF;AACF;","names":[]}
package/dist/compile/index.cjs CHANGED
@@ -478,8 +478,12 @@ var init_mjml = __esm({
478
478
  // src/compile/maizzle.ts
479
479
  var maizzle_exports = {};
480
480
  __export(maizzle_exports, {
481
- compileMaizzle: () => compileMaizzle
481
+ compileMaizzle: () => compileMaizzle,
482
+ isMaizzle6: () => isMaizzle6
482
483
  });
484
+ function isMaizzle6(mod) {
485
+ return "createRenderer" in mod;
486
+ }
483
487
  async function compileMaizzle(source) {
484
488
  if (!source || !source.trim()) {
485
489
  throw new CompileError("Maizzle source must not be empty.", "maizzle", "validation");
@@ -499,16 +503,24 @@ async function compileMaizzle(source) {
499
503
  );
500
504
  }
501
505
  let maizzleRender;
506
+ let maizzle;
502
507
  try {
503
- const maizzle = await import("@maizzle/framework");
504
- maizzleRender = maizzle.render;
508
+ maizzle = await import("@maizzle/framework");
505
509
  } catch (e) {
506
510
  throw new CompileError(
507
- 'Maizzle compilation requires "@maizzle/framework". Install it:\n npm install @maizzle/framework',
511
+ 'Maizzle compilation requires "@maizzle/framework". Install it:\n npm install @maizzle/framework@5',
512
+ "maizzle",
513
+ "compile"
514
+ );
515
+ }
516
+ if (isMaizzle6(maizzle)) {
517
+ throw new CompileError(
518
+ "Maizzle 6 is installed, and this engine compiles Maizzle 5 templates.\nMaizzle 6 renders Vue single-file components rather than HTML, so an\nHTML template is not something it can read. Install the supported major:\n npm install @maizzle/framework@5",
508
519
  "maizzle",
509
520
  "compile"
510
521
  );
511
522
  }
523
+ maizzleRender = maizzle.render;
512
524
  const compilePromise = maizzleRender(source, {
513
525
  css: {
514
526
  inline: {