AkurAI-Framework / site/content/docs/ai-media.md

Latest change 36f53e8d189d0609aaabc65e705cf9db9d497d14 - Port Media components as vanilla ES modules by Ólafur Búi Ólafsson

# Media Components

A collection of native HTML media components for rendering images, galleries, videos, and audio in the AI chat interface.

## Image

Renders a responsive image card with optional caption. Uses lazy loading and aspect-ratio preservation.

**Payload shape:**
```js
{
  src: string,        // Required. Image URL (sets directly to <img src>).
  alt?: string,       // Optional. Alt text for accessibility.
  caption?: string    // Optional. Caption text below the image.
}
```

**Example:**
```js
{
  src: "https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800",
  alt: "Mountain landscape",
  caption: "A serene mountain landscape at sunset"
}
```

**Rendering:**
- Image wrapped in a `.card` container
- Responsive: 100% width, auto height
- Optional caption in muted gray text
- Lazy loading enabled (`loading="lazy"`)

---

## Image Gallery

Renders a responsive grid of thumbnails with a lightbox overlay. Click any image to enlarge it; press Esc or click the overlay to close.

**Payload shape:**
```js
{
  images: Array<{
    src: string,      // Required. Image URL.
    alt?: string      // Optional. Alt text for the thumbnail.
  }>
}
```

**Example:**
```js
{
  images: [
    { src: "https://example.com/photo1.jpg", alt: "Mountain" },
    { src: "https://example.com/photo2.jpg", alt: "Valley" },
    { src: "https://example.com/photo3.jpg", alt: "Lake" }
  ]
}
```

**Rendering:**
- Grid container with auto-fit columns (min 150px, max 1fr)
- Thumbnail hover effect: slight zoom on hover
- Click to open full-screen lightbox
- Lightbox has semi-transparent dark overlay
- Image-specific alt text shown in lightbox caption
- Esc key or click-outside to close

---

## Video

Renders a native `<video>` element with browser controls and optional caption.

**Payload shape:**
```js
{
  src: string,        // Required. Video URL (sets directly to <video src>).
  poster?: string,    // Optional. Poster image URL (preview frame).
  caption?: string    // Optional. Caption text below the video.
}
```

**Example:**
```js
{
  src: "https://commondatastorage.googleapis.com/gtv-videos-library/sample/big_buck_bunny.mp4",
  poster: "https://peach.blender.org/wp-content/uploads/image/poster_bunny.png",
  caption: "Sample video — Big Buck Bunny"
}
```

**Rendering:**
- Native `<video controls>` — full browser playback controls (play, pause, volume, fullscreen, etc.)
- Responsive: 100% width, auto height
- Poster image shown before play
- Optional caption in muted gray text
- Black background during playback

---

## Audio

Renders a native `<audio>` element with browser controls and optional title.

**Payload shape:**
```js
{
  src: string,      // Required. Audio URL (sets directly to <audio src>).
  title?: string    // Optional. Title text above the player.
}
```

**Example:**
```js
{
  src: "https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3",
  title: "Sample audio track"
}
```

**Rendering:**
- Optional title in bold, full-color text
- Native `<audio controls>` — browser playback controls (play, pause, volume, seek, etc.)
- Responsive: 100% width
- Clean, minimal styling

---

## Design Notes

### Lazy Loading

Images and galleries use `loading="lazy"` to defer loading off-screen images until they're about to be scrolled into view. This speeds up initial page load, especially in long conversations.

### XSS Safety

All components safely set `src`, `alt`, `href`, and text content from the payload. No `innerHTML` is used. Text content is set via `textContent`, preventing injection.

### Native Elements

Components use browser-native `<img>`, `<video>`, and `<audio>` elements — no custom players, no libraries. Users get standard browser UI and full keyboard accessibility.

### Responsive Design

- Images and videos scale to 100% width, preserving aspect ratio
- Gallery grid uses `auto-fit` to responsively reflow columns
- All components work on mobile and desktop

### Styling

Components reuse the design system:
- `.card` class for consistent borders, padding, and background
- CSS custom properties for colors (e.g., `var(--fg)`, `var(--muted)`)
- Rounded corners (`border-radius: 10px` for media, `8px` for wrappers)
- Smooth transitions on hover

### Accessibility

- Images have `alt` text for screen readers
- Videos and audio use native controls (keyboard accessible)
- Lightbox closes with Esc key
- All text is semantic HTML (`<p>`, `<h3>`, etc.)