video_translate/docs/plans/2026-03-19-upload-subtitle-defaults.md

# Upload Subtitle Defaults Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Add upload-screen controls for initial subtitle position and size, then apply those defaults when the editor loads generated subtitles.

**Architecture:** The upload screen owns temporary subtitle default settings and previews them locally. `App` stores the selected defaults during upload confirmation and passes them into `EditorScreen`, which uses them while normalizing generated subtitles and rendering the overlay.

**Tech Stack:** React, TypeScript, Vite, Vitest, Testing Library, Tailwind utility classes

---

### Task 1: Add failing tests for upload defaults flow

**Files:**
- Create: `src/components/UploadScreen.test.tsx`
- Modify: `src/components/EditorScreen.test.tsx`

**Step 1: Write the failing test**

Add tests that:

- verify upload-screen subtitle size and position controls start at the expected defaults
- verify changing them updates the upload preview
- verify upload confirmation passes subtitle defaults through `onUpload`
- verify `EditorScreen` initializes the subtitle overlay with upload-provided defaults

**Step 2: Run test to verify it fails**

Run: `npm run test -- src/components/UploadScreen.test.tsx src/components/EditorScreen.test.tsx`
Expected: FAIL because upload defaults do not yet exist and the editor cannot consume them

**Step 3: Write minimal implementation**

Do not implement here; continue to Tasks 2 through 4.

**Step 4: Run test to verify it passes**

Run after Tasks 2 through 4.

**Step 5: Commit**

```bash
git add src/components/UploadScreen.test.tsx src/components/EditorScreen.test.tsx src/components/UploadScreen.tsx src/components/EditorScreen.tsx src/App.tsx src/types.ts
git commit -m "test: cover upload subtitle defaults flow"
```

### Task 2: Add shared subtitle-default types and app-level state

**Files:**
- Modify: `src/types.ts`
- Modify: `src/App.tsx`

**Step 1: Write the failing test**

Covered by Task 1.

**Step 2: Run test to verify it fails**

Run: `npm run test -- src/components/UploadScreen.test.tsx src/components/EditorScreen.test.tsx`
Expected: FAIL on missing props and missing subtitle-default state

**Step 3: Write minimal implementation**

- Add a shared interface for upload subtitle defaults
- Store subtitle defaults in `App`
- Extend the upload callback signature
- Pass the chosen defaults into `EditorScreen`

**Step 4: Run test to verify it passes**

Run after Tasks 3 and 4.

**Step 5: Commit**

```bash
git add src/types.ts src/App.tsx src/components/UploadScreen.tsx src/components/EditorScreen.tsx
git commit -m "feat: plumb upload subtitle defaults through app state"
```

### Task 3: Implement upload-screen subtitle defaults UI

**Files:**
- Modify: `src/components/UploadScreen.tsx`
- Test: `src/components/UploadScreen.test.tsx`

**Step 1: Write the failing test**

Covered by Task 1.

**Step 2: Run test to verify it fails**

Run: `npm run test -- src/components/UploadScreen.test.tsx`
Expected: FAIL because the controls and preview do not exist

**Step 3: Write minimal implementation**

- Add subtitle size and vertical position state with current-editor default values
- Add a preview card showing sample subtitle text
- Add range inputs and a reset button
- Ensure upload confirmation sends the chosen defaults via `onUpload`

**Step 4: Run test to verify it passes**

Run: `npm run test -- src/components/UploadScreen.test.tsx`
Expected: PASS

**Step 5: Commit**

```bash
git add src/components/UploadScreen.tsx src/components/UploadScreen.test.tsx
git commit -m "feat: add upload-screen subtitle default controls"
```

### Task 4: Apply upload defaults inside the editor

**Files:**
- Modify: `src/components/EditorScreen.tsx`
- Modify: `src/components/EditorScreen.test.tsx`

**Step 1: Write the failing test**

Covered by Task 1.

**Step 2: Run test to verify it fails**

Run: `npm run test -- src/components/EditorScreen.test.tsx`
Expected: FAIL because the editor still uses hard-coded defaults

**Step 3: Write minimal implementation**

- Accept upload subtitle defaults as a prop
- Use them while normalizing subtitles
- Render the overlay at the chosen bottom offset
- Keep existing editor controls working from these defaults

**Step 4: Run test to verify it passes**

Run: `npm run test -- src/components/EditorScreen.test.tsx`
Expected: PASS

**Step 5: Commit**

```bash
git add src/components/EditorScreen.tsx src/components/EditorScreen.test.tsx src/App.tsx src/types.ts
git commit -m "feat: initialize editor subtitles from upload defaults"
```

### Task 5: Verify targeted behavior

**Files:**
- Modify: `src/components/UploadScreen.tsx` if verification reveals issues
- Modify: `src/components/EditorScreen.tsx` if verification reveals issues

**Step 1: Write the failing test**

Only add one if targeted verification reveals a missing edge case.

**Step 2: Run test to verify it fails**

Only if a regression is found.

**Step 3: Write minimal implementation**

Apply the smallest follow-up fix needed to make the targeted flow green.

**Step 4: Run test to verify it passes**

Run: `npm run test -- src/components/UploadScreen.test.tsx src/components/EditorScreen.test.tsx`
Expected: PASS

Optional broader check:

Run: `npm run test -- src/components/UploadScreen.test.tsx src/components/EditorScreen.test.tsx src/lib/exportPayload.test.ts`
Expected: PASS

**Step 5: Commit**

```bash
git add src/components/UploadScreen.tsx src/components/UploadScreen.test.tsx src/components/EditorScreen.tsx src/components/EditorScreen.test.tsx src/App.tsx src/types.ts
git commit -m "test: verify upload subtitle default behavior"
```