immish/docs/timeline.md

Timeline & Photos

This document describes the photo timeline, asset display, and related functionality.

Timeline Overview

The timeline is the main view of the app, displaying all photos and videos in chronological order (newest first).

Asset Types

Asset States

┌─────────────────────────────────────────────────────────────┐
│                        Asset States                          │
├───────────────┬───────────────┬─────────────────────────────┤
│    LOCAL      │    REMOTE     │         MERGED              │
├───────────────┼───────────────┼─────────────────────────────┤
│ On device     │ On server     │ Both device and server      │
│ Not uploaded  │ Not on device │ Linked by checksum          │
│ localId set   │ remoteId set  │ Both IDs set                │
└───────────────┴───────────────┴─────────────────────────────┘

Asset Model

Asset {
  id: String              // Unique identifier
  name: String            // Filename
  type: AssetType         // image, video, audio, other
  createdAt: DateTime     // When created/taken
  updatedAt: DateTime     // Last modified
  checksum: String?       // File hash for deduplication
  width: Integer?         // Image/video width
  height: Integer?        // Image/video height
  durationInSeconds: Int? // Video duration
  isFavorite: Boolean     // Marked as favorite
  isArchived: Boolean     // Hidden from timeline
  isTrashed: Boolean      // In trash
  livePhotoVideoId: String? // Paired video for live photos

  // State indicators
  localId: String?        // Device gallery ID
  remoteId: String?       // Server asset ID
  storage: AssetState     // local, remote, or merged
}

Asset Types Enum

Type	Description
image	Photos (JPEG, PNG, HEIC, etc.)
video	Videos (MP4, MOV, etc.)
audio	Audio files
other	Other file types

Playback Styles

Style	Description
image	Static image
video	Full video
imageAnimated	GIF or animated image
livePhoto	Photo with motion component
videoLooping	Short looping video

Timeline Display

Grid Configuration

• Tiles per row: Configurable (default: 4)
• Dynamic layout: Optional variable row heights
• Group by: Day, Month, or None

Date Headers

Assets are grouped by date with section headers:

December 2024
├── Dec 15 (if grouping by day)
│   └── [asset grid]
├── Dec 14
│   └── [asset grid]
...

Asset Thumbnail Display

Each asset shows:

• Thumbnail image
• Video duration (if video)
• Live photo indicator (if motion photo)
• Favorite indicator (heart icon)
• Selection checkbox (in multi-select mode)
• Stack indicator (if part of stack)

Loading Strategy

Pagination

• Timeline loads in batches (default: 1024 assets)
• Additional assets loaded when scrolling
• Opposite direction pre-loading (64 assets)

Thumbnail Loading

1. Check local cache first
2. Load from local device if available
3. Fetch from server with thumbhash placeholder
4. Cache for future use

Image Quality Levels

Level	Use Case	Resolution
Thumbhash	Instant placeholder	~4x4 blurred
Thumbnail	Grid view	~250px
Preview	Full screen initial	~1080px
Original	Full zoom	Full resolution

Multi-User Timeline

When partner sharing is enabled:

• Timeline can include multiple users' assets
• Assets are merged chronologically
• User indicator shows asset owner

Multi-Select Mode

Activation

• Long press on any asset
• Or tap select button in app bar

Available Actions

┌─────────────────────────────────────────────────────────────┐
│  [X] Cancel   Selected: 5                                   │
├─────────────────────────────────────────────────────────────┤
│  ♥ Favorite  │  📦 Archive  │  🗑 Delete  │  📤 Share  │ ⋮ │
└─────────────────────────────────────────────────────────────┘

Actions Available

Action	Description
Favorite	Toggle favorite status
Archive	Move to archive
Delete	Move to trash
Share	Share via system share
Download	Download to device
Add to Album	Add to existing/new album
Create Stack	Stack selected assets
Move to Locked	Move to locked folder

Pull to Refresh

Refresh Behavior

1. Single pull: Incremental sync
2. Double pull (within 4 seconds): Full refresh
   • Clears local cache
   • Re-fetches all data

Sync Process

1. Check server for new assets
2. Download metadata for new assets
3. Update local database
4. Refresh album data
5. Update UI

Memory Lane

Display

• Horizontal scrolling widget at top of timeline
• Shows "X years ago" cards
• Only visible if user has memories enabled

Memory Card

┌─────────────────┐
│   [Thumbnail]   │
│                 │
│   2 years ago   │
└─────────────────┘

Memory API

GET /memories?for={today's date}

Response: Array of Memory objects
{
  "id": "memory-id",
  "data": {
    "year": 2022
  },
  "assets": [...]
}

Scroll Scrubber

Features

• Appears on right side when scrolling
• Shows date labels
• Drag to quickly navigate
• Snaps to month boundaries (if enough history)

Configuration

• Enabled when timeline spans 12+ months
• Custom scroll controller for smooth navigation

Asset Visibility

Assets can have different visibility states:

State	Timeline	Archive	Trash	Locked
Normal	✓
Archived		✓
Trashed			✓
Hidden/Locked				✓

Asset Stacks

Multiple similar assets can be "stacked":

• Only primary asset shown in timeline
• Stack indicator shows count
• Tap to view stack contents
• Can unstack to separate

Real-time Updates

Via WebSocket connection:

• New uploads appear immediately
• Deletions remove assets from view
• Updates refresh asset metadata

WebSocket Events

Event	Action
on_upload_success	Add new asset to timeline
on_asset_delete	Remove asset
on_asset_trash	Move to trash
on_asset_restore	Restore from trash
on_asset_update	Refresh metadata
on_asset_hidden	Hide from timeline

Performance Optimizations

1. Virtualized list: Only renders visible items
2. Image caching: Configurable cache size
3. Lazy loading: Load data as needed
4. Debounced scroll: Reduce render calls
5. Background prefetching: Load ahead

Cache Settings

Setting	Default	Description
thumbnailCacheSize	10000	Max cached thumbnails
imageCacheSize	350	Max cached full images
albumThumbnailCacheSize	200	Max album thumbs

---

Previous: Main Navigation | Next: Search