npm - why-hydration - Versions diffs - 0.1.4 → 0.2.0 - Mend

why-hydration 0.1.4 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (39) hide show

package/CHANGELOG.md +108 -1
package/README.md +220 -33
package/dist/{chunk-WQLUD25W.js → chunk-3OAI2ZHY.js} +375 -118
package/dist/chunk-3OAI2ZHY.js.map +1 -0
package/dist/{chunk-OGQEPU7G.cjs → chunk-DXPTZB3Z.cjs} +44 -2
package/dist/chunk-DXPTZB3Z.cjs.map +1 -0
package/dist/{chunk-DSO337ME.cjs → chunk-KX6G7I4Y.cjs} +384 -118
package/dist/chunk-KX6G7I4Y.cjs.map +1 -0
package/dist/chunk-MK3TYHKM.js +966 -0
package/dist/chunk-MK3TYHKM.js.map +1 -0
package/dist/chunk-R7IWOK5M.cjs +989 -0
package/dist/chunk-R7IWOK5M.cjs.map +1 -0
package/dist/{chunk-FV3PEJQE.js → chunk-XIM33ZGB.js} +44 -2
package/dist/chunk-XIM33ZGB.js.map +1 -0
package/dist/index.cjs +32 -24
package/dist/index.d.cts +43 -5
package/dist/index.d.ts +43 -5
package/dist/index.js +2 -2
package/dist/next/index.cjs +5 -5
package/dist/next/index.d.cts +1 -1
package/dist/next/index.d.ts +1 -1
package/dist/next/index.js +3 -3
package/dist/next/script.cjs +2 -2
package/dist/next/script.js +1 -1
package/dist/react.cjs +5 -5
package/dist/react.d.cts +23 -3
package/dist/react.d.ts +23 -3
package/dist/react.js +3 -3
package/dist/{types-6wTih14e.d.cts → types-C14vcpBO.d.cts} +9 -0
package/dist/{types-6wTih14e.d.ts → types-C14vcpBO.d.ts} +9 -0
package/package.json +1 -1
package/dist/chunk-3KULWJ7A.js +0 -569
package/dist/chunk-3KULWJ7A.js.map +0 -1
package/dist/chunk-5CBGYE7A.cjs +0 -592
package/dist/chunk-5CBGYE7A.cjs.map +0 -1
package/dist/chunk-DSO337ME.cjs.map +0 -1
package/dist/chunk-FV3PEJQE.js.map +0 -1
package/dist/chunk-OGQEPU7G.cjs.map +0 -1
package/dist/chunk-WQLUD25W.js.map +0 -1

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,112 @@
 # Changelog
