docs/interactive-ux/README.md

# Interactive supervised extraction UX

This directory contains the supplied interactive-UX design documents, aligned with the implementation as of 2026-05-12.

The product direction is to turn drum sample extraction from a one-shot batch process into an interactive, supervised, progressively improving workflow. User edits should become constraints, preferences, and examples that improve clustering, review priority, labeling, and cleanup instead of only changing a visible table row.

## Current implementation status

The project now has a first supervised-editing foundation layered on top of the immutable extraction manifest:

- `supervised_state.py` persists `supervision_state.json` beside each completed run manifest.
- The state contains hits, clusters, confidence scores, review queue entries, constraints, events, suggestions, and undo snapshots.
- The FastAPI backend exposes state, move, pull-out, lock, suppress, review/favorite, suggestion, explanation, and undo endpoints.
- The browser UI includes an interactive supervision panel with a review queue, cluster board, suggestion inbox, constraint/event log, and cluster explanation drawer.
- The supervised layer now rewrites edited sample WAVs, MIDI, target reconstruction, full-context reproduced audio, and ZIP artifacts under `supervised/` while preserving original batch outputs.

## Documents

| Document | Purpose | Alignment status |
|---|---|---|
| [`FEATURE_REQUIREMENTS.md`](./FEATURE_REQUIREMENTS.md) | Functional requirements for interaction-driven quality improvements | Updated with implemented/partial/not-started status |
| [`SCOPE.md`](./SCOPE.md) | MVP, v2, and research/backlog boundaries | Updated to reflect delivered MVP foundation |
| [`FEASIBILITY_MATRIX.md`](./FEASIBILITY_MATRIX.md) | Feasibility, complexity, effort, UX value, quality value table | Kept as design prioritization with implementation notes |
| [`TASKS.md`](./TASKS.md) | Implementation task breakdown with dependencies and acceptance criteria | Updated with current task statuses |
| [`PROGRESS.md`](./PROGRESS.md) | Current status, completed work, open work, next actions | Updated after this development pass |
| [`ARCHITECTURE_NOTES.md`](./ARCHITECTURE_NOTES.md) | Required state model and technical approach | Updated with actual module/API mapping |

## Principle

Good interaction:

```text
user moves one hit into another cluster
→ system creates force-cluster/must-link constraints
→ semantic state recomputes confidence and review priority
→ similar ambiguous hits are proposed as suggestions
→ the UI explains the state/event/constraint changes
```

Bad interaction:

```text
user moves one hit
→ only that one visible DOM row changes
→ future clustering ignores the correction
```

## Current build recommendation

Next implementation should close the gap between semantic edits and artifact output:

1. Re-export edited sample pack from `supervision_state.json` without rerunning Demucs/onset detection.
2. Add waveform click-to-add missed onset backed by `force-onset` constraints.
3. Add restore for suppressed hits and batch accepted suggestions.
4. Make move/pull-out trigger a real local reclustering pass using cached feature vectors.
5. Add visible diff previews before accepting grouped suggestions.
6. Add browser-level tests for the interactive supervision panel.

The strongest technical foundation remains constraint-aware clustering plus uncertainty-driven review. The current pass implements the persistent state and UI/API shell needed for that foundation.


## Pass 5 implementation status

Implemented after initial alignment:

- supervised edited-state export under `supervised/`,
- add-onset waveform mode backed by `POST /api/jobs/{job_id}/hits/force-onset`,
- suppressed-hit restore backed by `POST /api/jobs/{job_id}/hits/{hit_id}/restore`,
- exact suggestion diff previews in API state and UI,
- validation via `scripts/test_supervised_export_and_force_onset.py`.

Still open:

- cluster merge/relabel/split workflows,
- cached feature-vector local reclustering,
- edited-vs-original comparison,
- browser-level UI tests.