why-hydration 0.1.4 → 0.2.0

package/dist/{chunk-WQLUD25W.js → chunk-3OAI2ZHY.js}

@@ -1,12 +1,20 @@
-import { getServerHtmlForRoot } from './chunk-FV3PEJQE.js';
+import { getServerHtmlForRoot } from './chunk-XIM33ZGB.js';
 
 // src/core/env.ts
-var isDev = typeof process !== "undefined" && process.env != null && process.env.NODE_ENV !== "production";
+function readNodeEnv() {
+  try {
+    return process.env.NODE_ENV;
+  } catch {
+    return void 0;
+  }
+}
+var isDev = readNodeEnv() !== "production";
 
 // src/core/diff.ts
 var IGNORED_ATTRIBUTES = /* @__PURE__ */ new Set(["data-reactroot"]);
 function parseServerHtml(html, rootTagName) {
-  const container = document.createElement(rootTagName || "div");
+  const doc = document.implementation.createHTMLDocument("");
+  const container = doc.createElement(rootTagName || "div");
   container.innerHTML = html;
   return container;
 }
@@ -157,21 +165,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);
@@ -181,7 +189,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) {
@@ -351,8 +359,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]/;
-function isRandomLike(value) {
-  const v = value.trim();
+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(value2) {
+  return stripBidiControls(value2).replace(/[٠-٩۰-۹٫٬]/g, (ch) => {
+    if (ch === "\u066B") return ".";
+    if (ch === "\u066C") return ",";
+    const code2 = ch.charCodeAt(0);
+    const zero = code2 >= 1776 ? 1776 : 1632;
+    return String(code2 - zero);
+  });
+}
+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;
@@ -361,16 +387,26 @@ function isRandomLike(value) {
   if (NANOID_RE.test(v) && /[A-Za-z]/.test(v) && /[0-9]/.test(v)) return true;
   return false;
 }
-function looksLikeTime(value) {
-  return /\b\d{1,2}:\d{2}(?::\d{2})?(?:\s?[AaPp][Mm])?\b/.test(value.trim());
+function looksLikeTime(value2) {
+  return /\b\d{1,2}:\d{2}(?::\d{2})?(?:\s?[AaPp][Mm])?\b/.test(
+    normalizeNumerals(value2).trim()
+  );
+}
+var ISO_DATE = /^\d{4}-\d{1,2}(?:-\d{1,2})?(?:[T ]\d{1,2}:\d{2}(?::\d{2})?)?/;
+var NUMERIC_DATE = /^\d{1,4}[/.-]\d{1,2}[/.-]\d{1,4}$/;
+var TIME_OF_DAY = /^\d{1,2}:\d{2}(?::\d{2})?(?:\s?[AaPp]\.?[Mm]\.?)?$/;
+var MONTH_NAME = /\b(?:jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)[a-z]*\b/i;
+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);
     return v.length === 10 ? n * 1e3 : n;
   }
+  if (!looksLikeDate(v)) return null;
   const parsed = Date.parse(v);
   if (!Number.isNaN(parsed)) return parsed;
   if (looksLikeTime(v)) {
@@ -379,23 +415,23 @@ 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) {
-  const at = a.trim();
-  const bt = b.trim();
+  const at = normalizeNumerals(a).trim();
+  const bt = normalizeNumerals(b).trim();
   if (!NUMERIC_LIKE.test(at) || !NUMERIC_LIKE.test(bt)) return false;
   const digitsOnly = (s) => s.replace(/\D/g, "");
   const da = digitsOnly(at);
   const db = digitsOnly(bt);
   if (!da || da !== db) return false;
   const hasSep = (s) => /[.,\s\u00a0\u2009]/.test(s);
-  return (hasSep(at) || hasSep(bt)) && at !== bt;
+  return (hasSep(at) || hasSep(bt)) && a.trim() !== b.trim();
 }
 var CONTENT_ATTRIBUTES = /* @__PURE__ */ new Set([
   "value",
@@ -419,9 +455,10 @@ function looksLikeThirdPartyNode(html, tagName) {
   if (!h) return false;
   return THIRD_PARTY_MARKERS.test(h) || h.includes("about:blank");
 }
+var DATE_PARTS_RE = /^(\d{1,4})[/.-](\d{1,2})[/.-](\d{1,4})$/;
 function isSameDateDifferentOrder(a, b) {
-  const partsA = a.trim().match(/^(\d{1,4})[/.-](\d{1,2})[/.-](\d{1,4})$/);
-  const partsB = b.trim().match(/^(\d{1,4})[/.-](\d{1,2})[/.-](\d{1,4})$/);
+  const partsA = normalizeNumerals(a).trim().match(DATE_PARTS_RE);
+  const partsB = normalizeNumerals(b).trim().match(DATE_PARTS_RE);
   if (!partsA || !partsB) return false;
   const setA = [partsA[1], partsA[2], partsA[3]].sort().join("|");
   const setB = [partsB[1], partsB[2], partsB[3]].sort().join("|");
@@ -487,6 +524,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) {
@@ -509,8 +703,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")
   };
 };
@@ -528,8 +721,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")
   };
 };
