immish/docs/gallery-viewer.md

# Gallery Viewer

This document describes the full-screen asset viewer for viewing photos and videos.

## Overview

The gallery viewer provides:
- Full-screen photo/video viewing
- Swipe navigation between assets
- Pinch-to-zoom on images
- Video playback controls
- Asset actions and info

## Viewer Layout

```
┌─────────────────────────────────────────────────────────────┐
│  ←  [♥] [🔍] [▶️] [⬆️] [⬇️] [+] [📺] [💬] [ℹ️]              │
│     (contextual actions based on asset state)               │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│                                                             │
│                                                             │
│                    [Full Screen Asset]                      │
│                                                             │
│                                                             │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  [Video controls - if video asset]                          │
├─────────────────────────────────────────────────────────────┤
│  [Share]  [Edit]  [Archive]  [Stack]  [Delete]              │
│     (contextual actions - vary by asset ownership/type)     │
└─────────────────────────────────────────────────────────────┘
```

## Navigation

### Gestures
| Gesture | Action |
|---------|--------|
| Swipe left/right | Navigate to next/previous asset |
| Swipe down | Close viewer |
| Swipe up | Show asset info panel |
| Single tap | Toggle controls visibility |
| Double tap | Toggle zoom |
| Pinch | Zoom in/out |

### Tap-to-Navigate Mode
Optional setting that enables:
- Tap left quarter: Previous asset
- Tap right quarter: Next asset
- Tap center: Toggle controls

## Image Viewing

### Loading Strategy
1. Show thumbhash placeholder immediately
2. Load thumbnail from cache
3. Load preview resolution
4. Load original when zoomed

### Zoom Features
- Pinch to zoom (up to 3x)
- Double tap to toggle zoom
- Pan when zoomed
- Reset on page change

### Motion Photos
- Long press to play motion component
- Auto-plays on image tap (optional)
- Shows motion indicator icon

## Video Playback

### Video Controls
```
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│                    [Video Frame]                            │
│                                                             │
│                      ▶ / ⏸                                 │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  0:45 ────────●────────────────────────── 3:24             │
│                                                             │
│  [Mute] [Quality] [Fullscreen] [Cast]                      │
└─────────────────────────────────────────────────────────────┘
```

### Video Settings
| Setting | Description |
|---------|-------------|
| Auto-play | Start playing when opened |
| Loop | Repeat when finished |
| Load Original | Use full quality (uses more data) |

### Video Quality
- Transcoded versions available
- Original quality option
- Adaptive based on network

## Top App Bar

### Actions Available (conditional based on context)
| Icon | Condition | Action |
|------|-----------|--------|
| ← | Always | Close viewer / Go back |
| ♥ | Remote asset, owner only | Toggle favorite |
| 🔍 | Owner, not in timeline/trash/locked | Locate in timeline |
| ▶️ | Live/motion photo | Play motion photo |
| ⬆️ | Local-only asset | Upload to server |
| ⬇️ | Remote-only, owner | Download to device |
| + | Remote, owner/partner, not trashed/locked | Add to album |
| 📺 | Remote + WebSocket connected, or casting | Cast to Chromecast |
| ↩️ | Trashed asset | Restore from trash |
| 💬 | In shared album, not locked | View activities/comments |
| ℹ️ | Always | Show info panel |

## Bottom Action Bar

### Actions (conditional based on context)
| Icon | Condition | Action |
|------|-----------|--------|
| 📤 Share | Always | System share sheet |
| 🎨 Edit | Image only, not locked | Open image editor |
| 📦 Archive | Owner, not locked | Archive/Unarchive asset |
| 📚 Stack | Owner with stacked assets, not locked | Show stack options |
| 🗑 Delete | Owner, not in album | Move to trash or delete |
| ⬇️ Download | Non-owner only | Download to device |
| ✕ Remove | In album view | Remove from current album |

### Context-Specific Behavior
- **Owner viewing own asset**: Share, Edit, Archive, Delete visible
- **Non-owner viewing partner asset**: Share, Download visible
- **Viewing in album**: Share, Edit, Archive, Remove from album visible
- **Viewing in locked folder**: Only Share and Delete visible

