docs/TASKS.md

# Task ledger

Last updated: 2026-05-12

## Completed in current pass: API validation and visible errors

- [x] Fix `/api/jobs` rejecting UI-submitted `subdivision` values such as `"16"`.
- [x] Add defensive backend coercion for integer, float, and boolean pipeline parameters.
- [x] Convert frontend control values according to `/api/config.defaults` before submitting jobs.
- [x] Add a global visible error banner for failed API/network requests.
- [x] Surface extraction-start failures in the summary and Pipeline log panels.
- [x] Add regression coverage in `scripts/test_param_validation_and_api_errors.py`.


## User-requested tasks

| Task | Status | Evidence |
|---|---:|---|
| Review the project | Done | `docs/PROJECT_REVIEW.md`. |
| Determine length of significant subprocesses | Done | `pipeline_runner.py`, `scripts/benchmark_subprocesses.py`, `docs/benchmark-subprocesses.json`, `docs/PIPELINE_TIMING_AND_REALTIME.md`. |
| Identify near-realtime subprocesses | Done | `docs/PIPELINE_TIMING_AND_REALTIME.md`. |
| Add documentation to project | Done | `docs/*.md`, updated `README.md`. |
| Replace Gradio UI | Done | Active app is FastAPI + custom web UI; Gradio moved to `legacy/`. |
| Document features, tasks, and progress | Done | `docs/FEATURES.md`, this file, `docs/PROGRESS.md`. |
| Continue development while keeping docs up-to-date | In progress | Latest pass adds SSE progress, per-hit review artifacts, hit/sample audition, hardened artifact serving, and docs updates. |

## Completed implementation tasks

- [x] Preserve old Gradio apps in `legacy/`.
- [x] Expose extraction as a FastAPI job API.
- [x] Serve a custom browser UI from `web/`.
- [x] Add per-stage timing to the pipeline.
- [x] Write per-run `manifest.json`.
- [x] Add synthetic benchmark script.
- [x] Add API documentation.
- [x] Add UI replacement documentation.
- [x] Add project review and realtime analysis documentation.
- [x] Add run-history listing endpoint: `GET /api/jobs`.
- [x] Add run-history UI panel.
- [x] Add disk cache for stem/full-mix loads.
- [x] Extend cache clearing to disk cache.
- [x] Add prototype-based `online_preview` clustering mode.
- [x] Add UI controls for clustering mode and disk cache.
- [x] Fix duplicate sample writes in `build_archive`.
- [x] Add feature, task, and progress docs.
- [x] Add `GET /api/jobs/{id}/events` SSE progress stream.
- [x] Add per-hit review WAV export under `review/hits/`.
- [x] Add manifest `hits` rows with onset, duration, cluster, representative flag, and artifact path.
- [x] Add click-to-audition for waveform onset markers and detected hit rows.
- [x] Add sample-row audition controls.
- [x] Harden artifact path containment with `Path.relative_to()`.
- [x] Add hit review/streaming documentation.

## Validation tasks

- [x] Python compile check for active Python files.
- [x] FastAPI smoke test for health/config/job flow.
- [x] Pipeline smoke test on synthetic audio.
- [x] API history/cache smoke test.
- [x] SSE and review-hit artifact smoke test via `scripts/test_sse_and_review_hits.py`.
- [x] Git status reviewed before packaging.
- [x] Project archive excludes `.runs/`, `.cache/`, and dependency folders.

## Remaining high-value tasks

- [ ] Add onset adjustment and rerun-from-onsets flow.
- [ ] Add cluster merge/split/relabel workflow.
- [ ] Add side-by-side run comparison.
- [ ] Convert frontend to TypeScript with a small Vite build once UX stabilizes.
- [ ] Add automated browser-level UI tests.

## Interactive UX continuation tasks

