why-hydration 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+## 0.1.3
+
+Stability + accuracy overhaul from running on a large production Next.js app.
+Detection is now **deterministic** and reports **every** mismatch at once.
+
+- **LCS child alignment.** Children are matched by an LCS (tag+id) instead of by
+  index, so a node the client injects mid-tree (react-toastify's
+  `<section class="Toastify">`, a portal, a modal, an ad) is treated as an
+  insertion — it no longer shifts every sibling and cascade into a different set
+  of false positives on each refresh. This makes results **consistent across
+  refreshes**.
+- **Collect all mismatches.** The diff now returns every divergence on the page
+  (deduped by value), so the overlay shows them together instead of one-per-
+  refresh. The panel is scrollable and shows a "↓ N issues — scroll to see all"
+  hint (with a ✕ close button) when there are more than fit.
+- **Skip client-injected containers** — toasts, modals, portals, overlays,
+  tooltips, consent banners, chat/analytics widgets (by class/role/`aria-live`)
+  are never reported and never mask a real mismatch.
+- **Skip pending Suspense fallbacks** — content inside a streaming `<!--$?-->`
+  boundary (server `Loading…` vs client content) is expected, not a mismatch.
+- **No duplicates** — value-based dedup means the same mismatch (e.g. two links
+  with the same conditional class) appears once.
+- **All class/style mismatches captured.** React can emit several changes in one
+  hydration message; the parser now extracts all of them (not just the first).
+- Adjacent delete+insert is coalesced into a single `structure` report.
+- License: removed MIT (now `UNLICENSED`); added the author's LinkedIn.
+
+## 0.1.2
+
+Accuracy overhaul from running on a large production Next.js app — fixes real
+false positives and misclassifications.
+
+- **New `attribute-mismatch` category.** A `class`/`style` difference (e.g. a
+  conditional `forceHide` class) is now reported correctly with the exact
+  changed tokens — previously misclassified as "locale-format" because the class
+  list contained digits.
+- **Component name + source file:line.** Reports now name the offending
+  component (e.g. `<PriceTag>`) and, where React exposes it, the source
+  `file:line`, read from React's fiber and its hydration diff.
+- **Modern React message parsing.** React 18.3+/19 print a JSX diff tree
+  (`+`/`-` lines) instead of "Prop X did not match"; the parser now understands
+  it and extracts the attribute/value and component. This is required because
+  React does **not** patch mismatched attributes, so the DOM diff alone can't
+  see them.
+- **Third-party noise is skipped.** Hidden ads/consent/analytics iframes (e.g.
+  Google Funding Choices `googlefcInactive`, `about:blank`) no longer produce
+  false "browser-only API" reports and no longer mask your real mismatch.
+- **Stricter locale detection** — number-format matching now requires actual
+  numeric values, so class lists / ids with digits no longer false-match.
+- **Reliable timing.** Detection re-checks across a short settling window
+  because React applies client values to mismatched subtrees a few hundred ms
+  after hydration; value-based dedup prevents double reports.
+- Docs: detection scope (full load vs client navigation), `attribute-mismatch`
+  category, refreshed screenshots showing component names.
+
+## 0.1.1
+
+Fixes found by end-to-end testing in a real Next.js app (App Router + Pages
+Router, React 18 & 19). **0.1.0 is broken in Next.js — use 0.1.1 or later.**
+
+- **`'use client'` directive** is now injected into the `react` and `next`
+  bundles. Without it, `<HydrationInspector>` crashed in a Server Component
+  layout (`useRef only works in Client Components`). `why-hydration/next` is now
+  client-only; import `HydrationSnapshotScript` from `why-hydration/next/script`.
+- **Diff skips framework comment markers** (React `<!--$-->`, RSC payload) that
+  were reported as false `viewport-branching` mismatches.
+- **Inline `style` is normalized through the CSSOM**, so the server snapshot and
+  the browser-normalized live DOM (`#hex` → `rgb()`, spacing) no longer produce
+  a false `unknown` mismatch.
+- **`typesVersions`** added so subpath types resolve under `moduleResolution:
+  "node"` (fixes `next build` type errors in apps using classic resolution).
+
+Verified live: locale-format, non-deterministic-value, date-time, and
+browser-only-api classify correctly in App Router and Pages Router; the tool is
+a zero-code no-op in a production `next build`.
+
+## 0.1.0
+
+Initial release.

package/README.md

