Guard bridge messages, optimize DOM measurements

mCodex · mCodex · commit 5a7c875cbeee · 2026-04-24T15:16:43.000-03:00
Only accept the bridge namespaced payloads for height updates and forward other messages to consumers. SizedWebView now checks that JS messages are strings starting with the bridge prefix before calling setHeightFromPayload; unprefixed payloads are passed to the caller's onMessage. useAutoHeight.parseHeightPayload was tightened to accept only numbers or prefixed bridge strings (bare numeric strings are rejected).

The injected AUTO_HEIGHT_BRIDGE script was optimized: added a domDirty flag (set by the MutationObserver and cleared after pruning) so pruneTrailingNodes runs only when structure changed; prefer the wrapper element as the single authoritative reflow target to avoid multiple forced layouts; and other small measurement-path simplifications to reduce reflows and work per frame.

Documentation: README gains a “Built for speed” section describing hot-path complexity and rationale for the optimizations.
diff --git a/README.md b/README.md
@@ -142,6 +142,21 @@ The example showcases:
 | Scrolling in parent `ScrollView` | Nested scroll can fight gestures | Parent retains full momentum and gesture priority |
 
 Benchmarks were captured on CMS articles up to 3k words in a 60 fps RN dev build. The bridge batches DOM mutations so even long documents resize without thrashing the JS thread.
+
+### 🏎️ Built for speed
+
+Every hot path is designed to run at its theoretical complexity floor — no allocations in steady state, no repeated DOM walks, and at most one forced layout per measurement frame.
+
+| Hot path | Complexity | Notes |
+| --- | --- | --- |
+| Message parsing (`useAutoHeight`) | **O(1)** | Namespaced-prefix check, single `Number()` coerce, constant-bound clamp. |
+| Height commit (rAF-batched) | **O(1)** amortized per frame | Sub-pixel diffs are dropped; at most one React render per animation frame. |
+| DOM mutation callback | **O(added nodes)** | Scans only each mutation's `addedNodes`, not the whole tree. Media elements are deduped via a `WeakSet`. |
+| `measureHeight` | **1 forced reflow / call** | Reads the wrapper element only — its box is authoritative because every `<body>` child lives inside it. |
+| Trailing-node prune DFS | Runs only when the DOM is **dirty** | A mutation-driven dirty flag skips the recursive walk on resize / font / viewport ticks when nothing structural changed. |
+
+The net effect: resize storms, font loads, and viewport changes cost a single `getBoundingClientRect()` per frame — nothing more. Paired with `sideEffects: false` and named-only exports, the library stays fast *and* small in the final bundle.
+
 ### 📦 Bundle & tree-shaking
 
 - Ships as ESM-first (`lib/module/**`) with `"sideEffects": false`.
