@envive-ai/react-hooks 0.3.60 → 0.3.61

package/src/hooks/Intersection/__tests__/useIntersection.test.ts

@@ -1,6 +1,12 @@
 import { act, renderHook } from '@testing-library/react';
 import { RefObject } from 'react';
-import { useIntersection } from '../useIntersection';
+import Logger from 'src/application/logging/logger';
+import {
+  VISIBILITY_FALLBACK_GRACE_MS,
+  VISIBILITY_FALLBACK_INTERVAL_MS,
+  VISIBILITY_FOREGROUND_GRACE_MS,
+  useIntersection,
+} from '../useIntersection';
 
 class MockIntersectionObserver {
   static instances: MockIntersectionObserver[] = [];
@@ -131,4 +137,223 @@ describe('useIntersection', () => {
 
     expect(lastObserver().disconnected).toBe(true);
   });
+
+  describe('visibility fallback', () => {
+    let logErrorSpy: ReturnType<typeof vi.spyOn>;
+
+    const rect = (partial: Partial<DOMRect>): DOMRect => {
+      const base = {
+        top: 0,
+        left: 0,
+        bottom: 0,
+        right: 0,
+        x: 0,
+        y: 0,
+        toJSON: () => ({}),
+        ...partial,
+      };
+      // Derive area from the bounds like a real DOMRect, unless explicitly overridden, so
+      // the on-screen guard (width/height > 0) sees realistic geometry.
+      return {
+        ...base,
+        width: partial.width ?? base.right - base.left,
+        height: partial.height ?? base.bottom - base.top,
+      } as DOMRect;
+    };
+
+    const connectedNode = (nodeRect: Partial<DOMRect>) => {
+      const node = document.createElement('span');
+      document.body.appendChild(node);
+      vi.spyOn(node, 'getBoundingClientRect').mockReturnValue(rect(nodeRect));
+      return node;
+    };
+
+    beforeEach(() => {
+      vi.useFakeTimers();
+      logErrorSpy = vi.spyOn(Logger.prototype, 'logError').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+      logErrorSpy.mockRestore();
+      document.body.innerHTML = '';
+    });
+
+    it('reports visibility and logs an error when an on-screen element is never reported by the observer', () => {
+      const node = connectedNode({ top: 100, bottom: 300, left: 0, right: 200 });
+      const ref: RefObject<HTMLElement> = { current: node };
+
+      const { result } = renderHook(() =>
+        useIntersection(ref, '0px', { widget_type: 'ProductCardV3' }),
+      );
+      expect(result.current).toBe(false);
+
+      // First check happens after the grace window.
+      act(() => {
+        vi.advanceTimersByTime(VISIBILITY_FALLBACK_GRACE_MS);
+      });
+
+      expect(result.current).toBe(true);
+      expect(logErrorSpy).toHaveBeenCalledTimes(1);
+      const [message, , context] = logErrorSpy.mock.calls[0];
+      expect(message).toContain('Visibility fallback engaged');
+      expect(context).toMatchObject({ widget_type: 'ProductCardV3' });
+
+      // Fires at most once — once visible, the reconciliation loop stops
+      act(() => {
+        vi.advanceTimersByTime(VISIBILITY_FALLBACK_INTERVAL_MS * 3);
+      });
+      expect(logErrorSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not engage for an element that is genuinely off screen', () => {
+      const node = connectedNode({ top: 5000, bottom: 5200, left: 0, right: 200 });
+      const ref: RefObject<HTMLElement> = { current: node };
+
+      const { result } = renderHook(() => useIntersection(ref, '0px'));
+
+      act(() => {
+        vi.advanceTimersByTime(VISIBILITY_FALLBACK_GRACE_MS + VISIBILITY_FALLBACK_INTERVAL_MS * 4);
+      });
+
+      expect(result.current).toBe(false);
+      expect(logErrorSpy).not.toHaveBeenCalled();
+    });
+
+    it('does not engage when the observer reports visibility first', () => {
+      const node = connectedNode({ top: 100, bottom: 300, left: 0, right: 200 });
+      const ref: RefObject<HTMLElement> = { current: node };
+
+      const { result } = renderHook(() => useIntersection(ref, '0px'));
+      act(() => {
+        lastObserver().fire(true, node);
+      });
+      expect(result.current).toBe(true);
+
+      act(() => {
+        vi.advanceTimersByTime(VISIBILITY_FALLBACK_GRACE_MS + VISIBILITY_FALLBACK_INTERVAL_MS * 4);
+      });
+
+      expect(logErrorSpy).not.toHaveBeenCalled();
+    });
+
+    it('does not engage for a detached node', () => {
+      const node = document.createElement('span');
+      vi.spyOn(node, 'getBoundingClientRect').mockReturnValue(
+        rect({ top: 100, bottom: 300, left: 0, right: 200 }),
+      );
+      const ref: RefObject<HTMLElement> = { current: node };
+
+      const { result } = renderHook(() => useIntersection(ref, '0px'));
+
+      act(() => {
+        vi.advanceTimersByTime(VISIBILITY_FALLBACK_GRACE_MS + VISIBILITY_FALLBACK_INTERVAL_MS * 4);
+      });
+
+      expect(result.current).toBe(false);
+      expect(logErrorSpy).not.toHaveBeenCalled();
+    });
+
+    it('recovers on foreground (visibilitychange) without waiting for the poll interval', () => {
+      const node = connectedNode({ top: 100, bottom: 300, left: 0, right: 200 });
+      const ref: RefObject<HTMLElement> = { current: node };
+
+      const { result } = renderHook(() =>
+        useIntersection(ref, '0px', { widget_type: 'ProductCardV3' }),
+      );
+      expect(result.current).toBe(false);
+
+      // Tab returns to foreground; the grace is far shorter than the poll interval.
+      act(() => {
+        document.dispatchEvent(new Event('visibilitychange'));
+        vi.advanceTimersByTime(VISIBILITY_FOREGROUND_GRACE_MS);
+      });
+
+      expect(result.current).toBe(true);
+      expect(logErrorSpy).toHaveBeenCalledTimes(1);
+      expect(logErrorSpy.mock.calls[0][2]).toMatchObject({ widget_type: 'ProductCardV3' });
+    });
+
+    it('does not engage on foreground when the observer re-fires within the grace window', () => {
+      const node = connectedNode({ top: 100, bottom: 300, left: 0, right: 200 });
+      const ref: RefObject<HTMLElement> = { current: node };
+
+      const { result } = renderHook(() => useIntersection(ref, '0px'));
+
+      // Foreground schedules the grace check...
+      act(() => {
+        document.dispatchEvent(new Event('visibilitychange'));
+      });
+      // ...but a healthy observer re-fires first (in its own flush, as it would in the
+      // browser within a frame), flipping isVisible and tearing down the grace timer.
+      act(() => {
+        lastObserver().fire(true, node);
+      });
+      act(() => {
+        vi.advanceTimersByTime(VISIBILITY_FOREGROUND_GRACE_MS * 2);
+      });
+
+      expect(result.current).toBe(true);
+      expect(logErrorSpy).not.toHaveBeenCalled();
+    });
+
+    it('does not engage on foreground while the document is still hidden', () => {
+      const node = connectedNode({ top: 100, bottom: 300, left: 0, right: 200 });
+      const ref: RefObject<HTMLElement> = { current: node };
+      const visibilitySpy = vi.spyOn(document, 'visibilityState', 'get').mockReturnValue('hidden');
+
+      const { result } = renderHook(() => useIntersection(ref, '0px'));
+
+      act(() => {
+        document.dispatchEvent(new Event('visibilitychange'));
+        vi.advanceTimersByTime(VISIBILITY_FOREGROUND_GRACE_MS);
+      });
+
+      expect(result.current).toBe(false);
+      expect(logErrorSpy).not.toHaveBeenCalled();
+      visibilitySpy.mockRestore();
+    });
+
+    it('does not engage for a zero-area element within the viewport (unlaid-out / collapsed)', () => {
+      // An inline wrapper that has not laid out its content yet reports a zero-area rect at
+      // a viewport position. That is genuinely not-visible, not something the observer missed.
+      const node = connectedNode({ top: 100, bottom: 100, left: 50, right: 50 });
+      const ref: RefObject<HTMLElement> = { current: node };
+
+      const { result } = renderHook(() => useIntersection(ref, '0px'));
+
+      act(() => {
+        vi.advanceTimersByTime(VISIBILITY_FALLBACK_GRACE_MS + VISIBILITY_FALLBACK_INTERVAL_MS * 4);
+      });
+
+      expect(result.current).toBe(false);
+      expect(logErrorSpy).not.toHaveBeenCalled();
+    });
+
+    it('recovers a stuck on-screen element even while the document is hidden, but stays silent', () => {
+      // The environments this fallback exists for — iOS/WebKit in-app webviews and bfcache
+      // restores — can report the document as hidden while the shopper is actually looking at
+      // it, so recovery must NOT be gated on visibility (that was the CircleCI failure: a
+      // headless page reports non-visible and the widget never un-stuck). The error, however,
+      // is only a genuine signal when the page is visible — a suppressed observer in a real
+      // background tab is expected, not a bug — so it must not fire here and flood telemetry.
+      const node = connectedNode({ top: 100, bottom: 300, left: 0, right: 200 });
+      const ref: RefObject<HTMLElement> = { current: node };
+      const visibilitySpy = vi
+        .spyOn(document, 'visibilityState', 'get')
+        .mockReturnValue('hidden');
+
+      const { result } = renderHook(() =>
+        useIntersection(ref, '0px', { widget_type: 'ProductCardV3' }),
+      );
+
+      act(() => {
+        vi.advanceTimersByTime(VISIBILITY_FALLBACK_GRACE_MS);
+      });
+
+      expect(result.current).toBe(true); // recovered despite being "hidden"
+      expect(logErrorSpy).not.toHaveBeenCalled(); // but no false-positive error logged
+      visibilitySpy.mockRestore();
+    });
+  });
 });