@@ -3,7 +3,6 @@
 [![npm version](https://img.shields.io/npm/v/why-hydration.svg)](https://www.npmjs.com/package/why-hydration)
 [![npm downloads](https://img.shields.io/npm/dm/why-hydration.svg)](https://www.npmjs.com/package/why-hydration)
 [![minzipped size](https://img.shields.io/bundlephobia/minzip/why-hydration.svg)](https://bundlephobia.com/package/why-hydration)
-[![license: MIT](https://img.shields.io/npm/l/why-hydration.svg)](LICENSE)
 
 📦 **npm:** https://www.npmjs.com/package/why-hydration
 
@@ -428,14 +427,24 @@ field in `package.json` to match your URL.
 **Can I send reports to my logging?** Yes — pass `onReport`; you receive the full
 `HydrationReport`.
 
-**Does it slow my app down?** No. It's dev-only, runs the diff once after
-hydration (plus once per real React signal), and holds no standing observers.
+**Why do results now show all at once and stay the same on refresh?** The diff
+aligns children with an LCS and collects every mismatch deterministically, so
+injected nodes (toasts, portals, ads) can't shift the comparison and change the
+results between refreshes.
+
+**Does it slow my app down?** No. It's dev-only, diffs across a short settling
+window right after hydration (React applies client values a few hundred ms
+later), then stops — no standing observers.
 
 ## Contributing
 
 Adding a cause category is a self-contained change — see
 [CONTRIBUTING.md](CONTRIBUTING.md).
 
-## License
+## Author
+
+Built by **[Razan Aboushi](https://www.linkedin.com/in/razan-aboushi/)** ·
+[GitHub](https://github.com/razan-aboushi) ·
+[LinkedIn](https://www.linkedin.com/in/razan-aboushi/)
 
-[MIT](LICENSE) © [Razan Aboushi](https://github.com/razan-aboushi)
+© 2026 Razan Aboushi. All rights reserved.

package/dist/{chunk-AN3N7274.cjs → chunk-DSO337ME.cjs}

@@ -12,57 +12,84 @@ function parseServerHtml(html, rootTagName) {
   container.innerHTML = html;
   return container;
 }
-function diffTrees(serverRoot, clientRoot, basePath = tagPath(clientRoot)) {
-  return diffChildren(serverRoot, clientRoot, basePath);
+function collectDivergences(serverRoot, clientRoot, limit = 60) {
+  const out = [];
+  collectChildren(serverRoot, clientRoot, tagPath(clientRoot), out, limit);
+  return out;
 }
-function diffSnapshotAgainstDom(serverHtml, clientRoot) {
+function collectSnapshotAgainstDom(serverHtml, clientRoot, limit = 60) {
   const serverRoot = parseServerHtml(serverHtml, clientRoot.tagName);
-  return diffTrees(serverRoot, clientRoot);
+  return collectDivergences(serverRoot, clientRoot, limit);
+}
+function diffTrees(serverRoot, clientRoot) {
+  return collectDivergences(serverRoot, clientRoot, 1)[0] ?? null;
+}
+function diffSnapshotAgainstDom(serverHtml, clientRoot) {
+  return collectSnapshotAgainstDom(serverHtml, clientRoot, 1)[0] ?? null;
 }
-function diffChildren(serverParent, clientParent, parentPath) {
+function collectChildren(serverParent, clientParent, parentPath, out, limit) {
+  if (out.length >= limit) return;
   const serverChildren = meaningfulChildNodes(serverParent);
   const clientChildren = meaningfulChildNodes(clientParent);
-  const max = Math.max(serverChildren.length, clientChildren.length);
-  for (let i = 0; i < max; i++) {
-    const serverNode = serverChildren[i] ?? null;
-    const clientNode = clientChildren[i] ?? null;
-    const path = childPath(parentPath, clientNode ?? serverNode, i);
+  const parentPending = hasPendingSuspense(serverParent);
+  const parentTag = elementTag(clientParent);
+  const pairs = alignChildren(serverChildren, clientChildren);
+  let index = 0;
+  for (let k = 0; k < pairs.length; k++) {
+    if (out.length >= limit) return;
+    const [serverNode, clientNode] = pairs[k];
+    if (serverNode && !clientNode && k + 1 < pairs.length) {
+      const [nextServer, nextClient] = pairs[k + 1];
+      if (!nextServer && nextClient && !isInjectedContainer(nextClient)) {
+        const path2 = childPath(parentPath, nextClient, index);
+        index += 1;
+        k += 1;
+        out.push({
+          kind: "structure",
+          path: path2,
+          tagName: elementTag(nextClient),
+          parentTagName: parentTag,
+          server: serialize(serverNode),
+          client: serialize(nextClient),
+          element: asElement(nextClient)
+        });
+        continue;
+      }
+    }
+    const anchor = clientNode ?? serverNode;
+    if (!anchor) continue;
+    const path = childPath(parentPath, anchor, index);
+    index += 1;
     if (serverNode && !clientNode) {
-      return {
+      out.push({
         kind: "node-removed",
         path,
         tagName: elementTag(serverNode),
-        parentTagName: elementTag(clientParent),
+        parentTagName: parentTag,
         server: serialize(serverNode),
         client: null,
         element: asElement(clientParent)
-      };
-    }
-    if (!serverNode && clientNode) {
-      return {
+      });
+    } else if (!serverNode && clientNode) {
+      if (isInjectedContainer(clientNode)) continue;
+      if (clientNode.nodeType === Node.ELEMENT_NODE && parentPending) continue;
+      out.push({
         kind: "node-added",
         path,
         tagName: elementTag(clientNode),
-        parentTagName: elementTag(clientParent),
+        parentTagName: parentTag,
         server: null,
         client: serialize(clientNode),
         element: asElement(clientNode)
-      };
+      });
+    } else if (serverNode && clientNode) {
+      collectNode(serverNode, clientNode, path, parentTag, out, limit);
     }
-    if (!serverNode || !clientNode) continue;
-    const divergence = diffNode(
-      serverNode,
-      clientNode,
-      path,
-      elementTag(clientParent)
-    );
-    if (divergence) return divergence;
   }
-  return null;
 }
-function diffNode(serverNode, clientNode, path, parentTag) {
+function collectNode(serverNode, clientNode, path, parentTag, out, limit) {
   if (serverNode.nodeType !== clientNode.nodeType) {
-    return {
+    out.push({
       kind: "structure",
       path,
       tagName: elementTag(clientNode),
@@ -70,28 +97,29 @@ function diffNode(serverNode, clientNode, path, parentTag) {
       server: serialize(serverNode),
       client: serialize(clientNode),
       element: asElement(clientNode)
-    };
+    });
+    return;
   }
   if (serverNode.nodeType === Node.TEXT_NODE || serverNode.nodeType === Node.COMMENT_NODE) {
     const serverText = serverNode.textContent ?? "";
     const clientText = clientNode.textContent ?? "";
     if (serverText !== clientText) {
-      return {
+      out.push({
         kind: "text",
         path,
         parentTagName: parentTag,
         server: serverText,
         client: clientText,
         element: asElement(clientNode.parentNode)
-      };
+      });
     }
-    return null;
+    return;
   }
   if (serverNode.nodeType === Node.ELEMENT_NODE) {
     const serverEl = serverNode;
     const clientEl = clientNode;
     if (serverEl.tagName !== clientEl.tagName) {
-      return {
+      out.push({
         kind: "structure",
         path,
         tagName: clientEl.tagName,
@@ -99,13 +127,13 @@ function diffNode(serverNode, clientNode, path, parentTag) {
         server: serialize(serverEl),
         client: serialize(clientEl),
         element: clientEl
-      };
+      });
+      return;
     }
     const attrDivergence = diffAttributes(serverEl, clientEl, path, parentTag);
-    if (attrDivergence) return attrDivergence;
-    return diffChildren(serverEl, clientEl, path);
+    if (attrDivergence) out.push(attrDivergence);
+    collectChildren(serverEl, clientEl, path, out, limit);
   }
-  return null;
 }
 function diffAttributes(serverEl, clientEl, path, parentTag) {
   const names = /* @__PURE__ */ new Set();
@@ -157,6 +185,56 @@ function normalizeStyle(value) {
   }
   return value.split(";").map((s) => s.trim()).filter(Boolean).sort().join(";");
 }
+function nodeKey(node) {
+  if (node.nodeType === Node.ELEMENT_NODE) {
+    const el = node;
+    return el.id ? `${el.tagName}#${el.id}` : el.tagName;
+  }
+  if (node.nodeType === Node.TEXT_NODE) return "#text";
+  return "#other";
+}
+function alignChildren(server, client) {
+  const m = server.length;
+  const n = client.length;
+  if (m === 0 || n === 0 || m > 200 || n > 200 || m * n > 1e4) {
+    const pairs2 = [];
+    const max = Math.max(m, n);
+    for (let i2 = 0; i2 < max; i2++) {
+      pairs2.push([server[i2] ?? null, client[i2] ?? null]);
+    }
+    return pairs2;
+  }
+  const sk = server.map(nodeKey);
+  const ck = client.map(nodeKey);
+  const dp = Array.from(
+    { length: m + 1 },
+    () => new Array(n + 1).fill(0)
+  );
+  for (let i2 = m - 1; i2 >= 0; i2--) {
+    for (let j2 = n - 1; j2 >= 0; j2--) {
+      dp[i2][j2] = sk[i2] === ck[j2] ? dp[i2 + 1][j2 + 1] + 1 : Math.max(dp[i2 + 1][j2], dp[i2][j2 + 1]);
+    }
+  }
+  const pairs = [];
+  let i = 0;
+  let j = 0;
+  while (i < m && j < n) {
+    if (sk[i] === ck[j]) {
+      pairs.push([server[i], client[j]]);
+      i++;
+      j++;
+    } else if (dp[i + 1][j] >= dp[i][j + 1]) {
+      pairs.push([server[i], null]);
+      i++;
+    } else {
+      pairs.push([null, client[j]]);
+      j++;
+    }
+  }
+  while (i < m) pairs.push([server[i++], null]);
+  while (j < n) pairs.push([null, client[j++]]);
+  return pairs;
+}
 var NOISE_TAGS = /* @__PURE__ */ new Set([
   "SCRIPT",
   "STYLE",
@@ -165,6 +243,7 @@ var NOISE_TAGS = /* @__PURE__ */ new Set([
   "NOSCRIPT"
 ]);
 var TRACKER_MARKER = /googlefc|adsbygoogle|google_ads|googletag|__tcfapi|onetrust|optanon|cookiebot|usercentrics|didomi|quantcast|grammarly|gtm|hotjar|fullstory|intercom|drift|zendesk|livechat|tawk|hubspot|turnstile|recaptcha/i;
+var INJECTED_MARKER = /toastify|toast|modal|portal|overlay|backdrop|drawer|dialog|popover|popper|tooltip|snackbar|notification|consent|gdpr|cookie-?(?:banner|consent)|intercom|drift|crisp|tawk|zendesk|onetrust|usercentrics/i;
 function isThirdPartyNoiseElement(el) {
   const identity = `${el.getAttribute("name") ?? ""} ${el.id} ${typeof el.className === "string" ? el.className : ""}`;
   if (TRACKER_MARKER.test(identity)) return true;
@@ -176,6 +255,25 @@ function isThirdPartyNoiseElement(el) {
   }
   return false;
 }
+function isInjectedContainer(node) {
+  if (node.nodeType !== Node.ELEMENT_NODE) return false;
+  const el = node;
+  if (isNoiseElement(el)) return true;
+  const cls = typeof el.className === "string" ? el.className : "";
+  if (INJECTED_MARKER.test(`${el.id} ${cls}`)) return true;
+  if (el.hasAttribute("aria-live")) return true;
+  const role = el.getAttribute("role");
+  if (role && /^(dialog|alertdialog|tooltip|status|alert)$/.test(role.trim())) {
+    return true;
+  }
+  if (el.tagName.includes("-PORTAL") || el.tagName.includes("-OVERLAY")) {
+    return true;
+  }
+  for (const attr of Array.from(el.attributes)) {
+    if (/portal|radix|headlessui|floating-ui/i.test(attr.name)) return true;
+  }
+  return false;
+}
 function isNoiseElement(node) {
   if (node.nodeType !== Node.ELEMENT_NODE) return false;
   const el = node;
@@ -185,19 +283,38 @@ function isNoiseElement(node) {
   if (isThirdPartyNoiseElement(el)) return true;
   return false;
 }
+function hasPendingSuspense(parent) {
+  for (const n of Array.from(parent.childNodes)) {
+    if (n.nodeType === Node.COMMENT_NODE && (n.nodeValue ?? "").startsWith("$?")) {
+      return true;
+    }
+  }
+  return false;
+}
 function meaningfulChildNodes(parent) {
-  const children = Array.from(parent.childNodes);
-  const hasElement = children.some(
+  const raw = Array.from(parent.childNodes);
+  const hasElement = raw.some(
     (n) => n.nodeType === Node.ELEMENT_NODE && !isNoiseElement(n)
   );
-  return children.filter((node) => {
-    if (isNoiseElement(node)) return false;
-    if (node.nodeType === Node.COMMENT_NODE) return false;
-    if (node.nodeType !== Node.TEXT_NODE) return true;
+  const result = [];
+  const boundaryStack = [];
+  for (const node of raw) {
+    if (node.nodeType === Node.COMMENT_NODE) {
+      const data = node.nodeValue ?? "";
+      if (data === "$?" || data === "$" || data === "$!") boundaryStack.push(data);
+      else if (data === "/$") boundaryStack.pop();
+      continue;
+    }
+    if (boundaryStack.includes("$?")) continue;
+    if (isNoiseElement(node)) continue;
+    if (node.nodeType !== Node.TEXT_NODE) {
+      result.push(node);
+      continue;
+    }
     const text = node.textContent ?? "";
-    if (text.trim() !== "") return true;
-    return !hasElement;
-  });
+    if (text.trim() !== "" || !hasElement) result.push(node);
+  }
+  return result;
 }
 function serialize(node) {
   if (node.nodeType === Node.ELEMENT_NODE) {
@@ -217,8 +334,10 @@ function tagPath(el) {
 }
 function childPath(parentPath, node, index) {
   if (node.nodeType === Node.ELEMENT_NODE) {
-    const tag = node.tagName.toLowerCase();
-    return `${parentPath} > ${tag}:nth-child(${index + 1})`;
+    const el = node;
+    const tag = el.tagName.toLowerCase();
+    const id = el.id ? `#${el.id}` : "";
+    return `${parentPath} > ${tag}${id}:nth-child(${index + 1})`;
   }
   if (node.nodeType === Node.COMMENT_NODE) {
     return `${parentPath} > #comment[${index}]`;
@@ -866,27 +985,87 @@ function parseHydrationMessage(message) {
     reactMessage: message
   };
 }
+function parseAllHydrationDivergences(message) {
+  if (!isHydrationMessage(message)) return [];
+  const plus = [];
+  const minus = [];
+  for (const raw of message.split("\n")) {
+    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] : [];
+  }
+  const out = [];
+  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 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);
+  for (let i = 0; i < len; i++) {
+    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 });
+    }
+  }
+  return out.length ? out : parseHydrationMessage(message) ? [parseHydrationMessage(message)] : [];
+}
 
 // src/core/inspect.ts
 function inspectRoot(root, collector, context = {}, enrich) {
   const serverHtml = chunkOGQEPU7G_cjs.getServerHtmlForRoot(root);
-  if (serverHtml == null) return false;
-  const divergence = diffSnapshotAgainstDom(serverHtml, root);
-  if (!divergence) return false;
-  if (context.reactMessage && !divergence.reactMessage) {
-    divergence.reactMessage = context.reactMessage;
+  if (serverHtml == null) return 0;
+  const divergences = collectSnapshotAgainstDom(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;
+    }
   }
-  const enriched = enrich ? enrich(divergence) : {};
-  return collector.report(divergence, { ...context, ...enriched }) != null;
+  return reported;
 }
 function reportFromMessage(message, collector, context = {}) {
-  const divergence = parseHydrationMessage(message);
-  if (!divergence) return false;
-  return collector.report(divergence, {
-    ...context,
-    component: extractComponentFromMessage(message) ?? context.component,
-    reactMessage: message
-  }) != null;
+  const divergences = parseAllHydrationDivergences(message);
+  const component = extractComponentFromMessage(message) ?? context.component;
+  let reported = 0;
+  for (const divergence of divergences) {
+    if (collector.report(divergence, { ...context, component, reactMessage: message }) != null) {
+      reported += 1;
+    }
+  }
+  return reported;
 }
 
 exports.BUILT_IN_RULES = BUILT_IN_RULES;
@@ -905,5 +1084,5 @@ exports.parseHydrationMessage = parseHydrationMessage;
 exports.parseServerHtml = parseServerHtml;
 exports.reportFromMessage = reportFromMessage;
 exports.signatureOf = signatureOf;
-//# sourceMappingURL=chunk-AN3N7274.cjs.map
-//# sourceMappingURL=chunk-AN3N7274.cjs.map
+//# sourceMappingURL=chunk-DSO337ME.cjs.map
+//# sourceMappingURL=chunk-DSO337ME.cjs.map