why-hydration 0.1.5 → 0.2.0

package/dist/{chunk-AT6A77X3.cjs → chunk-KX6G7I4Y.cjs}

@@ -167,21 +167,21 @@ function diffAttributes(serverEl, clientEl, path, parentTag) {
   }
   return null;
 }
-function normalizeAttr(name, value) {
-  if (value == null) return null;
+function normalizeAttr(name, value2) {
+  if (value2 == null) return null;
   if (name === "class") {
-    return value.trim().split(/\s+/).filter(Boolean).sort().join(" ");
+    return value2.trim().split(/\s+/).filter(Boolean).sort().join(" ");
   }
   if (name === "style") {
-    return normalizeStyle(value);
+    return normalizeStyle(value2);
   }
-  return value;
+  return value2;
 }
-function normalizeStyle(value) {
+function normalizeStyle(value2) {
   if (typeof document !== "undefined") {
     try {
       const el = document.createElement("div");
-      el.style.cssText = value;
+      el.style.cssText = value2;
       const decls = [];
       for (let i = 0; i < el.style.length; i++) {
         const prop = el.style.item(i);
@@ -191,7 +191,7 @@ function normalizeStyle(value) {
     } catch {
     }
   }
-  return value.split(";").map((s) => s.trim()).filter(Boolean).sort().join(";");
+  return value2.split(";").map((s) => s.trim()).filter(Boolean).sort().join(";");
 }
 function nodeKey(node) {
   if (node.nodeType === Node.ELEMENT_NODE) {
@@ -361,26 +361,26 @@ var RANDOM_DECIMAL_RE = /^0?\.\d{6,}$/;
 var NANOID_RE = /^[A-Za-z0-9_-]{10,}$/;
 var ARABIC_INDIC_DIGITS = /[٠-٩۰-۹]/;
 var LATIN_DIGITS = /[0-9]/;
-var BIDI_CONTROLS = /[‎‏؜⁦-⁩]/g;
-function stripBidiControls(value) {
-  return value.replace(BIDI_CONTROLS, "");
+var BIDI_CONTROLS = /[\u200e\u200f\u061c\u2066-\u2069]/g;
+function stripBidiControls(value2) {
+  return value2.replace(BIDI_CONTROLS, "");
 }
 function differsOnlyByBidiControls(a, b) {
   const sa = stripBidiControls(a);
   const sb = stripBidiControls(b);
   return a !== b && sa === sb && sa.trim() !== "";
 }
-function normalizeNumerals(value) {
-  return stripBidiControls(value).replace(/[٠-٩۰-۹٫٬]/g, (ch) => {
+function normalizeNumerals(value2) {
+  return stripBidiControls(value2).replace(/[٠-٩۰-۹٫٬]/g, (ch) => {
     if (ch === "\u066B") return ".";
     if (ch === "\u066C") return ",";
-    const code = ch.charCodeAt(0);
-    const zero = code >= 1776 ? 1776 : 1632;
-    return String(code - zero);
+    const code2 = ch.charCodeAt(0);
+    const zero = code2 >= 1776 ? 1776 : 1632;
+    return String(code2 - zero);
   });
 }
-function isRandomLike(value) {
-  const v = value.trim();
+function isRandomLike(value2) {
+  const v = value2.trim();
   if (!v) return false;
   if (UUID_RE.test(v)) return true;
   if (REACT_ID_RE.test(v)) return true;
@@ -389,9 +389,9 @@ function isRandomLike(value) {
   if (NANOID_RE.test(v) && /[A-Za-z]/.test(v) && /[0-9]/.test(v)) return true;
   return false;
 }
-function looksLikeTime(value) {
+function looksLikeTime(value2) {
   return /\b\d{1,2}:\d{2}(?::\d{2})?(?:\s?[AaPp][Mm])?\b/.test(
-    normalizeNumerals(value).trim()
+    normalizeNumerals(value2).trim()
   );
 }
 var ISO_DATE = /^\d{4}-\d{1,2}(?:-\d{1,2})?(?:[T ]\d{1,2}:\d{2}(?::\d{2})?)?/;
@@ -401,8 +401,8 @@ var MONTH_NAME = /\b(?:jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)[a-z]*\b/
 function looksLikeDate(v) {
   return ISO_DATE.test(v) || NUMERIC_DATE.test(v) || TIME_OF_DAY.test(v) || MONTH_NAME.test(v) && /\d/.test(v);
 }
-function toTimestamp(value) {
-  const v = value.trim();
+function toTimestamp(value2) {
+  const v = value2.trim();
   if (!v) return null;
   if (/^\d{10,13}$/.test(v)) {
     const n = Number(v);
@@ -417,11 +417,11 @@ function toTimestamp(value) {
   }
   return null;
 }
-function hasArabicIndicDigits(value) {
-  return ARABIC_INDIC_DIGITS.test(value);
+function hasArabicIndicDigits(value2) {
+  return ARABIC_INDIC_DIGITS.test(value2);
 }
-function hasLatinDigits(value) {
-  return LATIN_DIGITS.test(value);
+function hasLatinDigits(value2) {
+  return LATIN_DIGITS.test(value2);
 }
 var NUMERIC_LIKE = /^[+-]?[\d.,\s\u00a0\u2009]+$/;
 function isSameNumberDifferentSeparators(a, b) {
@@ -526,6 +526,163 @@ function messageIndicatesInvalidNesting(message) {
   return /validateDOMNesting/i.test(message) || /cannot (?:be a|contain).*(?:descendant|child)/i.test(message) || /cannot appear as a (?:child|descendant)/i.test(message);
 }
 
+// src/core/classify/messages.ts
+var code = (text) => ({ code: text });
+var value = (text) => ({ value: text });
+function param(params, name) {
+  const v = params[name];
+  return typeof v === "string" ? v : "";
+}
+function paramList(params, name) {
+  const v = params[name];
+  return Array.isArray(v) ? v : [];
+}
+function valueList(items, separator) {
+  const out = [];
+  items.forEach((item, i) => {
+    if (i > 0) out.push(separator);
+    out.push(value(item));
+  });
+  return out;
+}
+function renderMessage(template, params = {}) {
+  if (typeof template === "function") return template(params);
+  const out = [];
+  template.split("`").forEach((part, i) => {
+    if (i % 2 === 1) {
+      out.push(
+        code(part.replace(/\{(\w+)\}/g, (_, n) => param(params, n)))
+      );
+      return;
+    }
+    let last = 0;
+    for (const m of part.matchAll(/\{(\w+)\}/g)) {
+      const at = m.index ?? 0;
+      if (at > last) out.push(part.slice(last, at));
+      out.push(value(param(params, m[1])));
+      last = at + m[0].length;
+    }
+    if (last < part.length) out.push(part.slice(last));
+  });
+  return out.filter((s) => s !== "");
+}
+function plainText(segments) {
+  return segments.map(
+    (s) => typeof s === "string" ? s : "code" in s ? `\`${s.code}\`` : s.value
+  ).join("");
+}
+function classDetail(params, words) {
+  const added = paramList(params, "added");
+  const removed = paramList(params, "removed");
+  if (!added.length && !removed.length) return [];
+  const out = [words.open];
+  if (added.length) {
+    out.push(words.added, ...valueList(added, words.listSeparator));
+  }
+  if (removed.length) {
+    if (added.length) out.push(words.partSeparator);
+    out.push(words.removed, ...valueList(removed, words.listSeparator));
+  }
+  out.push(words.close);
+  return out;
+}
+var EN_MESSAGES = {
+  "non-deterministic-value": {
+    explanation: "The server and client rendered different random-looking values (an id, token, or Math.random() output). Anything non-deterministic in render produces a different value on each side.",
+    suggestion: "Use React `useId()` for ids. For random values, generate them after mount (in `useEffect`) or pass a value down from the server so both sides agree. Never call `Math.random()`/`crypto` during render."
+  },
+  "date-time": {
+    explanation: "The values are dates/times that differ between server render and client render \u2014 the clock moved (or the timezone differs) between the two environments.",
+    suggestion: "Render the current time after mount, or pass a single server timestamp down and format it identically on both sides. Pin an explicit timezone when formatting."
+  },
+  "locale-format.bidi": {
+    explanation: "The values differ only by invisible bidirectional control marks (LRM/RLM/isolates). `Intl` adds these around numbers and dates in RTL locales, and different ICU versions \u2014 Node vs the browser \u2014 emit different ones for the same input.",
+    suggestion: "Format the value in one place and pass the string down, or pin the same locale and timezone on both sides. If the marks are harmless, add `suppressHydrationWarning` to the element."
+  },
+  "locale-format.script": {
+    explanation: "The same value was formatted with different digit scripts (Arabic-Indic \u0660\u0661\u0662 vs Latin 012). The server and client resolved to different locales.",
+    suggestion: "Pass an explicit `locale` (and timezone) to `Intl.NumberFormat` / `toLocaleString` on both server and client, or format the value after mount so only the client locale is ever used."
+  },
+  "locale-format.separators": {
+    explanation: "The same number was formatted with different grouping/decimal separators between server and client (e.g. 1,234.56 vs 1.234,56).",
+    suggestion: "Pass an explicit locale to `Intl.NumberFormat`/`toLocaleString` on both sides so the separators match."
+  },
+  "locale-format.date-order": {
+    explanation: "The same date was rendered in a different field order (MM/DD vs DD/MM) between server and client.",
+    suggestion: "Format dates with an explicit locale and timezone via `Intl` on both sides."
+  },
+  "browser-only-api": {
+    explanation: "The client rendered content the server left empty \u2014 the signature of reading a browser-only API (`window`, `document`, `localStorage`, `navigator`, `matchMedia`) during render.",
+    suggestion: "Gate browser-only reads behind a mounted flag or `useEffect`, or use `useSyncExternalStore` with a server snapshot so the first client render matches the server."
+  },
+  "viewport-branching": {
+    explanation: "A whole subtree was added, removed, or swapped between server and client \u2014 typically a JavaScript width/viewport check that branches the tree at first render.",
+    suggestion: "Render both branches and switch between them with CSS media queries at first paint instead of branching in JavaScript, or defer the JS-driven branch until after mount."
+  },
+  "invalid-html-nesting": {
+    explanation: "A node was moved or ejected because the markup is invalid HTML (e.g. a `<div>` inside a `<p>`, or nested `<a>`). The browser repairs the server DOM, so it no longer matches what React expects.",
+    suggestion: "Fix the markup validity: block elements cannot live inside `<p>`, anchors cannot nest, etc. Replace the invalid parent with a `<div>` or restructure the tree."
+  },
+  "whitespace-minification": {
+    explanation: "The mismatch is whitespace-only \u2014 the text is identical apart from spaces/newlines. An HTML minifier likely collapsed whitespace around the hydration root differently from React.",
+    suggestion: "Check your HTML minifier settings (e.g. `conservativeCollapse`) around the app root, or avoid minifying whitespace inside hydrated markup."
+  },
+  "third-party-dom-mutation.extension-attribute": {
+    explanation: "The attribute `{attribute}` was injected by a browser extension or third-party script (e.g. Grammarly, ColorZilla) before hydration, so the client DOM no longer matches the server.",
+    suggestion: "This is usually harmless. Add `suppressHydrationWarning` to the affected element, or defer third-party script init until after hydration."
+  },
+  "third-party-dom-mutation.root-attribute": {
+    explanation: "An attribute (`{attribute}`) appeared on a root element that the server never sent \u2014 a hallmark of an extension or early third-party script mutating the DOM.",
+    suggestion: "Add `suppressHydrationWarning` to the root element, or defer the third-party script until after hydration."
+  },
+  "third-party-dom-mutation.injected-node": {
+    explanation: "A {tag} was injected by a third-party script or browser extension (ads, consent, analytics, chat) after the server render. It is not part of your app's hydration, so this is usually harmless noise.",
+    suggestion: 'If React warns about it, add `suppressHydrationWarning` to the nearest server-rendered wrapper, or load the third-party script after hydration (e.g. Next.js `<Script strategy="afterInteractive">`).'
+  },
+  "attribute-mismatch.class": {
+    explanation: (p) => [
+      "The ",
+      code("class"),
+      " differs between server and client",
+      ...classDetail(p, {
+        added: "added on client: ",
+        removed: "removed on client: ",
+        listSeparator: ", ",
+        partSeparator: "; ",
+        open: " (",
+        close: ")"
+      }),
+      ". A class was applied conditionally on the client \u2014 commonly a viewport, media-query, theme, or feature-flag check that runs during the first render."
+    ],
+    suggestion: "Render the same className on the server and the first client paint. Move client-only conditions into `useEffect`/a mounted flag, or drive the visual change with CSS media queries instead of a JS class toggle."
+  },
+  "attribute-mismatch.style": {
+    explanation: "The inline `style` differs between server and client \u2014 an inline style was computed from client-only state (viewport size, theme, scroll position) during render.",
+    suggestion: "Compute the style after mount (`useEffect`) so the first client render matches the server, or move it to a CSS class / media query."
+  },
+  "attribute-mismatch.generic": {
+    explanation: "The `{attribute}` attribute differs between server (`{server}`) and client (`{client}`) \u2014 its value was derived from something that differs between the server and the first client render.",
+    suggestion: "Make the attribute deterministic across server and client, or set it after mount so the first client render matches the server HTML."
+  },
+  unknown: {
+    explanation: "A hydration mismatch was detected but could not be matched to a known cause. Inspect the server vs client values above.",
+    suggestion: "Compare the server and client values. Common causes are non-deterministic values, dates/locales, and browser-only APIs used during render."
+  },
+  "unknown.no-location": {
+    explanation: "React reported that hydration failed but did not say which node differed, and the DOM diff found no difference to point at.",
+    suggestion: "Make sure `<HydrationSnapshotScript>` (or the manual snapshot script) is in `<head>` so the DOM diff can locate the node, and read React's full warning in the browser console."
+  }
+};
+function describe(id, params = {}, catalog = EN_MESSAGES) {
+  const entry = catalog[id];
+  return {
+    messageId: id,
+    ...Object.keys(params).length ? { params } : {},
+    explanation: plainText(renderMessage(entry.explanation, params)),
+    suggestion: plainText(renderMessage(entry.suggestion, params))
+  };
+}
+
 // src/core/classify/rules.ts
 var DOCS_BASE = "https://github.com/razan-aboushi/why-hydration#cause-";
 function docs(category) {
@@ -548,8 +705,7 @@ var nonDeterministic = (d) => {
   return {
     category: "non-deterministic-value",
     confidence: 0.9,
-    explanation: "The server and client rendered different random-looking values (an id, token, or Math.random() output). Anything non-deterministic in render produces a different value on each side.",
-    suggestion: "Use React `useId()` for ids. For random values, generate them after mount (in `useEffect`) or pass a value down from the server so both sides agree. Never call `Math.random()`/`crypto` during render.",
+    ...describe("non-deterministic-value"),
     docsUrl: docs("non-deterministic-value")
   };
 };
@@ -567,8 +723,7 @@ var dateTime = (d) => {
   return {
     category: "date-time",
     confidence: smallDelta || bothTimes ? 0.85 : 0.7,
-    explanation: "The values are dates/times that differ between server render and client render \u2014 the clock moved (or the timezone differs) between the two environments.",
-    suggestion: "Render the current time after mount, or pass a single server timestamp down and format it identically on both sides. Pin an explicit timezone when formatting.",
+    ...describe("date-time"),
     docsUrl: docs("date-time")
   };
 };
@@ -580,8 +735,7 @@ var localeFormat = (d) => {
     return {
       category: "locale-format",
       confidence: 0.88,
-      explanation: "The values differ only by invisible bidirectional control marks (LRM/RLM/isolates). `Intl` adds these around numbers and dates in RTL locales, and different ICU versions \u2014 Node vs the browser \u2014 emit different ones for the same input.",
-      suggestion: "Format the value in one place and pass the string down, or pin the same locale and timezone on both sides. If the marks are harmless, add `suppressHydrationWarning` to the element.",
+      ...describe("locale-format.bidi"),
       docsUrl: docs("locale-format")
     };
   }
@@ -590,8 +744,7 @@ var localeFormat = (d) => {
     return {
       category: "locale-format",
       confidence: 0.92,
-      explanation: "The same value was formatted with different digit scripts (Arabic-Indic \u0660\u0661\u0662 vs Latin 012). The server and client resolved to different locales.",
-      suggestion: "Pass an explicit `locale` (and timezone) to `Intl.NumberFormat` / `toLocaleString` on both server and client, or format the value after mount so only the client locale is ever used.",
+      ...describe("locale-format.script"),
       docsUrl: docs("locale-format")
     };
   }
@@ -599,8 +752,7 @@ var localeFormat = (d) => {
     return {
       category: "locale-format",
       confidence: 0.82,
-      explanation: "The same number was formatted with different grouping/decimal separators between server and client (e.g. 1,234.56 vs 1.234,56).",
-      suggestion: "Pass an explicit locale to `Intl.NumberFormat`/`toLocaleString` on both sides so the separators match.",
+      ...describe("locale-format.separators"),
       docsUrl: docs("locale-format")
     };
   }
@@ -608,8 +760,7 @@ var localeFormat = (d) => {
     return {
       category: "locale-format",
       confidence: 0.75,
-      explanation: "The same date was rendered in a different field order (MM/DD vs DD/MM) between server and client.",
-      suggestion: "Format dates with an explicit locale and timezone via `Intl` on both sides.",
+      ...describe("locale-format.date-order"),
       docsUrl: docs("locale-format")
     };
   }
@@ -623,8 +774,7 @@ var browserOnlyApi = (d) => {
   return {
     category: "browser-only-api",
     confidence: 0.75,
-    explanation: "The client rendered content the server left empty \u2014 the signature of reading a browser-only API (`window`, `document`, `localStorage`, `navigator`, `matchMedia`) during render.",
-    suggestion: "Gate browser-only reads behind a mounted flag or `useEffect`, or use `useSyncExternalStore` with a server snapshot so the first client render matches the server.",
+    ...describe("browser-only-api"),
     docsUrl: docs("browser-only-api")
   };
 };
@@ -638,8 +788,7 @@ var viewportBranching = (d) => {
   return {
     category: "viewport-branching",
     confidence: 0.6,
-    explanation: "A whole subtree was added, removed, or swapped between server and client \u2014 typically a JavaScript width/viewport check that branches the tree at first render.",
-    suggestion: "Render both branches and switch between them with CSS media queries at first paint instead of branching in JavaScript, or defer the JS-driven branch until after mount.",
+    ...describe("viewport-branching"),
     docsUrl: docs("viewport-branching")
   };
 };
@@ -650,8 +799,7 @@ var invalidNesting = (d) => {
   return {
     category: "invalid-html-nesting",
     confidence: byMessage ? 0.9 : 0.72,
-    explanation: "A node was moved or ejected because the markup is invalid HTML (e.g. a `<div>` inside a `<p>`, or nested `<a>`). The browser repairs the server DOM, so it no longer matches what React expects.",
-    suggestion: "Fix the markup validity: block elements cannot live inside `<p>`, anchors cannot nest, etc. Replace the invalid parent with a `<div>` or restructure the tree.",
+    ...describe("invalid-html-nesting"),
     docsUrl: docs("invalid-html-nesting")
   };
 };
@@ -664,8 +812,7 @@ var whitespaceMinification = (d) => {
   return {
     category: "whitespace-minification",
     confidence: 0.7,
-    explanation: "The mismatch is whitespace-only \u2014 the text is identical apart from spaces/newlines. An HTML minifier likely collapsed whitespace around the hydration root differently from React.",
-    suggestion: "Check your HTML minifier settings (e.g. `conservativeCollapse`) around the app root, or avoid minifying whitespace inside hydrated markup.",
+    ...describe("whitespace-minification"),
     docsUrl: docs("whitespace-minification")
   };
 };
@@ -675,8 +822,9 @@ var thirdPartyDomMutation = (d) => {
       return {
         category: "third-party-dom-mutation",
         confidence: 0.88,
-        explanation: `The attribute \`${d.attribute}\` was injected by a browser extension or third-party script (e.g. Grammarly, ColorZilla) before hydration, so the client DOM no longer matches the server.`,
-        suggestion: "This is usually harmless. Add `suppressHydrationWarning` to the affected element, or defer third-party script init until after hydration.",
+        ...describe("third-party-dom-mutation.extension-attribute", {
+          attribute: d.attribute
+        }),
         docsUrl: docs("third-party-dom-mutation")
       };
     }
@@ -686,8 +834,9 @@ var thirdPartyDomMutation = (d) => {
       return {
         category: "third-party-dom-mutation",
         confidence: 0.6,
-        explanation: `An attribute (\`${d.attribute}\`) appeared on a root element that the server never sent \u2014 a hallmark of an extension or early third-party script mutating the DOM.`,
-        suggestion: "Add `suppressHydrationWarning` to the root element, or defer the third-party script until after hydration.",
+        ...describe("third-party-dom-mutation.root-attribute", {
+          attribute: d.attribute
+        }),
         docsUrl: docs("third-party-dom-mutation")
       };
     }
@@ -697,8 +846,9 @@ var thirdPartyDomMutation = (d) => {
     return {
       category: "third-party-dom-mutation",
       confidence: 0.7,
-      explanation: `A <${tag}> was injected by a third-party script or browser extension (ads, consent, analytics, chat) after the server render. It is not part of your app's hydration, so this is usually harmless noise.`,
-      suggestion: 'If React warns about it, add `suppressHydrationWarning` to the nearest server-rendered wrapper, or load the third-party script after hydration (e.g. Next.js `<Script strategy="afterInteractive">`).',
+      ...describe("third-party-dom-mutation.injected-node", {
+        tag: `<${tag}>`
+      }),
       docsUrl: docs("third-party-dom-mutation")
     };
   }
@@ -714,15 +864,10 @@ var attributeMismatch = (d) => {
     const clientSet = new Set(client.split(/\s+/).filter(Boolean));
     const added = [...clientSet].filter((c) => !serverSet.has(c));
     const removed = [...serverSet].filter((c) => !clientSet.has(c));
-    const parts = [];
-    if (added.length) parts.push(`added on client: ${added.join(", ")}`);
-    if (removed.length) parts.push(`removed on client: ${removed.join(", ")}`);
-    const detail = parts.length ? ` (${parts.join("; ")})` : "";
     return {
       category: "attribute-mismatch",
       confidence: 0.8,
-      explanation: `The \`class\` differs between server and client${detail}. A class was applied conditionally on the client \u2014 commonly a viewport, media-query, theme, or feature-flag check that runs during the first render.`,
-      suggestion: "Render the same className on the server and the first client paint. Move client-only conditions into `useEffect`/a mounted flag, or drive the visual change with CSS media queries instead of a JS class toggle.",
+      ...describe("attribute-mismatch.class", { added, removed }),
       docsUrl: docs("attribute-mismatch")
     };
   }
@@ -730,16 +875,18 @@ var attributeMismatch = (d) => {
     return {
       category: "attribute-mismatch",
       confidence: 0.75,
-      explanation: "The inline `style` differs between server and client \u2014 an inline style was computed from client-only state (viewport size, theme, scroll position) during render.",
-      suggestion: "Compute the style after mount (`useEffect`) so the first client render matches the server, or move it to a CSS class / media query.",
+      ...describe("attribute-mismatch.style"),
       docsUrl: docs("attribute-mismatch")
     };
   }
   return {
     category: "attribute-mismatch",
     confidence: 0.6,
-    explanation: `The \`${d.attribute}\` attribute differs between server (\`${server}\`) and client (\`${client}\`) \u2014 its value was derived from something that differs between the server and the first client render.`,
-    suggestion: "Make the attribute deterministic across server and client, or set it after mount so the first client render matches the server HTML.",
+    ...describe("attribute-mismatch.generic", {
+      attribute: d.attribute,
+      server,
+      client
+    }),
     docsUrl: docs("attribute-mismatch")
   };
 };
@@ -761,13 +908,21 @@ var BUILT_IN_RULES = [
 var UNKNOWN_CAUSE = {
   category: "unknown",
   confidence: 0,
-  explanation: "A hydration mismatch was detected but could not be matched to a known cause. Inspect the server vs client values above.",
-  suggestion: "Compare the server and client values. Common causes are non-deterministic values, dates/locales, and browser-only APIs used during render.",
+  ...describe("unknown"),
+  docsUrl: docs("unknown")
+};
+var UNKNOWN_NO_LOCATION_CAUSE = {
+  category: "unknown",
+  confidence: 0,
+  ...describe("unknown.no-location"),
   docsUrl: docs("unknown")
 };
 
 // src/core/classify/index.ts
 var CONFIDENCE_THRESHOLD = 0.5;
+function isLocationless(d) {
+  return d.server == null && d.client == null && !d.tagName && !d.attribute;
+}
 function classify(divergence, options = {}) {
   const threshold = options.threshold ?? CONFIDENCE_THRESHOLD;
   const rules = [
@@ -785,7 +940,7 @@ function classify(divergence, options = {}) {
       return result;
     }
   }
-  return UNKNOWN_CAUSE;
+  return isLocationless(divergence) ? UNKNOWN_NO_LOCATION_CAUSE : UNKNOWN_CAUSE;
 }
 
 // src/core/report.ts
@@ -794,12 +949,12 @@ function nextId() {
   counter += 1;
   return `wh_${Date.now().toString(36)}_${counter}`;
 }
-function truncate(value, max = 300) {
-  if (value == null) return null;
-  if (value.length <= max) return value;
-  const last = value.charCodeAt(max - 1);
+function truncate(value2, max = 300) {
+  if (value2 == null) return null;
+  if (value2.length <= max) return value2;
+  const last = value2.charCodeAt(max - 1);
   const end = last >= 55296 && last <= 56319 ? max - 1 : max;
-  return `${value.slice(0, end)}\u2026`;
+  return `${value2.slice(0, end)}\u2026`;
 }
 function buildReport(divergence, cause, context = {}) {
   return {
@@ -859,16 +1014,20 @@ var ReportCollector = class {
   getReports() {
     return this.reports;
   }
+  /** The cause this collector would assign — same rules, same threshold. */
+  classify(divergence) {
+    return classify(divergence, {
+      extra: this.options.extra,
+      threshold: this.options.threshold
+    });
+  }
   get isFull() {
     return this.reports.length >= this.maxReports;
   }
   report(divergence, context = {}) {
     if (this.isFull) return null;
     if (this.options.ignore?.(divergence)) return null;
-    const cause = classify(divergence, {
-      extra: this.options.extra,
-      threshold: this.options.threshold
-    });
+    const cause = this.classify(divergence);
     const report = buildReport(divergence, cause, context);
     const signature = signatureOf(report);
     if (this.seen.has(signature)) return null;
@@ -918,11 +1077,19 @@ function extractComponentFromMessage(message) {
   }
   return names.length ? names[names.length - 1] : void 0;
 }
+function diffLines(message) {
+  const lines = message.split("\n");
+  let link = -1;
+  lines.forEach((line, i) => {
+    if (/react\.dev\/link\/hydration-mismatch/.test(line)) link = i;
+  });
+  return link >= 0 ? lines.slice(link + 1) : lines;
+}
 var ATTR_RE = /^([\w:-]+)=(?:"([\s\S]*)"|\{([\s\S]*)\})$/;
 function parseModernDiff(message) {
   const plus = [];
   const minus = [];
-  for (const raw of message.split("\n")) {
+  for (const raw of diffLines(message)) {
     const line = raw.trim();
     const p = /^\+\s+(.+)$/.exec(line);
     const mn = /^-\s+(.+)$/.exec(line);
@@ -1054,7 +1221,7 @@ function parseAllHydrationDivergences(message) {
   };
   const plus = [];
   const minus = [];
-  for (const raw of message.split("\n")) {
+  for (const raw of diffLines(message)) {
     const line = raw.trim();
     const p = /^\+\s+(.+)$/.exec(line);
     const mn = /^-\s+(.+)$/.exec(line);
@@ -1137,8 +1304,13 @@ function serverTreeFor(root, html) {
   serverTrees.set(root, { html, tree });
   return tree;
 }
-function reportFromMessage(message, collector, context = {}) {
-  const divergences = parseAllHydrationDivergences(message);
+function reportFromMessage(message, collector, context = {}, options = {}) {
+  const mode = options.locationless ?? "include";
+  const divergences = parseAllHydrationDivergences(message).filter((d) => {
+    if (mode === "include") return true;
+    const bare = isLocationless(d) && collector.classify(d).messageId === "unknown.no-location";
+    return mode === "skip" ? !bare : bare;
+  });
   const component = extractComponentFromMessage(message) ?? context.component;
   let reported = 0;
   for (const divergence of divergences) {
@@ -1155,19 +1327,28 @@ function reportFromMessage(message, collector, context = {}) {
 
 exports.BUILT_IN_RULES = BUILT_IN_RULES;
 exports.CONFIDENCE_THRESHOLD = CONFIDENCE_THRESHOLD;
+exports.EN_MESSAGES = EN_MESSAGES;
 exports.ReportCollector = ReportCollector;
 exports.UNKNOWN_CAUSE = UNKNOWN_CAUSE;
+exports.UNKNOWN_NO_LOCATION_CAUSE = UNKNOWN_NO_LOCATION_CAUSE;
 exports.buildReport = buildReport;
+exports.classDetail = classDetail;
 exports.classify = classify;
+exports.code = code;
 exports.diffSnapshotAgainstDom = diffSnapshotAgainstDom;
 exports.diffTrees = diffTrees;
 exports.formatConsoleArgs = formatConsoleArgs;
 exports.inspectRoot = inspectRoot;
 exports.isDev = isDev;
 exports.isHydrationMessage = isHydrationMessage;
+exports.isInternalComponent = isInternalComponent;
+exports.isLocationless = isLocationless;
+exports.param = param;
 exports.parseHydrationMessage = parseHydrationMessage;
 exports.parseServerHtml = parseServerHtml;
+exports.plainText = plainText;
+exports.renderMessage = renderMessage;
 exports.reportFromMessage = reportFromMessage;
 exports.signatureOf = signatureOf;
-//# sourceMappingURL=chunk-AT6A77X3.cjs.map
-//# sourceMappingURL=chunk-AT6A77X3.cjs.map
+//# sourceMappingURL=chunk-KX6G7I4Y.cjs.map
+//# sourceMappingURL=chunk-KX6G7I4Y.cjs.map