@@ -537,13 +729,20 @@ var localeFormat = (d) => {
   if (!isValueDivergence(d)) return null;
   if (!bothDiffer(d)) return null;
   const { server, client } = d;
+  if (differsOnlyByBidiControls(server, client)) {
+    return {
+      category: "locale-format",
+      confidence: 0.88,
+      ...describe("locale-format.bidi"),
+      docsUrl: docs("locale-format")
+    };
+  }
   const scriptMismatch = hasArabicIndicDigits(server) && hasLatinDigits(client) || hasLatinDigits(server) && hasArabicIndicDigits(client);
   if (scriptMismatch) {
     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")
     };
   }
@@ -551,8 +750,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")
     };
   }
@@ -560,8 +758,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")
     };
   }
@@ -575,8 +772,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")
   };
 };
@@ -586,11 +782,11 @@ var viewportBranching = (d) => {
   if (isInvalidNesting(d.parentTagName, d.tagName) || messageIndicatesInvalidNesting(d.reactMessage)) {
     return null;
   }
+  if (d.server == null && d.client == null && !d.tagName) return null;
   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")
   };
 };
@@ -601,8 +797,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")
   };
 };
@@ -615,8 +810,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")
   };
 };
@@ -626,18 +820,21 @@ 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")
       };
     }
-    const atRoot = /^(html|body)\b/.test(d.path) && d.server == null;
+    const el = d.element;
+    const atRoot = d.server == null && el != null && /^(?:HTML|BODY)$/.test(el.tagName);
     if (atRoot) {
       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")
       };
     }
@@ -647,8 +844,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")
     };
   }
@@ -664,15 +862,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")
     };
   }
@@ -680,16 +873,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")
   };
 };
@@ -711,13 +906,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 = [
@@ -735,7 +938,7 @@ function classify(divergence, options = {}) {
       return result;
     }
   }
-  return UNKNOWN_CAUSE;
+  return isLocationless(divergence) ? UNKNOWN_NO_LOCATION_CAUSE : UNKNOWN_CAUSE;
 }
 
 // src/core/report.ts
@@ -744,9 +947,12 @@ function nextId() {
   counter += 1;
   return `wh_${Date.now().toString(36)}_${counter}`;
 }
