@emailens/engine 0.10.0 → 0.10.2

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.
package/dist/index.d.cts CHANGED
@@ -1,6 +1,6 @@
1
- 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, I as ImageReport, g as InboxPreview, h as SizeReport, i as TemplateReport, O as OverflowReport, V as VisualReport, j as DeliverabilityReport } from './types-DEAn3IiX.cjs';
2
- export { k as AccessibilityIssue, B as BaseIssue, l as ClientTruncation, m as DeliverabilityCheck, n as DeliverabilityIssue, o as EstimateOptions, p as ExportScope, q as FixType, r as ImageInfo, s as ImageIssue, t as InboxPreviewIssue, u as InputFormat, v as LinkIssue, w as OverflowIssue, P as PreviewResult, x as Severity, y as SizeIssue, z as SpamIssue, G as TemplateIssue, H as TokenEstimate, J as TokenEstimateWithWarnings, K as VisualIssue, M as estimateAiFixTokens, N as generateFixPrompt, Q as heuristicTokenCount } from './types-DEAn3IiX.cjs';
3
- export { C as CompileError, a as CompileReactEmailOptions, S as SandboxStrategy } from './react-email-B1Rd5itD.cjs';
1
+ 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, I as ImageReport, g as InboxPreview, h as SizeReport, i as TemplateReport, O as OverflowReport, V as VisualReport, j as DeliverabilityReport } from './types-BLR3-Fzo.cjs';
2
+ export { k as AccessibilityIssue, B as BaseIssue, l as ClientTruncation, m as DeliverabilityCheck, n as DeliverabilityIssue, o as EstimateOptions, p as ExportScope, q as FixType, r as ImageInfo, s as ImageIssue, t as InboxPreviewIssue, u as InputFormat, v as LinkIssue, w as OverflowIssue, P as PreviewResult, x as Severity, y as SizeIssue, z as SourceLocation, G as SpamIssue, H as TemplateIssue, J as TokenEstimate, K as TokenEstimateWithWarnings, M as VisualIssue, N as estimateAiFixTokens, Q as generateFixPrompt, R as heuristicTokenCount } from './types-BLR3-Fzo.cjs';
3
+ export { C as CompileError, a as CompileReactEmailOptions, S as SandboxStrategy } from './react-email-DTzVpGgB.cjs';
4
4
 
5
5
  declare const EMAIL_CLIENTS: EmailClient[];
6
6
  declare function getClient(id: string): EmailClient | undefined;
@@ -8,6 +8,17 @@ declare function getClient(id: string): EmailClient | undefined;
8
8
  declare function transformForClient(html: string, clientId: string, framework?: Framework): TransformResult;
9
9
  declare function transformForAllClients(html: string, framework?: Framework): TransformResult[];
10
10
 
11
+ /** Options shared by every entry point that parses HTML. */
12
+ interface ParseOptions {
13
+ /**
14
+ * Record source positions so issues carry a `loc`. Costs a little parse time
15
+ * (parse5 tracks a location record per node and per attribute), so it is
16
+ * opt-in for callers that need to point at the source — editors, CI
17
+ * annotations, agents.
18
+ */
19
+ positions?: boolean;
20
+ }
21
+
11
22
  /**
12
23
  * Analyze an HTML email and return CSS compatibility warnings
13
24
  * for all target email clients.
@@ -18,7 +29,7 @@ declare function transformForAllClients(html: string, framework?: Framework): Tr
18
29
  * snippets reference source-level constructs so users know how to
19
30
  * modify their framework source code.
20
31
  */
21
- declare function analyzeEmail(html: string, framework?: Framework): CSSWarning[];
32
+ declare function analyzeEmail(html: string, framework?: Framework, options?: ParseOptions): CSSWarning[];
22
33
  /**
23
34
  * Generate a summary of CSS compatibility for the email.
24
35
  */
@@ -178,6 +189,11 @@ declare const AI_FIX_SYSTEM_PROMPT = "You are an expert email developer speciali
178
189
  * DO NOT EDIT — regenerate with: bun run sync:caniemail
179
190
  */
180
191
  declare const CSS_SUPPORT: Record<string, Record<string, SupportLevel>>;
