@emailens/engine 0.10.1 → 0.10.2

package/dist/index.cjs

@@ -64,18 +64,22 @@ __export(index_exports, {
   COMPOUND_VALUE_FEATURES: () => COMPOUND_VALUE_FEATURES,
   CSS_FUNCTION_FEATURES: () => CSS_FUNCTION_FEATURES,
   CSS_SUPPORT: () => CSS_SUPPORT,
+  CSS_SUPPORT_NOTES: () => CSS_SUPPORT_NOTES,
   CompileError: () => CompileError,
   EMAIL_CLIENTS: () => EMAIL_CLIENTS,
   EMPTY_DELIVERABILITY: () => EMPTY_DELIVERABILITY,
   GENERIC_LINK_TEXT: () => GENERIC_LINK_TEXT,
   HTML_ELEMENT_FEATURES: () => HTML_ELEMENT_FEATURES,
   MAX_HTML_SIZE: () => MAX_HTML_SIZE,
+  MAX_WARNING_LOCATIONS: () => MAX_WARNING_LOCATIONS,
   STRUCTURAL_FIX_PROPERTIES: () => STRUCTURAL_FIX_PROPERTIES,
+  VALUE_CAVEAT_PROPS: () => VALUE_CAVEAT_PROPS,
   alphaBlend: () => alphaBlend,
   analyzeEmail: () => analyzeEmail,
   analyzeImages: () => analyzeImages,
   analyzeSpam: () => analyzeSpam,
   auditEmail: () => auditEmail,
+  caveatApplies: () => caveatApplies,
   checkAccessibility: () => checkAccessibility,
   checkOverflow: () => checkOverflow,
   checkSize: () => checkSize,
@@ -158,7 +162,11 @@ var EMAIL_CLIENTS = [
     engine: "Microsoft Word",
     darkModeSupport: true,
     icon: "monitor",
-    deprecated: "2026-10"
+    // End of support ~Q2 2029 (Microsoft: "supported until at least 2029").
+    // The April 2026 date some sources cite is the opt-out phase, when classic
+    // stops being the Windows default, not end of support. October 2026 was
+    // wrong: the nearest real Oct date is Oct 2025, for legacy Outlook for Mac.
+    deprecated: "2029-06"
   },
   {
     id: "outlook-ios",
@@ -8991,6 +8999,16 @@ function getStyleValue(style, property) {
   }
   return null;
 }
+function getStyleValues(style, property) {
+  const values = [];
+  for (const part of splitStyleDeclarations(style)) {
+    const colonIndex = part.indexOf(":");
+    if (colonIndex === -1) continue;
+    if (part.slice(0, colonIndex).trim().toLowerCase() !== property) continue;
+    values.push(part.slice(colonIndex + 1).trim());
+  }
+  return values;
+}
 function parseInlineStyle(style) {
   const map = /* @__PURE__ */ new Map();
   const declarations = splitStyleDeclarations(style);
@@ -9741,6 +9759,7 @@ function downlevelCSS(html) {
 
 // src/constants.ts
 var MAX_HTML_SIZE = 2 * 1024 * 1024;
+var MAX_WARNING_LOCATIONS = 100;
 var GENERIC_LINK_TEXT = /* @__PURE__ */ new Set([
   "click here",
   "here",
@@ -10477,9 +10496,231 @@ function transformForAllClients(html, framework) {
 }
 
 // src/analyze.ts
-var cheerio4 = __toESM(require("cheerio"), 1);
 var csstree5 = __toESM(require("css-tree"), 1);
 
+// src/rules/value-caveats.ts
+var VALUE_CAVEAT_PROPS = /* @__PURE__ */ new Set([
+  "background",
+  "border-radius",
+  "display",
+  "font-size",
+  "font-weight",
+  "letter-spacing",
+  "margin",
+  "overflow",
+  "position",
+  "text-align",
+  "transition"
+]);
+function normalize(value) {
+  return value.replace(/\/\*[\s\S]*?\*\//g, " ").toLowerCase().replace(/!\s*important/g, " ").replace(/;+\s*$/, "").replace(/\s+/g, " ").trim();
+}
+var preparedValues = /* @__PURE__ */ new WeakMap();
+function prepare(values) {
+  let out = preparedValues.get(values);
+  if (!out) {
+    out = [...new Set(values.map(normalize))];
+    preparedValues.set(values, out);
+  }
+  return out;
+}
+function topLevelSplit(value, sep) {
+  const parts = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < value.length; i++) {
+    const c = value[i];
+    if (c === "(") depth++;
+    else if (c === ")") depth = Math.max(0, depth - 1);
+    else if (c === sep && depth === 0) {
+      parts.push(value.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(value.slice(start));
+  return parts.map((p) => p.trim()).filter(Boolean);
+}
+function tokens(value) {
+  return topLevelSplit(value, " ");
+}
+function hasUnit(value, units) {
+  return new RegExp(`\\d(?:${units.join("|")})\\b`).test(value);
+}
+function bareNumbers(value) {
+  return tokens(value).filter((t) => /^[+-]?\d+(?:\.\d+)?(?:e[+-]?\d+)?$/.test(t)).map(Number);
+}
+function hasNegative(value) {
+  return /(?:^|[\s,(])-\.?\d/.test(value);
+}
+function dashed(v) {
+  return v.replace(/\s+/g, "-");
+}
+function unprefixed(token) {
+  return token.replace(/^-(?:webkit|moz|ms|o)-/, "");
+}
+function quotedValues(note) {
+  var _a;
+  const supported = [];
+  const banned = [];
+  for (const m of note.matchAll(/`([^`]+)`/g)) {
+    const clause = (_a = note.slice(0, m.index).split(/[.;]/).pop()) != null ? _a : "";
+    (/\bsupports\b/i.test(clause) ? supported : banned).push(dashed(m[1].toLowerCase().trim()));
+  }
+  return { supported, banned };
+}
+function isColorOnly(value) {
+  if (value.startsWith("#")) return /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/.test(value);
+  if (parseColor(value)) return true;
+  return ["none", "inherit", "initial", "unset", "revert", "currentcolor"].includes(value) || // A custom property is usually a palette colour, and we cannot resolve it.
+  value.startsWith("var(");
+}
+var POSITION_KEYWORDS = ["relative", "absolute", "fixed", "sticky"];
+var RELATIVE_FONT_UNITS = [
+  "cqmin",
+  "cqmax",
+  "vmin",
+  "vmax",
+  "rlh",
+  "rex",
+  "rch",
+  "ric",
+  "rem",
+  "svw",
+  "svh",
+  "lvw",
+  "lvh",
+  "dvw",
+  "dvh",
+  "cqw",
+  "cqh",
+  "cqi",
+  "cqb",
+  "cap",
+  "ic",
+  "lh",
+  "em",
+  "ex",
+  "ch",
+  "vw",
+  "vh",
+  "vi",
+  "vb"
+];
+var NOT_A_PROPERTY_NAME = /* @__PURE__ */ new Set([
+  "all",
+  "allow-discrete",
+  "normal",
+  "ease",
+  "ease-in",
+  "ease-out",
+  "ease-in-out",
+  "linear",
+  "step-start",
+  "step-end",
+  "none",
+  "initial",
+  "inherit",
+  "unset",
+  "revert",
+  "revert-layer"
+]);
+function namesAProperty(layer) {
+  return tokens(layer).some((t) => /^[a-z][a-z0-9-]*$/.test(t) && !NOT_A_PROPERTY_NAME.has(t));
+}
+function triggers(prop, value, note, noteLc) {
+  switch (prop) {
+    case "margin": {
+      const negative = noteLc.includes("negative");
+      const auto = noteLc.includes("auto");
+      if (!negative && !auto) return true;
+      return negative && hasNegative(value) || auto && /\bauto\b/.test(value);
+    }
+    case "position": {
+      const used = POSITION_KEYWORDS.find((k) => tokens(value).some((t) => unprefixed(t) === k));
+      if (!used) return false;
+      const m = note.match(/supports\s+.+?\s+but not\s+([^.]+)/i);
+      if (m) return m[1].toLowerCase().includes(used);
+      return true;
+    }
+    case "overflow": {
+      if (!/\b(?:auto|scroll|overlay)\b/.test(value)) return false;
+      if (!noteLc.includes("cannot scroll") && !noteLc.includes("overflow-block")) return true;
+      return noteLc.includes("cannot scroll");
+    }
+    case "font-size": {
+      if (noteLc.includes("percentage") || noteLc.includes("relative")) {
+        return hasUnit(value, RELATIVE_FONT_UNITS) || /\d\s*%/.test(value) || tokens(value).some((t) => t === "smaller" || t === "larger");
+      }
+      if (noteLc.includes("`rem`")) return hasUnit(value, ["rem"]);
+      return true;
+    }
+    case "display": {
+      const only = note.match(/only supports\s+([^.]*)/i);
+      if (only) {
+        const allowed = quotedValues(only[1]).banned.map((q) => q.replace(/^display:-?/, "")).filter((q) => /^[a-z-]+$/.test(q));
+        if (!allowed.length) return true;
+        return !allowed.includes(dashed(value));
+      }
+      const { banned } = quotedValues(note);
+      if (banned.length) {
+        const v = dashed(value);
+        return banned.includes(v) || banned.includes(unprefixed(v));
+      }
+      if (noteLc.includes("two-value syntax")) return tokens(value).length > 1;
+      return true;
+    }
+    case "font-weight": {
+      const nums = bareNumbers(value);
+      if (!nums.length) return false;
+      if (noteLc.includes("font weight")) return nums.some((n) => n !== 400 && n !== 700);
+      if (noteLc.includes("only the following numeric values")) {
+        return nums.some((n) => n % 100 !== 0 || n < 100 || n > 900);
+      }
+      return true;
+    }
+    case "border-radius": {
+      if (noteLc.includes("slash")) return topLevelSplit(value, "/").length > 1;
+      return true;
+    }
+    case "text-align": {
+      const { supported, banned } = quotedValues(note);
+      if (!banned.length) return true;
+      return tokens(value).some(
+        (t) => !supported.includes(t) && (banned.includes(t) || banned.includes(unprefixed(t)))
+      );
+    }
+    case "background": {
+      if (noteLc.includes("only `background-color`")) return !isColorOnly(value);
+      if (noteLc.includes("multiple values")) {
+        return topLevelSplit(value, ",").length > 1 || topLevelSplit(value, "/").length > 1;
+      }
+      return true;
+    }
+    case "letter-spacing": {
+      const negative = noteLc.includes("negative");
+      const em = noteLc.includes("`em`");
+      if (!negative && !em) return true;
+      return negative && hasNegative(value) || em && hasUnit(value, ["em"]);
+    }
+    case "transition": {
+      if (noteLc.includes("`all`")) {
+        if (["none", "inherit", "initial", "unset", "revert"].includes(value)) return false;
+        return topLevelSplit(value, ",").some((layer) => !namesAProperty(layer));
+      }
+      return true;
+    }
+    default:
+      return true;
+  }
+}
+function caveatApplies(prop, values, notes) {
+  if (!VALUE_CAVEAT_PROPS.has(prop)) return true;
+  if (!(values == null ? void 0 : values.length)) return true;
+  const note = (notes != null ? notes : []).join(" ");
+  const noteLc = note.toLowerCase();
+  return prepare(values).some((value) => triggers(prop, value, note, noteLc));
+}
+
 // src/dark-mode-checker.ts
 var csstree4 = __toESM(require("css-tree"), 1);
 
@@ -10756,6 +10997,209 @@ function applyColorInversion($, mode) {
   });
 }
 
+// src/source-location.ts
+function toLoc(p) {
+  return {
+    line: p.startLine,
+    column: p.startCol,
+    endLine: p.endLine,
+    endColumn: p.endCol,
+    offset: p.startOffset,
+    length: p.endOffset - p.startOffset
+  };
+}
+function locOfElement(el) {
+  var _a;
+  const raw = el == null ? void 0 : el.sourceCodeLocation;
+  if (!raw) return void 0;
+  return toLoc((_a = raw.startTag) != null ? _a : raw);
+}
+function locOfAttr(el, attr) {
+  var _a, _b, _c, _d;
+  const raw = el == null ? void 0 : el.sourceCodeLocation;
+  if (!raw) return void 0;
+  const attrLoc = (_d = (_a = raw.attrs) == null ? void 0 : _a[attr]) != null ? _d : (_c = (_b = raw.startTag) == null ? void 0 : _b.attrs) == null ? void 0 : _c[attr];
+  return attrLoc ? toLoc(attrLoc) : locOfElement(el);
+}
+function locOfFirst($, selector) {
+  const el = $(selector).first()[0];
+  return el ? locOfElement(el) : void 0;
+}
+function cssBlockAnchor(styleEl, cssText, source) {
+  var _a;
+  const children = styleEl == null ? void 0 : styleEl.children;
+  if (!children || children.length !== 1) return void 0;
+  const loc = (_a = children[0]) == null ? void 0 : _a.sourceCodeLocation;
+  if (!loc) return void 0;
+  const mapper = source ? crMapper(source.slice(loc.startOffset, loc.endOffset), cssText) : null;
+  const extraBefore = mapper ? (index) => mapper(index) - index : crOffsetter(cssText, loc.endOffset - loc.startOffset);
+  return __spreadValues({ loc, extraBefore }, mapper ? { source } : {});
+}
+function crMapper(raw, decoded) {
+  if (raw.length === decoded.length) return (index) => index;
+  const points = [];
+  const extras = [];
+  let r = 0;
+  let d = 0;
+  let extra = 0;
+  while (d < decoded.length) {
+    if (r >= raw.length) return null;
+    if (raw[r] === decoded[d]) {
+      r++;
+      d++;
+      continue;
+    }
+    if (raw[r] === "\r" && decoded[d] === "\n") {
+      const consumed = raw[r + 1] === "\n" ? 2 : 1;
+      extra += consumed - 1;
+      points.push(d);
+      extras.push(extra);
+      r += consumed;
+      d += 1;
+      continue;
+    }
+    return null;
+  }
+  if (r !== raw.length) return null;
+  return (index) => index + lookup(points, extras, index);
+}
+function lookup(points, extras, index) {
+  let lo = 0;
+  let hi = points.length - 1;
+  let found = 0;
+  while (lo <= hi) {
+    const mid = lo + hi >> 1;
+    if (points[mid] < index) {
+      found = extras[mid];
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return found;
+}
+function findRawOffset(raw, decoded, index, token) {
+  if (!token) return -1;
+  let occurrence = 0;
+  for (let at = decoded.indexOf(token); at !== -1 && at < index; at = decoded.indexOf(token, at + 1)) {
+    occurrence++;
+  }
+  let found = -1;
+  let from = 0;
+  for (let i = 0; i <= occurrence; i++) {
+    found = raw.indexOf(token, from);
+    if (found === -1) return -1;
+    from = found + 1;
+  }
+  return found;
+}
+function positionOf(source, offset) {
+  const prefix = source.slice(0, offset);
+  return { line: prefix.split("\n").length, column: offset - prefix.lastIndexOf("\n") };
+}
+function crOffsetter(text, rawLength) {
+  const removed = rawLength - text.length;
+  if (removed === 0) return () => 0;
+  const newlines = countNewlines(text, text.length);
+  if (removed !== newlines || newlines === 0) return null;
+  return (index) => countNewlines(text, index);
+}
+function countNewlines(text, upTo) {
+  let n = 0;
+  for (let i = 0; i < upTo && i < text.length; i++) if (text.charCodeAt(i) === 10) n++;
+  return n;
+}
+function locInCssBlock(anchor, cssLoc) {
+  if (!anchor || !cssLoc) return void 0;
+  const { loc: block, extraBefore } = anchor;
+  if (!extraBefore) {
+    return {
+      line: block.startLine,
+      column: block.startCol,
+      endLine: block.startLine,
+      endColumn: block.startCol,
+      offset: block.startOffset,
+      length: 0
+    };
+  }
+  const line = block.startLine + cssLoc.start.line - 1;
+  const column = cssLoc.start.line === 1 ? block.startCol + cssLoc.start.column - 1 : cssLoc.start.column;
+  const endLine = block.startLine + cssLoc.end.line - 1;
+  const endColumn = cssLoc.end.line === 1 ? block.startCol + cssLoc.end.column - 1 : cssLoc.end.column;
+  const start = block.startOffset + cssLoc.start.offset + extraBefore(cssLoc.start.offset);
+  const end = block.startOffset + cssLoc.end.offset + extraBefore(cssLoc.end.offset);
+  if (anchor.source) {
+    const from = positionOf(anchor.source, start);
+    const to = positionOf(anchor.source, end);
+    return {
+      line: from.line,
+      column: from.column,
+      endLine: to.line,
+      endColumn: to.column,
+      offset: start,
+      length: end - start
+    };
+  }
+  return { line, column, endLine, endColumn, offset: start, length: end - start };
+}
+function locInTextNode(node, index, length, source) {
+  var _a;
+  const anchor = node == null ? void 0 : node.sourceCodeLocation;
+  if (!anchor) return void 0;
+  const data = (_a = node.data) != null ? _a : "";
+  const rawLength = anchor.endOffset - anchor.startOffset;
+  if (source) {
+    const raw = source.slice(anchor.startOffset, anchor.endOffset);
+    const token = data.slice(index, index + length);
+    const at = findRawOffset(raw, data, index, token);
+    if (at !== -1) {
+      const start2 = anchor.startOffset + at;
+      const from = positionOf(source, start2);
+      const to = positionOf(source, start2 + token.length);
+      return {
+        line: from.line,
+        column: from.column,
+        endLine: to.line,
+        endColumn: to.column,
+        offset: start2,
+        length: token.length
+      };
+    }
+  }
+  const extraBefore = crOffsetter(data, rawLength);
+  if (!extraBefore) {
+    const clamped = Math.min(length, rawLength);
+    return {
+      line: anchor.startLine,
+      column: anchor.startCol,
+      endLine: anchor.startLine,
+      endColumn: anchor.startCol + clamped,
+      offset: anchor.startOffset,
+      length: clamped
+    };
+  }
+  const start = positionAt(data, index, anchor);
+  const end = positionAt(data, index + length, anchor);
+  const startOffset = anchor.startOffset + index + extraBefore(index);
+  const endOffset = anchor.startOffset + index + length + extraBefore(index + length);
+  return {
+    line: start.line,
+    column: start.column,
+    endLine: end.line,
+    endColumn: end.column,
+    offset: startOffset,
+    length: endOffset - startOffset
+  };
+}
+function positionAt(data, index, anchor) {
+  const prefix = data.slice(0, index);
+  const newlines = prefix.split("\n").length - 1;
+  if (newlines === 0) {
+    return { line: anchor.startLine, column: anchor.startCol + index };
+  }
+  return { line: anchor.startLine + newlines, column: index - prefix.lastIndexOf("\n") };
+}
+
 // src/dark-mode-checker.ts
 var DARK_MEDIA_RE = /\(\s*prefers-color-scheme\s*:\s*dark\s*\)/i;
 var MAX_UNCOVERED_ELEMENTS = 3;
@@ -10852,15 +11296,16 @@ function checkDarkModeFromDom($) {
     return name === "color-scheme" || name === "supported-color-schemes";
   });
   if (!hasOptIn) {
+    const headLoc = locOfFirst($, "head");
     for (const clientId of PREFERS_COLOR_SCHEME_CLIENTS) {
-      warnings.push({
+      warnings.push(__spreadValues({
         severity: "warning",
         client: clientId,
         property: "dark-mode-opt-in",
         message: `The email has @media (prefers-color-scheme: dark) styles but no dark-mode opt-in meta tag. ${(_b = (_a = getClient(clientId)) == null ? void 0 : _a.name) != null ? _b : clientId} may keep the email in light mode, so the dark styles never activate.`,
         suggestion: 'Add both opt-in tags to <head>: <meta name="color-scheme" content="light dark"> and <meta name="supported-color-schemes" content="light dark">.',
         fixType: "structural"
-      });
+      }, headLoc ? { loc: headLoc, locs: [headLoc] } : {}));
     }
   }
   if (darkBlock.rules === 0) return warnings;
@@ -10878,8 +11323,9 @@ function checkDarkModeFromDom($) {
     if (inline ? coveredByImportant.has(el) : coveredByAny.has(el)) return;
     uncovered++;
     const selector = describeSelector($, el);
+    const loc = locOfAttr(el, inline ? "style" : "bgcolor");
     for (const clientId of PREFERS_COLOR_SCHEME_CLIENTS) {
-      warnings.push({
+      warnings.push(__spreadValues({
         severity: "warning",
         client: clientId,
         property: "dark-mode-coverage",
@@ -10887,12 +11333,25 @@ function checkDarkModeFromDom($) {
         suggestion: inline ? `Override it inside @media (prefers-color-scheme: dark) with a dark background-color and !important (an inline style beats a plain rule), or move the colour onto a class the dark block already targets.` : `Override it inside @media (prefers-color-scheme: dark) with a dark background-color, or give the element a class the dark block already targets.`,
         fixType: "css",
         selector
-      });
+      }, loc ? { loc, locs: [loc] } : {}));
     }
   });
   return warnings;
 }
 
+// src/parse-html.ts
+var cheerio4 = __toESM(require("cheerio"), 1);
+function loadHtml(html, options) {
+  return (options == null ? void 0 : options.positions) ? cheerio4.load(html, { sourceCodeLocationInfo: true }) : cheerio4.load(html);
+}
+function fromHtml(html, empty, fn, options) {
+  if (!html || !html.trim()) return empty;
+  if (html.length > MAX_HTML_SIZE) {
+    throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
+  }
+  return fn(loadHtml(html, options), html);
+}
+
 // src/analyze.ts
 var HTML_ELEMENT_SELECTORS = {
   "<style>": "style",
@@ -10945,14 +11404,25 @@ var CSS_FUNCTION_DETECTORS = CSS_FUNCTION_FEATURES.map((fn) => ({
   pattern: `${fn}(`
   // require opening paren — matches "min(" but not "Minion"
 }));
-function analyzeEmailFromDom($, framework) {
+function analyzeEmailFromDom($, framework, source) {
   const warnings = [];
-  const seenWarnings = /* @__PURE__ */ new Set();
+  const seenWarnings = /* @__PURE__ */ new Map();
   function addWarning(w) {
     const key = `${w.client}:${w.property}:${w.severity}:${w.selector || ""}`;
-    if (!seenWarnings.has(key)) {
-      seenWarnings.add(key);
+    const existing = seenWarnings.get(key);
+    if (!existing) {
+      seenWarnings.set(key, w);
       warnings.push(w);
+      return;
+    }
+    if (!existing.locs || !w.locs) return;
+    for (const loc of w.locs) {
+      if (existing.locs.some((l) => l.offset === loc.offset)) continue;
+      if (existing.locs.length >= MAX_WARNING_LOCATIONS) {
+        existing.locsTruncated = true;
+        break;
+      }
+      existing.locs.push(loc);
     }
   }
   function describeSelector2(el) {
@@ -10970,10 +11440,16 @@ function analyzeEmailFromDom($, framework) {
   for (const feature of HTML_ELEMENT_FEATURES) {
     const selector = HTML_ELEMENT_SELECTORS[feature];
     if (!selector) continue;
-    if ($(selector).length === 0) continue;
+    const matches = $(selector);
+    if (matches.length === 0) continue;
     const supportData = CSS_SUPPORT[feature];
     if (!supportData) continue;
     const baseSeverity = HTML_ELEMENT_SEVERITY[feature] || "warning";
+    const found = matches.toArray().map((m) => locOfElement(m)).filter((l) => l !== void 0);
+    const featureOccurrences = found.length ? __spreadValues({
+      locs: found.slice(0, MAX_WARNING_LOCATIONS)
+    }, found.length > MAX_WARNING_LOCATIONS ? { truncated: true } : {}) : void 0;
+    const featureLoc = featureOccurrences == null ? void 0 : featureOccurrences.locs[0];
     for (const client of EMAIL_CLIENTS) {
       const support = supportData[client.id];
       if (support === "unsupported") {
@@ -10981,7 +11457,7 @@ function analyzeEmailFromDom($, framework) {
         const message = msgFn ? msgFn(client.name) : `${client.name} does not support ${feature}.`;
         const sug = getSuggestion(feature, client.id, framework);
         const fix = getCodeFix(feature, client.id, framework);
-        addWarning(__spreadValues({
+        addWarning(__spreadValues(__spreadValues({
           severity: baseSeverity,
           client: client.id,
           property: feature,
@@ -10989,11 +11465,11 @@ function analyzeEmailFromDom($, framework) {
           suggestion: sug.text,
           fix,
           fixType: getFixType(feature)
-        }, framework && (sug.isGenericFallback || fix && isCodeFixGenericFallback(feature, client.id, framework)) ? { fixIsGenericFallback: true } : {}));
+        }, featureOccurrences ? occurrenceFields(featureOccurrences) : {}), framework && (sug.isGenericFallback || fix && isCodeFixGenericFallback(feature, client.id, framework)) ? { fixIsGenericFallback: true } : {}));
       } else if (support === "partial" && feature === "<style>") {
         const sug = getSuggestion("<style>:partial", client.id, framework);
         const fix = getCodeFix("<style>", client.id, framework);
-        addWarning(__spreadValues({
+        addWarning(__spreadValues(__spreadValues({
           severity: "warning",
           client: client.id,
           property: "<style>",
@@ -11001,55 +11477,97 @@ function analyzeEmailFromDom($, framework) {
           suggestion: sug.text,
           fix,
           fixType: getFixType("<style>")
-        }, framework && (sug.isGenericFallback || fix && isCodeFixGenericFallback("<style>", client.id, framework)) ? { fixIsGenericFallback: true } : {}));
+        }, featureOccurrences ? occurrenceFields(featureOccurrences) : {}), framework && (sug.isGenericFallback || fix && isCodeFixGenericFallback("<style>", client.id, framework)) ? { fixIsGenericFallback: true } : {}));
       }
     }
   }
   const parsedAtRules = /* @__PURE__ */ new Set();
+  const selectorLocs = /* @__PURE__ */ new Map();
   const parsedProperties = /* @__PURE__ */ new Set();
   const propertyLines = /* @__PURE__ */ new Map();
+  const propertyLocs = /* @__PURE__ */ new Map();
   const propertyValues = /* @__PURE__ */ new Map();
   const detectedCssFunctions = /* @__PURE__ */ new Set();
   const detectedPseudoClasses = /* @__PURE__ */ new Set();
   const detectedPseudoElements = /* @__PURE__ */ new Set();
+  let blockAnchor;
+  function recordSelectorLoc(key, cssLoc) {
+    if (!cssLoc) return;
+    const loc = locInCssBlock(blockAnchor, cssLoc);
+    if (!loc) return;
+    const seen = selectorLocs.get(key);
+    if (!seen) {
+      selectorLocs.set(key, { locs: [loc] });
+      return;
+    }
+    if (seen.locs.some((l) => l.offset === loc.offset)) return;
+    if (seen.locs.length >= MAX_WARNING_LOCATIONS) {
+      seen.truncated = true;
+      return;
+    }
+    seen.locs.push(loc);
+  }
+  function recordLoc(key, cssLoc, value) {
+    const loc = locInCssBlock(blockAnchor, cssLoc);
+    if (!loc) return;
+    const seen = propertyLocs.get(key);
+    if (!seen) {
+      propertyLocs.set(key, __spreadValues({ locs: [loc] }, value !== void 0 ? { values: [value] } : {}));
+      return;
+    }
+    if (seen.locs.some((l) => l.offset === loc.offset)) return;
+    if (seen.locs.length >= MAX_WARNING_LOCATIONS) {
+      seen.truncated = true;
+      return;
+    }
+    seen.locs.push(loc);
+    if (seen.values && value !== void 0) seen.values.push(value);
+  }
   $("style").each((_, el) => {
     const cssText = $(el).text();
+    blockAnchor = cssBlockAnchor(el, cssText, source);
     try {
       const ast = csstree5.parse(cssText, { parseCustomProperty: true, positions: true });
       csstree5.walk(ast, {
         enter(node) {
           if (node.type === "Atrule") {
             parsedAtRules.add(`@${node.name}`);
+            recordSelectorLoc(`@${node.name}`, node.loc);
           }
           if (node.type === "PseudoClassSelector") {
             detectedPseudoClasses.add(`:${node.name}`);
+            recordSelectorLoc(`:${node.name}`, node.loc);
           }
           if (node.type === "PseudoElementSelector") {
             detectedPseudoElements.add(`::${node.name}`);
+            recordSelectorLoc(`::${node.name}`, node.loc);
           }
           if (node.type === "Declaration") {
             const prop = node.property.toLowerCase();
             parsedProperties.add(prop);
-            if (node.loc && !propertyLines.has(prop)) {
-              propertyLines.set(prop, node.loc.start.line);
-            }
             const valueStr = csstree5.generate(node.value);
             const seenValues = propertyValues.get(prop);
             if (seenValues) seenValues.push(valueStr);
             else propertyValues.set(prop, [valueStr]);
+            if (node.loc) {
+              if (!propertyLines.has(prop)) propertyLines.set(prop, node.loc.start.line);
+              recordLoc(prop, node.loc, valueStr);
+            }
             for (const det of COMPOUND_DETECTORS) {
-              if (prop === det.property && valueStr.includes(det.valueIncludes)) {
+              if (prop === det.property && valueStr.toLowerCase().includes(det.valueIncludes)) {
                 parsedProperties.add(det.key);
-                if (node.loc && !propertyLines.has(det.key)) {
-                  propertyLines.set(det.key, node.loc.start.line);
+                if (node.loc) {
+                  if (!propertyLines.has(det.key)) propertyLines.set(det.key, node.loc.start.line);
+                  recordLoc(det.key, node.loc);
                 }
               }
             }
             for (const fn of CSS_FUNCTION_DETECTORS) {
               if (valueStr.includes(fn.pattern)) {
                 detectedCssFunctions.add(fn.key);
-                if (node.loc && !propertyLines.has(fn.key)) {
-                  propertyLines.set(fn.key, node.loc.start.line);
+                if (node.loc) {
+                  if (!propertyLines.has(fn.key)) propertyLines.set(fn.key, node.loc.start.line);
+                  recordLoc(fn.key, node.loc);
                 }
               }
             }
@@ -11061,33 +11579,42 @@ function analyzeEmailFromDom($, framework) {
   });
   for (const atRule of AT_RULE_FEATURES) {
     if (!parsedAtRules.has(atRule)) continue;
-    checkPropertySupport(atRule, addWarning, framework);
+    checkPropertySupport(atRule, addWarning, framework, void 0, void 0, void 0, selectorLocs.get(atRule));
   }
   const cssPropertiesToCheck = Object.keys(CSS_SUPPORT).filter(
     (k) => !k.startsWith("<") && !k.startsWith("@")
   );
   $("[style]").each((_, el) => {
-    var _a;
     const style = $(el).attr("style") || "";
     const props = parseStyleProperties(style);
     const selector = describeSelector2(el);
+    const locs = elementLocs(locOfAttr(el, "style"));
     for (const prop of props) {
       for (const det of COMPOUND_DETECTORS) {
         if (prop === det.property) {
           const value2 = getStyleValue(style, prop);
-          if (value2 == null ? void 0 : value2.includes(det.valueIncludes)) {
-            checkPropertySupport(det.key, addWarning, framework, selector);
+          if (value2 == null ? void 0 : value2.toLowerCase().includes(det.valueIncludes)) {
+            checkPropertySupport(det.key, addWarning, framework, selector, void 0, void 0, locs);
           }
         }
       }
       if (cssPropertiesToCheck.includes(prop)) {
-        checkPropertySupport(prop, addWarning, framework, selector, void 0, (_a = getStyleValue(style, prop)) != null ? _a : void 0);
+        const declared = getStyleValues(style, prop);
+        checkPropertySupport(
+          prop,
+          addWarning,
+          framework,
+          selector,
+          void 0,
+          declared.length ? declared : void 0,
+          locs
+        );
       }
       const value = getStyleValue(style, prop);
       if (value) {
         for (const fn of CSS_FUNCTION_DETECTORS) {
           if (value.includes(fn.pattern)) {
-            checkPropertySupport(fn.key, addWarning, framework, selector);
+            checkPropertySupport(fn.key, addWarning, framework, selector, void 0, void 0, locs);
           }
         }
       }
@@ -11103,87 +11630,66 @@ function analyzeEmailFromDom($, framework) {
       framework,
       void 0,
       propertyLines.get(prop),
-      values ? values.join(" ") : void 0
+      values,
+      propertyLocs.get(prop)
     );
   }
   for (const compound of COMPOUND_VALUE_FEATURES) {
     if (compound.startsWith(":") || compound.startsWith("::")) continue;
     if (parsedProperties.has(compound)) {
-      checkPropertySupport(compound, addWarning, framework, void 0, propertyLines.get(compound));
+      checkPropertySupport(compound, addWarning, framework, void 0, propertyLines.get(compound), void 0, propertyLocs.get(compound));
     }
   }
   for (const pseudo of detectedPseudoClasses) {
     if (CSS_SUPPORT[pseudo]) {
-      checkPropertySupport(pseudo, addWarning, framework);
+      checkPropertySupport(pseudo, addWarning, framework, void 0, void 0, void 0, selectorLocs.get(pseudo));
     }
   }
   for (const pseudo of detectedPseudoElements) {
     if (CSS_SUPPORT[pseudo]) {
-      checkPropertySupport(pseudo, addWarning, framework);
+      checkPropertySupport(pseudo, addWarning, framework, void 0, void 0, void 0, selectorLocs.get(pseudo));
     }
   }
   for (const fn of detectedCssFunctions) {
-    checkPropertySupport(fn, addWarning, framework, void 0, propertyLines.get(fn));
+    checkPropertySupport(fn, addWarning, framework, void 0, propertyLines.get(fn), void 0, propertyLocs.get(fn));
   }
   for (const w of checkDarkModeFromDom($)) addWarning(w);
   const severityOrder = { error: 0, warning: 1, info: 2 };
   warnings.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
   return warnings;
 }
-function analyzeEmail(html, framework) {
+function analyzeEmail(html, framework, options) {
   if (!html || !html.trim()) {
     return [];
   }
   if (html.length > MAX_HTML_SIZE) {
     throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
   }
-  const $ = cheerio4.load(html);
-  return analyzeEmailFromDom($, framework);
+  const $ = loadHtml(html, options);
+  return analyzeEmailFromDom($, framework, (options == null ? void 0 : options.positions) ? html : void 0);
 }
 function getFixType(prop) {
   return STRUCTURAL_FIX_PROPERTIES.has(prop) ? "structural" : "css";
 }
-var VALUE_CAVEAT_PROPS = /* @__PURE__ */ new Set(["margin", "position", "overflow"]);
-var POSITION_KEYWORDS = ["relative", "absolute", "fixed", "sticky"];
-function valueTriggersCaveat(prop, value, notes) {
-  const note = (notes != null ? notes : []).join(" ");
-  const noteLc = note.toLowerCase();
-  if (prop === "margin") {
-    if (/(?:^|[\s:(])-\.?\d/.test(value) && noteLc.includes("negative")) return true;
-    if (/\bauto\b/.test(value) && noteLc.includes("auto")) return true;
-    return false;
-  }
-  if (prop === "position") {
-    const used = POSITION_KEYWORDS.find((k) => new RegExp(`\\b${k}\\b`).test(value));
-    if (!used) return false;
-    const m = note.match(/supports\s+.+?\s+but not\s+([^.]+)/i);
-    if (m) return m[1].toLowerCase().includes(used);
-    return used === "fixed" || used === "sticky";
-  }
-  if (prop === "overflow") {
-    if (!/\b(?:auto|scroll)\b/.test(value)) return false;
-    return noteLc.includes("cannot scroll");
-  }
-  return true;
-}
 function noteSuffix(notes) {
   if (!(notes == null ? void 0 : notes.length)) return "";
   const cleaned = notes.map((n) => n.replace(/^(?:Partial|Buggy|Not supported)\.\s*/i, "").trim()).filter(Boolean);
   return cleaned.length ? ` ${cleaned.join(" ")}` : "";
 }
-function checkPropertySupport(prop, addWarning, framework, selector, line, value) {
-  var _a;
+function checkPropertySupport(prop, addWarning, framework, selector, line, values, occurrences) {
+  var _a, _b, _c, _d, _e, _f;
+  const loc = occurrences == null ? void 0 : occurrences.locs[0];
+  const reportedLine = (_a = loc == null ? void 0 : loc.line) != null ? _a : line;
   const supportData = CSS_SUPPORT[prop];
   if (!supportData) return;
   const fixType = getFixType(prop);
-  const valueGated = VALUE_CAVEAT_PROPS.has(prop);
   for (const client of EMAIL_CLIENTS) {
     const support = supportData[client.id] || "unknown";
-    const notes = (_a = CSS_SUPPORT_NOTES[prop]) == null ? void 0 : _a[client.id];
+    const notes = (_b = CSS_SUPPORT_NOTES[prop]) == null ? void 0 : _b[client.id];
     if (support === "unsupported") {
       const sug = getSuggestion(prop, client.id, framework);
       const fix = getCodeFix(prop, client.id, framework);
-      addWarning(__spreadValues(__spreadValues(__spreadValues({
+      addWarning(__spreadValues(__spreadValues(__spreadValues(__spreadValues({
         severity: "warning",
         client: client.id,
         property: prop,
@@ -11191,12 +11697,13 @@ function checkPropertySupport(prop, addWarning, framework, selector, line, value
         suggestion: sug.text,
         fix,
         fixType
-      }, selector ? { selector } : {}), line !== void 0 ? { line } : {}), framework && (sug.isGenericFallback || fix && isCodeFixGenericFallback(prop, client.id, framework)) ? { fixIsGenericFallback: true } : {}));
+      }, selector ? { selector } : {}), reportedLine !== void 0 ? { line: reportedLine } : {}), occurrences ? occurrenceFields(occurrences) : {}), framework && (sug.isGenericFallback || fix && isCodeFixGenericFallback(prop, client.id, framework)) ? { fixIsGenericFallback: true } : {}));
     } else if (support === "partial") {
-      if (valueGated && value !== void 0 && !valueTriggersCaveat(prop, value, notes)) continue;
+      if (!caveatApplies(prop, values, notes)) continue;
+      const hits = triggeringOccurrences(prop, occurrences, notes);
       const sug = getSuggestion(prop, client.id, framework);
       const fix = getCodeFix(prop, client.id, framework);
-      addWarning(__spreadValues(__spreadValues(__spreadValues({
+      addWarning(__spreadValues(__spreadValues(__spreadValues(__spreadValues({
         severity: "info",
         client: client.id,
         property: prop,
@@ -11204,7 +11711,7 @@ function checkPropertySupport(prop, addWarning, framework, selector, line, value
         suggestion: sug.text,
         fix,
         fixType
-      }, selector ? { selector } : {}), line !== void 0 ? { line } : {}), framework && (sug.isGenericFallback || fix && isCodeFixGenericFallback(prop, client.id, framework)) ? { fixIsGenericFallback: true } : {}));
+      }, selector ? { selector } : {}), ((_d = (_c = hits == null ? void 0 : hits.locs[0]) == null ? void 0 : _c.line) != null ? _d : reportedLine) !== void 0 ? { line: (_f = (_e = hits == null ? void 0 : hits.locs[0]) == null ? void 0 : _e.line) != null ? _f : reportedLine } : {}), hits ? occurrenceFields(hits) : {}), framework && (sug.isGenericFallback || fix && isCodeFixGenericFallback(prop, client.id, framework)) ? { fixIsGenericFallback: true } : {}));
     }
   }
 }
@@ -11223,6 +11730,19 @@ function generateCompatibilityScore(warnings) {
   }
   return result;
 }
+function occurrenceFields({ locs, truncated }) {
+  return __spreadValues({ loc: locs[0], locs: [...locs] }, truncated ? { locsTruncated: true } : {});
+}
+function triggeringOccurrences(prop, occurrences, notes) {
+  const values = occurrences == null ? void 0 : occurrences.values;
+  if (!occurrences || !values) return occurrences;
+  const locs = occurrences.locs.filter((_, i) => caveatApplies(prop, [values[i]], notes));
+  if (!locs.length || locs.length === occurrences.locs.length) return occurrences;
+  return __spreadValues({ locs }, occurrences.truncated ? { truncated: true } : {});
+}
+function elementLocs(loc) {
+  return loc ? { locs: [loc] } : void 0;
+}
 function warningsForClient(warnings, clientId) {
   return warnings.filter((w) => w.client === clientId);
 }
@@ -11563,16 +12083,6 @@ function extractCode(response) {
   return response.trim();
 }
 
-// src/parse-html.ts
-var cheerio5 = __toESM(require("cheerio"), 1);
-function fromHtml(html, empty, fn) {
-  if (!html || !html.trim()) return empty;
-  if (html.length > MAX_HTML_SIZE) {
-    throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
-  }
-  return fn(cheerio5.load(html), html);
-}
-
 // src/spam-scorer.ts
 var SPAM_TRIGGER_PHRASES = [
   "act now",
@@ -12041,6 +12551,8 @@ function validateLinksFromDom($) {
     const href = $(el).attr("href") || "";
     const text = $(el).text().trim();
     const category = classifyHref(href);
+    const elLoc = locOfElement(el);
+    const hrefLoc = href ? locOfAttr(el, "href") : elLoc;
     switch (category) {
       case "https":
         breakdown.https++;
@@ -12071,95 +12583,95 @@ function validateLinksFromDom($) {
       hrefCounts.set(href, (hrefCounts.get(href) || 0) + 1);
     }
     if (!href || !href.trim()) {
-      issues.push({
+      issues.push(__spreadValues({
         severity: "error",
         rule: "empty-href",
         message: "Link has no href attribute",
         text: text.slice(0, 80) || "(no text)"
-      });
+      }, elLoc ? { loc: elLoc } : {}));
       return;
     }
     if (category === "javascript" && !isPlaceholderHref(href)) {
-      issues.push({
+      issues.push(__spreadValues({
         severity: "error",
         rule: "javascript-href",
         message: "Link uses javascript: protocol",
         href: href.slice(0, 100),
         text: text.slice(0, 80) || "(no text)"
-      });
+      }, hrefLoc ? { loc: hrefLoc } : {}));
       return;
     }
     if (isPlaceholderHref(href)) {
-      issues.push({
+      issues.push(__spreadValues({
         severity: "warning",
         rule: "placeholder-href",
         message: "Link has a placeholder href (# or javascript:void)",
         href,
         text: text.slice(0, 80) || "(no text)"
-      });
+      }, hrefLoc ? { loc: hrefLoc } : {}));
       return;
     }
     if (category === "http") {
-      issues.push({
+      issues.push(__spreadValues({
         severity: "warning",
         rule: "insecure-link",
         message: "Link uses HTTP instead of HTTPS",
         href: href.slice(0, 120),
         text: text.slice(0, 80) || "(no text)"
-      });
+      }, hrefLoc ? { loc: hrefLoc } : {}));
     }
     if (category === "protocol-relative") {
-      issues.push({
+      issues.push(__spreadValues({
         severity: "warning",
         rule: "protocol-relative",
         message: "Protocol-relative URL may break in email clients \u2014 use https:// explicitly",
         href: href.slice(0, 120),
         text: text.slice(0, 80) || "(no text)"
-      });
+      }, hrefLoc ? { loc: hrefLoc } : {}));
     }
     if (text && GENERIC_LINK_TEXT.has(text.toLowerCase())) {
-      issues.push({
+      issues.push(__spreadValues({
         severity: "warning",
         rule: "generic-link-text",
         message: `Link text "${text}" is vague \u2014 use descriptive text for accessibility and engagement`,
         href: href.slice(0, 120),
         text
-      });
+      }, elLoc ? { loc: elLoc } : {}));
     }
     if (!text && !$(el).attr("aria-label") && !$(el).find("img[alt]").length) {
-      issues.push({
+      issues.push(__spreadValues({
         severity: "error",
         rule: "empty-link-text",
         message: "Link has no visible text or aria-label",
         href: href.slice(0, 120)
-      });
+      }, elLoc ? { loc: elLoc } : {}));
     }
     if (category === "mailto" && href.trim().toLowerCase() === "mailto:") {
-      issues.push({
+      issues.push(__spreadValues({
         severity: "error",
         rule: "empty-mailto",
         message: "mailto: link has no email address",
         href,
         text: text.slice(0, 80) || "(no text)"
-      });
+      }, hrefLoc ? { loc: hrefLoc } : {}));
     }
     if (category === "tel" && href.trim().toLowerCase() === "tel:") {
-      issues.push({
+      issues.push(__spreadValues({
         severity: "error",
         rule: "empty-tel",
         message: "tel: link has no phone number",
         href,
         text: text.slice(0, 80) || "(no text)"
-      });
+      }, hrefLoc ? { loc: hrefLoc } : {}));
     }
     if (href.length > 2e3) {
-      issues.push({
+      issues.push(__spreadValues({
         severity: "info",
         rule: "long-url",
         message: "URL exceeds 2000 characters \u2014 may be truncated by some email clients",
         href: href.slice(0, 120) + "...",
         text: text.slice(0, 80) || "(no text)"
-      });
+      }, hrefLoc ? { loc: hrefLoc } : {}));
     }
   });
   links.each((_, el) => {
@@ -12168,14 +12680,15 @@ function validateLinksFromDom($) {
     if (trimmed.startsWith("#") && trimmed.length > 1) {
       const targetId = trimmed.slice(1);
       const target = $(`[id="${targetId}"]`);
+      const anchorLoc = locOfAttr(el, "href");
       if (target.length === 0) {
-        issues.push({
+        issues.push(__spreadValues({
           severity: "error",
           rule: "broken-anchor",
           message: `Anchor link "${trimmed}" points to an element that does not exist`,
           href: trimmed,
           text: $(el).text().trim().slice(0, 80) || "(no text)"
-        });
+        }, anchorLoc ? { loc: anchorLoc } : {}));
       }
     }
   });
@@ -12191,8 +12704,8 @@ function validateLinksFromDom($) {
   }
   return { totalLinks, issues, breakdown };
 }
-function validateLinks(html) {
-  return fromHtml(html, EMPTY_LINKS, validateLinksFromDom);
+function validateLinks(html, options) {
+  return fromHtml(html, EMPTY_LINKS, validateLinksFromDom, options);
 }
 
 // src/accessibility-checker.ts
@@ -12217,24 +12730,31 @@ function describeElement($, el) {
 function checkLangAttribute($) {
   const lang = $("html").attr("lang");
   if (!lang || !lang.trim()) {
-    return {
+    const loc = locOfFirst($, "html");
+    return __spreadProps(__spreadValues({
       severity: "error",
       rule: "missing-lang",
-      message: "Missing lang attribute on <html> element",
+      message: "Missing lang attribute on <html> element"
+    }, loc ? { loc } : {}), {
       details: 'Screen readers use the lang attribute to determine pronunciation. Add lang="en" (or appropriate language code).'
-    };
+    });
   }
   return null;
 }
+function titleLoc($) {
+  return $("title").length ? locOfFirst($, "title") : locOfFirst($, "head");
+}
 function checkTitle($) {
   const title = $("title").text().trim();
   if (!title) {
-    return {
+    const loc = titleLoc($);
+    return __spreadProps(__spreadValues({
       severity: "warning",
       rule: "missing-title",
-      message: "Missing or empty <title> element",
+      message: "Missing or empty <title> element"
+    }, loc ? { loc } : {}), {
       details: "The <title> helps screen readers identify the email content."
-    };
+    });
   }
   return null;
 }
@@ -12244,34 +12764,38 @@ function checkImageAlt($) {
     const alt = $(el).attr("alt");
     const src = $(el).attr("src") || "";
     const role = $(el).attr("role");
+    const elLoc = locOfElement(el);
     if (role === "presentation" || role === "none") return;
     if (alt === void 0) {
-      issues.push({
+      issues.push(__spreadProps(__spreadValues({
         severity: "error",
         rule: "img-missing-alt",
         message: "Image missing alt attribute",
-        element: describeElement($, el),
+        element: describeElement($, el)
+      }, elLoc ? { loc: elLoc } : {}), {
         details: 'Every image must have an alt attribute. Use alt="" for decorative images.'
-      });
+      }));
     } else if (alt.trim() === "") {
       const isLikelyContent = !src.includes("spacer") && !src.includes("pixel") && !src.includes("tracking") && !src.includes("1x1") && !src.includes("transparent");
       if (isLikelyContent && ($(el).attr("width") || "0") !== "1") {
-        issues.push({
+        issues.push(__spreadProps(__spreadValues({
           severity: "info",
           rule: "img-empty-alt",
           message: "Image has empty alt text \u2014 verify it is decorative",
-          element: describeElement($, el),
+          element: describeElement($, el)
+        }, locOfAttr(el, "alt") ? { loc: locOfAttr(el, "alt") } : {}), {
           details: "Empty alt is correct for decorative images, but content images need descriptive alt text."
-        });
+        }));
       }
     } else if (/\.(png|jpg|jpeg|gif|svg|webp|bmp)$/i.test(alt)) {
-      issues.push({
+      issues.push(__spreadProps(__spreadValues({
         severity: "error",
         rule: "img-filename-alt",
         message: "Image alt text is a filename, not a description",
-        element: describeElement($, el),
+        element: describeElement($, el)
+      }, locOfAttr(el, "alt") ? { loc: locOfAttr(el, "alt") } : {}), {
         details: `Alt "${alt}" should describe the image content, not the file name.`
-      });
+      }));
     }
   });
   return issues;
@@ -12279,28 +12803,31 @@ function checkImageAlt($) {
 function checkLinkAccessibility($) {
   const issues = [];
   $("a").each((_, el) => {
+    const elLoc = locOfElement(el);
     const text = $(el).text().trim().toLowerCase();
     const ariaLabel = $(el).attr("aria-label");
     const title = $(el).attr("title");
     const imgAlt = $(el).find("img").attr("alt");
     if (!text && !ariaLabel && !title && !imgAlt) {
-      issues.push({
+      issues.push(__spreadProps(__spreadValues({
         severity: "error",
         rule: "link-no-accessible-name",
         message: "Link has no accessible name",
-        element: describeElement($, el),
+        element: describeElement($, el)
+      }, elLoc ? { loc: elLoc } : {}), {
         details: "Links need visible text, aria-label, or an image with alt text."
-      });
+      }));
       return;
     }
     if (text && GENERIC_LINK_TEXT.has(text) && !ariaLabel) {
-      issues.push({
+      issues.push(__spreadProps(__spreadValues({
         severity: "warning",
         rule: "link-generic-text",
         message: `Link text "${$(el).text().trim()}" is not descriptive`,
-        element: describeElement($, el),
+        element: describeElement($, el)
+      }, elLoc ? { loc: elLoc } : {}), {
         details: "Screen readers often list links out of context. Use text that describes the destination."
-      });
+      }));
     }
   });
   return issues;
@@ -12310,18 +12837,20 @@ function checkTableAccessibility($) {
   $("table").each((_, el) => {
     if ($(el).parents('table[role="presentation"], table[role="none"]').length > 0) return;
     const role = $(el).attr("role");
+    const tableLoc = locOfElement(el);
     const hasHeaders = $(el).find("th").length > 0;
     const looksLikeLayout = !hasHeaders;
     if (looksLikeLayout && role !== "presentation" && role !== "none") {
       const nestedTables = $(el).find("table").length;
       if (nestedTables > 0 || $(el).find("td").length > 2) {
-        issues.push({
+        issues.push(__spreadProps(__spreadValues({
           severity: "info",
           rule: "table-missing-role",
-          message: 'Layout table missing role="presentation"',
+          message: 'Layout table missing role="presentation"'
+        }, tableLoc ? { loc: tableLoc } : {}), {
           element: `<table> with ${$(el).find("td").length} cells`,
           details: `Add role="presentation" to tables used for layout so screen readers don't announce them as data tables.`
-        });
+        }));
       }
     }
   });
@@ -12332,6 +12861,7 @@ function checkTextSizeAndContrast($) {
   let smallTextCount = 0;
   $("[style]").each((_, el) => {
     const style = $(el).attr("style") || "";
+    const styleLoc = locOfAttr(el, "style");
     const fontSizeMatch = style.match(/font-size\s*:\s*(\d+(?:\.\d+)?)(px|pt)/i);
     if (fontSizeMatch) {
       const size = parseFloat(fontSizeMatch[1]);
@@ -12340,13 +12870,14 @@ function checkTextSizeAndContrast($) {
       if (pxSize < 9 && pxSize > 0) {
         smallTextCount++;
         if (smallTextCount <= 3) {
-          issues.push({
+          issues.push(__spreadProps(__spreadValues({
             severity: "warning",
             rule: "small-text",
             message: `Very small text (${fontSizeMatch[0].trim()})`,
-            element: describeElement($, el),
+            element: describeElement($, el)
+          }, styleLoc ? { loc: styleLoc } : {}), {
             details: "Text smaller than 9px is difficult to read, especially on mobile devices."
-          });
+          }));
         }
       }
     }
@@ -12391,21 +12922,23 @@ function checkTextSizeAndContrast($) {
         }
         const grade = wcagGrade(ratio);
         if (grade === "Fail") {
-          issues.push({
+          issues.push(__spreadProps(__spreadValues({
             severity: "error",
             rule: "low-contrast",
             message: `Low contrast ratio ${ratio.toFixed(1)}:1 \u2014 fails WCAG minimum`,
-            element: describeElement($, el),
+            element: describeElement($, el)
+          }, styleLoc ? { loc: styleLoc } : {}), {
             details: `Foreground ${colorValue} on background needs at least ${isLargeText ? "3:1" : "4.5:1"} contrast ratio.`
-          });
+          }));
         } else if (!isLargeText && grade === "AA Large") {
-          issues.push({
+          issues.push(__spreadProps(__spreadValues({
             severity: "warning",
             rule: "low-contrast",
             message: `Low contrast ratio ${ratio.toFixed(1)}:1 \u2014 fails WCAG AA for normal text`,
-            element: describeElement($, el),
+            element: describeElement($, el)
+          }, styleLoc ? { loc: styleLoc } : {}), {
             details: `Foreground ${colorValue} on background needs at least 4.5:1 for normal-sized text.`
-          });
+          }));
         }
       }
     }
@@ -12428,29 +12961,32 @@ function checkCharsetDeclaration($) {
     const content = httpEquiv.attr("content") || "";
     if (/charset\s*=/i.test(content)) return null;
   }
-  return {
+  const loc = locOfFirst($, "head");
+  return __spreadProps(__spreadValues({
     severity: "warning",
     rule: "missing-charset",
-    message: "Missing charset declaration",
+    message: "Missing charset declaration"
+  }, loc ? { loc } : {}), {
     details: 'Add <meta charset="utf-8"> in <head> to prevent encoding issues across email clients.'
-  };
+  });
 }
 function checkSemanticStructure($) {
   const issues = [];
   const headings = [];
   $("h1, h2, h3, h4, h5, h6").each((_, el) => {
     const level = parseInt(el.tagName.replace(/h/i, ""), 10);
-    headings.push({ level, text: $(el).text().trim().slice(0, 60) });
+    headings.push({ level, text: $(el).text().trim().slice(0, 60), loc: locOfElement(el) });
   });
   for (let i = 1; i < headings.length; i++) {
     const gap = headings[i].level - headings[i - 1].level;
     if (gap > 1) {
-      issues.push({
+      issues.push(__spreadProps(__spreadValues({
         severity: "info",
         rule: "heading-skip",
-        message: `Heading level skipped: h${headings[i - 1].level} to h${headings[i].level}`,
+        message: `Heading level skipped: h${headings[i - 1].level} to h${headings[i].level}`
+      }, headings[i].loc ? { loc: headings[i].loc } : {}), {
         details: "Skipped heading levels can confuse screen readers. Use sequential heading levels."
-      });
+      }));
       break;
     }
   }
@@ -12491,8 +13027,8 @@ function checkAccessibilityFromDom($) {
   const score = Math.max(0, 100 - penalty);
   return { score, issues };
 }
-function checkAccessibility(html) {
-  return fromHtml(html, EMPTY_ACCESSIBILITY, checkAccessibilityFromDom);
+function checkAccessibility(html, options) {
+  return fromHtml(html, EMPTY_ACCESSIBILITY, checkAccessibilityFromDom, options);
 }
 
 // src/image-analyzer.ts
@@ -12539,6 +13075,8 @@ function analyzeImagesFromDom($) {
     const height = (_c = img.attr("height")) != null ? _c : null;
     const style = (img.attr("style") || "").toLowerCase();
     const imgIssues = [];
+    const elLoc = locOfElement(el);
+    const srcLoc = src ? locOfAttr(el, "src") : elLoc;
     const tracking = isTrackingPixel(img);
     let dataUriBytes = 0;
     if (src.startsWith("data:")) {
@@ -12562,59 +13100,59 @@ function analyzeImagesFromDom($) {
       const hasStyleHeight = /height\s*:/.test(style);
       if (!hasStyleWidth && !hasStyleHeight) {
         imgIssues.push("missing-dimensions");
-        issues.push({
+        issues.push(__spreadValues({
           rule: "missing-dimensions",
           severity: "warning",
           message: "Image missing width/height attributes \u2014 causes layout shifts and Outlook rendering issues.",
           src: truncateSrc(src)
-        });
+        }, elLoc ? { loc: elLoc } : {}));
       }
     }
     if (dataUriBytes > DATA_URI_WARN_BYTES) {
       const kb = Math.round(dataUriBytes / 1024);
       imgIssues.push("large-data-uri");
-      issues.push({
+      issues.push(__spreadValues({
         rule: "large-data-uri",
         severity: "warning",
         message: `Data URI is ${kb}KB \u2014 consider hosting the image externally to reduce email size.`,
         src: truncateSrc(src)
-      });
+      }, srcLoc ? { loc: srcLoc } : {}));
     }
     if (alt === null) {
       imgIssues.push("missing-alt");
-      issues.push({
+      issues.push(__spreadValues({
         rule: "missing-alt",
         severity: "warning",
         message: "Image missing alt attribute \u2014 hurts deliverability and accessibility.",
         src: truncateSrc(src)
-      });
+      }, elLoc ? { loc: elLoc } : {}));
     }
     if (src.toLowerCase().endsWith(".webp") || src.includes("image/webp")) {
       imgIssues.push("webp-format");
-      issues.push({
+      issues.push(__spreadValues({
         rule: "webp-format",
         severity: "info",
         message: "WebP format detected \u2014 not supported by all email clients. Consider PNG or JPEG.",
         src: truncateSrc(src)
-      });
+      }, srcLoc ? { loc: srcLoc } : {}));
     }
     if (src.toLowerCase().endsWith(".svg") || src.includes("image/svg")) {
       imgIssues.push("svg-format");
-      issues.push({
+      issues.push(__spreadValues({
         rule: "svg-format",
         severity: "info",
         message: "SVG format detected \u2014 not supported by most email clients. Use PNG instead.",
         src: truncateSrc(src)
-      });
+      }, srcLoc ? { loc: srcLoc } : {}));
     }
     if (!style.includes("display:block") && !style.includes("display: block")) {
       imgIssues.push("missing-display-block");
-      issues.push({
+      issues.push(__spreadValues({
         rule: "missing-display-block",
         severity: "info",
         message: "Image without display:block \u2014 may cause unwanted gaps in Outlook.",
         src: truncateSrc(src)
-      });
+      }, elLoc ? { loc: elLoc } : {}));
     }
     images.push({
       src: truncateSrc(src),
@@ -12652,8 +13190,8 @@ function analyzeImagesFromDom($) {
   }
   return { total: images.length, totalDataUriBytes, issues, images };
 }
-function analyzeImages(html) {
-  return fromHtml(html, EMPTY_IMAGES, analyzeImagesFromDom);
+function analyzeImages(html, options) {
+  return fromHtml(html, EMPTY_IMAGES, analyzeImagesFromDom, options);
 }
 
 // src/inbox-preview.ts
@@ -12871,11 +13409,57 @@ function checkSize(html) {
   return fromHtml(html, EMPTY_SIZE, checkSizeFromDom);
 }
 
+// src/dom-text.ts
+function visibleTextNodes($) {
+  var _a, _b, _c, _d;
+  const nodes = [];
+  const stack = [...(_b = (_a = $.root()[0]) == null ? void 0 : _a.children) != null ? _b : []].reverse();
+  while (stack.length > 0) {
+    const node = stack.pop();
+    const tag = (_c = node.tagName) == null ? void 0 : _c.toLowerCase();
+    if (tag === "style" || tag === "script" || tag === "head") continue;
+    if (node.type === "text") {
+      nodes.push(node);
+      continue;
+    }
+    const children = (_d = node.children) != null ? _d : [];
+    for (let i = children.length - 1; i >= 0; i--) stack.push(children[i]);
+  }
+  return nodes;
+}
+
 // src/template-checker.ts
-function checkTemplateVariablesFromDom($) {
+function checkTemplateVariablesFromDom($, source) {
+  var _a;
   const issues = [];
   const seen = /* @__PURE__ */ new Set();
-  const textContent = extractTextContent($);
+  const textNodes = visibleTextNodes($);
+  const positioned = textNodes.some((n) => n.sourceCodeLocation);
+  for (const node of positioned ? textNodes : []) {
+    const data = (_a = node.data) != null ? _a : "";
+    for (const [pattern, label] of TEMPLATE_VARIABLE_PATTERNS) {
+      pattern.lastIndex = 0;
+      let match;
+      while ((match = pattern.exec(data)) !== null) {
+        const variable = match[0];
+        const key = `text:${variable}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        const loc = locInTextNode(node, match.index, variable.length, source);
+        issues.push(__spreadValues({
+          rule: "unresolved-variable",
+          severity: "error",
+          message: `Unresolved ${label} variable "${variable}" found in text content.`,
+          variable,
+          location: "text"
+        }, loc ? { loc } : {}));
+      }
+    }
+  }
+  const textContent = textNodes.map((n) => {
+    var _a2;
+    return (_a2 = n.data) != null ? _a2 : "";
+  }).join("");
   for (const [pattern, label] of TEMPLATE_VARIABLE_PATTERNS) {
     pattern.lastIndex = 0;
     let match;
@@ -12908,13 +13492,14 @@ function checkTemplateVariablesFromDom($) {
             const key = `attr:${attr}:${variable}`;
             if (seen.has(key)) continue;
             seen.add(key);
-            issues.push({
+            const loc = locOfAttr(el, attr);
+            issues.push(__spreadValues({
               rule: "unresolved-variable",
               severity: "error",
               message: `Unresolved ${label} variable "${variable}" found in ${attr} attribute.`,
               variable,
               location: "attribute"
-            });
+            }, loc ? { loc } : {}));
           }
         }
       }
@@ -12922,13 +13507,13 @@ function checkTemplateVariablesFromDom($) {
   }
   return { unresolvedCount: issues.length, issues };
 }
-function extractTextContent($) {
-  const clone = $.root().clone();
-  clone.find("style, script, head").remove();
-  return clone.text();
-}
-function checkTemplateVariables(html) {
-  return fromHtml(html, EMPTY_TEMPLATE, checkTemplateVariablesFromDom);
+function checkTemplateVariables(html, options) {
+  return fromHtml(
+    html,
+    EMPTY_TEMPLATE,
+    ($, h) => checkTemplateVariablesFromDom($, (options == null ? void 0 : options.positions) ? h : void 0),
+    options
+  );
 }
 
 // src/overflow-checker.ts
@@ -12944,32 +13529,71 @@ function fixedPxWidth($el) {
 function isFluid(style) {
   return /max-width\s*:\s*100%/i.test(style) || /width\s*:\s*100%/i.test(style);
 }
-function addWidthIssue(width, label, issues, seen) {
+function addWidthIssue(width, label, issues, seen, loc) {
   const key = `w:${label}:${width}`;
-  if (seen.has(key)) return;
-  seen.add(key);
-  issues.push({
+  const existing = seen.get(key);
+  if (existing) {
+    addOccurrence(existing, loc);
+    return;
+  }
+  const issue = __spreadValues({
     rule: "fixed-width-overflow",
     severity: "warning",
     message: `${label} has a fixed width of ${width}px, wider than the ${EMAIL_MAX_WIDTH}px email frame \u2014 it will force horizontal scrolling, especially on mobile.`,
     detail: `Use width:100% with max-width:${EMAIL_MAX_WIDTH}px instead of a fixed width beyond the frame.`
-  });
+  }, loc ? { loc, locs: [loc] } : {});
+  seen.set(key, issue);
+  issues.push(issue);
 }
-function checkOverflowFromDom($) {
+function locateInNodes(nodes, starts, index, length, source) {
+  var _a;
+  let lo = 0;
+  let hi = starts.length - 1;
+  let found = -1;
+  while (lo <= hi) {
+    const mid = lo + hi >> 1;
+    if (starts[mid] <= index) {
+      found = mid;
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  if (found === -1) return void 0;
+  const node = nodes[found];
+  const within = index - starts[found];
+  const available = ((_a = node.data) != null ? _a : "").length - within;
+  return locInTextNode(node, within, Math.min(length, available), source);
+}
+function addOccurrence(issue, loc) {
+  if (!loc || !issue.locs) return;
+  if (issue.locs.some((l) => l.offset === loc.offset)) return;
+  if (issue.locs.length >= MAX_WARNING_LOCATIONS) {
+    issue.locsTruncated = true;
+    return;
+  }
+  issue.locs.push(loc);
+}
+function checkOverflowFromDom($, source) {
+  var _a;
   const issues = [];
-  const seen = /* @__PURE__ */ new Set();
+  const seen = /* @__PURE__ */ new Map();
+  const tokensSeen = /* @__PURE__ */ new Set();
   $("[width], [style*='width']").each((_, el) => {
     const $el = $(el);
     const width = fixedPxWidth($el);
     if (width === null || width <= EMAIL_MAX_WIDTH) return;
     if (isFluid($el.attr("style") || "")) return;
     const tag = (el.tagName || "element").toLowerCase();
-    addWidthIssue(width, `<${tag}>`, issues, seen);
+    const fromStyle = /(?:^|[;\s])width\s*:\s*\d+px/i.test($el.attr("style") || "");
+    addWidthIssue(width, `<${tag}>`, issues, seen, locOfAttr(el, fromStyle ? "style" : "width"));
   });
   $("style").each((_, el) => {
+    const cssText = $(el).text();
+    const anchor = cssBlockAnchor(el, cssText, source);
     let ast;
     try {
-      ast = csstree6.parse($(el).text());
+      ast = csstree6.parse(cssText, { positions: true });
     } catch (e) {
       return;
     }
@@ -12979,13 +13603,17 @@ function checkOverflowFromDom($) {
         if (node.type !== "Rule") return;
         let widthPx = null;
         let fluid = false;
+        let widthLoc;
         node.block.children.forEach((child) => {
           if (child.type !== "Declaration") return;
           const prop = child.property.toLowerCase();
           const val = csstree6.generate(child.value);
           if (prop === "width") {
             const m = val.match(/^(\d+)px$/);
-            if (m) widthPx = parseInt(m[1], 10);
+            if (m) {
+              widthPx = parseInt(m[1], 10);
+              widthLoc = locInCssBlock(anchor, child.loc);
+            }
             if (/\b100%/.test(val)) fluid = true;
           } else if (prop === "max-width" && /\b100%/.test(val)) {
             fluid = true;
@@ -12993,36 +13621,46 @@ function checkOverflowFromDom($) {
         });
         if (widthPx !== null && widthPx > EMAIL_MAX_WIDTH && !fluid) {
           const selector = csstree6.generate(node.prelude).trim().slice(0, 40);
-          addWidthIssue(widthPx, selector || "rule", issues, seen);
+          addWidthIssue(widthPx, selector || "rule", issues, seen, widthLoc);
         }
       }
     });
   });
   const usesWrapGuard = /overflow-wrap|word-break|word-wrap/i.test($.html());
   if (!usesWrapGuard) {
-    const $body = $("body");
+    const nodes = visibleTextNodes($);
+    const starts = [];
     let text = "";
-    if ($body.length) {
-      const clone = $body.clone();
-      clone.find("style, script").remove();
-      text = clone.text();
-    }
-    for (const token of text.split(/\s+/)) {
-      if (token.length <= UNBREAKABLE_STRING_LENGTH || seen.has(token)) continue;
-      seen.add(token);
+    for (const node of nodes) {
+      starts.push(text.length);
+      text += (_a = node.data) != null ? _a : "";
+    }
+    let at = 0;
+    for (const token of text.split(/(\s+)/)) {
+      const start = at;
+      at += token.length;
+      if (/^\s*$/.test(token)) continue;
+      if (token.length <= UNBREAKABLE_STRING_LENGTH || tokensSeen.has(token)) continue;
+      tokensSeen.add(token);
       const preview = token.length > 50 ? `${token.slice(0, 50)}\u2026` : token;
-      issues.push({
+      const loc = locateInNodes(nodes, starts, start, token.length, source);
+      issues.push(__spreadValues({
         rule: "unbreakable-string",
         severity: "warning",
         message: `A ${token.length}-character unbroken string ("${preview}") can't wrap and will force horizontal scrolling on narrow screens.`,
         detail: `Add overflow-wrap: anywhere (or word-break: break-word) to its container.`
-      });
+      }, loc ? { loc, locs: [loc] } : {}));
     }
   }
   return { hasOverflow: issues.length > 0, issues };
 }
-function checkOverflow(html) {
-  return fromHtml(html, EMPTY_OVERFLOW, checkOverflowFromDom);
+function checkOverflow(html, options) {
+  return fromHtml(
+    html,
+    EMPTY_OVERFLOW,
+    ($, h) => checkOverflowFromDom($, (options == null ? void 0 : options.positions) ? h : void 0),
+    options
+  );
 }
 
 // src/visual-checker.ts
@@ -13035,8 +13673,8 @@ function isSolidColor(value) {
   return c !== null && c.a !== 0;
 }
 function firstColor(value) {
-  const tokens = value.match(/#[0-9a-fA-F]{3,8}|rgba?\([^)]+\)|hsla?\([^)]+\)|\b[a-zA-Z]{3,}\b/g) || [];
-  for (const t of tokens) {
+  const tokens2 = value.match(/#[0-9a-fA-F]{3,8}|rgba?\([^)]+\)|hsla?\([^)]+\)|\b[a-zA-Z]{3,}\b/g) || [];
+  for (const t of tokens2) {
     const lc = t.toLowerCase();
     if (lc === "transparent") continue;
     if (/^(?:linear|radial|conic|gradient|deg|turn|rad|grad|to|at|from|in|circle|ellipse|closest|farthest|side|corner|url)$/.test(lc)) continue;
@@ -13073,8 +13711,17 @@ function hasFontFallback(value) {
     return WEB_SAFE_FONTS.has(t) || GENERIC_FONT_FAMILIES.has(t) || t.startsWith("-apple-system") || t === "blinkmacsystemfont";
   });
 }
-function inspectDeclarations(style, issues, seen) {
-  var _a, _b;
+function addOccurrence2(issue, loc) {
+  if (!loc || !issue.locs) return;
+  if (issue.locs.some((l) => l.offset === loc.offset)) return;
+  if (issue.locs.length >= MAX_WARNING_LOCATIONS) {
+    issue.locsTruncated = true;
+    return;
+  }
+  issue.locs.push(loc);
+}
+function inspectDeclarations(style, issues, seen, locs) {
+  var _a, _b, _c;
   const combined = `${(_a = style.get("background-image")) != null ? _a : ""} ${(_b = style.get("background")) != null ? _b : ""}`;
   const isGradient = GRADIENT_RE.test(combined);
   const isImage = isGradient || /url\(/i.test(combined);
@@ -13082,30 +13729,40 @@ function inspectDeclarations(style, issues, seen) {
     const stop = isGradient ? firstColor(combined) : null;
     const fix = stop ? `background-color: ${stop};` : `background-color: <solid colour matching the image>;`;
     const key = `bg:${fix}`;
-    if (!seen.has(key)) {
-      seen.add(key);
-      issues.push({
+    const loc = (_c = locs == null ? void 0 : locs.get("background-image")) != null ? _c : locs == null ? void 0 : locs.get("background");
+    const existing = seen.get(key);
+    if (existing) {
+      addOccurrence2(existing, loc);
+    } else {
+      const issue = __spreadValues({
         rule: "missing-background-fallback",
         severity: "warning",
         message: `${isGradient ? "Gradient" : "Background image"} has no background-color fallback \u2014 it renders as a blank area (and can hide overlaid text) in Outlook and other clients that drop image backgrounds.`,
         detail: isGradient ? `Add a solid fallback beneath the gradient using its first colour stop.` : `Add a solid background-color so the area still has colour when the image is dropped.`,
         fix
-      });
+      }, loc ? { loc, locs: [loc] } : {});
+      seen.set(key, issue);
+      issues.push(issue);
     }
   }
   const font = style.get("font-family");
   if (font && !CSS_WIDE_KEYWORDS.has(font.trim().toLowerCase()) && !hasFontFallback(font)) {
     const fix = `font-family: ${font.trim()}, Arial, sans-serif;`;
     const key = `font:${font.trim().toLowerCase()}`;
-    if (!seen.has(key)) {
-      seen.add(key);
-      issues.push({
+    const loc = locs == null ? void 0 : locs.get("font-family");
+    const existing = seen.get(key);
+    if (existing) {
+      addOccurrence2(existing, loc);
+    } else {
+      const issue = __spreadValues({
         rule: "missing-font-fallback",
         severity: "warning",
         message: `font-family "${font.trim()}" has no web-safe fallback \u2014 clients that strip web fonts (Gmail, Outlook) fall back to Times New Roman.`,
         detail: `End the stack with a web-safe font and a generic family.`,
         fix
-      });
+      }, loc ? { loc, locs: [loc] } : {});
+      seen.set(key, issue);
+      issues.push(issue);
     }
   }
 }
@@ -13118,30 +13775,47 @@ function ruleToMap(node) {
   });
   return map;
 }
-function checkVisualFromDom($) {
+function checkVisualFromDom($, source) {
   const issues = [];
-  const seen = /* @__PURE__ */ new Set();
+  const seen = /* @__PURE__ */ new Map();
   $("[style]").each((_, el) => {
-    inspectDeclarations(parseInlineStyle($(el).attr("style") || ""), issues, seen);
+    const attrLoc = locOfAttr(el, "style");
+    const style = parseInlineStyle($(el).attr("style") || "");
+    const locs = attrLoc ? new Map([...style.keys()].map((prop) => [prop, attrLoc])) : void 0;
+    inspectDeclarations(style, issues, seen, locs);
   });
   $("style").each((_, el) => {
+    const cssText = $(el).text();
+    const anchor = cssBlockAnchor(el, cssText, source);
     let ast;
     try {
-      ast = csstree7.parse($(el).text());
+      ast = csstree7.parse(cssText, { positions: true });
     } catch (e) {
       return;
     }
     csstree7.walk(ast, {
       visit: "Rule",
       enter(node) {
-        if (node.type === "Rule") inspectDeclarations(ruleToMap(node), issues, seen);
+        if (node.type !== "Rule") return;
+        const locs = /* @__PURE__ */ new Map();
+        node.block.children.forEach((child) => {
+          if (child.type !== "Declaration") return;
+          const loc = locInCssBlock(anchor, child.loc);
+          if (loc) locs.set(child.property.toLowerCase(), loc);
+        });
+        inspectDeclarations(ruleToMap(node), issues, seen, locs);
       }
     });
   });
   return { issues };
 }
-function checkVisual(html) {
-  return fromHtml(html, EMPTY_VISUAL, checkVisualFromDom);
+function checkVisual(html, options) {
+  return fromHtml(
+    html,
+    EMPTY_VISUAL,
+    ($, h) => checkVisualFromDom($, (options == null ? void 0 : options.positions) ? h : void 0),
+    options
+  );
 }
 
 // src/audit.ts
@@ -13160,7 +13834,8 @@ var EMPTY_AUDIT = {
 function runAudit($, html, framework, options) {
   var _a;
   const skip = new Set((_a = options == null ? void 0 : options.skip) != null ? _a : []);
-  const warnings = skip.has("compatibility") ? [] : analyzeEmailFromDom($, framework);
+  const source = (options == null ? void 0 : options.positions) ? html : void 0;
+  const warnings = skip.has("compatibility") ? [] : analyzeEmailFromDom($, framework, source);
   const scores = skip.has("compatibility") ? {} : generateCompatibilityScore(warnings);
   const spam = skip.has("spam") ? EMPTY_SPAM : analyzeSpamFromDom($, options == null ? void 0 : options.spam);
   const links = skip.has("links") ? EMPTY_LINKS : validateLinksFromDom($);
@@ -13168,19 +13843,19 @@ function runAudit($, html, framework, options) {
   const images = skip.has("images") ? EMPTY_IMAGES : analyzeImagesFromDom($);
   const inboxPreview = skip.has("inboxPreview") ? EMPTY_INBOX_PREVIEW : extractInboxPreviewFromDom($);
   const size = skip.has("size") ? EMPTY_SIZE : checkSizeFromDom($, html);
-  const templateVariables = skip.has("templateVariables") ? EMPTY_TEMPLATE : checkTemplateVariablesFromDom($);
-  const overflow = skip.has("overflow") ? EMPTY_OVERFLOW : checkOverflowFromDom($);
-  const visual = skip.has("visual") ? EMPTY_VISUAL : checkVisualFromDom($);
+  const templateVariables = skip.has("templateVariables") ? EMPTY_TEMPLATE : checkTemplateVariablesFromDom($, source);
+  const overflow = skip.has("overflow") ? EMPTY_OVERFLOW : checkOverflowFromDom($, source);
+  const visual = skip.has("visual") ? EMPTY_VISUAL : checkVisualFromDom($, source);
   return { compatibility: { warnings, scores }, spam, links, accessibility, images, inboxPreview, size, templateVariables, overflow, visual };
 }
 function auditEmail(html, options) {
-  return fromHtml(html, EMPTY_AUDIT, ($, h) => runAudit($, h, options == null ? void 0 : options.framework, options));
+  return fromHtml(html, EMPTY_AUDIT, ($, h) => runAudit($, h, options == null ? void 0 : options.framework, options), options);
 }
 
 // src/plain-text.ts
-var cheerio6 = __toESM(require("cheerio"), 1);
+var cheerio5 = __toESM(require("cheerio"), 1);
 function toPlainText(html) {
-  const $ = cheerio6.load(html);
+  const $ = cheerio5.load(html);
   $("style, script, head").remove();
   $("[data-skip-in-text='true']").remove();
   const lines = [];
@@ -13282,7 +13957,6 @@ function toPlainText(html) {
 }
 
 // src/session.ts
-var cheerio7 = __toESM(require("cheerio"), 1);
 function createSession(html, options) {
   if (!html || !html.trim()) {
     const fw = options == null ? void 0 : options.framework;
@@ -13309,16 +13983,17 @@ function createSession(html, options) {
   if (html.length > MAX_HTML_SIZE) {
     throw new Error(`HTML input exceeds ${MAX_HTML_SIZE / 1024}KB limit.`);
   }
-  const $ = cheerio7.load(html);
+  const $ = loadHtml(html, options);
   const framework = options == null ? void 0 : options.framework;
+  const source = (options == null ? void 0 : options.positions) ? html : void 0;
   return {
     html,
     framework,
     audit(opts) {
-      return runAudit($, html, framework, opts);
+      return runAudit($, html, framework, __spreadProps(__spreadValues({}, opts), { positions: options == null ? void 0 : options.positions }));
     },
     analyze() {
-      return analyzeEmailFromDom($, framework);
+      return analyzeEmailFromDom($, framework, source);
     },
     score(warnings) {
       return generateCompatibilityScore(warnings);
@@ -13342,13 +14017,13 @@ function createSession(html, options) {
       return checkSizeFromDom($, html);
     },
     checkTemplateVariables() {
-      return checkTemplateVariablesFromDom($);
+      return checkTemplateVariablesFromDom($, source);
     },
     checkOverflow() {
-      return checkOverflowFromDom($);
+      return checkOverflowFromDom($, source);
     },
     checkVisual() {
-      return checkVisualFromDom($);
+      return checkVisualFromDom($, source);
     },
     // Transforms create isolated copies since they mutate the DOM
     transformForClient(clientId) {
@@ -13379,18 +14054,22 @@ var CompileError = class extends Error {
   COMPOUND_VALUE_FEATURES,
   CSS_FUNCTION_FEATURES,
   CSS_SUPPORT,
+  CSS_SUPPORT_NOTES,
   CompileError,
   EMAIL_CLIENTS,
   EMPTY_DELIVERABILITY,
   GENERIC_LINK_TEXT,
   HTML_ELEMENT_FEATURES,
   MAX_HTML_SIZE,
+  MAX_WARNING_LOCATIONS,
   STRUCTURAL_FIX_PROPERTIES,
+  VALUE_CAVEAT_PROPS,
   alphaBlend,
   analyzeEmail,
   analyzeImages,
   analyzeSpam,
   auditEmail,
+  caveatApplies,
   checkAccessibility,
   checkOverflow,
   checkSize,