why-hydration 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## 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 +150,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

@@ -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  ·  🐙 **GitHub:** https://github.com/razan-aboushi/why-hydration  ·  💼 **Author:** [Razan Aboushi](https://www.linkedin.com/in/razan-aboushi/)
@@ -288,6 +290,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 +331,27 @@ 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`. |
+
+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 +368,54 @@ 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's own layout **always renders left-to-right**, on any page. 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 and needs no configuration. The overlay lives in an
+  isolated Shadow DOM, sets `direction: ltr` on both `:host` and the panel, and
+  carries a `dir="ltr"` attribute as well — belt and braces, because the CSS
+  `all` shorthand deliberately excludes `direction` (per spec), so
+  `:host { all: initial }` alone would still let `direction: rtl` leak in and
+  flip the server/client diff columns.
+- Values are rendered as **text**, so Arabic, Hebrew and mixed bidi content
+  display intact inside the LTR panel without reordering the surrounding
+  layout.
+
+### 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,6 +478,13 @@ 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
@@ -508,6 +579,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 +597,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>
@@ -628,11 +717,21 @@ 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. Verified independently against Rollup, which is what
+  Vite uses for production builds: **99 B** under webpack, **166 B** under
+  Rollup, versus ~40 KB for the same entry built for development.
 - `<HydrationSnapshotScript>` also renders `null` outside development, so no
   snapshot script is emitted into your production HTML.
 
@@ -662,6 +761,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 +782,25 @@ 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 "Learn more →" link 404s.** The links point at this README on GitHub
 (`github.com/razan-aboushi/why-hydration#cause-…`). If you've forked the
@@ -701,7 +824,15 @@ 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.
+left-to-right on purpose; this is not a bug. Detection covers Arabic-script
+formatting mismatches on both sides, not just Arabic-vs-Latin.
+
+**My Arabic app shows two identical-looking values as a mismatch.** 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). Format the value in one place and pass
+the string down, or add `suppressHydrationWarning` if the marks are harmless.
 
 ---
 

package/dist/{chunk-3KULWJ7A.js → chunk-3I6F4K4L.js}

