<!-- source-hash: 9f63d7c2dd408b85d0a130f82da97780 -->
Custom React hook for building a fully controlled horizontal scrollbar with drag, click-to-seek, wheel forwarding, edge-fade indicators, and RAF-throttled sync — all driven directly against the DOM without relying on native scrollbar styling.

## Key Components

| Export | Type | Description |
|--------|------|-------------|
| `useHorizontalScrollbar` | Hook | Main hook returning all refs, state, and event handlers |
| `scrollRef` | Callback ref | Attach to the scrollable container; auto-sets up `ResizeObserver` |
| `trackRef` | `RefObject<HTMLDivElement>` | Attach to the scrollbar track element |
| `thumbRef` | `RefObject<HTMLDivElement>` | Attach to the draggable thumb element |
| `thumbRatio` | `number` | Thumb width as a fraction of track width (`0` = hidden) |
| `canScrollLeft` | `boolean` | Whether content can scroll further left (for edge fades) |
| `canScrollRight` | `boolean` | Whether content can scroll further right (for edge fades) |

**Event Handlers Returned:**

| Handler | Attach To |
|---------|-----------|
| `onScroll` | Scrollable container `onScroll` |
| `onTrackClick` | Track element `onClick` |
| `onTrackWheel` | Track element `onWheel` |
| `onThumbPointerDown` | Thumb `onPointerDown` |
| `onThumbPointerMove` | Thumb `onPointerMove` |
| `onThumbPointerUp` | Thumb `onPointerUp` |

## Usage Example

```typescript
import { useHorizontalScrollbar } from './use-horizontal-scrollbar'

function ScrollableTable() {
  const {
    scrollRef, trackRef, thumbRef,
    thumbRatio, canScrollLeft, canScrollRight,
    onScroll, onTrackClick, onTrackWheel,
    onThumbPointerDown, onThumbPointerMove, onThumbPointerUp,
  } = useHorizontalScrollbar()

  return (
    <div>
      {canScrollLeft && <div className="fade-left" />}

      {/* Scrollable content */}
      <div ref={scrollRef} onScroll={onScroll} style={{ overflowX: 'auto' }}>
        <table>{/* wide content */}</table>
      </div>

      {canScrollRight && <div className="fade-right" />}

      {/* Custom scrollbar */}
      {thumbRatio > 0 && (
        <div
          ref={trackRef}
          onClick={onTrackClick}
          onWheel={onTrackWheel}
          style={{ position: 'relative', height: 8 }}
        >
          <div
            ref={thumbRef}
            data-scrollbar-thumb
            onPointerDown={onThumbPointerDown}
            onPointerMove={onThumbPointerMove}
            onPointerUp={onThumbPointerUp}
            style={{ position: 'absolute', width: `${thumbRatio * 100}%`, cursor: 'grab' }}
          />
        </div>
      )}
    </div>
  )
}
```

> **Performance note:** Thumb position is written directly to `thumb.style.left` via `requestAnimationFrame`, bypassing React re-renders on every scroll event. Only `thumbRatio`, `canScrollLeft`, and `canScrollRight` trigger state updates.