Refine bridge docs and integer-only payload parsing

mCodex · mCodex · commit a82d1e00c3b2 · 2026-05-05T10:13:48.000-03:00
Clarify bridge behavior and measurement algorithm, and tighten payload parsing to ASCII-digit integers.

Changes:
- README: Explain the bridge is idempotent, measures the page in-place (no re-parenting or injected inline styles), update measurement sources order, and note skipping of inert and out-of-flow elements. Clarify iOS WKWebView/getBoundingClientRect behavior and bootstrap grace logic.
- src/constants/autoHeightBridge.ts: Update comments to describe O(k) complexity, clarify getBoundingClientRect semantics, and remove an unused RENDERABLE_MEDIA_TAGS block from the injected bridge string.
- src/hooks/useAutoHeight.ts: Only accept namespaced integer payloads from the bridge (changed regex from allowing decimals to /^
\d+$/) and update explanatory comments and example imports.
- src/__tests__/useAutoHeight.test.tsx: Update test name/text to expect integer-only payloads and add decimal payloads to forged inputs.

Rationale: Improve documentation accuracy about how the injected bridge operates, tighten input validation to reject fractional or otherwise coerced numeric payloads, and keep the injected script lean by removing unused tag metadata.
diff --git a/README.md b/README.md
@@ -149,15 +149,15 @@ Fix it with `loadingContainerStyle`:
 
 ## 🧠 How It Works
 
-The injected bridge runs once per page, before content loads, and turns the WebView into a self-measuring component:
+The injected bridge is idempotent and may run at both `injectedJavaScriptBeforeContentLoaded` and `injectedJavaScript` (the second injection is a no-op when the first already published the global handle, but covers iOS inline `source.html` cases where the early hook is skipped). It turns the WebView into a self-measuring component:
 
-- **Re-parents body children into a dedicated wrapper.** The wrapper has no explicit height and no `overflow: hidden`, so its layout is never clamped by the native frame size.
-- **Multi-source measurement (the production-grade fix).** Each measurement is the `Math.max` of four authoritative layout sources:
-  1. `wrapper.scrollHeight` / `wrapper.offsetHeight` — primary, fastest, accurate for normal block flow.
-  2. `document.body.scrollHeight` / `documentElement.scrollHeight` — backstop when frameworks style `body`/`html` directly.
-  3. The last non-inert child's `getBoundingClientRect().bottom + computedMarginBottom` — catches margin-collapse, late image reflow, and trailing absolutely-positioned content where `scrollHeight` momentarily under-reports on iOS WKWebView.
+- **Measures the page in place.** The bridge does not re-parent `<body>` children into a wrapper and does not inject inline styles; it reads layout directly from the document's existing flow so framework- or CMS-generated DOM stays untouched (preserving margin collapse, author CSS, and any structure the page expects).
+- **Multi-source measurement (the production-grade fix).** Each measurement is the `Math.max` of authoritative layout sources:
+  1. `document.body.scrollHeight` / `document.body.offsetHeight` — primary document metrics for normal block flow.
+  2. `document.documentElement.scrollHeight` / `document.documentElement.offsetHeight` — backstop when frameworks style `html` directly or when the root box exceeds `body`.
+  3. The last non-inert in-flow child's `getBoundingClientRect().bottom + computedMarginBottom` — catches margin-collapse, late image reflow, and end-of-document cases where scroll metrics momentarily under-report on iOS WKWebView.
 
-  Inert siblings (`SCRIPT`, `STYLE`, `META`, `LINK`, `TITLE`, `HEAD`, `NOSCRIPT`) are skipped during the last-child walk so they never short-circuit the probe.
+  Inert siblings (`SCRIPT`, `STYLE`, `META`, `LINK`, `TITLE`, `HEAD`, `NOSCRIPT`) and out-of-flow positions (`fixed` / `sticky` / `absolute`) are skipped during the last-in-flow-child walk so they never short-circuit the probe.
 - **Bootstrap-grace adaptive fallback.** A timer re-arms itself only while either condition holds:
   - `pendingLoads > 0` (an image / iframe / video is still loading), **or**
   - `Date.now() - bootstrapAt < BOOTSTRAP_GRACE_MS` (5 s grace window from script start, refreshed on `markLoading`, font `loadingdone`, and external `state.refresh` calls).
diff --git a/src/__tests__/useAutoHeight.test.tsx b/src/__tests__/useAutoHeight.test.tsx
@@ -136,13 +136,14 @@ describe('useAutoHeight', () => {
     unmount();
   });
 
