<!-- source-hash: f4d365e1aafe7c4342c44a64be1e2e6e -->
Defines the shared `MediaItem` data contract and lightweight accessor utilities used by media carousel components across the OpenFrame platform.

## Key Components

### `MediaItem` Interface

Core data shape for a single carousel slide. Supports three media types:

| Field | Type | Description |
|---|---|---|
| `id` | `string?` | Optional stable key (omitted by most vendor/profile/category converters) |
| `type` | `'image' \| 'video' \| 'youtube'` | Media kind — drives rendering strategy |
| `src` | `string` | Media source URL |
| `alt` | `string?` | Accessibility alt text |
| `title` | `string?` | Display title |
| `caption` | `string?` | Slide caption |
| `poster` | `string?` | Video poster/placeholder image |
| `thumbnail` | `string?` | Thumbnail URL |
| `width` / `height` | `number?` | Intrinsic dimensions |
| `duration` | `number?` | Video duration in seconds |

### Accessor Functions

| Function | Returns | Description |
|---|---|---|
| `getMediaType(item)` | `'image' \| 'video' \| 'youtube'` | Extracts the media type from an item |
| `getMediaSrc(item)` | `string` | Extracts the source URL |
| `getMediaPoster(item)` | `string \| undefined` | Extracts the video poster image URL |

## Usage Example

```typescript
import { MediaItem, getMediaType, getMediaSrc, getMediaPoster } from './media-carousel-utils-stub';

const slide: MediaItem = {
  type: 'video',
  src: 'https://cdn.example.com/clip.mp4',
  poster: 'https://cdn.example.com/thumb.jpg',
  title: 'Product Demo',
  duration: 120,
};

const type = getMediaType(slide);   // 'video'
const src = getMediaSrc(slide);     // 'https://cdn.example.com/clip.mp4'
const poster = getMediaPoster(slide); // 'https://cdn.example.com/thumb.jpg'
```

> **Note:** The carousel keys slides by array index rather than `item.id`. Converters (hub vendor, profile, and category) conventionally omit the `id` field.