docs/FIXED_WORKSTATION_UI.md

# Fixed workstation UI

Last updated: 2026-05-12

## Goal

The web app should behave like a compact workstation rather than a long document page. The default screen must not require document scrolling. Secondary tools live in left and right sidebars plus a bottom bar, with each tool panel independently expandable/collapsible.

## Implemented layout

| Region | Contents | Scroll behavior |
|---|---|---|
| Top bar | App title, explicit `Upload audio` button, selected-file metadata, backend status, primary `Extract Samples` action | Fixed height; no scroll |
| Left sidebar | Source/drop guidance, selected-hit/sample context, pipeline stages/logs, run history | Sidebar-internal scroll only |
| Center workspace | Large waveform, Source/Stem/Reproduced transport, and representative sample cards | Sample grid scrolls internally when needed |
| Right sidebar | Common extraction controls, exports, and advanced parameters grouped by stage | Sidebar-internal scroll only |
| Bottom bar | Interactive review/edit tools and raw tables | Panel-internal scroll only |

The document itself is locked with `overflow: hidden`; long content is constrained to the relevant tool panel.

## Upload behavior

Implemented upload affordances:

1. A visible `Upload audio` control in the top bar.
2. A selected-file label beside the upload button.
3. Whole-app drag/drop for audio files.
4. A full-screen drop overlay while dragging files over the app.
5. Existing multipart upload path through `POST /api/jobs` remains unchanged.

## Design constraints

- Keep the center workspace visually simple: waveform, transport, sample cards.
- Do not reintroduce long-page scrolling.
- Avoid duplicate controls; power tools should live in sidebars or the bottom dock.
- Keep tool panels based on native `<details>` so they remain simple and keyboard-accessible.
- Preserve all existing DOM ids used by the no-build JavaScript app.

## Validation

Static checks added/performed for this pass:

- `node --check web/app.js`
- DOM id/reference check for every `$()` lookup in `web/app.js`
- Duplicate id check for `web/index.html`
- Python compile check for active Python files
- FastAPI extraction smoke test


## Pass 9 additions

- The center transport now exposes explicit `Source`, `Stem`, and `Reproduced` preview modes.
- The right sidebar now separates the normal workflow from advanced tuning.
- Common controls are limited to stem choice, hit sensitivity, sample group count, and two presets.
- Advanced parameters are grouped into stem separation, hit detection, grouping, export/cache sections.

## Clean default refinement

The fixed workstation layout now defaults to a much quieter state:

- left-sidebar utility panels are closed initially;
- the right-sidebar exports panel is closed initially;
- the bottom dock is only a compact tab bar until opened;
- the common-control card remains open because it is part of the core extraction loop;
- helper copy is hidden from the default common-control view;
- the waveform and sample grid receive more viewport space.

The layout still does not use document-level scrolling. Opening a panel expands only that panel or dock and uses local scrolling as needed.

## 2026-05-12 update: guided start and progress waveform

The fixed workstation now starts with a visible `Start here` flow in the left sidebar. Selecting or dropping a file immediately renders the uploaded waveform in the center workspace before extraction starts. During extraction, the waveform is tinted from left to right using the backend job `progress.fraction`; this fraction is based on exact completed work units such as Demucs chunks when available, and exact stage boundaries otherwise.