## Asset Info Panel

Swipe up or tap info button to show:

```
┌─────────────────────────────────────────────────────────────┐
│  ─────  (drag handle)                                       │
├─────────────────────────────────────────────────────────────┤
│  IMG_1234.jpg                                               │
│  December 15, 2024 at 3:45 PM                              │
├─────────────────────────────────────────────────────────────┤
│  Details                                                    │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 📷 Apple iPhone 15 Pro                               │   │
│  │ 📐 4032 × 3024                                       │   │
│  │ 💾 4.2 MB                                            │   │
│  │ 📍 San Francisco, CA                                 │   │
│  └─────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────┤
│  EXIF Information                                           │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Aperture: f/1.8                                      │   │
│  │ Shutter: 1/120s                                      │   │
│  │ ISO: 64                                              │   │
│  │ Focal Length: 24mm                                   │   │
│  └─────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────┤
│  Description                                                │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Add a description...                                 │   │
│  └─────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────┤
│  People                                                     │
│  [Face thumbnails with names]                               │
├─────────────────────────────────────────────────────────────┤
│  Location                                                   │
│  [Small map preview]                                        │
└─────────────────────────────────────────────────────────────┘
```

### Info Sections
1. **Header**: Filename and date
2. **Details**: Camera, dimensions, size, location
3. **EXIF**: Technical camera data
4. **Description**: Editable caption
5. **People**: Recognized faces
6. **Location**: Map preview (if geotagged)

## Asset Stacks

### What are Stacks?
Groups of similar assets shown as one item:
- Burst photos
- Edited versions
- Similar shots

### Stack Display
```
┌─────────────────────────────────────────────────────────────┐
│  [Main stack asset displayed]                               │
├─────────────────────────────────────────────────────────────┤
│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐                          │
│  │  1  │ │  2  │ │  3  │ │  4  │  ← Stack thumbnails      │
│  │  ●  │ │     │ │     │ │     │                          │
│  └─────┘ └─────┘ └─────┘ └─────┘                          │
└─────────────────────────────────────────────────────────────┘
```

### Stack Actions
- Tap thumbnail to switch
- Long press to set as primary
- Unstack to separate assets

## Editing

### Available Edits
- Crop and rotate
- Filters
- Adjustments (brightness, contrast, etc.)

### Edit Flow
1. Tap edit icon
2. Make changes
3. Save as new or overwrite

## Casting

### Chromecast Support
- Cast images to TV
- Shows high-resolution version
- Video streaming support

### Cast Flow
1. Tap cast icon
2. Select device
3. Asset displays on TV
4. Control from phone

## Download

### Download Options
- Save to device gallery
- Choose quality (original/transcoded)
- Live photos download both parts

### Download API
```
GET /assets/{id}/original

Response: Binary file data
```

## Activities (Comments)

For shared albums with activity enabled:

### Activity Panel
```
┌─────────────────────────────────────────────────────────────┐
│  ←  Activity                                                │
├─────────────────────────────────────────────────────────────┤
│  👤 Jane: Love this photo! ♥                               │
│  👤 John: Great shot!                                       │
│  👤 You: Thanks!                                            │
├─────────────────────────────────────────────────────────────┤
│  [Add a comment...]                            [Send]       │
└─────────────────────────────────────────────────────────────┘
```

### Activity API
```
GET /activities?albumId={albumId}&assetId={assetId}

POST /activities
Body:
{
  "albumId": "album-uuid",
  "assetId": "asset-uuid",
  "type": "comment" | "like",
  "comment": "Great photo!"
}
```

## Performance

### Image Caching
- Thumbnails cached aggressively
- Preview images cached with limits
- Original images not cached (too large)

### Preloading
- Next/previous images preloaded
- Smooth navigation experience
- Configurable cache size

### Memory Management
- Release memory when leaving
- Dispose video players
- Clear caches when low memory

---

[Previous: Library](./library.md) | [Next: Backup & Upload](./backup.md)