192
+ /**
193
+ * Caveat notes per (feature, client) from caniemail — the "why" behind a
194
+ * partial/buggy/unsupported rating. Sparse: only cells with a note appear.
195
+ */
196
+ declare const CSS_SUPPORT_NOTES: Record<string, Record<string, string[]>>;
181
197
  /**
182
198
  * Properties that require HTML structural changes (not just CSS swaps)
183
199
  * to fix. These cannot be solved by replacing one CSS value with another.
@@ -192,6 +208,29 @@ declare const COMPOUND_VALUE_FEATURES: readonly ["::after", "::before", "::first
192
208
  /** CSS function features (e.g., "linear-gradient"). */
193
209
  declare const CSS_FUNCTION_FEATURES: readonly ["calc", "clamp", "conic-gradient", "fit-content", "linear-gradient", "max", "min", "radial-gradient"];
194
210
 
211
+ /**
212
+ * Properties whose "partial" rating is value-level: the property usually
213
+ * renders fine and only specific values hit the caveat. For these the warning
214
+ * is gated on the value actually written, using the per-client caniemail note,
215
+ * instead of flagging every use. Properties not listed keep the plain
216
+ * "partial → warn" behaviour.
217
+ *
218
+ * Adding a property here is a promise to read its notes: the gate is only as
219
+ * honest as the predicate below, and a wrong `false` is a missed rendering bug.
220
+ */
221
+ declare const VALUE_CAVEAT_PROPS: ReadonlySet<string>;
222
+ /**
223
+ * Does any of the values written for `prop` trigger this client's partial-support
224
+ * caveat? Values are per-declaration: a stylesheet setting `position: relative`
225
+ * in one rule and `position: fixed` in another passes both, and the caveat
226
+ * applies if either does.
227
+ *
228
+ * Returns true (report it) for a property that isn't value-gated, and for one
229
+ * where we never saw a value — an at-rule, a pseudo-class, a detected CSS
230
+ * function.
231
+ */
232
+ declare function caveatApplies(prop: string, values: readonly string[] | undefined, notes: string[] | undefined): boolean;
233
+
195
234
  /**
196
235
  * Analyze an HTML email for content hygiene issues.
197
236
  *
@@ -213,7 +252,7 @@ declare function analyzeSpam(html: string, options?: SpamAnalysisOptions): SpamR
213
252
  * empty/placeholder hrefs, javascript: protocol, insecure HTTP,
214
253
  * generic link text, accessibility issues, and more.
215
254
  */
216
- declare function validateLinks(html: string): LinkReport;
255
+ declare function validateLinks(html: string, options?: ParseOptions): LinkReport;
217
256
 
218
257
  /**
219
258
  * Audit an HTML email for accessibility issues.
@@ -222,7 +261,7 @@ declare function validateLinks(html: string): LinkReport;
222
261
  * layout table roles, link accessibility, heading hierarchy, and
223
262
  * color contrast. Returns a 0–100 score and detailed issues.
224
263
  */
225
- declare function checkAccessibility(html: string): AccessibilityReport;
264
+ declare function checkAccessibility(html: string, options?: ParseOptions): AccessibilityReport;
226
265
 
227
266
  /**
228
267
  * Analyze images in an HTML email for best practices.
@@ -231,7 +270,7 @@ declare function checkAccessibility(html: string): AccessibilityReport;
231
270
  * attributes, unsupported formats (WebP, SVG), tracking pixels,
232
271
  * missing display:block, and overall image heaviness.
233
272
  */
234
- declare function analyzeImages(html: string): ImageReport;
273
+ declare function analyzeImages(html: string, options?: ParseOptions): ImageReport;
235
274
 
236
275
  /**
237
276
  * Extract subject and preheader text from the email HTML, plus
@@ -260,22 +299,22 @@ declare function checkSize(html: string): SizeReport;
260
299
  *
261
300
  * Returns the count of unresolved variables and detailed issues.
262
301
  */
263
- declare function checkTemplateVariables(html: string): TemplateReport;
302
+ declare function checkTemplateVariables(html: string, options?: ParseOptions): TemplateReport;
264
303
 
265
304
  /**
266
305
  * Detect content likely to overflow the email frame or mobile viewport:
267
306
  * fixed pixel widths wider than the frame, and long unbreakable strings.
268
307
  */
