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.