<!-- source-hash: 8512b2544239a58f8faa59a6fd3794a7 -->
Accessible, memoized React carousel component for displaying mixed media (images, videos, YouTube embeds) with dot pagination, keyboard navigation, touch swipe support, and broken-image fallback handling.

## Key Components

### `MediaCarousel` (default export)
A `memo`-wrapped component implementing the canonical slide viewer used across OpenFrame homepage categories, vendor screenshots, profiles, and Reddit embeds.

**Props (`MediaCarouselProps`):**

| Prop | Type | Default | Description |
|---|---|---|---|
| `media` | `MediaItem[]` | — | Array of slide descriptors |
| `aspectRatio` | `'16/9' \| '4/3' \| '3/2' \| '1/1'` | `'16/9'` | Container aspect ratio |
| `showArrows` | `boolean` | `true` | Hover-revealed prev/next arrows |
| `objectFit` | `'contain' \| 'cover'` | `'contain'` | Image fit within container |
| `posterPriority` | `boolean` | `false` | Eager-loads first slide (LCP optimization) |
| `transformImageSrc` | `(url: string) => string` | — | URL rewrite hook (e.g. proxy `http://` sources) |
| `reserveDotRow` | `boolean` | `false` | Always reserves dot-row height to prevent layout shift on media set swaps |

### Internal Helpers

| Function | Description |
|---|---|
| `renderVideo` | Routes `video`/`youtube` items through the `<Video>` SSoT component |
| `renderImage` | Renders images with skeleton loading, opacity fade-in, and broken-URL fallback UI |
| `renderImageUnavailable` | Fallback UI with `ImageOffIcon` and original URL link when image 404s |
| `renderMainMedia` | Dispatches to `renderVideo` or `renderImage` based on `item.type` |
| `getAspectRatioClass` | Maps `aspectRatio` prop to Tailwind aspect-ratio class |

## Usage Example

```typescript
import { MediaCarousel } from './media-carousel';
import type { MediaItem } from '../utils/media-carousel-utils-stub';

const slides: MediaItem[] = [
  { type: 'image', src: 'https://cdn.example.com/screenshot.png', alt: 'Dashboard' },
  { type: 'youtube', src: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ', alt: 'Demo' },
  { type: 'video', src: 'https://stream.mux.com/video.m3u8', poster: 'https://cdn.example.com/poster.jpg' },
];

// Vendor detail page — prioritize first image for LCP, proxy mixed content
<MediaCarousel
  media={slides}
  aspectRatio="16/9"
  objectFit="contain"
  posterPriority
  transformImageSrc={(url) => url.replace('http://', 'https://proxy.example.com/')}
/>

// Categories showcase — reserve dot row so 1-vs-N-slide swap never shifts layout
<MediaCarousel
  media={categorySlides}
  reserveDotRow
  showArrows={false}
/>
```

## Interaction Model

- **Touch:** Swipe threshold of 50px triggers `nextSlide`/`prevSlide`; edge-case `clientX === 0` handled via explicit `null` checks (not truthiness).
- **Keyboard:** `ArrowLeft`/`ArrowRight` when the carousel `<div>` has focus; disabled for single-slide sets.
- **Index safety:** `currentIndex` is clamped via `useEffect` whenever `media.length` shrinks at runtime.
- **Image loading:** Each image is keyed by URL (`loadedImageSrc`), preventing a late `onLoad` from a previous slide from revealing the current image prematurely.

## Source

[`media-carousel.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/media-carousel.tsx)