diff --git a/src/__tests__/index.test.tsx b/src/__tests__/index.test.tsx
@@ -105,13 +105,13 @@ describe('SizedWebView', () => {
     );
 
     const webViewProps = capturedWebViewProps.at(-1) ?? {};
-    const event = { nativeEvent: { data: '360' } } as any;
+    const event = { nativeEvent: { data: '__RN_SIZED_WV__:360' } } as any;
 
     act(() => {
       (webViewProps.onMessage as (evt: unknown) => void)?.(event);
     });
 
-    expect(__setHeightFromPayload).toHaveBeenCalledWith('360');
+    expect(__setHeightFromPayload).toHaveBeenCalledWith('__RN_SIZED_WV__:360');
     expect(onMessage).toHaveBeenCalledWith(event);
 
     act(() => {
@@ -132,11 +132,11 @@ describe('SizedWebView', () => {
 
     act(() => {
       (webViewProps.onMessage as (evt: unknown) => void)?.({
-        nativeEvent: { data: '480' },
+        nativeEvent: { data: '__RN_SIZED_WV__:480' },
       });
     });
 
-    expect(__setHeightFromPayload).toHaveBeenCalledWith('480');
+    expect(__setHeightFromPayload).toHaveBeenCalledWith('__RN_SIZED_WV__:480');
 
     act(() => {
       renderResult.unmount();
@@ -261,4 +261,33 @@ describe('SizedWebView', () => {
       renderResult.unmount();
     });
   });
+
+  it('does not forward unprefixed user-land messages to the auto-height hook', () => {
+    const { __setHeightFromPayload } = jest.requireMock(
+      '../hooks/useAutoHeight'
+    );
+    const onMessage = jest.fn();
+
+    const renderResult = render(
+      <SizedWebView source={{ html: '<p>Hi</p>' }} onMessage={onMessage} />
+    );
+
+    const webViewProps = capturedWebViewProps.at(-1) ?? {};
+    const userLandEvent = {
+      nativeEvent: { data: '400' },
+    } as any;
+
+    act(() => {
+      (webViewProps.onMessage as (evt: unknown) => void)?.(userLandEvent);
+    });
+
+    // Bare numeric string is user-land traffic: must NOT reach the hook,
+    // but MUST still be forwarded to the consumer's onMessage.
+    expect(__setHeightFromPayload).not.toHaveBeenCalled();
+    expect(onMessage).toHaveBeenCalledWith(userLandEvent);
+
+    act(() => {
+      renderResult.unmount();
+    });
+  });
 });
diff --git a/src/__tests__/useAutoHeight.test.tsx b/src/__tests__/useAutoHeight.test.tsx
@@ -73,7 +73,7 @@ describe('useAutoHeight', () => {
     expect(latest.height).toBe(120);
 
     act(() => {
-      latest.setHeightFromPayload('240');
+      latest.setHeightFromPayload('__RN_SIZED_WV__:240');
     });
 
     expect(requestAnimationFrameMock).toHaveBeenCalledTimes(1);
@@ -121,6 +121,21 @@ describe('useAutoHeight', () => {
     unmount();
   });
 
+  it('rejects bare numeric strings without the bridge prefix', () => {
+    const { unmount } = render(
+      <Harness minHeight={0} onHeightChange={onHeightChange} />
+    );
+
+    act(() => {
+      latest.setHeightFromPayload('400');
+    });
+
+    expect(requestAnimationFrameMock).not.toHaveBeenCalled();
+    expect(latest.height).toBeUndefined();
+    expect(onHeightChange).not.toHaveBeenCalled();
+    unmount();
+  });
+
   it('ignores invalid or insignificant height updates', () => {
     const { unmount } = render(
       <Harness minHeight={64} onHeightChange={onHeightChange} />
diff --git a/src/components/SizedWebView.tsx b/src/components/SizedWebView.tsx
@@ -8,6 +8,7 @@ import {
 } from 'react-native-webview';
 
 import { AUTO_HEIGHT_BRIDGE } from '../constants/autoHeightBridge';
+import { BRIDGE_MESSAGE_PREFIX } from '../constants/bridgeProtocol';
 import { useAutoHeight } from '../hooks/useAutoHeight';
 import { composeInjectedScript } from '../utils/composeInjectedScript';
 
@@ -90,8 +91,16 @@ const SizedWebViewImpl = (props: SizedWebViewProps) => {
 
   const handleMessage = useCallback(
     (event: WebViewMessageEvent) => {
-      if (isJsEnabled) {
-        setHeightFromPayload(event.nativeEvent.data);
+      // Only bridge-prefixed strings can mutate the container height. Any
+      // other payload (user-land `postMessage('hello')`, numeric strings from
+      // the page, etc.) is forwarded untouched to the consumer's `onMessage`.
+      const data = event.nativeEvent.data;
+      if (
+        isJsEnabled &&
+        typeof data === 'string' &&
+        data.startsWith(BRIDGE_MESSAGE_PREFIX)
+      ) {
+        setHeightFromPayload(data);
       }
       onMessage?.(event);
     },
diff --git a/src/constants/autoHeightBridge.ts b/src/constants/autoHeightBridge.ts
@@ -70,6 +70,11 @@ export const AUTO_HEIGHT_BRIDGE = `(() => {
     cleanup: [],
     wrapper: null,
     mediaObserver: null,
+    // Dirty flag: set to true whenever the DOM mutates so that the next
+    // measure runs pruneTrailingNodes. Cleared after each prune pass. This
+    // skips the recursive hasRenderableContent DFS on every rAF tick during
+    // resize / font-load storms when no structural mutation has happened.
+    domDirty: true,
   };
 
   window[GLOBAL_KEY] = state;
@@ -267,6 +272,9 @@ export const AUTO_HEIGHT_BRIDGE = `(() => {
       break;
     }
 
+    // Mark the subtree as clean until the next MutationObserver callback.
+    state.domDirty = false;
+
     if (removed) {
       scheduleMeasure(true);
     }
@@ -310,31 +318,28 @@ export const AUTO_HEIGHT_BRIDGE = `(() => {
     var html = document.documentElement;
     var body = document.body;
     var wrapper = ensureWrapper();
-    var scrollingElement = document.scrollingElement;
 
-    pruneTrailingNodes(wrapper);
+    // Only walk the trailing-node DFS when something actually mutated since
+    // the last pass. Resize / font / viewport ticks don't change structure.
+    if (state.domDirty) {
+      pruneTrailingNodes(wrapper);
+    }
 
+    // Fast path: when the wrapper exists (it wraps every body child) its
+    // layout box is authoritative, so a single reflow via one element is
+    // enough. Reading multiple elements forces a reflow per read. Only fall
+    // back to html/body when the wrapper is unavailable.
     var targets = [];
 
     if (wrapper) {
       targets.push(wrapper);
-    }
-
-    if (body && targets.indexOf(body) === -1) {
-      targets.push(body);
-    }
-
-    if (html && targets.indexOf(html) === -1) {
-      targets.push(html);
-    }
-
-    if (
-      scrollingElement &&
-      scrollingElement !== body &&
-      scrollingElement !== html &&
-      targets.indexOf(scrollingElement) === -1
-    ) {
-      targets.push(scrollingElement);
+    } else {
+      if (body) {
+        targets.push(body);
+      }
+      if (html && html !== body) {
+        targets.push(html);
+      }
     }
 
     if (!targets.length) {
@@ -773,6 +778,7 @@ export const AUTO_HEIGHT_BRIDGE = `(() => {
     }
 
     var mutationObserver = new MutationObserver(function (mutations) {
+      state.domDirty = true;
       requestDebouncedMeasure();
 
       if (!state.wrapper || !document.contains(state.wrapper)) {
diff --git a/src/hooks/useAutoHeight.ts b/src/hooks/useAutoHeight.ts
@@ -40,10 +40,12 @@ export interface UseAutoHeightResult {
   /**
    * Handler for raw `onMessage` payloads from `react-native-webview`.
    *
-   * Accepts either the namespaced string the bridge emits
-   * (`"__RN_SIZED_WV__:<number>"`) or a bare numeric value (kept for backward
-   * compatibility with tests and custom integrations). Invalid, out-of-range,
-   * or sub-threshold values are silently ignored.
+   * Accepts only the namespaced string the bridge emits
+   * (`"__RN_SIZED_WV__:<number>"`) or a raw `number` (useful for direct /
+   * programmatic calls from tests and custom integrations). Bare numeric
+   * strings, invalid values, and out-of-range values are silently ignored —
+   * this is what prevents user-land `postMessage('123')` from mutating the
+   * container height.
    */
   setHeightFromPayload: (rawValue: unknown) => void;
 }
@@ -53,17 +55,28 @@ const HEIGHT_DIFF_THRESHOLD = 1;
 
 /**
  * Parses a raw payload into a positive finite pixel count, or `null` if the
- * value is unusable. Accepts the namespaced protocol string, plain numbers,
- * and numeric strings.
+ * value is unusable.
+ *
+ * Accepts:
+ * - `number` values (direct/programmatic calls — never reach the WebView).
+ * - Strings starting with {@link BRIDGE_MESSAGE_PREFIX} (bridge traffic).
+ *
+ * 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.
  */
 const parseHeightPayload = (rawValue: unknown): number | null => {
-  let candidate: unknown = rawValue;
+  let candidate: unknown;
 
-  if (
-    typeof candidate === 'string' &&
-    candidate.startsWith(BRIDGE_MESSAGE_PREFIX)
+  if (typeof rawValue === 'number') {
+    candidate = rawValue;
+  } else if (
+    typeof rawValue === 'string' &&
+    rawValue.startsWith(BRIDGE_MESSAGE_PREFIX)
   ) {
-    candidate = candidate.slice(BRIDGE_MESSAGE_PREFIX.length);
+    candidate = rawValue.slice(BRIDGE_MESSAGE_PREFIX.length);
+  } else {
+    return null;
   }
 
   const numericValue =
