TalkEdit/polish_plan.md

# TalkEdit — Testing & Robustness Plan

Tests are critical before launch to prevent regressions and ensure the app is stable. Below is every function in the codebase that needs test coverage, organized by module.

---

## 1. Rust backend (`src-tauri/src/`)

### licensing.rs — already has partial coverage (4 tests)
- [ ] `verify_license_key` — valid key, invalid format, invalid signature, expired key ✅ (exists)
- [ ] `load_cached_license` — file exists, file missing, malformed file
- [ ] `cache_license` — write and read back
- [ ] `remove_license` — removes file, no-ops if missing
- [ ] `get_or_start_trial` — creates new trial file, loads existing, handles corrupt file
- [ ] `get_trial_info` — active trial (29 days), expired trial (0 days), exactly at boundary
- [ ] `get_trial_days_remaining` — active returns Some, expired returns None,
- [ ] `clear_trial` — removes file, no-ops if missing
- [ ] `get_app_status` — licensed (cached license), trial active, expired (no license, no trial)
- [ ] `has_feature` — feature exists, feature missing, empty features list

### models.rs — no existing tests
- [ ] `list_models` — whisper models found, llm models found, mixed, empty dirs
- [ ] `delete_model` — deletes file, deletes directory, path doesn't exist
- [ ] `huggingface_cache_dir` — HF_HOME set, XDG_CACHE_HOME set, defaults to ~/.cache

### transcription.rs — no existing tests
- [ ] `ensure_model_downloaded` — returns success (stub function)

### paths.rs — no existing tests
- [ ] `project_root` — dev layout, packaged (TAURI_RESOURCE_DIR), fallback
- [ ] `python_exe` — bundled path, venv paths, fallback to .venv312
- [ ] `backend_script` — joins project_root/backend
- [ ] `root_script` — joins project_root

---

## 2. Frontend store (`frontend/src/store/`)

### editorStore.ts (Zustand) — partially covered (2 tests)
- [ ] `reset` ✅ (in beforeEach)
- [ ] `setGlobalGainDb` — clamps to -24/+24 ✅ (exists)
- [ ] `addGainRange` — adds with correct start/end/gain ✅ (exists)
- [ ] `addCutRange` — adds with correct start/end, handles overlapping ranges
- [ ] `addMuteRange` — adds with correct start/end
- [ ] `addSpeedRange` — adds with correct start/end/speed
- [ ] `removeCutRange` — removes existing, no-ops on missing
- [ ] `removeMuteRange` — removes existing, no-ops on missing
- [ ] `removeGainRange` — removes existing, no-ops on missing
- [ ] `removeSpeedRange` — removes existing, no-ops on missing
- [ ] `updateCutRange` — updates bounds, prevents negative duration
- [ ] `updateMuteRange` — updates bounds
- [ ] `updateGainRangeBounds` — updates bounds
- [ ] `updateSpeedRangeBounds` — updates bounds
- [ ] `updateGainRange` — updates gain value
- [ ] `updateSpeedRange` — updates speed value
- [ ] `setSelectedWordIndices` — single, multiple, empty, out of range handled
- [ ] `replaceWordRange` — replaces words in middle, replaces at start, handles invalid indices
- [ ] `updateWordText` — updates word, preserves timing, no-ops on bad index
- [ ] `getWordAtTime` — exact match, between words, before first word, after last word, no words
- [ ] `loadVideo` — sets videoUrl, resets state, handles missing file
- [ ] `setCurrentTime` — sets time, clamps to 0-duration
- [ ] `setTranscribing` — toggles flag, sets status
- [ ] `setTranscription` — sets words and segments, handles empty arrays
- [ ] `setMarkInTime` / `setMarkOutTime` — sets and clears
- [ ] `clearMarkRange` — clears both marks
- [ ] `addTimelineMarker` — adds with label/color/time
- [ ] `removeTimelineMarker` — removes by id
- [ ] `updateTimelineMarker` — updates label/color
- [ ] `setZonePreviewPaddingSeconds` — sets and clamps
- [ ] `setBackgroundMusic` / `updateBackgroundMusic` — sets and updates
- [ ] `setAdditionalClips` — adds, removes, reorders
- [ ] `setSilenceTrimGroups` — sets groups

