# Starsend Production Console v2 — Design Document

**Date:** 2026-02-27
**Status:** Approved
**Scope:** Full visual overhaul + Previz tab + Revision editor port + structural features
**Execution:** Two parallel Gemini 3.1 Pro consultations + Claude iteration

---

## Context

The v1 Production Console (built during the Holistic Recoil-Starsend v2.0 Rebuild) is functionally complete but visually misaligned with the Recoil production console aesthetic. The console uses a GitHub-dark color scheme while Recoil has a distinctive terminal/aerospace authority look that JT prefers.

Additionally:
- The Script tab uses an iframe embedding of Recoil's Revision editor (ADR-R13 "Strangler Fig"). JT doesn't like the embedded feel.
- No Previz tab exists — previz approval is handled item-by-item in Dailies, but JT wants a full storyboard layout view.
- Missing: status bar, toast notifications, compact information density, inline prompt editing with auto-save.

---

## Decision: Two-Agent Gemini Consultation

Split the work across two focused Gemini consultations to stay within context limits:

### Agent A: Console Shell + Design System + New Tabs
**Context:** Recoil's `console.css` (687 lines) + current `console.html` + current JS modules + manifest data structures + review_server.py endpoints
**Output:** Complete rewrite of console.html, console_app.js, and all tab modules with new design system

### Agent B: Revision Editor Port
**Context:** Recoil's `revision_editor_v2.html` (~29K) + Fountain parsing logic + annotation system + Recoil serve.py API endpoints
**Output:** Native `tabs/script.js` module with full screenplay viewing, annotation, and editing capabilities

---

## 1. Visual Design System

Adopt Recoil's design system wholesale for visual consistency across the production toolchain.

### Color Palette
```css
/* Backgrounds (4-tier depth) */
--bg-primary: #0a0a0a;
--bg-secondary: #111;
--bg-tertiary: #1a1a1a;
--bg-card: #151515;
--bg-hover: #1e1e1e;
--bg-active: #252525;

/* Borders (3-tier contrast ladder) */
--border-dim: #2a2a2a;
--border-default: #333;
--border-bright: #444;

/* Text (4-tier hierarchy) */
--text-primary: #e0e0e0;
--text-secondary: #aaa;
--text-label: #888;
--text-dim: #666;

/* Accents (functional, not decorative) */
--accent-green: #4caf50;      /* Primary action, success */
--accent-green-dim: #2d5a2e;  /* Green backgrounds */
--accent-amber: #ff9800;      /* Warning, in-progress */
--accent-amber-dim: #5a3d00;
--accent-red: #f44336;        /* Error, danger */
--accent-red-dim: #5a1a1a;
--accent-blue: #2196f3;       /* Secondary action, links */
--accent-blue-dim: #1a3a5a;
--accent-cyan: #00bcd4;       /* Highlight, special emphasis */
```

### Typography
```css
--font-mono: 'JetBrains Mono', 'SF Mono', 'Fira Code', 'Cascadia Code', monospace;
--font-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
```

**Rule:** All UI chrome (buttons, labels, tab names, headers, status indicators) uses monospace + UPPERCASE + letter-spacing. Body content uses system sans.

### Spacing (4px baseline)
| Unit | Usage |
|------|-------|
| 4px | Tight gaps, element spacing |
| 6px | Button padding, small gaps |
| 8px | Default gap, section spacing |
| 12px | Card internal padding, larger gaps |
| 16px | Major spacing, panel padding |
| 20px | Tab panel padding |

### Border Radius
```css
--radius-sm: 4px;   /* Buttons, inputs */
--radius-md: 6px;   /* Cards, modals */
--radius-lg: 8px;   /* Large containers */
```

### Transitions
```css
--transition-fast: 150ms ease;    /* Hover states */
--transition-normal: 250ms ease;  /* Layout changes, progress bars */
```

### Custom Scrollbar
```css
::-webkit-scrollbar { width: 6px; height: 6px; }
::-webkit-scrollbar-track { background: transparent; }
::-webkit-scrollbar-thumb { background: var(--border-default); border-radius: 3px; }
::-webkit-scrollbar-thumb:hover { background: var(--border-bright); }
```

---

## 2. Layout Structure

