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

Principle

Good interaction:

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:

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.