<!-- source-hash: 67580105f9f032b02b2f1fd926ec7677 -->
A React hook that tracks which document section is currently visible in the viewport based on scroll position, and handles smooth navigation to sections when clicked.

## Key Components

### Constants

- **`SCROLL_OFFSET`** (`100px`) — Unified offset value used for both scroll-target positioning and active-section detection threshold, ensuring the highlight indicator stays in sync with the clicked section's resting position.

### Interfaces

- **`ScrollSpySection`** — Shape of a section entry (`id`, optional `title`, optional `level`)
- **`UseScrollSpyReturn`** — Hook return type exposing `activeSection` and `handleSectionClick`

### `useScrollSpy(sections)`

The primary export. Accepts an array of `ScrollSpySection` objects and returns:

| Return Value | Type | Description |
|---|---|---|
| `activeSection` | `string` | ID of the currently visible section |
| `handleSectionClick` | `(sectionId: string) => void` | Scrolls to the target section and pins it as active for 800ms |

**Scroll detection** is throttled at 100ms via `setTimeout` to avoid excessive re-renders. The scroll listener is bypassed while a programmatic click-scroll is in progress (`isScrollingFromClick` ref guard).

**Section stability** is maintained by comparing serialized IDs (`sectionIds` memo) to avoid unnecessary effect re-runs when the sections reference changes but content is identical.

## Usage Example

```typescript
import { useScrollSpy } from "./use-scroll-spy"

const sections = [
  { id: "introduction", title: "Introduction", level: 1 },
  { id: "installation", title: "Installation", level: 2 },
  { id: "configuration", title: "Configuration", level: 2 },
]

function DocSidebar() {
  const { activeSection, handleSectionClick } = useScrollSpy(sections)

  return (
    <nav>
      {sections.map(section => (
        <button
          key={section.id}
          onClick={() => handleSectionClick(section.id)}
          style={{ fontWeight: activeSection === section.id ? "bold" : "normal" }}
        >
          {section.title}
        </button>
      ))}
    </nav>
  )
}
```

**Source:** [`use-scroll-spy.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-scroll-spy.ts)