### licenseStore.ts — no existing tests
- [ ] `canEdit` — true for Licensed, true for Trial, false for Expired, false for null
- [ ] `checkStatus` — calls getAppStatus, sets correct state, handles error (falls to Expired)
- [ ] `activateLicense` — valid key sets Licensed, invalid key returns false
- [ ] `deactivateLicense` — reverts to trial if valid, falls to Expired otherwise
- [ ] `hasFeature` — returns true for matching, false for missing
- [ ] `setShowDialog` — toggles dialog visibility
- [ ] Persist middleware — Licensed status persists, Trial/Expired does not

### aiStore.ts — no existing tests
- [ ] `setProviderConfig` — updates provider, encrypts API keys
- [ ] `setDefaultProvider` — changes default
- [ ] `setCustomFillerWords` — sets and clears
- [ ] `setFillerResult` — sets and clears
- [ ] `setProcessing` — toggles with message

---

## 3. Frontend hooks (`frontend/src/hooks/`)

### useKeyboardShortcuts.ts — no existing tests
- [ ] Keyboard event dispatch — space plays/pauses, J/K/L speed controls, I/O marks, Delete cuts, Ctrl+Z undo
- [ ] `toggleCheatsheet` — creates overlay with correct content, toggles off
- [ ] Skip logic — skips correctly forward and back from current playhead