-  it('rejects prefixed payloads that are not plain decimal numbers', () => {
+  it('rejects prefixed payloads that are not plain integer numbers', () => {
     const { unmount } = render(
       <Harness minHeight={0} onHeightChange={onHeightChange} />
     );
 
-    // Hex, exponential, leading/trailing whitespace, and signed values must
-    // all be treated as forged input — the bridge only emits plain decimals.
+    // Hex, exponential, leading/trailing whitespace, signed, and decimal
+    // values must all be treated as forged input — the bridge only emits
+    // ASCII-digit integers (`String(Math.ceil(height))`).
     const forgedPayloads = [
       '__RN_SIZED_WV__:0x100',
       '__RN_SIZED_WV__:1e10',
@@ -151,6 +152,8 @@ describe('useAutoHeight', () => {
       '__RN_SIZED_WV__:-360',
       '__RN_SIZED_WV__:NaN',
       '__RN_SIZED_WV__:Infinity',
+      '__RN_SIZED_WV__:360.5',
+      '__RN_SIZED_WV__:.5',
     ];
 
     for (const payload of forgedPayloads) {
diff --git a/src/constants/autoHeightBridge.ts b/src/constants/autoHeightBridge.ts
@@ -8,10 +8,13 @@
  * correct rendering inside iOS 26 WKWebView.
  *
  * @remarks
- * ## Measurement algorithm (O(1))
+ * ## Measurement algorithm (O(k))
  *
  * Every measurement is the `Math.max` of multiple authoritative layout
- * sources, **without mutating** the host page's DOM or styles:
+ * sources, **without mutating** the host page's DOM or styles. The cost is
+ * O(k) where k is the number of trailing inert / out-of-flow siblings the
+ * last-child walk has to skip (typically 0–2 — effectively constant in
+ * steady state):
  *
  * 1. `body.scrollHeight` / `body.offsetHeight` — primary signal; includes
  *    body padding and any block-level margin that did not collapse out.
@@ -21,8 +24,13 @@
  *    computedMarginBottom` — catches margin-collapse (where the last
  *    child's bottom margin escapes `<body>`) and late-reflow scenarios
  *    where `scrollHeight` momentarily under-reports on iOS WKWebView.
- *    `getBoundingClientRect` is part of the CSSOM View spec and returns
- *    document-layout coordinates, NOT viewport-clamped values.
+ *    Per the CSSOM View spec, `getBoundingClientRect` returns
+ *    viewport-relative coordinates whose values are NOT clamped to the
+ *    visible viewport. We use the bottom value as a proxy for the
+ *    document's bottom edge under the assumption the page itself is not
+ *    internally scrolled during measurement — a safe assumption since the
+ *    host RN component sets `scrollEnabled={false}` and the bridge never
+ *    triggers programmatic scrolling.
  *
  * Inert siblings (`SCRIPT`, `STYLE`, `META`, `LINK`, `TITLE`, `HEAD`,
  * `NOSCRIPT`) and out-of-flow positions (`fixed` / `sticky` / `absolute`)
@@ -271,18 +279,6 @@ export const AUTO_HEIGHT_BRIDGE: string = `(() => {
   // ============================================================
   // SECTION: Content classification
   // ============================================================
-  var RENDERABLE_MEDIA_TAGS = {
-    IMG: true,
-    IFRAME: true,
-    VIDEO: true,
-    SVG: true,
-    CANVAS: true,
-    PICTURE: true,
-    OBJECT: true,
-    EMBED: true,
-    AUDIO: true,
-  };
-
   // Inert tags — never contribute to layout height. Skipped by the last-child
   // walk in measureHeight() so a trailing <script>/<style> never fools the
   // position-based probe into reporting 0.
@@ -335,9 +331,11 @@ export const AUTO_HEIGHT_BRIDGE: string = `(() => {
    *
    * The position-based probe catches cases where scrollHeight under-reports
    * (margin-collapse where the last child's bottom margin escapes \`<body>\`,
-   * late image reflow, etc.). It is spec-correct on both iOS WKWebView and
-   * Android WebView — \`getBoundingClientRect\` returns document-layout
-   * coordinates, not viewport-clamped values.
+   * late image reflow, etc.). \`getBoundingClientRect\` returns
+   * viewport-relative coordinates per CSSOM View, but those values are not
+   * clamped to the visible viewport — and the host RN component sets
+   * \`scrollEnabled={false}\` so the WebView is never internally scrolled,
+   * making the bottom value a reliable proxy for the document's bottom edge.
    *
    * Complexity: O(k) where k is the number of trailing inert / out-of-flow
    * siblings (typically 0–2). Single layout flush per call.
diff --git a/src/hooks/useAutoHeight.ts b/src/hooks/useAutoHeight.ts
@@ -60,18 +60,19 @@ const HEIGHT_DIFF_THRESHOLD = 1;
  * Accepts:
  * - `number` values (direct/programmatic calls — never reach the WebView).
  * - Strings starting with {@link BRIDGE_MESSAGE_PREFIX} whose suffix is a
- *   plain decimal number (the only shape the bridge ever emits).
+ *   non-empty run of ASCII digits (the only shape the bridge ever emits:
+ *   `MESSAGE_PREFIX + String(Math.ceil(height))`).
  *
  * Bare numeric strings (e.g. `'360'`) are rejected: only the namespaced
  * bridge protocol is trusted, so user-land `postMessage('123')` cannot mutate
  * the container height.
  *
- * Hex (`0x100`), exponential (`1e10`), and whitespace-padded inputs are also
- * rejected — `Number()` would silently coerce them, but the bridge never
- * produces such payloads, so anything matching those shapes is treated as a
- * tampered/forged message.
+ * Decimals (`12.5`), hex (`0x100`), exponential (`1e10`), and
+ * whitespace-padded inputs are also rejected — `Number()` would silently
+ * coerce them, but the bridge never produces such payloads, so anything
+ * matching those shapes is treated as a tampered/forged message.
  */
-const BRIDGE_NUMBER_PATTERN = /^\d+(?:\.\d+)?$/;
+const BRIDGE_NUMBER_PATTERN = /^\d+$/;
 
 const parseHeightPayload = (rawValue: unknown): number | null => {
   let numericValue: number;
@@ -121,6 +122,7 @@ const parseHeightPayload = (rawValue: unknown): number | null => {
  *
  * @example
  * ```tsx
+ * import { View } from 'react-native';
  * import { WebView } from 'react-native-webview';
  * import { AUTO_HEIGHT_BRIDGE, useAutoHeight } from 'react-native-sized-webview';
  *