@@ -1,12 +1,12 @@
-import { isDev, ReportCollector, inspectRoot, reportFromMessage, formatConsoleArgs, isHydrationMessage } from './chunk-WQLUD25W.js';
-import { readSnapshot, DEFAULT_SNAPSHOT_SELECTORS } from './chunk-FV3PEJQE.js';
+import { isDev, ReportCollector, inspectRoot, reportFromMessage, formatConsoleArgs, isHydrationMessage } from './chunk-AS5DZZHI.js';
+import { getServerHtmlForRoot, readSnapshot, DEFAULT_SNAPSHOT_SELECTORS } from './chunk-XIM33ZGB.js';
 import * as React2 from 'react';
 
 // src/react/console.ts
 function installConsoleInterceptor(onMessage) {
   if (typeof console === "undefined") return () => {
   };
-  const original = console.error.bind(console);
+  const original = console.error;
   const patched = (...args) => {
     try {
       const message = formatConsoleArgs(args);
@@ -15,7 +15,7 @@ function installConsoleInterceptor(onMessage) {
       }
     } catch {
     }
-    original(...args);
+    original.apply(console, args);
   };
   console.error = patched;
   return () => {
@@ -52,6 +52,32 @@ function createConsoleReporter() {
   return sink;
 }
 
+// src/react/capture.ts
+var MAX_CAPTURED = 50;
+var captured = /* @__PURE__ */ new Set();
+var listeners = /* @__PURE__ */ new Set();
+var uninstall = null;
+function startCapture() {
+  if (uninstall || typeof window === "undefined") return;
+  uninstall = installConsoleInterceptor((message) => {
+    if (captured.has(message) || captured.size >= MAX_CAPTURED) return;
+    captured.add(message);
+    for (const listener of [...listeners]) listener(message);
+  });
+}
+function subscribeCapture(listener) {
+  startCapture();
+  listeners.add(listener);
+  for (const message of [...captured]) listener(message);
+  return () => {
+    if (!listeners.delete(listener)) return;
+    if (listeners.size === 0 && uninstall) {
+      uninstall();
+      uninstall = null;
+    }
+  };
+}
+
 // src/react/overlay.ts
 var CONTAINER_ID = "why-hydration-overlay";
 var CATEGORY_LABELS = {
@@ -262,6 +288,7 @@ function createOverlay(options = {}) {
     host.id = CONTAINER_ID;
     host.setAttribute("data-why-hydration", "overlay");
     host.setAttribute("aria-hidden", "false");
+    host.setAttribute("dir", "ltr");
     const shadow = host.attachShadow({ mode: "open" });
     const style = document.createElement("style");
     style.textContent = STYLES;
@@ -313,6 +340,8 @@ function createOverlay(options = {}) {
     countEl = null;
     hintEl = null;
     hintTextEl = null;
+    count = 0;
+    hintDismissed = false;
   }
   function push(report) {
     ensureMounted();
@@ -381,6 +410,7 @@ function resolveReactSource(node) {
 }
 
 // src/react/controller.ts
+var INSPECT_FALLBACK_MS = 50;
 function buildIgnore(ignore) {
   if (!ignore || ignore.length === 0) return void 0;
   return (divergence) => {
@@ -404,11 +434,14 @@ var InspectorController = class {
     this.started = false;
     this.pendingContext = {};
     this.messages = /* @__PURE__ */ new Set();
+    this.warnedRoots = /* @__PURE__ */ new Set();
     this.settlingTimers = [];
+    this.inspectScheduled = false;
+    this.inspectTimer = null;
     this.onRecoverableError = (error, info) => {
       if (!isDev) return;
       const message = error instanceof Error ? error.message : String(error);
-      this.messages.add(message);
+      this.rememberMessage(message);
       this.mergeContext({
         componentStack: info?.componentStack,
         component: firstComponentFromStack(info?.componentStack),
@@ -420,30 +453,31 @@ var InspectorController = class {
     this.collector = new ReportCollector({
       maxReports: options.maxReports,
       extra: options.classify,
-      ignore: buildIgnore(options.ignore)
+      ignore: buildIgnore(options?.ignore)
     });
   }
   start() {
     if (this.started || !isDev || typeof window === "undefined") return;
     this.started = true;
-    this.pendingContext = {};
-    this.messages.clear();
     if (this.options.onReport) {
-      this.collector.addSink(this.options.onReport);
+      this.cleanups.push(this.collector.addSink(this.options.onReport));
     }
-    this.collector.addSink(createConsoleReporter());
+    this.cleanups.push(this.collector.addSink(createConsoleReporter()));
     if (this.options.overlay !== false) {
       const overlayOpts = typeof this.options.overlay === "object" ? this.options.overlay : {};
       const handle = createOverlay(overlayOpts);
-      this.collector.addSink(handle.push);
-      this.cleanups.push(() => handle.destroy());
+      this.cleanups.push(
+        this.collector.addSink(handle.push, { replay: true }),
+        () => handle.destroy()
+      );
     }
-    const restore = installConsoleInterceptor((message) => {
-      this.messages.add(message);
-      this.mergeContext({ reactMessage: message });
-      this.scheduleInspect();
-    });
-    this.cleanups.push(restore);
+    this.cleanups.push(
+      subscribeCapture((message) => {
+        this.rememberMessage(message);
+        this.mergeContext({ reactMessage: message });
+        this.scheduleInspect();
+      })
+    );
     this.scheduleSettlingInspections();
   }
   // React applies client values to mismatched subtrees via a client re-render a
@@ -458,18 +492,31 @@ var InspectorController = class {
       this.settlingTimers.push(timer);
     }
   }
+  rememberMessage(message) {
+    if (this.messages.size >= MAX_CAPTURED && !this.messages.has(message)) {
+      return;
+    }
+    this.messages.add(message);
+  }
   mergeContext(ctx) {
     this.pendingContext = {
-      componentStack: this.pendingContext.componentStack ?? ctx.componentStack,
-      component: this.pendingContext.component ?? ctx.component,
-      location: this.pendingContext.location ?? ctx.location,
-      reactMessage: this.pendingContext.reactMessage ?? ctx.reactMessage
+      componentStack: ctx.componentStack ?? this.pendingContext.componentStack,
+      component: ctx.component ?? this.pendingContext.component,
+      location: ctx.location ?? this.pendingContext.location,
+      reactMessage: ctx.reactMessage ?? this.pendingContext.reactMessage
+    };
+  }
+  domContext() {
+    return {
+      componentStack: this.pendingContext.componentStack,
+      component: this.pendingContext.component,
+      location: this.pendingContext.location
     };
   }
   stop() {
     for (const timer of this.settlingTimers.splice(0)) clearTimeout(timer);
+    this.clearScheduledInspect();
     for (const cleanup of this.cleanups.splice(0)) cleanup();
-    this.messages.clear();
     this.started = false;
   }
   getReports() {
@@ -483,16 +530,31 @@ var InspectorController = class {
     if (!this.started || typeof document === "undefined" || this.collector.isFull) {
       return;
     }
-    const selectors = this.options.roots ?? snapshotSelectors();
+    const configured = this.options.roots;
+    const selectors = configured ?? snapshotSelectors();
+    const context = this.domContext();
     const seen = /* @__PURE__ */ new Set();
     for (const selector of selectors) {
-      const root = document.querySelector(selector);
+      let root = null;
+      try {
+        root = document.querySelector(selector);
+      } catch {
+        this.warnRoot(selector, `"${selector}" is not a valid CSS selector.`);
+        continue;
+      }
       if (!root || seen.has(root)) continue;
       seen.add(root);
+      if (configured && getServerHtmlForRoot(root) == null) {
+        this.warnRoot(
+          selector,
+          `no server HTML was captured for "${selector}". Add it to the \`selectors\` prop of <HydrationSnapshotScript> so the server markup for that root is snapshotted.`
+        );
+        continue;
+      }
       inspectRoot(
         root,
         this.collector,
-        this.pendingContext,
+        context,
         (divergence) => resolveReactSource(divergence.element ?? null)
       );
     }
@@ -500,12 +562,27 @@ var InspectorController = class {
       reportFromMessage(message, this.collector, this.pendingContext);
     }
   }
+  warnRoot(selector, detail) {
+    if (this.warnedRoots.has(selector)) return;
+    this.warnedRoots.add(selector);
+    console.warn(`[why-hydration] Skipping root: ${detail}`);
+  }
   scheduleInspect() {
-    const run = () => this.inspectAllRoots();
-    if (typeof requestAnimationFrame === "function") {
-      requestAnimationFrame(run);
-    } else {
-      Promise.resolve().then(run);
+    if (this.inspectScheduled) return;
+    this.inspectScheduled = true;
+    const run = () => {
+      if (!this.inspectScheduled) return;
+      this.clearScheduledInspect();
+      this.inspectAllRoots();
+    };
+    if (typeof requestAnimationFrame === "function") requestAnimationFrame(run);
+    this.inspectTimer = setTimeout(run, INSPECT_FALLBACK_MS);
+  }
+  clearScheduledInspect() {
+    this.inspectScheduled = false;
+    if (this.inspectTimer != null) {
+      clearTimeout(this.inspectTimer);
+      this.inspectTimer = null;
     }
   }
 };
@@ -521,20 +598,13 @@ function firstComponentFromStack(stack) {
 }
 function InspectorImpl(props) {
   const { children, overlay, onReport, ignore, classify, maxReports } = props;
-  const controllerRef = React2.useRef(null);
-  if (controllerRef.current === null) {
-    controllerRef.current = new InspectorController({
-      overlay,
-      onReport,
-      ignore,
-      classify,
-      maxReports
-    });
-    controllerRef.current.start();
-  }
+  startCapture();
+  const optionsRef = React2.useRef({});
+  optionsRef.current = { overlay, onReport, ignore, classify, maxReports };
   React2.useEffect(() => {
-    const controller = controllerRef.current;
-    return () => controller?.stop();
+    const controller = new InspectorController(optionsRef.current);
+    controller.start();
+    return () => controller.stop();
   }, []);
   return React2.createElement(React2.Fragment, null, children);
 }
@@ -555,7 +625,10 @@ function createHydrationInspector(options = {}) {
   const controller = new InspectorController(options);
   controller.start();
   function Provider(props) {
-    React2.useEffect(() => () => controller.stop(), []);
+    React2.useEffect(() => {
+      controller.start();
+      return () => controller.stop();
+    }, []);
     return React2.createElement(React2.Fragment, null, props.children);
   }
   return {
@@ -565,5 +638,5 @@ function createHydrationInspector(options = {}) {
 }
 
 export { HydrationInspector, createHydrationInspector };
-//# sourceMappingURL=chunk-3KULWJ7A.js.map
-//# sourceMappingURL=chunk-3KULWJ7A.js.map
+//# sourceMappingURL=chunk-3I6F4K4L.js.map
+//# sourceMappingURL=chunk-3I6F4K4L.js.map