import { useState, useCallback, type RefCallback } from 'react';

export function useNodeBridge<T extends HTMLElement = HTMLElement>(): [
  T | null,
  RefCallback<T>
] {
  const [targetNode, setTargetNode] = useState<T | null>(null);

  const attachRef = useCallback<RefCallback<T>>((element) => {
    if (element !== targetNode) {
      setTargetNode(element);
    }
  }, [targetNode]);

  return [targetNode, attachRef];
}

import { useEffect, useRef, type RefCallback } from 'react';
import { useNodeBridge } from './useNodeBridge';

interface IntersectionConfig extends IntersectionObserverInit {
  haltOnFirstIntersection?: boolean;
}

export function useViewportIntersection<T extends HTMLElement = HTMLElement>(
  config: IntersectionConfig = {}
): [RefCallback<T>, IntersectionObserverEntry | undefined] {
  const [node, attachRef] = useNodeBridge<T>();
  const [entry, setEntry] = useState<IntersectionObserverEntry>();
  const observerRef = useRef<IntersectionObserver | null>(null);

  const { haltOnFirstIntersection = false, ...observerOptions } = config;

  useEffect(() => {
    if (!node) return;
    if (haltOnFirstIntersection && entry?.isIntersecting) return;

    observerRef.current = new IntersectionObserver(
      ([latestEntry]) => setEntry(latestEntry),
      observerOptions
    );

    observerRef.current.observe(node);

    return () => {
      observerRef.current?.disconnect();
      observerRef.current = null;
    };
  }, [node, observerOptions, haltOnFirstIntersection, entry?.isIntersecting]);

  return [attachRef, entry];
}

content dimensions without triggering layout thrashing. Unlike window.resize, it tracks individual element boundaries, making it ideal for responsive charts, dynamic typography, and canvas scaling.

import { useEffect, useRef, type RefCallback } from 'react';
import { useNodeBridge } from './useNodeBridge';

export function useLayoutMetrics<T extends HTMLElement = HTMLElement>(): [
  RefCallback<T>,
  DOMRectReadOnly | null
] {
  const [node, attachRef] = useNodeBridge<T>();
  const [metrics, setMetrics] = useState<DOMRectReadOnly | null>(null);
  const observerRef = useRef<ResizeObserver | null>(null);

  useEffect(() => {
    if (!node) return;

    observerRef.current = new ResizeObserver((entries) => {
      const firstEntry = entries[0];
      if (firstEntry) {
        setMetrics(firstEntry.contentRect);
      }
    });

    observerRef.current.observe(node);

    return () => {
      observerRef.current?.disconnect();
      observerRef.current = null;
    };
  }, [node]);

  return [attachRef, metrics];
}

Architecture Rationale: contentRect is extracted directly from the first entry, which aligns with single-element observation patterns. The hook returns null initially, allowing components to render placeholders until dimensions resolve. This avoids hydration mismatches in SSR environments.

Step 4: Structural Mutation Watching

MutationObserver tracks attribute shifts, child node additions, and text modifications. It requires strict configuration to prevent callback flooding.

import { useEffect, useRef, type RefCallback } from 'react';
import { useNodeBridge } from './useNodeBridge';

interface MutationConfig extends MutationObserverInit {
  debounceMs?: number;
}

export function useAttributeWatcher<T extends HTMLElement = HTMLElement>(
  config: MutationConfig = { attributes: true, childList: true }
): [RefCallback<T>, MutationRecord[] | null] {
  const [node, attachRef] = useNodeBridge<T>();
  const [records, setRecords] = useState<MutationRecord[] | null>(null);
  const observerRef = useRef<MutationObserver | null>(null);
  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);

  const { debounceMs = 0, ...observerOptions } = config;

  useEffect(() => {
    if (!node) return;

    const flushRecords = (batch: MutationRecord[]) => {
      if (debounceMs > 0) {
        if (timerRef.current) clearTimeout(timerRef.current);
        timerRef.current = setTimeout(() => setRecords(batch), debounceMs);
      } else {
        setRecords(batch);
      }
    };

    observerRef.current = new MutationObserver((mutations) => {
      flushRecords(mutations);
    });

    observerRef.current.observe(node, observerOptions);

    return () => {
      observerRef.current?.disconnect();
      observerRef.current = null;
      if (timerRef.current) clearTimeout(timerRef.current);
    };
  }, [node, observerOptions, debounceMs]);

  return [attachRef, records];
}

Why this structure: Mutation callbacks can fire dozens of times during a single DOM update cycle. The optional debounceMs parameter batches rapid changes into a single state update, drastically reducing React reconciliation overhead. Cleanup explicitly clears timers to prevent memory leaks during fast component unmounting.

Pitfall Guide

1. Observer Recreation on Every Render

Explanation: Instantiating observers directly in the component body or inside useEffect without stable references causes the browser to tear down and rebuild observers on every state change. This spikes CPU usage and breaks observation continuity. Fix: Always store observer instances in useRef. Initialize them inside useEffect and only recreate them when configuration options or target nodes actually change.

2. Missing Disconnection in Cleanup