269
- declare function checkOverflow(html: string): OverflowReport;
308
+ declare function checkOverflow(html: string, options?: ParseOptions): OverflowReport;
270
309
 
271
310
  /**
272
311
  * Detect probable visual bugs in a stylized email: background images/gradients
273
312
  * with no colour fallback, and font stacks with no web-safe fallback. Each
274
313
  * issue includes a concrete fix.
275
314
  */
276
- declare function checkVisual(html: string): VisualReport;
315
+ declare function checkVisual(html: string, options?: ParseOptions): VisualReport;
277
316
 
278
- interface AuditOptions {
317
+ interface AuditOptions extends ParseOptions {
279
318
  framework?: Framework;
280
319
  /** Options for spam analysis */
281
320
  spam?: SpamAnalysisOptions;
@@ -323,7 +362,7 @@ declare function auditEmail(html: string, options?: AuditOptions): AuditReport;
323
362
  */
324
363
  declare function toPlainText(html: string): string;
325
364
 
326
- interface CreateSessionOptions {
365
+ interface CreateSessionOptions extends ParseOptions {
327
366
  /** Framework for fix snippets (applies to analyze/audit/transform). */
328
367
  framework?: Framework;
329
368
  }
@@ -348,8 +387,12 @@ interface EmailSession {
348
387
  * Run all analysis checks in one call (shares pre-parsed DOM).
349
388
  *
350
389
  * Equivalent to `auditEmail()` but avoids re-parsing the HTML.
390
+ *
391
+ * `positions` is not accepted here: source positions are recorded at parse
392
+ * time, so the session's own option decides, and a per-call flag could only
393
+ * be ignored. Pass it to `createSession()` instead.
351
394
  */
352
- audit(options?: Omit<AuditOptions, "framework">): AuditReport;
395
+ audit(options?: Omit<AuditOptions, "framework" | "positions">): AuditReport;
353
396
  /**
354
397
  * Analyze CSS compatibility warnings (shares pre-parsed DOM).
355
398
  *
@@ -440,6 +483,13 @@ declare function createSession(html: string, options?: CreateSessionOptions): Em
440
483
  */
441
484
  /** Maximum HTML input size: 2MB. Inputs exceeding this are rejected early. */
442
485
  declare const MAX_HTML_SIZE: number;
486
+ /**
487
+ * Most occurrences recorded on a single warning's `locs`.
488
+ *
489
+ * A generated email can repeat one broken pattern hundreds of times; past a
490
+ * point the extra positions stop informing anyone and just inflate the report.
491
+ */
492
+ declare const MAX_WARNING_LOCATIONS = 100;
443
493
  declare const GENERIC_LINK_TEXT: Set<string>;
444
494
  declare const EMPTY_DELIVERABILITY: DeliverabilityReport;
445
495
 
@@ -512,4 +562,4 @@ declare function alphaBlend(fg: RGBA, bgR: number, bgG: number, bgB: number): [n
512
562
  */
513
563
  declare function downlevelCSS(html: string): string;
514
564
 
515
- export { AI_FIX_SYSTEM_PROMPT, AT_RULE_FEATURES, AccessibilityReport, AiFixResult, AiProvider, type AuditOptions, type AuditReport, COMPOUND_VALUE_FEATURES, CSSWarning, CSS_FUNCTION_FEATURES, CSS_SUPPORT, CodeFix, type CreateSessionOptions, DeliverabilityReport, DiffResult, EMAIL_CLIENTS, EMPTY_DELIVERABILITY, EmailClient, type EmailSession, ExportPromptOptions, Framework, GENERIC_LINK_TEXT, type GenerateAiFixOptions, HTML_ELEMENT_FEATURES, ImageReport, InboxPreview, LinkReport, MAX_HTML_SIZE, OverflowReport, type RGBA, STRUCTURAL_FIX_PROPERTIES, SizeReport, SpamAnalysisOptions, SpamReport, SupportLevel, TemplateReport, TransformResult, VisualReport, type WcagGrade, alphaBlend, analyzeEmail, analyzeImages, analyzeSpam, auditEmail, checkAccessibility, checkOverflow, checkSize, checkTemplateVariables, checkVisual, contrastRatio, createSession, diffResults, downlevelCSS, errorWarnings, extractInboxPreview, formatRgb, generateAiFix, generateCompatibilityScore, getClient, getCodeFix, getSuggestion, parseColor, relativeLuminance, simulateDarkMode, structuralWarnings, toPlainText, transformForAllClients, transformForClient, validateLinks, warningsForClient, wcagGrade };
565
+ export { AI_FIX_SYSTEM_PROMPT, AT_RULE_FEATURES, AccessibilityReport, AiFixResult, AiProvider, type AuditOptions, type AuditReport, COMPOUND_VALUE_FEATURES, CSSWarning, CSS_FUNCTION_FEATURES, CSS_SUPPORT, CSS_SUPPORT_NOTES, CodeFix, type CreateSessionOptions, DeliverabilityReport, DiffResult, EMAIL_CLIENTS, EMPTY_DELIVERABILITY, EmailClient, type EmailSession, ExportPromptOptions, Framework, GENERIC_LINK_TEXT, type GenerateAiFixOptions, HTML_ELEMENT_FEATURES, ImageReport, InboxPreview, LinkReport, MAX_HTML_SIZE, MAX_WARNING_LOCATIONS, OverflowReport, type ParseOptions, type RGBA, STRUCTURAL_FIX_PROPERTIES, SizeReport, SpamAnalysisOptions, SpamReport, SupportLevel, TemplateReport, TransformResult, VALUE_CAVEAT_PROPS, VisualReport, type WcagGrade, alphaBlend, analyzeEmail, analyzeImages, analyzeSpam, auditEmail, caveatApplies, checkAccessibility, checkOverflow, checkSize, checkTemplateVariables, checkVisual, contrastRatio, createSession, diffResults, downlevelCSS, errorWarnings, extractInboxPreview, formatRgb, generateAiFix, generateCompatibilityScore, getClient, getCodeFix, getSuggestion, parseColor, relativeLuminance, simulateDarkMode, structuralWarnings, toPlainText, transformForAllClients, transformForClient, validateLinks, warningsForClient, wcagGrade };
package/dist/index.d.ts CHANGED
@@ -1,6 +1,6 @@
1
- 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, I as ImageReport, g as InboxPreview, h as SizeReport, i as TemplateReport, O as OverflowReport, V as VisualReport, j as DeliverabilityReport } from './types-DEAn3IiX.js';
2
- export { k as AccessibilityIssue, B as BaseIssue, l as ClientTruncation, m as DeliverabilityCheck, n as DeliverabilityIssue, o as EstimateOptions, p as ExportScope, q as FixType, r as ImageInfo, s as ImageIssue, t as InboxPreviewIssue, u as InputFormat, v as LinkIssue, w as OverflowIssue, P as PreviewResult, x as Severity, y as SizeIssue, z as SpamIssue, G as TemplateIssue, H as TokenEstimate, J as TokenEstimateWithWarnings, K as VisualIssue, M as estimateAiFixTokens, N as generateFixPrompt, Q as heuristicTokenCount } from './types-DEAn3IiX.js';
3
- export { C as CompileError, a as CompileReactEmailOptions, S as SandboxStrategy } from './react-email-D4XyNztP.js';
1
+ 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, I as ImageReport, g as InboxPreview, h as SizeReport, i as TemplateReport, O as OverflowReport, V as VisualReport, j as DeliverabilityReport } from './types-BLR3-Fzo.js';
2
+ export { k as AccessibilityIssue, B as BaseIssue, l as ClientTruncation, m as DeliverabilityCheck, n as DeliverabilityIssue, o as EstimateOptions, p as ExportScope, q as FixType, r as ImageInfo, s as ImageIssue, t as InboxPreviewIssue, u as InputFormat, v as LinkIssue, w as OverflowIssue, P as PreviewResult, x as Severity, y as SizeIssue, z as SourceLocation, G as SpamIssue, H as TemplateIssue, J as TokenEstimate, K as TokenEstimateWithWarnings, M as VisualIssue, N as estimateAiFixTokens, Q as generateFixPrompt, R as heuristicTokenCount } from './types-BLR3-Fzo.js';
3
+ export { C as CompileError, a as CompileReactEmailOptions, S as SandboxStrategy } from './react-email-DwBWB2kr.js';
4
4
 
5
5
  declare const EMAIL_CLIENTS: EmailClient[];
6
6
  declare function getClient(id: string): EmailClient | undefined;
@@ -8,6 +8,17 @@ declare function getClient(id: string): EmailClient | undefined;
8
8
  declare function transformForClient(html: string, clientId: string, framework?: Framework): TransformResult;
9
9
  declare function transformForAllClients(html: string, framework?: Framework): TransformResult[];
10
10
 
11
+ /** Options shared by every entry point that parses HTML. */
12
+ interface ParseOptions {
13
+ /**
14
+ * Record source positions so issues carry a `loc`. Costs a little parse time
15
+ * (parse5 tracks a location record per node and per attribute), so it is
16
+ * opt-in for callers that need to point at the source — editors, CI
17
+ * annotations, agents.
18
+ */
19
+ positions?: boolean;
20
+ }
21
+
11
22
  /**
12
23
  * Analyze an HTML email and return CSS compatibility warnings
13
24
  * for all target email clients.
@@ -18,7 +29,7 @@ declare function transformForAllClients(html: string, framework?: Framework): Tr
18
29
  * snippets reference source-level constructs so users know how to
19
30
  * modify their framework source code.
20
31
  */
21
- declare function analyzeEmail(html: string, framework?: Framework): CSSWarning[];
32
+ declare function analyzeEmail(html: string, framework?: Framework, options?: ParseOptions): CSSWarning[];
22
33
  /**
23
34
  * Generate a summary of CSS compatibility for the email.
24
35
  */
@@ -178,6 +189,11 @@ declare const AI_FIX_SYSTEM_PROMPT = "You are an expert email developer speciali
178
189
  * DO NOT EDIT — regenerate with: bun run sync:caniemail
179
190
  */
180
191
  declare const CSS_SUPPORT: Record<string, Record<string, SupportLevel>>;
192
+ /**
193
+ * Caveat notes per (feature, client) from caniemail — the "why" behind a
194
+ * partial/buggy/unsupported rating. Sparse: only cells with a note appear.
195
+ */
196
+ declare const CSS_SUPPORT_NOTES: Record<string, Record<string, string[]>>;
181
197
  /**
182
198
  * Properties that require HTML structural changes (not just CSS swaps)
183
199
  * to fix. These cannot be solved by replacing one CSS value with another.
@@ -192,6 +208,29 @@ declare const COMPOUND_VALUE_FEATURES: readonly ["::after", "::before", "::first
192
208
  /** CSS function features (e.g., "linear-gradient"). */
193
209
  declare const CSS_FUNCTION_FEATURES: readonly ["calc", "clamp", "conic-gradient", "fit-content", "linear-gradient", "max", "min", "radial-gradient"];
194
210
 
211
+ /**
212
+ * Properties whose "partial" rating is value-level: the property usually
213
+ * renders fine and only specific values hit the caveat. For these the warning
214
+ * is gated on the value actually written, using the per-client caniemail note,
215
+ * instead of flagging every use. Properties not listed keep the plain
216
+ * "partial → warn" behaviour.
217
+ *
218
+ * Adding a property here is a promise to read its notes: the gate is only as
219
+ * honest as the predicate below, and a wrong `false` is a missed rendering bug.
220
+ */
221
+ declare const VALUE_CAVEAT_PROPS: ReadonlySet<string>;
222
+ /**
223
+ * Does any of the values written for `prop` trigger this client's partial-support
224
+ * caveat? Values are per-declaration: a stylesheet setting `position: relative`
225
+ * in one rule and `position: fixed` in another passes both, and the caveat
226
+ * applies if either does.
227
+ *
228
+ * Returns true (report it) for a property that isn't value-gated, and for one
229
+ * where we never saw a value — an at-rule, a pseudo-class, a detected CSS
230
+ * function.
231
+ */
232
+ declare function caveatApplies(prop: string, values: readonly string[] | undefined, notes: string[] | undefined): boolean;
233
+
195
234
  /**
196
235
  * Analyze an HTML email for content hygiene issues.
197
236
  *
@@ -213,7 +252,7 @@ declare function analyzeSpam(html: string, options?: SpamAnalysisOptions): SpamR
213
252
  * empty/placeholder hrefs, javascript: protocol, insecure HTTP,
214
253
  * generic link text, accessibility issues, and more.
215
254
  */
216
- declare function validateLinks(html: string): LinkReport;
255
+ declare function validateLinks(html: string, options?: ParseOptions): LinkReport;
217
256
 
218
257
  /**
219
258
  * Audit an HTML email for accessibility issues.
@@ -222,7 +261,7 @@ declare function validateLinks(html: string): LinkReport;
222
261
  * layout table roles, link accessibility, heading hierarchy, and
223
262
  * color contrast. Returns a 0–100 score and detailed issues.
224
263
  */
225
- declare function checkAccessibility(html: string): AccessibilityReport;
264
+ declare function checkAccessibility(html: string, options?: ParseOptions): AccessibilityReport;
226
265
 
227
266
  /**
228
267
  * Analyze images in an HTML email for best practices.
@@ -231,7 +270,7 @@ declare function checkAccessibility(html: string): AccessibilityReport;
231
270
  * attributes, unsupported formats (WebP, SVG), tracking pixels,
232
271
  * missing display:block, and overall image heaviness.
233
272
  */
234
- declare function analyzeImages(html: string): ImageReport;
273
+ declare function analyzeImages(html: string, options?: ParseOptions): ImageReport;
235
274
 
236
275
  /**
237
276
  * Extract subject and preheader text from the email HTML, plus
@@ -260,22 +299,22 @@ declare function checkSize(html: string): SizeReport;
260
299
  *
261
300
  * Returns the count of unresolved variables and detailed issues.
262
301
  */
263
- declare function checkTemplateVariables(html: string): TemplateReport;
302
+ declare function checkTemplateVariables(html: string, options?: ParseOptions): TemplateReport;
264
303
 
265
304
  /**
266
305
  * Detect content likely to overflow the email frame or mobile viewport:
267
306
  * fixed pixel widths wider than the frame, and long unbreakable strings.
268
307
  */
269
- declare function checkOverflow(html: string): OverflowReport;
308
+ declare function checkOverflow(html: string, options?: ParseOptions): OverflowReport;
270
309
 
271
310
  /**
272
311
  * Detect probable visual bugs in a stylized email: background images/gradients
273
312
  * with no colour fallback, and font stacks with no web-safe fallback. Each
274
313
  * issue includes a concrete fix.
275
314
  */
276
- declare function checkVisual(html: string): VisualReport;
315
+ declare function checkVisual(html: string, options?: ParseOptions): VisualReport;
277
316
 
278
- interface AuditOptions {
317
+ interface AuditOptions extends ParseOptions {
279
318
  framework?: Framework;
280
319
  /** Options for spam analysis */
281
320
  spam?: SpamAnalysisOptions;
@@ -323,7 +362,7 @@ declare function auditEmail(html: string, options?: AuditOptions): AuditReport;
323
362
  */
324
363
  declare function toPlainText(html: string): string;
325
364
 
326
- interface CreateSessionOptions {
365
+ interface CreateSessionOptions extends ParseOptions {
327
366
  /** Framework for fix snippets (applies to analyze/audit/transform). */
328
367
  framework?: Framework;
329
368
  }
@@ -348,8 +387,12 @@ interface EmailSession {
348
387
  * Run all analysis checks in one call (shares pre-parsed DOM).
349
388
  *
350
389
  * Equivalent to `auditEmail()` but avoids re-parsing the HTML.
390
+ *
391
+ * `positions` is not accepted here: source positions are recorded at parse
392
+ * time, so the session's own option decides, and a per-call flag could only
393
+ * be ignored. Pass it to `createSession()` instead.
351
394
  */
352
- audit(options?: Omit<AuditOptions, "framework">): AuditReport;
395
+ audit(options?: Omit<AuditOptions, "framework" | "positions">): AuditReport;
353
396
  /**
354
397
  * Analyze CSS compatibility warnings (shares pre-parsed DOM).
355
398
  *
@@ -440,6 +483,13 @@ declare function createSession(html: string, options?: CreateSessionOptions): Em
440
483
  */
441
484
  /** Maximum HTML input size: 2MB. Inputs exceeding this are rejected early. */
442
485
  declare const MAX_HTML_SIZE: number;
486
+ /**
487
+ * Most occurrences recorded on a single warning's `locs`.
488
+ *
489
+ * A generated email can repeat one broken pattern hundreds of times; past a
490
+ * point the extra positions stop informing anyone and just inflate the report.
491
+ */
492
+ declare const MAX_WARNING_LOCATIONS = 100;
443
493
  declare const GENERIC_LINK_TEXT: Set<string>;
444
494
  declare const EMPTY_DELIVERABILITY: DeliverabilityReport;
445
495
 
@@ -512,4 +562,4 @@ declare function alphaBlend(fg: RGBA, bgR: number, bgG: number, bgB: number): [n
512
562
  */
513
563
  declare function downlevelCSS(html: string): string;
514
564
 
515
- export { AI_FIX_SYSTEM_PROMPT, AT_RULE_FEATURES, AccessibilityReport, AiFixResult, AiProvider, type AuditOptions, type AuditReport, COMPOUND_VALUE_FEATURES, CSSWarning, CSS_FUNCTION_FEATURES, CSS_SUPPORT, CodeFix, type CreateSessionOptions, DeliverabilityReport, DiffResult, EMAIL_CLIENTS, EMPTY_DELIVERABILITY, EmailClient, type EmailSession, ExportPromptOptions, Framework, GENERIC_LINK_TEXT, type GenerateAiFixOptions, HTML_ELEMENT_FEATURES, ImageReport, InboxPreview, LinkReport, MAX_HTML_SIZE, OverflowReport, type RGBA, STRUCTURAL_FIX_PROPERTIES, SizeReport, SpamAnalysisOptions, SpamReport, SupportLevel, TemplateReport, TransformResult, VisualReport, type WcagGrade, alphaBlend, analyzeEmail, analyzeImages, analyzeSpam, auditEmail, checkAccessibility, checkOverflow, checkSize, checkTemplateVariables, checkVisual, contrastRatio, createSession, diffResults, downlevelCSS, errorWarnings, extractInboxPreview, formatRgb, generateAiFix, generateCompatibilityScore, getClient, getCodeFix, getSuggestion, parseColor, relativeLuminance, simulateDarkMode, structuralWarnings, toPlainText, transformForAllClients, transformForClient, validateLinks, warningsForClient, wcagGrade };
565
+ export { AI_FIX_SYSTEM_PROMPT, AT_RULE_FEATURES, AccessibilityReport, AiFixResult, AiProvider, type AuditOptions, type AuditReport, COMPOUND_VALUE_FEATURES, CSSWarning, CSS_FUNCTION_FEATURES, CSS_SUPPORT, CSS_SUPPORT_NOTES, CodeFix, type CreateSessionOptions, DeliverabilityReport, DiffResult, EMAIL_CLIENTS, EMPTY_DELIVERABILITY, EmailClient, type EmailSession, ExportPromptOptions, Framework, GENERIC_LINK_TEXT, type GenerateAiFixOptions, HTML_ELEMENT_FEATURES, ImageReport, InboxPreview, LinkReport, MAX_HTML_SIZE, MAX_WARNING_LOCATIONS, OverflowReport, type ParseOptions, type RGBA, STRUCTURAL_FIX_PROPERTIES, SizeReport, SpamAnalysisOptions, SpamReport, SupportLevel, TemplateReport, TransformResult, VALUE_CAVEAT_PROPS, VisualReport, type WcagGrade, alphaBlend, analyzeEmail, analyzeImages, analyzeSpam, auditEmail, caveatApplies, checkAccessibility, checkOverflow, checkSize, checkTemplateVariables, checkVisual, contrastRatio, createSession, diffResults, downlevelCSS, errorWarnings, extractInboxPreview, formatRgb, generateAiFix, generateCompatibilityScore, getClient, getCodeFix, getSuggestion, parseColor, relativeLuminance, simulateDarkMode, structuralWarnings, toPlainText, transformForAllClients, transformForClient, validateLinks, warningsForClient, wcagGrade };