| Task | Status | Evidence |
|---|---:|---|
| Add supplied interactive UX docs under `docs/interactive-ux/` | Done | `docs/interactive-ux/*.md`. |
| Read and align UX docs with current implementation | Done | Status sections updated in every interactive UX document. |
| Add persistent semantic job state | Done | `supervised_state.py`, `supervision_state.json`. |
| Add event log and constraint store | Done | `supervised_state.py`; tested by `scripts/test_interactive_supervision.py`. |
| Add hit/cluster confidence and review queue | Done/Partial | Heuristic confidence and review queue implemented; feature-margin confidence remains open. |
| Add move hit to cluster | Done | `POST /api/jobs/{job_id}/hits/{hit_id}/move`. |
| Add pull hit into new cluster | Done | `POST /api/jobs/{job_id}/hits/{hit_id}/pull-out`. |
| Add cluster lock/unlock | Done | `POST /api/jobs/{job_id}/clusters/{cluster_id}/lock`. |
| Add suppress hit as bleed/noise | Done | `POST /api/jobs/{job_id}/hits/{hit_id}/suppress`. |
| Add accept/favorite hit action | Done | `POST /api/jobs/{job_id}/hits/{hit_id}/review`; supervised re-export honors pinned/favorite representatives. |
| Add suggestion inbox | Done/Partial | UI/API supports accept/reject; exact diff preview still open. |
| Add cluster explanation drawer | Done | `GET /api/jobs/{job_id}/explain/cluster/{cluster_id}` plus UI drawer. |
| Add semantic undo | Done | `POST /api/jobs/{job_id}/undo`. |
| Add supervised export from edited state | Done | `supervised_export.py`; `POST /api/jobs/{job_id}/export`; UI edited download links. |
| Add click-to-add missed onset | Done | Add-onset waveform mode creates forced hits from `stem.wav`. |
| Add suppressed-hit restore | Done | `POST /api/jobs/{job_id}/hits/{hit_id}/restore`; UI restore button. |
| Add exact suggestion diff previews | Done | Suggestions expose `diff`; UI has `Diff` preview. |
| Add true local feature-neighborhood reclustering | Todo | Requires cached feature vectors and constraint-aware assignment. |

## Visual simplification tasks

| Task | Status | Notes |
|---|---|---|
| Restyle web UI to supplied minimal waveform-first reference | Done | Light theme, top-bar primary action, large waveform, compact right controls, sample-card grid, collapsible advanced/power panels. |
| Close remaining reference-alignment gaps | Done | Removed waveform header, added one custom transport row, moved fast modes into Advanced, collapsed power tools into Review & edit, hid visible audition players. |

## Latest validation tasks

- [x] `python3 -m py_compile app.py pipeline_runner.py sample_extractor.py supervised_state.py supervised_export.py scripts/*.py`
- [x] `node --check web/app.js`
- [x] `python3 scripts/test_api_job.py`

## Fixed workstation UI tasks

| Task | Status | Notes |
|---|---:|---|
| Remove document-level page scrolling | Done | `html, body` and `.shell` are viewport-locked; long content uses panel-local overflow. |
| Add left sidebar for secondary tools | Done | Source guidance, selection context, pipeline logs, and run history live in the left sidebar. |
| Add right sidebar for controls | Done | Core extraction, exports, and advanced model/DSP settings live in the right sidebar. |
| Add bottom bar for expandable editor panels | Done | Review/edit and raw tables live in `bottom-dock`. |
| Add explicit upload button | Done | Top bar now has a visible `Upload audio` control. |
| Make whole-app file dropping work | Done | Window-level drag/drop handlers select dropped files and prevent browser navigation. |
| Add drag overlay | Done | `globalDropOverlay` appears while dragging files over the app. |

## Pass 9 tasks: reproduced audio and parameter hierarchy

| Task | Status | Notes |
|---|---:|---|
| Export normalized source mix | Done | `source.wav` written per run. |
| Export non-target context bed | Done | `context_bed.wav` is source minus target stem; silent for `stem=all`. |
| Keep isolated target reconstruction | Done | `target_reconstruction.wav` written per run and per supervised export. |
| Make reproduced audio incorporate context | Done | `reconstruction.wav` is context bed plus target reconstruction. |
| Add full-context reproduction to ZIP | Done | `rendered_reproduction_full_mix.wav` plus compatibility alias. |
| Add target-stem reconstruction to ZIP | Done | `rendered_reconstruction_target_stem.wav`. |
| Update supervised export audio model | Done | Edited export writes full-context and target-only previews. |
| Add Source/Stem/Reproduced transport modes | Done | Transport buttons added in `web/index.html` and wired in `web/app.js`. |
| Separate common controls from advanced parameters | Done | Common controls: stem, sensitivity, sample groups, presets. |
| Group advanced parameters by pipeline stage | Done | Stem separation, hit detection, grouping, export/cache. |

Remaining follow-up tasks:

- [ ] Add source-vs-reproduced waveform/error comparison.
- [ ] Add LUFS loudness matching for long previews.
- [ ] Optionally cache explicit Demucs non-target stem sums instead of residual subtraction.

## Pass 10 tasks: clean default UI