package/src/hooks/Intersection/useIntersection.ts

@@ -3,11 +3,49 @@ import Logger from 'src/application/logging/logger';
 
 const logger = new Logger('useIntersection');
 
+// How long to wait before the fallback's FIRST reconcile. Long enough that a healthy
+// IntersectionObserver has delivered its initial callback (so we don't falsely flag a
+// normally-loading widget), short enough to keep the worst-case blank window small.
+// Exported for tests.
+export const VISIBILITY_FALLBACK_GRACE_MS = 1000;
+
+// How often the fallback re-checks after the initial grace. A genuinely stuck widget
+// recovers within grace + one interval (~1.3s). Exported for tests.
+export const VISIBILITY_FALLBACK_INTERVAL_MS = 300;
+
+// After the tab returns to the foreground, how long to wait before the fast-path reconcile —
+// long enough for a healthy observer to re-fire on its own (so we don't falsely flag it),
+// short enough that recovery is near-instant. Exported for tests.
+export const VISIBILITY_FOREGROUND_GRACE_MS = 200;
+
+const isOnScreen = (node: HTMLElement): boolean => {
+  const rect = node.getBoundingClientRect();
+  // Require real area: an element that has not laid out yet (a 0×0 inline wrapper mid-mount)
+  // or is collapsed to zero by an overflow-clipping ancestor is not something the observer
+  // wrongly missed — it is genuinely not visible. display:none subtrees report an all-zero
+  // rect and are excluded here too.
+  if (rect.width <= 0 || rect.height <= 0) {
+    return false;
+  }
+  return (
+    rect.top < window.innerHeight &&
+    rect.bottom > 0 &&
+    rect.left < window.innerWidth &&
+    rect.right > 0
+  );
+};
+
 // https://rasilbaidar.medium.com/trigger-event-when-element-enters-viewport-the-react-way-168509da2e23