-function truncate(value, max = 300) {
-  if (value == null) return null;
-  return value.length > max ? `${value.slice(0, max)}\u2026` : value;
+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 `${value2.slice(0, end)}\u2026`;
 }
 function buildReport(divergence, cause, context = {}) {
   return {
@@ -784,34 +990,48 @@ var ReportCollector = class {
     this.options = options;
     this.maxReports = options.maxReports ?? 25;
   }
-  addSink(sink) {
+  /**
+   * Register a sink. Pass `replay` for sinks that render *state* (the overlay)
+   * rather than react to *events* (`onReport`, the console): they need the
+   * reports collected before they were attached, which matters when a sink is
+   * re-attached after a stop/start cycle.
+   */
+  addSink(sink, options = {}) {
     this.sinks.add(sink);
+    if (options.replay) {
+      for (const report of this.reports) this.emit(sink, report);
+    }
     return () => this.sinks.delete(sink);
   }
+  emit(sink, report) {
+    try {
+      sink(report);
+    } catch {
+    }
+  }
   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;
     this.seen.add(signature);
     this.reports.push(report);
-    for (const sink of this.sinks) {
-      try {
-        sink(report);
-      } catch {
-      }
-    }
+    for (const sink of this.sinks) this.emit(sink, report);
     return report;
   }
   reset() {
@@ -855,11 +1075,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);
@@ -985,45 +1213,47 @@ function parseHydrationMessage(message) {
 }
 function parseAllHydrationDivergences(message) {
   if (!isHydrationMessage(message)) return [];
+  const fallback = () => {
+    const single = parseHydrationMessage(message);
+    return single ? [single] : [];
+  };
   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);
     if (p && p[1]) plus.push(p[1].trim());
     else if (mn && mn[1]) minus.push(mn[1].trim());
   }
-  if (plus.length === 0 && minus.length === 0) {
-    const single = parseHydrationMessage(message);
-    return single ? [single] : [];
-  }
+  if (plus.length === 0 && minus.length === 0) return fallback();
   const out = [];
+  const attrPlus = plus.filter((p) => ATTR_RE.test(p));
   const attrMinus = minus.filter((m) => ATTR_RE.test(m));
   const usedMinus = /* @__PURE__ */ new Set();
-  for (const p of plus) {
-    const pm = ATTR_RE.exec(p);
-    if (!pm) continue;
-    const name = pm[1];
-    const clientValue = pm[2] ?? pm[3] ?? "";
-    const idx = attrMinus.findIndex((m, k) => {
-      if (usedMinus.has(k)) return false;
-      const parsed = ATTR_RE.exec(m);
-      return parsed?.[1] === name;
-    });
-    if (idx >= 0) {
-      usedMinus.add(idx);
-      const parsed = ATTR_RE.exec(attrMinus[idx]);
-      out.push({
-        kind: "attribute",
-        path: "body",
-        attribute: name,
-        server: parsed ? parsed[2] ?? parsed[3] ?? "" : "",
-        client: clientValue,
-        reactMessage: message
-      });
-    }
+  const attribute = (name, server, client) => ({
+    kind: "attribute",
+    path: "body",
+    attribute: name,
+    server,
+    client,
+    reactMessage: message
+  });
+  for (const line of attrPlus) {
+    const name = attrName(line);
+    if (!name) continue;
+    const idx = attrMinus.findIndex(
+      (m, k) => !usedMinus.has(k) && attrName(m) === name
+    );
+    if (idx >= 0) usedMinus.add(idx);
+    const server = idx >= 0 ? attrValue(attrMinus[idx]) : null;
+    out.push(attribute(name, server, attrValue(line)));
   }
+  attrMinus.forEach((line, k) => {
+    if (usedMinus.has(k)) return;
+    const name = attrName(line);
+    if (name) out.push(attribute(name, attrValue(line), null));
+  });
   const textPlus = plus.filter((p) => !ATTR_RE.test(p));
   const textMinus = minus.filter((m) => !ATTR_RE.test(m));
   const len = Math.max(textPlus.length, textMinus.length);
@@ -1031,22 +1261,32 @@ function parseAllHydrationDivergences(message) {
     const client = textPlus[i] ?? null;
     const server = textMinus[i] ?? null;
     if (client !== null || server !== null) {
-      out.push({ kind: "text", path: "body", server, client, reactMessage: message });
+      out.push({
+        kind: "text",
+        path: "body",
+        server,
+        client,
+        reactMessage: message
+      });
     }
   }
-  return out.length ? out : parseHydrationMessage(message) ? [parseHydrationMessage(message)] : [];
+  return out.length ? out : fallback();
+}
+function attrName(line) {
+  return ATTR_RE.exec(line)?.[1];
+}
+function attrValue(line) {
+  const parsed = ATTR_RE.exec(line);
+  return parsed ? parsed[2] ?? parsed[3] ?? "" : "";
 }
 
 // src/core/inspect.ts
 function inspectRoot(root, collector, context = {}, enrich) {
   const serverHtml = getServerHtmlForRoot(root);
   if (serverHtml == null) return 0;
-  const divergences = collectSnapshotAgainstDom(serverHtml, root);
+  const divergences = collectDivergences(serverTreeFor(root, serverHtml), root);
   let reported = 0;
   for (const divergence of divergences) {
-    if (context.reactMessage && !divergence.reactMessage) {
-      divergence.reactMessage = context.reactMessage;
-    }
     const enriched = enrich ? enrich(divergence) : {};
     if (collector.report(divergence, { ...context, ...enriched }) != null) {
       reported += 1;
@@ -1054,18 +1294,35 @@ function inspectRoot(root, collector, context = {}, enrich) {
   }
   return reported;
 }
-function reportFromMessage(message, collector, context = {}) {
-  const divergences = parseAllHydrationDivergences(message);
+var serverTrees = /* @__PURE__ */ new WeakMap();
+function serverTreeFor(root, html) {
+  const cached = serverTrees.get(root);
+  if (cached && cached.html === html) return cached.tree;
+  const tree = parseServerHtml(html, root.tagName);
+  serverTrees.set(root, { html, tree });
+  return tree;
+}
+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) {
-    if (collector.report(divergence, { ...context, component, reactMessage: message }) != null) {
+    if (collector.report(divergence, {
+      ...context,
+      component,
+      reactMessage: message
+    }) != null) {
       reported += 1;
     }
   }
   return reported;
 }
 
-export { BUILT_IN_RULES, CONFIDENCE_THRESHOLD, ReportCollector, UNKNOWN_CAUSE, buildReport, classify, diffSnapshotAgainstDom, diffTrees, formatConsoleArgs, inspectRoot, isDev, isHydrationMessage, parseHydrationMessage, parseServerHtml, reportFromMessage, signatureOf };
-//# sourceMappingURL=chunk-WQLUD25W.js.map
-//# sourceMappingURL=chunk-WQLUD25W.js.map
+export { BUILT_IN_RULES, CONFIDENCE_THRESHOLD, EN_MESSAGES, ReportCollector, UNKNOWN_CAUSE, UNKNOWN_NO_LOCATION_CAUSE, buildReport, classDetail, classify, code, diffSnapshotAgainstDom, diffTrees, formatConsoleArgs, inspectRoot, isDev, isHydrationMessage, isInternalComponent, isLocationless, param, parseHydrationMessage, parseServerHtml, plainText, renderMessage, reportFromMessage, signatureOf };
+//# sourceMappingURL=chunk-3OAI2ZHY.js.map
+//# sourceMappingURL=chunk-3OAI2ZHY.js.map