<!-- source-hash: 22dd3f53bc1b8db26b9d173ca6be7427 -->
A React hook that detects when an element is approaching the viewport using a shared, module-level `IntersectionObserver` pool — one observer instance per unique `rootMargin` value, shared across all components using the hook.

## Key Components

| Export | Type | Description |
|--------|------|-------------|
| `useNearViewport` | Hook | Main hook; returns `ref` and `isNear` state |
| `UseNearViewportResult` | Interface | Return type generic over element type `T` |
| `getObserverFor` | Internal | Lazily creates/retrieves a shared `IntersectionObserver` per `rootMargin` |
| `observers` | `Map<string, IntersectionObserver>` | Module-level singleton pool keyed by `rootMargin` |
| `subscribers` | `WeakMap<Element, () => void>` | Tracks per-element callbacks; auto-GC'd when elements are removed |

## Usage Example

```typescript
import { useNearViewport } from './use-near-viewport';

// Basic lazy-render pattern
function MediaCard() {
  const { ref, isNear } = useNearViewport('500px');
  return (
    <div ref={ref}>
      {isNear ? <HeavyMediaComponent /> : <Placeholder />}
    </div>
  );
}

// Strict on-screen detection
function AnalyticsTracker() {
  const { ref, isNear } = useNearViewport('0px');
  useEffect(() => {
    if (isNear) trackImpression();
  }, [isNear]);
  return <div ref={ref} />;
}
```

## Behavior Notes

- **Fires once**: `isNear` flips to `true` on first intersection and never resets; the element is unobserved immediately after
- **Shared observers**: All components using the same `rootMargin` share a single `IntersectionObserver` — efficient for grid/list pages with many cards
- **StrictMode safe**: Cleanup uses callback identity checks to survive React's dev-mode double-mount cycle without dropping subscriptions
- **Race safe**: IO callback re-reads `subscribers` at fire time so late-firing callbacks after unmount cannot invoke stale state setters