+## 0.2.0
+### Minor Changes
+- The overlay now speaks Arabic, and renders right-to-left data correctly in any language.
+  **Arabic overlay**
+  - On a page whose `<html lang>` is Arabic, the whole panel is in Arabic and
+    laid out right-to-left — title, buttons, category names, explanations, fixes,
+    and the scroll hint, with correct Arabic plurals. Every other page, including
+    right-to-left pages in languages the overlay does not translate, gets the
+    English panel as before.
+  - New `overlay={{ locale: 'auto' | 'en' | 'ar' }}` option. `'auto'` is the
+    default and follows `<html lang>`.
+  - The console output and the `explanation`/`suggestion` strings in `onReport`
+    stay English and are byte-identical to 0.1.5. Every built-in cause now also
+    carries `messageId` and `params`, which is how the overlay finds the
+    translation.
+  **Right-to-left rendering fixes**
+  - Arabic values no longer have their sentence punctuation moved to the wrong
+    end. Each value cell takes its direction from its own content, in either
+    panel language.
+  - Arabic values are drawn in a proportional face instead of a monospace
+    fallback, which rendered them with their letters disconnected.
+  - Selectors, component names, file paths and attribute names are isolated
+    left-to-right, and quoted values inside explanations are isolated one by one,
+    so brackets cannot mirror and tokens cannot swap places.
+  - The panel declares its own `lang`. Previously an English panel on an Arabic
+    page inherited `lang="ar"`, so screen readers voiced it with an Arabic voice.
+  **Other fixes**
+  - Invisible bidi marks (LRM, RLM, isolates…) are drawn as labelled badges in
+    the value cells, so the bidi-mark case no longer shows two identical-looking
+    values. Value cells also preserve whitespace, so whitespace-only mismatches
+    are visible.
+  - Component attribution from a React component stack no longer names a DOM tag
+    such as `<p>`; it names the nearest component you wrote.
+  - React's bare "hydration failed" message no longer adds an empty card next to
+    a real mismatch. When it is the only signal it is still reported, with text
+    that says React did not name the node, instead of "inspect the values above".
+  - React 19 hydration errors no longer produce junk reports. React 19 prints a
+    bulleted list of possible causes above its diff tree, and each bullet was
+    read as a removed ("server") diff line — five bogus "Unknown" reports per
+    mismatch, with the real client value paired against the first bullet. Only
+    the tree after React's hydration-mismatch link is read as a diff now.
+## 0.1.5
+### Patch Changes
+- 7b16e20: Fix the inspector lifecycle, bound detection cost, and close detection gaps.
+  **Lifecycle**
+  - `createHydrationInspector()` is no longer dead after a React Strict Mode
+    remount. Its `<Provider>` only ever stopped the controller, so Strict Mode's
+    setup → cleanup → setup left the documented Vite/CRA/Remix integration
+    silently doing nothing for the rest of the session.
+  - The dev check no longer requires a `process` global. Vite, Rollup and esbuild
+    substitute `process.env.NODE_ENV` without defining `process` itself, which
+    compiled the old `typeof process !== 'undefined'` guard down to `false` and
+    disabled the inspector entirely in those bundlers.
+  - Scheduling races an animation frame against a timer, so a page that is hidden
+    at load — where the browser suspends `requestAnimationFrame` outright — is
+    still inspected.
+  - The console capture hands `console.error` back correctly when the same
+    listener subscribes twice, and its message cap now drops past-cap messages
+    instead of recording-but-forwarding them (which broke dedup exactly when the
+    cap was meant to engage).
+  **Cost**
+  - A burst of React warnings arriving in one frame triggers one diff pass rather
+    than one per warning.
+  - Captured server markup is parsed once per root and reused across the settling
+    window instead of being re-parsed on every pass.
+  - Retained warning text is bounded, so an app erroring in a render loop cannot
+    grow the per-pass cost without limit.
+  **Detection**
+  - `date-time` no longer fires on ordinary values. `Date.parse` accepts almost
+    anything — `100` is the year 100, `server-0` is the year 2000 — so prices,
+    counts and ids were being diagnosed as a clock or timezone drift. A value must
+    now look like a date by shape.
+  - Arabic formatting mismatches are detected when both sides use the same digit
+    script: grouping/decimal separators, field order and times in Arabic-Indic and
+    Persian digits previously fell through to `unknown`.
+  - Values differing only by invisible bidirectional control marks (LRM/RLM/ALM,
+    isolates) are detected and named. Different ICU versions emit different marks
+    for the same `Intl` call, so Node and the browser routinely produce strings
+    that look identical and are not.
+  - Report values are no longer truncated mid surrogate pair.
+  **Overlay**
+  - A panel re-mounted after being dismissed no longer reports a stale count or
+    promise scrolling it cannot do.
+  Note for anyone consuming `report.cause.category` in an `onReport` sink: the
+  `date-time` and `locale-format` fixes change which category some mismatches
+  resolve to.
 ## 0.1.4
 - **License: restored MIT.** Re-added `LICENSE` (MIT) and set
@@ -93,7 +200,7 @@ Router, React 18 & 19). **0.1.0 is broken in Next.js — use 0.1.1 or later.**
   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).
+"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

package/README.md CHANGED Viewed