-export const useIntersection = (element: RefObject<HTMLElement>, rootMargin: string) => {
+export const useIntersection = (
+  element: RefObject<HTMLElement>,
+  rootMargin: string,
+  logContext?: Record<string, unknown>,
+) => {
   const [isVisible, setIsVisible] = useState(false);
   const observerRef = useRef<IntersectionObserver | null>(null);
   const observedNodeRef = useRef<HTMLElement | null>(null);
+  const logContextRef = useRef(logContext);
+  logContextRef.current = logContext;
 
   // Runs after every render so it catches when element.current transitions from null to a
   // mounted DOM node, AND when the node under the ref is replaced. The replacement case is
@@ -18,35 +56,18 @@ export const useIntersection = (element: RefObject<HTMLElement>, rootMargin: str
   // keeping per-render cost O(1).
   useEffect(() => {
     const current = element?.current;
-    logger.logDebug('effect ran', {
-      elementCurrent: current,
-      rootMargin,
-      alreadyObserving: !!observerRef.current,
-      observingCurrentNode: observedNodeRef.current === current,
-    });
-
     if (!current) {
-      logger.logDebug('element.current is null — observer NOT attached');
       return;
     }
     if (observedNodeRef.current === current) return; // already observing this exact node
 
     if (observerRef.current) {
-      logger.logDebug('observed node was replaced — re-attaching observer', {
-        previousNode: observedNodeRef.current,
-        newNode: current,
-      });
+      // Node under the ref was replaced — drop the observer on the detached node.
       observerRef.current.disconnect();
     }
 
     const observer = new IntersectionObserver(
       ([entry]) => {
-        logger.logDebug('IntersectionObserver fired', {
-          isIntersecting: entry.isIntersecting,
-          intersectionRatio: entry.intersectionRatio,
-          boundingClientRect: entry.boundingClientRect,
-          target: entry.target,
-        });
         setIsVisible(entry.isIntersecting);
       },
       { rootMargin },
@@ -55,9 +76,80 @@ export const useIntersection = (element: RefObject<HTMLElement>, rootMargin: str
     observer.observe(current);
     observerRef.current = observer;
     observedNodeRef.current = current;
-    logger.logDebug('observer attached to element', current);
   });
 
+  // Safety net: visibility detection must not be a single point of failure. While the
+  // observer reports not-visible, periodically reconcile against the element's actual
+  // position; an element that is on screen while the observer stayed silent means
+  // observation is broken for a reason we haven't met yet (wrapped/overridden
+  // IntersectionObserver, engine quirk, a failure mode like the stale-node bug). Report it
+  // as a console error (so session tools can count affected sessions) and treat the
+  // element as visible so it still loads.
+  useEffect(() => {
+    if (isVisible) {
+      return undefined;
+    }
+
+    const reconcile = () => {
+      const node = element?.current;
+      if (!node || !node.isConnected) {
+        return;
+      }
+      if (isOnScreen(node)) {
+        // Recover the widget regardless of document.visibilityState. The environments this
+        // fallback exists for — iOS/WebKit in-app webviews and bfcache restores — can report
+        // the document as hidden even while the shopper is looking at it, so gating recovery
+        // on visibility would defeat the fix in exactly those cases. Only LOG a genuine
+        // failure when the page is actually visible, so a legitimately suppressed observer in
+        // a hidden/background tab does not flood error telemetry with false positives.
+        if (document.visibilityState === 'visible') {
+          logger.logError(
+            'Visibility fallback engaged — element is on screen but IntersectionObserver never reported it',
+            undefined,
+            {
+              ...logContextRef.current,
+              fallback_interval_ms: VISIBILITY_FALLBACK_INTERVAL_MS,
+            },
+          );
+        }
+        setIsVisible(true);
+      }
+    };
+
+    // Give the real observer a grace window to deliver its initial callback, then poll on a
+    // shorter cadence so a genuinely stuck widget recovers quickly.
+    let interval: ReturnType<typeof setInterval> | undefined;
+    const grace = setTimeout(() => {
+      reconcile();
+      interval = setInterval(reconcile, VISIBILITY_FALLBACK_INTERVAL_MS);
+    }, VISIBILITY_FALLBACK_GRACE_MS);
+
+    // Fast path: a widget composited while the tab was hidden can have its
+    // IntersectionObserver suppressed, and some engines fail to re-fire it when the tab
+    // returns to the foreground for an element already in the viewport. On visibility
+    // change, reconcile after a short grace — if a healthy observer re-fires first,
+    // isVisible flips and this effect tears the timer down before it runs.
+    let foregroundCheck: ReturnType<typeof setTimeout> | undefined;
+    const onVisibilityChange = () => {
+      if (document.visibilityState !== 'visible') {
+        return;
+      }
+      foregroundCheck = setTimeout(reconcile, VISIBILITY_FOREGROUND_GRACE_MS);
+    };
+    document.addEventListener('visibilitychange', onVisibilityChange);
+
+    return () => {
+      clearTimeout(grace);
+      if (interval !== undefined) {
+        clearInterval(interval);
+      }
+      document.removeEventListener('visibilitychange', onVisibilityChange);
+      if (foregroundCheck !== undefined) {
+        clearTimeout(foregroundCheck);
+      }
+    };
+  }, [isVisible, element]);
+
   // Disconnect on unmount only — intentionally separate from the setup effect above.
   useEffect(() => {
     return () => {

package/src/hooks/TrackComponentVisibleEvent/useTrackComponentVisibleEvent.ts

@@ -35,7 +35,9 @@ export const useTrackComponentVisibleEvent = (
   rootMargin: string = '0px',
   enabled: boolean = true,
 ): { isVisible: boolean } => {
-  const isVisible = useIntersection(element, rootMargin);
+  // eventProps (widget_config_id, widget_type, …) double as log context so the hook's
+  // visibility-fallback error identifies which widget it rescued.
+  const isVisible = useIntersection(element, rootMargin, eventProps);
   const hasTrackedEvent = useRef(false);
   const { trackEvent } = useAmplitude();
   const variantInfo = useAtomValue(pageVariantInfoAtom);