```
+------+----------------------------------------------+
| TOP  | STARSEND [green]  Leviathan    Season: $12.45| 48px
+------+----------------------------------------------+
| SIDE | Script  Previz  Bible  Board  Dailies [3]    | 36px
| BAR  |----------------------------------------------|
| 200px|                                              |
| EP001|            Tab content area                  |
| EP002|          (full height, scrollable)           |
| EP003|                                              |
|  ... |                                              |
|      |                                              |
|  [<] |                                              |
+------+----------------------------------------------+
| STATUS | Pipeline: ====-- 65%  | 23/39 | Dailies: 3| 32px
+---------+----------------------------------------------+
```

### Top Bar (48px)
- Left: "STARSEND" in monospace, green accent on brand name
- Center: Project name (from config)
- Right: Season cost in green monospace

### Collapsible Episode Sidebar (200px expanded, 40px collapsed)
- Episode list with status icons (green dot = complete, amber = in progress, dim = pending)
- Active episode: left green border + brighter bg + primary text
- Revision badge (orange) for episodes with pending revisions
- Collapse button at bottom (arrow icon)
- Selected episode shared globally across all tabs via AppState

### Tab Bar (36px)
- 5 tabs: Script, Previz, Bible, Board, Dailies
- Active: green underline + primary text
- Inactive: dim text, no underline
- Dailies tab: badge count (red bg) when items > 0
- All labels: monospace, uppercase, 11px, letter-spacing 0.8px
- Keyboard: Cmd+1-5

### Status Bar (32px, bottom)
- Left: "PIPELINE:" label + 120px progress bar (green fill) + shot count "23/39"
- Right: Dailies count + current operation ("Generating EP001 S03...")
- All monospace, 11px, dim text
- Updates every 5s

---

## 3. Tab 1: Script (Native Port)

**Agent B** ports the Revision editor natively into Starsend.

### Requirements
- Full Fountain screenplay display with syntax highlighting
- Annotation system: highlight text, add comments, propose edits
- Stale hash badge: "Script changed — N shots out of sync. [Update Manifest]"
- Grammar sidebar (toggleable): corpus stats from Recoil API
- Episode selector driven by global sidebar selection
- Auto-save annotations on edit (debounced 500ms)

### Data Sources
- Screenplay text: `GET /api/project/{name}/episodes/{ep}/screenplay` from Recoil (8420)
- Annotations: `GET /api/project/{name}/episodes/{ep}/annotations` from Recoil (8420)
- Stale check: `GET /api/stale-check/{episode}` from Starsend (8430)
- Corpus stats: `GET /api/project/{name}/corpus-summary` from Recoil (8420)

---

## 4. Tab 2: Previz (New)

The visual storyboard — episode laid out shot-by-shot for review before keyframe/video generation.

### Layout
Shot cards grouped by scene, vertical scroll. Scene headers show location name + time of day + location ref thumbnail.

### Shot Card Structure
```
+-------------------+
| [previz image]    |  9:16 aspect ratio
| or "pending"      |  placeholder
+-------------------+
| MCU - CAPTAIN     |  Shot type + subject
| "We're going      |  Screenplay text
|  deeper."         |  (from manifest)
+-------------------+
| [editable prompt] |  Click to edit
| Cinematic env...  |  Auto-save on blur
+-------------------+
| [Approve] [Reject]|  Action buttons
| $0.039            |  Cost badge
+-------------------+
```

### Features
- Scene grouping with collapsible scene headers
- Location ref thumbnail in scene header (from `/refs/locations/`)
- Inline prompt editing: click prompt text -> becomes editable textarea -> auto-save 500ms after last keystroke -> toast "Saved"
- Batch actions per scene: "Approve All", "Generate Missing"
- Cards without previz image: dim placeholder with [Generate] button
- Approval writes to Layer 1 manifest (`human_approvals`) via existing `/api/dailies/approve` endpoint
- Status indicators: green check (approved), red x (rejected), dim (pending), amber spinner (generating)

### Data Sources
- Manifest: `GET /api/manifest/{ep_dir}` — shots array with previz paths, prompts, status
- Previz images: `GET /output/previs/{ep_dir}/{shot_name}.png`
- Approve: `POST /api/dailies/approve` (reuse existing)
- Override prompt: `POST /api/dailies/override` (reuse existing)

---

## 5. Tab 3: Bible (Existing, Redesigned)

Same functionality, new aesthetic. Character grid, location refs, camera/film settings.

Key density improvements:
- Stat grid for camera/film (instead of 3-column div)
- Compact character cards with trait pills instead of text lines
- Location ref images in tighter grid
- Character edit: inline field editing with auto-save (not prompt() dialog)

---

## 6. Tab 4: Board (Existing, Redesigned)

Same functionality, tighter layout.