@@ -2,7 +2,9 @@
 [![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)
+[![CI](https://github.com/razan-aboushi/why-hydration/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/razan-aboushi/why-hydration/actions/workflows/ci.yml)
+[![prod bundle: 99 B gzipped](https://img.shields.io/badge/prod%20bundle-99%20B%20gzipped-brightgreen)](#production-behavior)
+[![node: >=18](https://img.shields.io/node/v/why-hydration)](#install)
 [![license: MIT](https://img.shields.io/npm/l/why-hydration.svg)](LICENSE)
 📦 **npm:** https://www.npmjs.com/package/why-hydration &nbsp;·&nbsp; 🐙 **GitHub:** https://github.com/razan-aboushi/why-hydration &nbsp;·&nbsp; 💼 **Author:** [Razan Aboushi](https://www.linkedin.com/in/razan-aboushi/)
@@ -58,9 +60,10 @@ together.
   incidental page noise.
 - 🌐 **Arabic-first locale detection** — digit-script mismatches (٠١٢ vs 012)
   are a first-class cause, not an afterthought.
-- 🔤 **RTL-safe overlay** — the overlay always renders left-to-right, even on
-  pages with `<html dir="rtl">`, since its content (paths, values, code) is
-  English.
+- 🔤 **Speaks Arabic, right-to-left** — on an Arabic page (`<html lang="ar">`)
+  the overlay is in Arabic and laid out right-to-left; everywhere else it is in
+  English. Page data renders in its own direction in both, and invisible bidi
+  marks are shown instead of hidden.
 - 🫧 **Zero production cost** — every code path is gated behind
   `process.env.NODE_ENV`, and CI fails the build if the production bundle for
   any entry point isn't tree-shaken to a no-op.
@@ -288,6 +291,14 @@ React/Next.js's own internal markup markers.
    misattribute every following sibling. This is a bounded check, not a
    standing `MutationObserver`, so legitimate DOM changes from your app's own
    state updates after this window are never mistaken for a hydration issue.
+   The passes are also bounded in cost. React logs its warnings in bursts, so
+   every signal that lands in the same frame is coalesced into **one** diff
+   rather than one diff each, and the captured server markup — re-materialising
+   it is a full HTML parse of your server render — is parsed **once per root**
+   and reused across every pass. Scheduling races an animation frame against a
+   50 ms timer, so a page that is hidden at load (where the browser suspends
+   `requestAnimationFrame` entirely) still gets inspected.
 4. **Classify.** Each divergence is passed through an ordered list of rules
    (see [Cause categories](#cause-categories)); the first rule whose
    confidence clears the threshold wins, otherwise the mismatch is reported as
@@ -321,6 +332,28 @@ production):
 A page with no mismatches renders **nothing** — no overlay, no console output.
+### Controlling the overlay
+| Action | Effect |
+| ------ | ------ |
+| **Dismiss** button, or **Esc** | Removes the panel for the rest of the page load. |
+| **✕** on the hint bar | Closes just the "scroll to see all" hint; the panel stays. |
+| `overlay={false}` | Never mounts it at all — `onReport` and the console output still work. |
+| `overlay={{ position }}` | `bottom-right` (default), `bottom-left`, `top-right`, `top-left`. |
+| `overlay={{ locale }}` | `'auto'` (default) follows `<html lang>`; `'en'` or `'ar'` pins the language. See [RTL and Arabic support](#rtl-and-arabic-support). |
+The overlay is a *view* over the collected reports, not the collector itself:
+dismissing it does not stop detection, and `onReport` keeps firing. If a
+mismatch is found after you dismissed it — a late signal, or a second hydration
+error — the panel returns showing that mismatch, starting from a clean count
+rather than resuming a stale one.
+It renders in an isolated Shadow DOM, is never part of your app's tree, and is
+excluded from its own diff, so it can never be mistaken for a mismatch.
+Mismatched values are rendered as **text**, and "Learn more" links are
+restricted to `http(s)` URLs, so nothing in a mismatched value can inject markup
+or script into the panel.
 ### In a real app
 Captured from a production Next.js app: every mismatch on the page collected
@@ -337,21 +370,82 @@ there are more than fit:
 ## RTL and Arabic support
-The overlay works correctly in apps that render right-to-left, e.g. pages with
-`<html dir="rtl">` for Arabic, Hebrew, or other RTL locales:
-- The overlay's own layout **always renders left-to-right**. Its content —
-  file paths, DOM selectors, code values, category names — is English, so
-  keeping it LTR keeps it readable regardless of the host page's direction.
-- This is automatic. The overlay renders inside an isolated Shadow DOM and
-  explicitly sets its own `direction`, so it does not inherit `dir="rtl"`
-  from the host page and does not mirror its layout. No configuration is
-  needed.
-- **Detection itself is locale-agnostic.** The [`locale-format`](#cause-locale-format)
-  category specifically detects Arabic-Indic vs. Latin digit-script mismatches
-  (`٠١٢` vs `012`), which is a common real-world source of hydration
-  mismatches in Arabic-first apps that format numbers with `Intl` or
-  `toLocaleString` without pinning an explicit locale.
+An Arabic app gets the same diagnosis quality as an English one. That covers
+both how the overlay renders and what the engine can actually detect.
+### The overlay
+**The overlay speaks the page's language.** On a page whose `<html lang>` is
+Arabic (`ar`, `ar-SA`, `ar-EG`, …) the whole panel is in Arabic and laid out
+right-to-left: title, buttons, category names, the explanation, the fix, and
+the scroll hint, with correct Arabic plurals. Every other page gets the English
+panel — including right-to-left pages in languages the overlay does not
+translate, such as Hebrew or Persian, where it stays left-to-right rather than
+mirroring English text. Pin it either way with `overlay={{ locale: 'en' }}` or
+`overlay={{ locale: 'ar' }}`.
+What stays English: the console output, and `cause.explanation` /
+`cause.suggestion` in the report `onReport` receives. Those are what people log,
+grep and paste into issues, so they do not change with the page. Each report
+also carries `cause.messageId` and `cause.params`, which is how the overlay
+finds the translation — and how your own tooling can, too. The "Learn more"
+links point at this README, which is in English, and say so.
+**Page data renders in its own direction, in either panel.** A mismatched value
+can be in any script, so each value cell takes its direction from its own first
+strong character. `السعر: ١٬٤٠٠ د.ك.` reads right-to-left with its full stop at
+the end even inside the English panel, and `Price: 1,400 KWD.` reads
+left-to-right inside the Arabic one. Selectors, component names, file paths and
+attribute names are code, so they are always isolated left-to-right — otherwise
+a right-to-left line would mirror their brackets and reorder their segments.
+Class tokens and other values quoted inside a sentence are isolated one by one,
+so two Arabic tokens cannot swap places. Arabic is drawn in a proportional face
+(a monospace fallback renders it with its letters disconnected), and Arabic
+labels are never letter-spaced or uppercased, which breaks their joining.
+**What differs is what you see.** Value cells preserve whitespace, so a
+whitespace-only mismatch no longer looks like two identical strings. Invisible
+characters that change layout — `LRM`, `RLM`, `ALM`, the bidi embeddings and
+isolates, zero-width space, BOM — are drawn as small labelled badges rather than
+applied, so the [bidi-mark case](#cause-locale-format) shows a visible
+difference instead of two cells that look the same.
+**It is isolated from the page.** The panel lives in a Shadow DOM, and its
+direction is set inside it, so nothing in the host page's CSS can flip it — the
+`all` shorthand deliberately excludes `direction` (per spec), so
+`:host { all: initial }` alone would not be enough. The panel also declares its
+own `lang`, so a screen reader voices it in its own language: before this, an
+English panel on an Arabic page was read aloud with an Arabic voice.
+### Detection
+Detection is direction-agnostic: every rule matches on the *shape* of a value,
+not its script. Three Arabic-specific cases are worth calling out, because the
+first is the one most people expect and the other two are the ones that
+actually bite:
+- **Different digit scripts.** Arabic-Indic `٠١٢` on one side, Latin `012` on
+  the other — the classic symptom of `Intl`/`toLocaleString` resolving to a
+  different locale on the server than in the browser. Reported as
+  [`locale-format`](#cause-locale-format) at 92% confidence.
+- **Same digit script, different formatting.** An Arabic-first app renders
+  Arabic-Indic digits on *both* sides, so there is no script difference to key
+  off — only a grouping separator (`١٬٤٠٠` vs `١٤٠٠`), a decimal separator
+  (`١٢٣٤٫٥٦` vs `١٢٣٤.٥٦`), a field order, or a time. These are folded to Latin
+  before the numeric/date shape tests run, so they are classified exactly like
+  their English equivalents instead of falling through to `unknown`. Persian /
+  Extended Arabic-Indic digits (`۰۱۲`) are handled the same way.
+- **Invisible bidi marks.** `Intl` wraps numbers and date fields in
+  bidirectional control characters (LRM, RLM, ALM, isolates) in RTL locales,
+  and *which* ones it emits differs between ICU versions — so Node and the
+  browser routinely format the same date into strings that are visually
+  identical and byte-different. This is the hardest hydration mismatch to debug
+  by eye, since the console diff looks like the same text twice. It is detected
+  and named explicitly.
+Both directions are covered by the test suite as a matched pair
+(`test/i18n.test.tsx`), plus overlay directionality in `test/direction.test.ts`,
+so English and Arabic behaviour cannot drift apart.
 ---
@@ -414,11 +508,19 @@ interface HydrationInspectorHandle {
 }
 ```
+`Provider` owns the inspector's lifetime: it must actually be mounted, and
+unmounting it tears the inspector down (overlay removed, `console.error`
+handed back untouched). Mounting it again restarts detection cleanly rather
+than stacking a second overlay or a second console patch — which is what makes
+it safe under `<React.StrictMode>`, where React deliberately runs every mount
+effect setup → cleanup → setup.
 ### `OverlayOptions`
 ```ts
 interface OverlayOptions {
   position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'; // default 'bottom-right'
+  locale?: 'auto' | 'en' | 'ar'; // default 'auto' — follows <html lang>
 }
 ```
@@ -467,9 +569,11 @@ interface HydrationReport {
   cause: {
     category: HydrationCauseCategory; // one of the categories below, or "unknown"
     confidence: number;               // 0–1
-    explanation: string;
-    suggestion: string;
+    explanation: string;              // always English
+    suggestion: string;               // always English
     docsUrl?: string;
+    messageId?: string;               // which message produced the text, e.g. "attribute-mismatch.class"
+    params?: Record<string, string | string[]>; // the values in it, e.g. { added: ['wide'], removed: [] }
   };
   raw?: { reactMessage?: string };   // the original React console message, if any
 }
@@ -508,6 +612,14 @@ Server and client rendered different random-looking values (UUID, token, React
 Values are dates/times that differ by a small delta — the clock or timezone
 moved between server and client render.
+Matched on **shape**, not on whether `Date.parse` happens to accept the value:
+ISO dates, `D/M/YYYY`-style dates, clock times, month names with a number, and
+10–13 digit epoch timestamps. That distinction matters because `Date.parse` is
+extremely permissive — it reads `100` as the year 100 and `server-0` as the
+year 2000 — so an ordinary price, count, or id would otherwise be diagnosed as
+a clock drift.
 **Fix:** render time after mount, or pass one server timestamp down and pin
 the timezone when formatting.
 **Reference:** [React — different client/server content](https://react.dev/reference/react-dom/client/hydrateRoot#handling-different-client-and-server-content).
@@ -518,11 +630,21 @@ the timezone when formatting.
 <img src="docs/screenshots/cause-locale-format.png" alt="locale-format report" width="420">
-Same underlying value, different formatting: **Arabic-Indic ٠١٢ vs Latin 012**,
-decimal/thousand separators (`1,234.56` vs `1.234,56`), or date field order
-(MM/DD vs DD/MM).
+Same underlying value, different formatting. Covers:
+- **Different digit scripts** — Arabic-Indic `٠١٢` vs Latin `012`, or Persian
+  `۰۱۲` vs Latin.
+- **Different separators or field order** — `1,234.56` vs `1.234,56`,
+  `١٬٤٠٠` vs `١٤٠٠`, MM/DD vs DD/MM. Detected in Arabic-Indic and Persian
+  digits as well as Latin, so an app that renders the same digit script on both
+  sides is still diagnosed.
+- **Invisible bidirectional marks** — values that are identical on screen but
+  differ by LRM/RLM/ALM or isolate characters, which `Intl` adds around numbers
+  and dates in RTL locales and which different ICU versions (Node vs the
+  browser) emit differently.
 **Fix:** pass an explicit `locale` and timezone to `Intl` on both sides, or
-format after mount.
+format after mount. See also [RTL and Arabic support](#rtl-and-arabic-support).
 **Reference:** [MDN `Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat).
 <a id="cause-third-party-dom-mutation"></a>
@@ -612,6 +734,13 @@ drive the visual change with a CSS media query instead of a JS class toggle.
 A mismatch was detected but didn't match any of the rules above. The report
 still shows the exact server vs. client values and node path so you can
 diagnose it directly.
+React also logs a bare "hydration failed" message that names no node at all.
+When the DOM diff or another React message has already located the mismatch,
+that message adds nothing and is not shown. When it is the *only* signal —
+typically because the snapshot script is missing — it is reported once, with an
+explanation that says React did not name the node and a fix that points at the
+snapshot script, rather than asking you to inspect values that do not exist.
 **Fix:** compare the two values — the cause is usually one of the categories
 above. If you find a reliable signal for it, add a custom rule via the
 `classify` option (see [Contributing](#contributing)).
@@ -628,11 +757,24 @@ above. If you find a reliable signal for it, add a custom rule via the
   check, written so bundlers can statically fold it away. In a production
   build, `<HydrationInspector>` becomes a plain pass-through and
   `createHydrationInspector()` returns no-op functions.
+- Production is **opt-out**, not opt-in: the internal dev check treats an
+  explicit `NODE_ENV === 'production'` as production and everything else,
+  including a bundle where `process` was never defined at all, as development.
+  That matters because Vite, Rollup and esbuild substitute
+  `process.env.NODE_ENV` without shimming `process` itself — requiring
+  `process` to exist would silently disable the inspector for all of them. It
+  cannot leak dev code into a production bundle, because the entry-point gates
+  above have already been folded away by then.
 - This is enforced, not just claimed: the project's CI pipeline runs a size
   budget (`npm run size`) against a real production bundle built with webpack
   and terser — the same toolchain Next.js and CRA use for production — and
   fails the build if the tree-shaken output for any entry point isn't reduced
-  to a near-empty stub.
+  to a near-empty stub. The budgets sit just above today's output, so even a
+  small leak fails CI. Verified independently against Rollup, which is what
+  Vite uses for production builds: **99 B** minified + gzipped under webpack,
+  and **156 B** minified (not gzipped) under Rollup — versus ~59 KB minified
+  for the same entry built for development. The Arabic translations exist only
+  in that development build.
 - `<HydrationSnapshotScript>` also renders `null` outside development, so no
   snapshot script is emitted into your production HTML.
@@ -662,6 +804,16 @@ above. If you find a reliable signal for it, add a custom rule via the
 - **Bounded, not continuous.** Detection re-checks the DOM a handful of times
   in the ~1.5 seconds after hydration and then stops — there is no standing
   `MutationObserver` watching your app for the rest of its lifetime.
+- **Bounded in cost, too.** A burst of React warnings landing in one frame
+  triggers one diff pass, not one per warning. The captured server markup is
+  parsed once per root and reused across passes rather than re-parsed each
+  time. Retained warning text is capped, so an app erroring in a render loop
+  cannot grow the per-pass cost without limit, and reports are capped by
+  `maxReports` (default 25).
+- **Symmetrical teardown.** Unmounting the inspector restores `console.error`
+  to exactly the function it replaced, removes the overlay, and clears every
+  pending timer — so a remount (including React Strict Mode's deliberate
+  double-mount in dev) leaves one overlay and one console patch, not two.
 ---
@@ -673,11 +825,30 @@ Remix, or a custom SSR setup. Use `createHydrationInspector` where you own
 The core engine (`why-hydration`) is framework-agnostic.
 **Nothing shows up, but I know there's a mismatch.** Confirm `NODE_ENV` isn't
-`production`, that `<HydrationInspector>` (or its `Provider`) actually wraps
-the part of the tree that mismatches, and that the snapshot script is present
-in `<head>` and runs before your app's hydration script. Without the snapshot
-script, the tool still reports mismatches it can parse from React's own
-console warning, but loses the precise DOM-level diff.
+`production`, that `<HydrationInspector>` (or its `Provider`) is actually
+**mounted** and wraps the part of the tree that mismatches, and that the
+snapshot script is present in `<head>` and runs before your app's hydration
+script. Without the snapshot script, the tool still reports mismatches it can
+parse from React's own console warning, but loses the precise DOM-level diff.
+If you passed `roots`, check the console for a
+`[why-hydration] Skipping root:` warning — a root with no captured server HTML
+can never produce a DOM-level report, and it says so rather than failing
+silently.
+**Does it work under `<React.StrictMode>`?** Yes. Strict Mode runs every mount
+effect setup → cleanup → setup in development, which tears the inspector down
+and rebuilds it. You get one overlay, one console patch, and each mismatch
+reported once — the warnings React logged during the first pass are replayed
+to the rebuilt inspector rather than lost.
+**I loaded the page in a background tab and got nothing.** Fixed — browsers
+suspend `requestAnimationFrame` on hidden pages, so scheduling races a frame
+against a 50 ms timer and no longer depends on the page being painted.
+**The component name in a report was a tag like `<p>`.** Fixed. React's
+component stacks list host elements first (`at p`, `at span`), and those were
+being taken as the component. The nearest component you wrote is used instead,
+and when there is none the report names no component rather than a tag.
 **The "Learn more →" link 404s.** The links point at this README on GitHub
 (`github.com/razan-aboushi/why-hydration#cause-…`). If you've forked the
@@ -700,8 +871,24 @@ production. It's dev-only, runs a bounded diff across roughly 1.5 seconds
 right after hydration, then stops.
 **Does it work with `<html dir="rtl">`?** Yes — see
-[RTL and Arabic support](#rtl-and-arabic-support). The overlay stays
-left-to-right on purpose; this is not a bug.
+[RTL and Arabic support](#rtl-and-arabic-support). The panel's language follows
+`<html lang>`, not `dir`: an Arabic page gets the Arabic right-to-left panel,
+and a right-to-left page in another language gets the English left-to-right
+one. Detection covers Arabic-script formatting mismatches on both sides, not
+just Arabic-vs-Latin.
+**I want the English panel on my Arabic site (or the reverse).** Pass
+`overlay={{ locale: 'en' }}` (or `'ar'`). The console and `onReport` are English
+either way.
+**My Arabic app reports a mismatch between two values that look the same.** They
+differ by invisible bidirectional control characters — `Intl` adds LRM/RLM/isolate
+marks around numbers and dates in RTL locales, and Node's ICU and the browser's
+ICU do not always agree on which. The report names this explicitly under
+[`locale-format`](#cause-locale-format), and the overlay draws each invisible
+mark as a small labelled badge (`RLM`, `LRM`, …) in the value cell, so you can
+see which side has it. Format the value in one place and pass the string down,
+or add `suppressHydrationWarning` if the marks are harmless.
 ---