### useVideoSync.ts — no existing tests
- [ ] Synchronization of store `isPlaying` with video element, audio element
- [ ] `togglePlay` — starts playing, pauses
- [ ] `seekTo` — seeks video to correct time, seeks audio to correct time
- [ ] Handles video element ref being null (doesn't crash)

---

## 4. Frontend lib (`frontend/src/lib/`)

### keybindings.ts — no existing tests
- [ ] `loadBindings` — loads from localStorage, falls back to standard preset when missing
- [ ] `saveBindings` — persists and reloads correctly
- [ ] `applyPreset` — 'standard' and 'left-hand' both apply all required bindings
- [ ] `detectConflicts` — detects duplicate keys, returns empty when no conflicts

---

## 5. Backend services (`backend/services/`)

### video_editor.py — no existing tests
- [ ] `apply_cut_segments` — keeps correct segments from transcript word list, FFmpeg concat cmd
- [ ] `apply_mute_ranges` — cuts audio for muted ranges
- [ ] `apply_gain_ranges` — adjusts volume (positive and negative) for FFmpeg filter chains
- [ ] `apply_speed_ranges` — time-stretches or compresses segments
- [ ] `mix_background_music` — mixes with ducking enabled, mixes without ducking, handles no music
- [ ] `build_export_filters` — stitches together all zone types into correct filter order

### audio_cleaner.py — no existing tests
- [ ] `detect_silence` — detects pauses above threshold, returns correct time ranges
- [ ] `remove_silence` — splits by silence, re-concatenates keep segments

### ai_provider.py — no existing tests
- [ ] `complete` — Ollama completion succeeds, OpenAI completion succeeds, Claude completion succeeds
- [ ] `complete` — handles missing provider, timeout, bad JSON response
- [ ] `list_ollama_models` — returns models list, handles connection error

### transcription.py — no existing tests
- [ ] `transcribe_file` — returns words with correct format (word, start, end, confidence)
- [ ] `transcribe_segment` — re-transcribes a range with offset-adjusted timestamps
- [ ] `_load_model` — caches model, returns existing from cache, handles GPU/CPU

### caption_generator.py — no existing tests
- [ ] `generate_srt` — correct SRT format, sequential numbering, proper timestamps
- [ ] `generate_vtt` — correct VTT format with header, chroma key tags
- [ ] `generate_ass` — correct ASS subtitle format

### gpu_utils.py — no existing tests
- [ ] `get_optimal_device` — returns CUDA when available, returns CPU otherwise

### audio_processing.py — no existing tests
- [ ] `extract_audio` — extracts wav from video, handles audio-only input, temp file cleanup

---

## 6. Frontend components — integration tests

### TranscriptEditor.tsx
- [ ] Word selection: click, shift+click range, drag select
- [ ] Ctrl+click seeks video to correct time
- [ ] Double-click enters edit mode, Enter commits, Escape cancels
- [ ] Zone mode drag creates correct zone type
- [ ] Search finds matches, navigates with Enter/Shift+Enter
- [ ] "Restore" button appears on hover over words in a zone, removes the zone
- [ ] Re-transcribe calls backend and updates words
- [ ] Selection toolbar buttons create correct zone types
- [ ] When `canEdit` is false, buttons are disabled and zone creation is blocked

### WaveformTimeline.tsx
- [ ] Canvas renders waveform when audio data loads
- [ ] Click seeks to correct time
- [ ] Zone drag creates zone on mouse up
- [ ] Zone selection and resize with handles
- [ ] Delete key removes selected zone
- [ ] Zoom and scroll work correctly
- [ ] Zone toggle buttons show/hide overlay layers
- [ ] Loading spinner shows when no waveform data
- [ ] Error message with retry button on load failure

### ExportDialog.tsx
- [ ] Fast mode card and re-encode card toggle correctly
- [ ] Resolution selector only visible in re-encode mode
- [ ] Format selector disables WAV for video files
- [ ] Export button triggers export with correct parameters
- [ ] Progress bar updates during export
- [ ] Loudness normalization checkbox shows LUFS target selector

### AIPanel.tsx
- [ ] Filler words tab: detect button sends request, displays results
- [ ] Apply All creates cut ranges for all fillers
- [ ] Clips tab: find clips shows suggestions
- [ ] Reprocess tab: model selector + reprocess button
- [ ] Error state with retry on API failure

### App.tsx — layout and toolbar
- [ ] Welcome screen shows when no video loaded
- [ ] Trial bar shows on welcome screen for Trial/Expired states
- [ ] Toolbar buttons toggle modes correctly (Cut, Mute, Gain, Speed)
- [ ] Toolbar buttons open correct panels (Zones, Silence, Markers, Music, Append, AI, Export, Settings, Help)
- [ ] File menu opens/closes, items work
- [ ] Split pane dividers are draggable and keyboard-accessible
- [ ] First-run welcome overlay shows once
- [ ] Hotkeys work: Escape clears modes, ? opens cheatsheet

---

## 7. Error handling regression tests

- [ ] Backend crash: show reconnect banner, not broken UI
- [ ] Transcription failure: show error, allow retry with different model
- [ ] Export failure: show FFmpeg stderr, allow copy
- [ ] Model download timeout: show error, allow retry
- [ ] File not found: handled gracefully on open/load
- [ ] Permission denied: handled gracefully on save/export
- [ ] Concurrent operations: block export during transcription, block transcription during export

---

## 8. Licensing & trial flow tests

- [ ] Fresh install: shows 30-day trial
- [ ] Day 29: still allows editing
- [ ] Day 31: shows expired, editing locked, export still works
- [ ] Activate valid license: switches to Licensed, clears trial
- [ ] Activate invalid license: shows error, stays on trial
- [ ] Deactivate license: returns to trial if valid, expires if trial over
- [ ] Expired banner shows correct message and activate link
- [ ] `canEdit` prop correctly gates all editing controls across all components

---

## Test infrastructure

| Layer | Framework | Run command |
|-------|-----------|-------------|
| Rust | `cargo test` (built-in) | `cd src-tauri && cargo test` |
| Frontend (Vitest) | Vitest + jsdom | `cd frontend && npx vitest run` |
| Frontend (components) | Playwright or Vitest + testing-library | `cd frontend && npx vitest run` |
| Python backend | pytest | `cd backend && python -m pytest` |

### Setup needed
- [ ] Frontend: `npm install -D vitest @testing-library/react @testing-library/jest-dom jsdom` (vitest likely already installed)
- [ ] Frontend: add `"test": "vitest run"` to `package.json` if not present
- [ ] Python: ensure pytest is installed (`pip install pytest pytest-asyncio`)
- [ ] CI: add GitHub Actions workflow for `cargo test && vitest run && pytest`

---

## Priority order

1. **store tests** (editorStore, licenseStore, aiStore) — core data integrity
2. **Rust licensing tests** — payment/trial logic must never break
3. **Rust models tests** — filesystem operations must be safe
4. **Backend service unit tests** — export pipeline, transcription, AI
5. **Component integration tests** — user-facing behavior
6. **Error handling regression tests** — robustness

---

## Robustness beyond tests

### React Error Boundary
The app has no error boundary — a single JS error in any component crashes the entire UI to a white screen. Wrap the app in a `<ErrorBoundary>` that catches render errors and shows a fallback with "Something went wrong" + a reload button.

- [ ] Create `ErrorBoundary.tsx` component (`componentDidCatch` pattern)
- [ ] Wrap the entire `<App />` in `main.tsx`
- [ ] Fallback shows: error message, stack trace (collapsed), "Reload" button, "Reset & Clear State" button

### Global JS error logging
Uncaught errors in async code and event handlers silently break the app. Add a `window.onerror` and `window.onunhandledrejection` handler that logs to the Tauri backend and shows a toast notification.

- [ ] Add global error handler in `main.tsx` that intercepts all uncaught errors
- [ ] Log to Rust backend via `invoke('log_error', { message, stack })` 
- [ ] Show a non-blocking toast notification (bottom-right) for non-fatal errors
- [ ] Fatal errors still go to the ErrorBoundary

### Input validation layer
The app trusts user input too much. Invalid values in number inputs, empty file paths, or negative durations can cause crashes or silent failures. Add validation at the store level.

- [ ] `editorStore.ts` — validate all setters: clamp numbers, reject empty strings for paths, enforce min/max on dB and speed values
- [ ] `licenseStore.ts` — validate license key format before sending to Rust (prefix check, base64 pattern)
- [ ] `aiStore.ts` — validate API key formatting, model name not empty
- [ ] Export options — validate resolution, format, loudness target against allowed values before sending to backend

### Frontend runtime assertions
The app makes assumptions about data shapes (e.g. `words[sorted[0]].start` assumes the index exists). Add assertion checks in critical paths that log a clear error instead of silently producing NaN or undefined.

- [ ] Add an `assert` utility function: `assert(condition, message)` that throws a descriptive error in dev, warns in prod
- [ ] Guard all array index access in TranscriptEditor, WaveformTimeline, ExportDialog
- [ ] Guard null/undefined checks on store actions that expect existing data

### Auto-save crash recovery
If the app crashes or the system loses power during editing, current work is lost. Add periodic auto-save to a temp file that gets restored on next launch.

- [ ] Every 60 seconds, save the full editor state to `app_data_dir/autosave.json`
- [ ] On launch, check if autosave.json exists and is newer than the last manual save
- [ ] Show a "Recover unsaved work?" prompt with date/time of autosave
- [ ] Clean up autosave after a manual save or after recovery is accepted/dismissed

### Backend health check & self-diagnostics
When the Python backend dies mid-session, the app doesn't know until a request fails. Add periodic health checks and a diagnostics panel.

- [ ] Poll `GET /health` every 15 seconds from the frontend
- [ ] If backend is unreachable: show a non-blocking banner "Backend disconnected — retrying..."
- [ ] When backend comes back online, dismiss the banner automatically
- [ ] Add a `/diagnostics` endpoint that reports: Python version, available FFmpeg, GPU detection, model cache sizes, disk space
- [ ] Wire to a "System Info" section in Settings or DevPanel

### CI pipeline with automated checks
Currently no CI exists. A GitHub Actions workflow would catch regressions on every push.

- [ ] Add `.github/workflows/ci.yml`:
  - `cargo test` — all Rust tests
  - `cargo clippy -- -D warnings` — enforce Rust lint rules
  - `npx vitest run` — all frontend tests
  - `npx tsc --noEmit` — TypeScript type check
  - `python -m pytest backend/tests/` — Python backend tests
  - `cargo build --release` — verify release build succeeds
- [ ] Run on push to `main` and on PRs
- [ ] Add Rust `#[deny(clippy::all)]` to catch common mistakes at build time

### Fuzz testing for Rust deserialization
The app deserializes user-provided JSON (project files, API responses) — any malformed input could crash the Rust backend. Add fuzz tests for the critical deserialization paths.

- [ ] Fuzz `TranscriptionResult` deserialization — malformed word/segment JSON
- [ ] Fuzz `.aive` project file loading — corrupted JSON, missing fields, wrong types
- [ ] Fuzz `LicensePayload` deserialization — tampered license payloads
- [ ] Use `cargo-fuzz` or `proptest` crate for property-based testing

### Performance telemetry (opt-in)
Without real-world data, you can't know where the app is slow. Add lightweight timing around operations that users complain about.

- [ ] Log timing for: transcription time, export time, AI completion time, model download time
- [ ] Store in localStorage (not sent anywhere — privacy-first)
- [ ] Show in DevPanel: last N operation timings
- [ ] Use this data to identify slow paths before users report them

### Recovery from bad project state
A corrupted `.aive` file or a partially-loaded project can leave the app in an unusable state. Add recovery paths.

- [ ] On project load failure: show error, offer "Load anyway with partial data" or "Cancel"
- [ ] Add "Reset Editor State" button in DevPanel (clears all state back to empty)
- [ ] Store action: validate all zone ranges are within video duration, auto-remove invalid ones on save