# Mobile Review App — UX Redesign Brief

Written mid-session before context compaction. This captures ALL of JT's feedback from live testing on 2026-03-04.

## What Exists Now

Files in `editors/mobile/`:
- `mobile-console.html` — PWA shell, 3-tab bottom bar (Dashboard/Previz/Dailies)
- `mobile-app.js` — Hash router, state, API helpers (mirrors ConsoleApp)
- `views/dashboard.js` — Progress rings, episode bars, stat cards
- `views/previz-grid.js` — 2-column shot grid grouped by scene
- `views/frame-viewer.js` — Full-screen 9:16 viewer with KEEP/PASS/REJECT buttons
- `views/dailies-queue.js` — Priority-grouped swipeable card list
- `lib/gestures.js` — Touch gesture handler
- `styles/mobile.css` — Mobile design system extending console.css
- `manifest.json`, `sw.js` — PWA support

Server: `/m` route added to `editors/review_server.py` (lines 511-519).

All views use same API endpoints as desktop console. No backend changes.

## Bugs Fixed During Session

1. Images not loading — `outputUrl()` wasn't prepending `/` to relative paths
2. Wrong field name — API returns `file_path` not `path` for takes
3. Server bound to 127.0.0.1 — needed `--host 0.0.0.0` for Tailscale access
4. PASS hung — viewer re-fetched entire manifest+board on every shot advance. Fixed with episode data caching.
5. Episode ID mismatch — API returns `EP001` format, routing needs `ep_001`. Normalized in dashboard + dailies.
6. Approve failed on already-approved shots — added context-aware action bar (UNLOCK for locked shots)

## JT's UX Feedback (Critical — This Drives the Redesign)

### Previz Tab = Storyboard
- Should mimic the desktop Production Console previz tab
- Shows shots in SEQUENCE so you can see how they flow scene-to-scene
- Tap into a shot to: see its takes, regenerate, change the prompt, etc.
- This is the "edit/manage" view — not the review view

### Dailies Tab = Full-Screen Review of NEW Renders
- Serves shots BIG, full-screen, one at a time
- Must be able to pinch-zoom to examine details
- Core actions: APPROVE or REJECT (send back to the bin)
- NO "PASS" button — confusing. Either approve, reject, or skip somehow.
- Swipe UP/DOWN to navigate between TAKES of the same shot
- After last take → auto-advance to next SHOT that needs review
- Only shows NEW renders — shots that were just generated and haven't been reviewed yet
- Needs notification: "3 new frames ready" badge that surfaces the newest first

### Navigation Flow Issues Found
- Dashboard "1 review" → tapped → went to dailies list with "P3" jargon → tapped REVIEW → went to episode picker → picked episode → landed on WRONG shot (first one, not the one needing review)
- The whole chain was broken. Fixed the worst bugs but the FLOW itself is wrong.
- Dashboard review count should go DIRECTLY to the first unreviewed frame
- Dailies should never show an intermediate list if there's only 1-2 items

### Swiping
- Card swiping in dailies doesn't work reliably on iOS Safari
- PWA gestures fight Safari's own swipe-back and scroll mechanics
- Rewrote to use direct touch handlers instead of Gestures library — still not great
- JT wants Tinder-like feel: spring physics, parallax, card stacking
- PWA probably can't deliver this. Capacitor or native SwiftUI would.
- Decision: keep polishing PWA for now, revisit native later

### General
- "P1/P2/P3/P4" priority labels are jargon — meaningless to user. Fixed to human labels.
- Need clear mental model: Previz = manage/edit, Dailies = review new stuff
- Dashboard needs to be impressive (investor wow screen) — progress rings exist but need polish

## What the Redesign Consultation Should Address

1. **Previz tab flow**: How does storyboard view work on mobile? Horizontal filmstrip? Vertical scroll? Scene grouping? What happens when you tap a shot — inline expand or full-screen?

2. **Dailies tab flow**: Full-screen take review. How do takes stack? Vertical swipe between takes, then auto-advance? What's the "new renders" notification system? How do you know which shots are new?

3. **Action vocabulary**: Approve/Reject are clear. What replaces "Pass"? Archive? Skip? Just swipe past? What about "needs more takes" (send back for regen)?

4. **Take navigation**: Up/down through takes of same shot, then forward to next shot. What's the visual metaphor? Card stack? Carousel? Simple slide?

5. **Notification/surfacing**: How does "3 new frames ready" work? Badge on tab? Push to top of dailies? Auto-open viewer?

6. **Dashboard**: What makes it investor-impressive? Live generation indicators? Cost tracking? Session stats?

7. **Data model**: Does the existing API support "new/unseen" tracking? Probably needs a `seen_at` timestamp or similar.

## Consultation Plan

1. **Round 1: Opus consult** — Package this brief + current mobile code + desktop previz.js/dailies.js patterns + original consultation (consultations/mobile_review_app/). 3-5 rounds redesigning UX flow with wireframes.

2. **Round 2: Gemini consult** — Take Opus output + full codebase to Gemini 3.1 Pro. Poke holes, validate data model, find edge cases.

3. **Round 3: Converge** — Synthesize into revised implementation plan replacing current Phase 2-4.

## Files to Include in Consultation Context

- This file (the brief)
- `editors/mobile/*.js` (all current mobile code)
- `editors/mobile/styles/mobile.css`
- `editors/tabs/previz.js` (desktop previz patterns)
- `editors/tabs/dailies.js` (desktop dailies patterns)
- `editors/console_app.js` (app framework patterns)
- `consultations/mobile_review_app/opus_round_1.md` (original design doc)
- `consultations/mobile_review_app/SYNTHESIS.md` (original synthesis)
- `plans/mobile_review_app.md` (original implementation plan)

## Test Project

Use `--project starsend-test` for testing. Has ep_001 with 7 shots in board (9 in manifest including SH02A, SH03A). Run server with `python3 editors/review_server.py --project starsend-test --host 0.0.0.0`.