Explanation: Forgetting to call .disconnect() in the effect cleanup function leaves observers attached to detached DOM nodes. This creates memory leaks and causes callbacks to fire on unmounted components, triggering state updates on dead trees. Fix: Every useEffect that creates an observer must return a cleanup function that calls .disconnect() and nullifies the ref. Test this by rapidly mounting/unmounting components in development.

3. The MutationObserver Firehose

Explanation: Enabling subtree: true alongside broad attributeFilter or childList: true on a large component tree generates hundreds of mutation records per second. React attempts to reconcile each record, freezing the UI. Fix: Narrow observation scope. Use attributeFilter: ['specific-attr'] instead of watching all attributes. Disable subtree unless child mutations are explicitly required. Implement debouncing or requestAnimationFrame batching for heavy mutation streams.

4. Ref Instability Causing Infinite Loops

Explanation: Using a standard useRef and manually updating .current inside a callback ref can trigger re-renders if the callback is recreated on every render. This creates an infinite loop where the observer reattaches continuously. Fix: Use a stable callback ref pattern with an equality check before updating state. Wrap the ref callback in useCallback with a dependency on the current node value to guarantee referential stability.

5. Blocking the Observer Callback

Explanation: Performing expensive calculations, network requests, or synchronous DOM queries inside the observer callback defeats the purpose of asynchronous batching. The browser defers the callback, but your logic still blocks the main thread when it executes. Fix: Keep observer callbacks lightweight. Only update React state or queue microtasks. Defer heavy computation to useEffect hooks that react to the state change, or schedule work with requestIdleCallback.

6. SSR Hydration Mismatches

Explanation: Observer APIs do not exist in Node.js environments. Attempting to instantiate them during server rendering throws ReferenceError: IntersectionObserver is not defined, breaking hydration. Fix: Guard all observer instantiation with typeof window !== 'undefined' checks. Alternatively, use dynamic imports or return null/placeholder values during SSR, allowing the client-side effect to initialize observation after hydration completes.

Production Bundle

Action Checklist

• Verify node bridge stability: Ensure callback refs only update state when the DOM element actually changes
• Implement deterministic cleanup: Every observer must disconnect and nullify its ref in the effect return function
• Configure mutation scope: Restrict MutationObserver to specific attributes or direct children; avoid subtree: true unless necessary
• Add debounce batching: Apply debounceMs or requestAnimationFrame to high-frequency mutation or resize callbacks
• Guard against SSR: Wrap observer instantiation in environment checks or defer initialization to client-side effects
• Test strict mode: Mount/unmount components rapidly in React 18 strict mode to verify no double-attachment or memory leaks
• Profile main thread: Use Chrome DevTools Performance tab to confirm observer callbacks do not block the main thread during scroll/resize events

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Lazy loading images or tracking scroll analytics	useViewportIntersection with haltOnFirstIntersection	Batches visibility checks off-main-thread; stops observing after trigger	Low CPU, minimal re-renders
Responsive charts or dynamic canvas sizing	useLayoutMetrics	Provides precise contentRect without layout thrashing; ignores viewport changes	Low memory, predictable updates
Syncing with third-party widget attributes	useAttributeWatcher with attributeFilter	Targets specific DOM mutations; debounce prevents callback flooding	Medium setup, high stability
CSS breakpoint synchronization	useMediaQuery (matchMedia wrapper)	Native browser optimization for CSSOM changes; avoids layout recalculation	Negligible overhead
Complex multi-element tracking	Compose individual hooks per element	Keeps observation scope isolated; prevents cross-component state coupling	Higher initial code, lower runtime cost

Configuration Template

// hooks/useDomObservation.ts
import { useEffect, useRef, useCallback, useState } from 'react';

export function useStableNodeRef<T extends HTMLElement = HTMLElement>(): [
  T | null,
  (node: T | null) => void
] {
  const [node, setNode] = useState<T | null>(null);
  const setRef = useCallback(
    (newNode: T | null) => {
      if (newNode !== node) setNode(newNode);
    },
    [node]
  );
  return [node, setRef];
}

export function useObserverLifecycle<T extends IntersectionObserver | ResizeObserver | MutationObserver>(
  factory: () => T,
  node: HTMLElement | null
): T | null {
  const observerRef = useRef<T | null>(null);

  useEffect(() => {
    if (!node) return;
    observerRef.current = factory();
    return () => {
      observerRef.current?.disconnect();
      observerRef.current = null;
    };
  }, [node, factory]);

  return observerRef.current;
}

Quick Start Guide

1. Install the base bridge: Copy useStableNodeRef into your hooks directory. This provides the stable DOM node acquisition layer required for all observers.
2. Choose your observation type: Import useViewportIntersection for visibility tracking, useLayoutMetrics for dimension changes, or useAttributeWatcher for DOM structure monitoring.
3. Attach to your component: Destructure the returned ref callback and pass it to your JSX element: <div ref={attachRef}>.
4. Consume the data: Use the second return value (entry, metrics, or records) inside your component logic or downstream useEffect hooks.
5. Validate in production: Run Chrome DevTools Performance profiling during scroll/resize events. Confirm that observer callbacks execute asynchronously and do not spike main-thread utilization.