# Stories Feature Design

**Goal:** Add Instagram-style ephemeral stories to the native iOS app, matching the web client's functionality for viewing, browsing, and creating stories.

**Scope:** Story strip on feed, story viewer, profile story indicator, story creation. Story archive is out of scope.

---

## 1. Story Strip (Feed)

Horizontal `ScrollView` at the top of `FeedView`, above gallery cards.

- First item: "+" button (opens `StoryCreateView` sheet) for authenticated users
- Remaining items: circular avatars with gradient ring (purple > accent > cyan) for users with active stories (24h window)
- Display name label below each avatar
- Tapping an avatar opens `StoryViewer` as a fullscreen cover, starting at that author
- Data: `getStoryAuthors()` endpoint, fetched on load and pull-to-refresh

**New files:**
- `Grain/Views/Stories/StoryStripView.swift` — horizontal avatar strip component
- `Grain/ViewModels/StoryStripViewModel.swift` — fetches story authors

**Shared component:**
- `Grain/Views/Stories/StoryRingView.swift` — gradient ring wrapper, reused on profile avatar

## 2. Story Viewer

Wire up the existing `StoryViewer.swift` and present it from feed and profile.

- Presented as `.fullScreenCover`
- Receives full authors list + starting index to enable swiping between authors
- Each author's stories fetched on demand via `getStories(actor:)`
- Auto-advance: 5-second timer per story, animated progress bars at top
- Navigation: tap left 1/3 = previous, tap right 2/3 = next
- Swipe left/right to jump between authors
- Dismisses after last story of last author
- Delete button on own stories via `deleteRecord`
- Status bar hidden for immersive experience

**Modified files:**
- `Grain/Views/Stories/StoryViewer.swift` — enhance with auto-advance timer, author list navigation
- `Grain/Views/Feed/FeedView.swift` — add fullscreen cover presentation
- `Grain/Views/Profile/ProfileView.swift` — add fullscreen cover on avatar tap

## 3. Profile Story Indicator

When a user has active stories, their profile avatar shows a gradient ring and becomes tappable to open the viewer.

- `ProfileDetailViewModel` already fetches stories — use `viewModel.stories.isEmpty` to determine ring visibility
- Wrap `AvatarView` with `StoryRingView` when stories exist
- Tap avatar to open `StoryViewer` as fullscreen cover
- No ring and no tap action when no stories

**Modified files:**
- `Grain/Views/Profile/ProfileView.swift` — conditional ring + tap gesture on avatar

## 4. Story Creation

Sheet presented from the "+" button in the story strip. Reuses photo processing from `CreateGalleryView`.

- Single photo selection via `PhotosPicker`
- Photo preview after selection
- Image resize: max 2000px, max 5MB with JPEG quality binary search
- Location auto-populated from EXIF GPS via reverse geocode (Nominatim), converted to H3 index
- Editable location text field
- Optional "Post to Bluesky" toggle
- Post: `uploadBlob` then `createRecord` with collection `social.grain.story`
- Record fields: media (blob ref), aspectRatio, location (H3 value + name), address, createdAt
- On success: refresh story strip, dismiss sheet

**New files:**
- `Grain/Views/Stories/StoryCreateView.swift`

**Reused from gallery creation:**
- Photo processing / resize utilities
- EXIF GPS extraction
- Reverse geocoding
- H3 conversion (SwiftyH3)

---

## Existing Infrastructure

Already built and ready to use:

- **Models:** `GrainStory`, `GrainStoryAuthor`, `StoryRecord` (in `Grain/Models/`)
- **API endpoints:** `getStories`, `getStory`, `getStoryArchive`, `getStoryAuthors` (in `Grain/API/Endpoints/StoryEndpoints.swift`)
- **Viewer component:** `StoryViewer.swift` (needs enhancement but base exists)
- **OAuth scope:** `repo:social.grain.story` already included
- **Photo processing:** resize, EXIF extraction, blob upload all exist in `CreateGalleryView`