| Task | Status | Notes |
|---|---:|---|
| Collapse secondary panels by default | Done | Source, selection, pipeline, history, exports, and review/edit no longer open on first load. |
| Make bottom dock compact by default | Done | Bottom dock is a small tab bar until `Review & edit` or `Tables` is opened. |
| Reduce top-bar visual weight | Done | Smaller brand mark, shorter upload control, compact backend status, smaller primary button. |
| Give center workspace more room | Done | Reduced sidebars/gaps/padding and collapsed bottom dock. |
| Hide long helper copy from common controls | Done | Common-control hint text is hidden; advanced descriptions remain in expandable sections. |
| Preserve no-scroll workstation behavior | Done | Body remains viewport-locked; panel-local scrolling remains. |
| Preserve all current features | Done | Existing DOM ids and API paths are preserved; changes are layout/CSS/default-open-state only. |


## Pass 11 tasks: immediate waveform and real progress flow

| Task | Status | Notes |
|---|---:|---|
| Show uploaded waveform immediately | Done | Browser decodes selected/dropped files with Web Audio and renders a peak envelope before extraction. |
| Preserve source preview playback before extraction | Done | Uploaded file object URL remains wired to the Source transport. |
| Add explicit sequential start flow | Done | Left sidebar `Start here` panel shows Load → Controls → Extract → Review/export. |
| Add top-level backend progress contract | Done | Job payloads include `progress` with fraction, stage, and work-unit fields. |
| Add stage progress fields | Done | `StageTiming` includes `progress`, `work_done`, and `work_total`. |
| Report Demucs chunk progress | Done | `extract_stem()` reports exact completed split chunks through `progress_cb`. |
| Render extraction progress on waveform | Done | Running jobs draw the uploaded/extracted waveform in completed and remaining colors. |
| Avoid guessed progress values | Done | UI consumes backend progress only; no ETA or timer interpolation is used. |
| Add docs for progress semantics | Done | See `docs/IMMEDIATE_WAVEFORM_AND_REAL_PROGRESS.md`. |

Follow-up tasks:

- [ ] Add finer-grained callback progress inside onset detection.
- [ ] Add finer-grained callback progress inside clustering pair computation.
- [ ] Add browser-level tests for upload waveform rendering and progress tinting.

## Automatic card-flow task batch

Completed:

- [x] Start extraction automatically after file drop/upload.
- [x] Keep immediate browser waveform rendering before backend work completes.
- [x] Add automatic tuning stage after source/stem loading.
- [x] Stream sample-card availability through `partial_samples`.
- [x] Group cards by detected type.
- [x] Add dismiss-card action.
- [x] Add draw-another-candidate action for missing samples.
- [x] Add simple trim/extend controls and save adjusted timing as forced hit.
- [x] Add waveform zoom/pan interaction.
- [x] Make MIDI export robust when `pretty_midi` is unavailable.

Next:

- [ ] Promote drawn candidate cards into backend representative choices.
- [ ] Add immediate local reclustering after dismiss/draw constraints.
- [ ] Add browser tests for the automatic card-flow path.


## Reference image UI alignment

- [x] Match top bar structure: brand, beta badge, current file, export buttons.
- [x] Match main layout: waveform left, settings right, sample columns below.
- [x] Keep automatic upload/process flow.
- [x] Keep advanced controls hidden behind a collapsed expert section.
- [x] Preserve existing review/edit tools in a secondary drawer.
- [ ] Implement true per-card selection and selected-only export artifacts.
- [ ] Run browser screenshot comparison in an environment that allows localhost rendering.


## Selected cards and separation backends

Completed:

- [x] Add Spleeter backend option.
- [x] Default new jobs to Spleeter `spleeter:4stems` + `drums`.
- [x] Keep Demucs as explicit quality/fallback backend.
- [x] Add `none` backend for full-mix preview.
- [x] Add optional `requirements-spleeter.txt`.
- [x] Add per-card checkbox selection.
- [x] Add selected-only backend export.
- [x] Persist draw-next representative overrides.
- [x] Rewrite preview audio immediately for trim/extend edits.
- [x] Add regression smoke test for selected export/card actions.

Next:

- [ ] Add card-column relabel/merge/split actions.
- [ ] Add browser-level tests for card selection/export/edit flows.
- [ ] Add localized high-quality separation refinement on short candidate windows.

## Upload/runtime fallback update (2026-05-12)

- Added a visible top-bar `Choose audio` affordance in addition to whole-app drag/drop.
- Fixed the default hidden state of the error banner so placeholder errors are not shown on page load.
- API errors now surface request path/status/detail in the visible banner and pipeline logs.
- `/api/config` now includes runtime diagnostics for optional separation backends.
- If Spleeter is unavailable, the simple UI keeps the app usable by switching to full-mix mode; backend fallback also uses full-mix rather than silently launching Demucs.