Key density improvements:
- Season budget bar uses stat-box pattern (big monospace numbers + uppercase labels)
- Episode grid rows more compact (8px padding instead of 10px)
- Drill-down shot table uses monospace for IDs and costs
- Launch Batch modal: deviation alerts with left-border severity indicators (Recoil pattern)

---

## 7. Tab 5: Dailies (Existing, Redesigned)

Same priority queue, more compact cards.

Key density improvements:
- Prompt text collapsed by default, click to expand
- Tighter card layout (12px padding instead of 16px)
- Inline prompt editing on Override (not modal): open prompt in-place, auto-save
- Take selection: side-by-side thumbnails, click to select (no modal)
- Empty state: monospace "ALL CLEAR" with large dim icon

---

## 8. Toast Notification System

```css
.toast {
  position: fixed;
  bottom: 48px;
  left: 50%;
  transform: translateX(-50%) translateY(20px);
  background: var(--bg-card);
  border: 1px solid var(--border-bright);
  padding: 8px 20px;
  border-radius: var(--radius-md);
  font-family: var(--font-mono);
  font-size: 12px;
  opacity: 0;
  transition: all 250ms ease;
}
.toast.show { opacity: 1; transform: translateX(-50%) translateY(0); }
.toast.success { border-color: var(--accent-green); color: var(--accent-green); }
.toast.error { border-color: var(--accent-red); color: var(--accent-red); }
```

- Auto-dismiss after 3s
- Triggered on: approve, reject, override save, launch, auto-save confirm, errors
- Queue: stack up to 3 toasts with 8px gap

---

## 9. Auto-Save System

- Debounce: 500ms after last keystroke
- Scope: prompt editing (Previz + Dailies), Bible character edits, annotation edits
- Visual feedback: brief "Saved" toast (1.5s auto-dismiss)
- Error handling: red "Save failed" toast, retry on next edit
- Implementation: shared `autoSave(endpoint, body, delay=500)` utility in console_app.js

---

## 10. API Endpoints (New for Previz)

No new endpoints needed. Previz tab reuses:
- `GET /api/manifest/{ep_dir}` — shot data with previz paths
- `GET /api/previs/{ep_dir}` — previz frame listing
- `POST /api/dailies/approve` — approve shot
- `POST /api/dailies/reject` — reject shot
- `POST /api/dailies/override` — save edited prompt

One potential addition:
- `POST /api/generate-previz` — trigger previz generation for specific shots (optional, can defer)

---

## Execution Plan

### Gemini Agent A: Console Shell + Design System + Tabs 2-5
**Context bundle:**
- Recoil `styles/console.css` (687 lines)
- Recoil `production_console.html` (design reference)
- Current Starsend `console.html` + `console_app.js` + `tabs/*.js`
- `review_server.py` API endpoint list
- This design document

**Deliverable:** Complete rewrite of:
- `editors/console.html` (new design system)
- `editors/console_app.js` (with toast system, auto-save, sidebar state)
- `editors/tabs/previz.js` (new)
- `editors/tabs/bible.js` (redesigned)
- `editors/tabs/board.js` (redesigned)
- `editors/tabs/dailies.js` (redesigned)

### Gemini Agent B: Revision Editor Port
**Context bundle:**
- Recoil `revision_editor_v2.html` (~29K)
- Recoil `serve.py` API endpoints for screenplay/annotations
- Design system CSS vars (from Agent A's output or this doc)
- Starsend `review_server.py` endpoint list

**Deliverable:** Complete:
- `editors/tabs/script.js` (native screenplay editor)
- Any CSS additions needed for Fountain syntax highlighting

### Claude Integration Pass
After both Gemini agents deliver, Claude:
1. Merges outputs into the codebase
2. Wires up all API calls to existing endpoints
3. Tests each tab against actual data
4. Fixes edge cases and iteration issues
5. Updates review_server.py if new endpoints needed

---

## Verification

1. Open `localhost:8430/console` — 5 tabs load, Recoil aesthetic, collapsible sidebar
2. Script tab: native screenplay display, stale badge, annotations
3. Previz tab: shot cards grouped by scene, inline prompt editing, auto-save
4. Bible tab: character grid, location refs, camera settings
5. Board tab: season budget, episode grid, launch batch with preflight
6. Dailies tab: priority queue, compact cards, inline override
7. Status bar: pipeline progress updating
8. Toast: approve a shot -> green "Approved" toast slides up
9. Auto-save: edit a prompt -> "Saved" toast after 500ms pause
10. Sidebar: collapse/expand, episode selection updates all tabs