docs/CARD_SELECTION_EXPORT_AND_EDITING.md

# Card selection, selected export, draw-next, and immediate timing edits

Last updated: 2026-05-12

## Goal

The default workflow should feel like reviewing cards rather than configuring a batch pipeline:

```text
drop audio → cards appear → keep/dismiss/draw/trim → export selected
```

## Implemented

### Per-card selection

Each visible sample card now has a real checkbox. Newly produced cards are selected by default until the user changes selection manually. After the user clears or changes the selection, the UI respects that manual state.

### Selected-only export

`POST /api/jobs/{job_id}/export-selected` renders only the selected card labels into a separate `selected/` export directory:

- `selected/sample-pack.zip`,
- `selected/samples/*.wav`,
- `selected/reconstruction.mid`,
- `selected/target_reconstruction.wav`,
- `selected/reconstruction.wav`,
- `selected/manifest.json`.

The original batch export is left untouched.

### Persisted draw-next

The card “draw another” action now calls:

```text
POST /api/jobs/{job_id}/samples/{sample_label}/draw
```

The backend cycles the semantic cluster representative to the next active hit and records that as a pinned representative override. Later selected/edited exports honor this choice.

### Immediate trim/extend preview

Trim/extend actions now call:

```text
POST /api/jobs/{job_id}/samples/{sample_label}/edit
```

The backend slices from `stem.wav`, writes an edited preview under `overrides/hits/`, updates the representative hit audio path, and returns a refreshed sample card. The user hears the edited clip immediately.

## Validation

Covered by:

```bash
python3 scripts/test_selected_export_card_actions.py
```

The test verifies:

1. extraction succeeds,
2. selected-only export writes a selected pack,
3. draw-next returns a playable representative WAV,
4. trim/extend writes a playable edited override WAV.

## Remaining work

- Add true cluster relabel/merge/split from the card columns.
- Add batch restore and bulk card operations.
- Add browser-level tests for checkbox selection and selected export.
- Add visual diff between original representative and edited representative.