why-hydration 0.1.1 → 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,14 +3,18 @@
 [![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
 
 **Tells you which component broke hydration, what differed, and how to fix it — in dev, with zero production cost.**
 
+A **React hydration error / hydration mismatch debugger** for **Next.js** (App
+Router & Pages Router), **Remix**, **Vite**, and any React SSR app. It points at
+the exact **component, file, and value** behind "Hydration failed because the
+server rendered HTML didn't match the client" — and tells you how to fix it.
+
 <p align="center">
-  <img src="docs/screenshots/overlay-hero.png" alt="why-hydration overlay showing three classified hydration mismatches" width="440">
+  <img src="docs/screenshots/overlay-hero.png" alt="why-hydration overlay showing classified React hydration mismatches in a Next.js app with component names" width="440">
 </p>
 
 React's hydration warnings tell you _that_ something mismatched, rarely _which
@@ -28,10 +32,13 @@ the client DOM, classifies the root cause, and hands you a specific fix.
                         or format the value after mount.
 ```
 
-- 🔍 **Where** — component (best-effort) + exact DOM node + selector path.
+- 🔍 **Where** — the **component name** (e.g. `<PriceTag>`) and **source file:line**,
+  read from React's own fiber/diff, plus the exact DOM node + selector path.
 - 🔀 **What** — server value vs client value, side by side.
 - 🧠 **Why** — the cause, classified into a known category with a confidence score.
 - 🛠️ **Fix** — a specific, actionable suggestion with a docs link.
+- 🧹 **Low noise** — skips third-party/extension injections (ads, consent, chat,
+  Grammarly) so you see _your_ bug, not their DOM.
 - 🫧 **Zero prod cost** — everything is gated on `process.env.NODE_ENV` and
   tree-shakes to a **no-op** (~0 B, size-budgeted in CI).
 - 🌐 **Arabic-first** — digit-script mismatches (٠١٢ vs 012) are a first-class cause.
@@ -156,6 +163,25 @@ A clean page with no mismatches shows **nothing** — no overlay, no logs.
 
 ---
 
+## When it detects (full load vs client navigation)
+
+Hydration mismatches happen **only during the initial server render + hydration**
+— i.e. a **full page load, refresh, or direct URL entry** to an SSR'd route.
+`why-hydration` detects those.
+
+**Client-side navigation** (Next.js `<Link>` / `router.push`, React Router) does
+**not** re-hydrate — the destination is rendered entirely on the client, so there
+is no server HTML to diverge from and **no hydration mismatch can occur**. This is
+React's design, not a limitation. To reproduce a mismatch on a specific route,
+**refresh that route** (or open its URL directly).
+
+Detection covers both React's console warning path and a real server-vs-client
+DOM diff, and re-checks across a short settling window (React applies client
+values to mismatched subtrees a few hundred ms after hydration), so time- and
+render-order-dependent mismatches are caught reliably.
+
+---
+
 ## Options
 
 ```tsx
@@ -311,6 +337,19 @@ early third-party script before hydration.
 third-party init to post-hydration.
 **Reference:** [React `suppressHydrationWarning`](https://react.dev/reference/react-dom/components/common#suppressing-unavoidable-hydration-mismatch-errors).
 
+<a id="cause-attribute-mismatch"></a>
+
+### attribute-mismatch
+
+A `class`, `style`, or other attribute differs between server and client — the
+report lists the exact tokens (e.g. _added on client: `forceHide`_). Usually a
+class/style applied by a client-only conditional (viewport, media query, theme,
+or feature flag) during the first render. React does **not** patch mismatched
+attributes, so `why-hydration` reads these from React's own diff.
+**Fix:** render the same attribute on the server and the first client paint —
+move the condition into `useEffect`/a mounted flag, or use CSS media queries.
+**Reference:** [React — different client/server content](https://react.dev/reference/react-dom/client/hydrateRoot#handling-different-client-and-server-content).
+
 <a id="cause-unknown"></a>
 
 ### unknown
@@ -388,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.