Stack L/R waveform lanes in stereo mode, with overlays drawn once at full band height

src/core/instrument/CLAUDE.md

@@ -220,7 +220,8 @@ slider couldn't. Two pure modules split the forward (draw) and inverse (edit) ma
 - `sample_bands` — **THE band-stack allocator**, and the only module that owns the Sample face's vertical inventory: three bands top-to-bottom (CHROME toolbar+control row / WAVEFORM elastic, floored at two stacked lanes / DECKS bottom-anchored at the knob deck's own wrapped height), plus the waveform band's lane split. A shared READ-ONLY surface for every band owner — a band's interior module lays out inside the rect it is handed and never re-allocates the stack.
 - `sample_chrome` — the CHROME band's interior: the toolbar row (title + Browse) over the control row (root strip, preview, velocity knob cell, curve button, channel toggle). The fixed run is right-anchored; the root strip takes the remainder.
 - `keyboard_strip` — piano-keyboard strip: MIDI-note→key rect mapping, black/white key layout, hit-test, root-marker rect, and the drag-delta note resolver.
-- `waveform_view` — waveform/marker geometry: maps frame span linearly across a rect; generic named draggable markers with drag-delta resolver, clamp, and zero-crossing snap.
+- `waveform_view` — the WAVEFORM band's interior: `waveformSurface` resolves the drawn lane(s) (two stacked lanes, L over R, only when the mode is stereo AND the source has a second channel — a mono source under stereo mode is dual-mono and draws one lane) plus **the** overlay rect, and `laneEnvelope` splits one multi-channel envelope pass per lane. Also maps frame span linearly across a rect; generic named draggable markers with drag-delta resolver, clamp, and zero-crossing snap.
+  - **Overlay contract (consumed by later waveform work).** `WaveformSurface::overlay` — equivalently the standalone `waveformOverlayArea(band)` — is the FULL band in both modes. Everything riding the waveform (the amp-envelope trace and its node handles, the start/loop markers, the loop region) draws ONCE into it, spanning both stacked lanes; hit-testing resolves against the same rect so a grab in the lower lane reaches them. Anything drawn or hit-tested per lane is a duplicate and a defect.
 - `capture_browser` — capture browser: card-grid layout + bank-filter tab strip geometry and hit-test; knows only counts and rects, draws nothing.
 - `browser_scroll` — scroll + type-to-filter layered over `capture_browser`: vertical scroll offset, scrollbar thumb, thumb-drag mapping, and name-substring search.
 - `param_slider` — parameter control-panel: vertical stack of TOGGLE (two-segment selector) and SLIDER (horizontal track) rows; maps normalized value to/from handle pixel.

src/core/instrument/ui/waveform_view.cpp

@@ -3,6 +3,7 @@
 #include "core/instrument/ui/waveform_view.h"
 
 #include <algorithm>
+#include <cstddef>
 #include <cstdlib>  // std::abs (int overload)
 
 namespace reasampler::instrument::ui {
@@ -17,6 +18,25 @@ std::int64_t clampFrame(std::int64_t f, std::int64_t frameCount) {
 
 }  // namespace
 
+Rect waveformOverlayArea(const Rect& band) { return band.empty() ? Rect{} : band; }
+
+WaveformSurface waveformSurface(const Rect& band, bool stereoMode, int sourceChannels) {
+    WaveformSurface s;
+    if (band.empty()) return s;
+    s.overlay = waveformOverlayArea(band);
+    const bool twoLanes = stereoMode && sourceChannels >= 2;
+    const WaveformLanes lanes = waveformLanes(band, twoLanes);
+    s.upper = lanes.upper;
+    s.lower = lanes.lower;
+    s.laneCount = twoLanes ? 2 : 1;
+    return s;
+}
+
+audio::Envelope laneEnvelope(const audio::Envelope& env, int lane) {
+    if (lane < 0 || static_cast<std::size_t>(lane) >= env.size()) return {};
+    return audio::Envelope{env[static_cast<std::size_t>(lane)]};
+}
+
 int frameToX(const Rect& area, std::int64_t frameCount, std::int64_t frame) {
     const int w = std::max(0, area.width);
     if (frameCount <= 0 || w <= 0) return area.x;

src/core/instrument/ui/waveform_view.h

@@ -1,22 +1,55 @@
-// waveform_view.h — waveform/marker geometry + zero-crossing snap. Mirror of keyboard_strip/
-// editor_geometry: frame<->pixel + marker hit-test + snap arithmetic lives here, unit-tested
-// outside the DAW; the shell draws and marshals mouse events into it.
+// waveform_view.h — the WAVEFORM band's interior: the drawn lane/overlay surface, plus
+// frame<->pixel mapping, marker hit-test and zero-crossing snap. Unit-tested outside the
+// DAW; the shell draws and marshals mouse events into it.
 //
-// The surface maps a sample's full frame span [0, frameCount] linearly across a horizontal
-// waveform rect. Markers are a generic N-named-marker set (not hardcoded specials), so a
-// different mode (e.g. start + %-length end + fades) can repurpose the same machinery.
+// The band maps a sample's full frame span [0, frameCount] linearly across its width.
+// Markers are a generic N-named-marker set (not hardcoded specials), so a different mode
+// (e.g. start + %-length end + fades) can repurpose the same machinery.
 
 #pragma once
 
 #include <cstdint>
 
 #include "core/instrument/ui/editor_geometry.h"  // Rect, contains
-#include "core/audio/peaks.h"            // AudioSample (float)
+#include "core/instrument/ui/sample_bands.h"     // waveformLanes (the band's lane inventory)
+#include "core/audio/peaks.h"            // AudioSample (float), Envelope
 
 namespace reasampler::instrument::ui {
 
 using audio::AudioSample;
 
+// What the waveform band actually draws: the channel lane(s), and THE rect every overlay
+// riding the waveform occupies.
+//
+// OVERLAY CONTRACT — `overlay` is the whole band in BOTH modes, never a lane. The amp
+// envelope trace and its node handles, the start/loop markers, and the loop region draw
+// ONCE into `overlay`, spanning both stacked lanes in stereo. Hit-testing reads the same
+// rect, so a grab in the lower lane resolves to the same overlay item as one in the upper.
+// Anything that draws per lane is a duplicate and a defect.
+struct WaveformSurface {
+    Rect upper;         // lane 0 -> channel 0 (LEFT); the whole band when single-lane
+    Rect lower;         // lane 1 -> channel 1 (RIGHT); empty() when single-lane
+    Rect overlay;       // the full band, both modes
+    int laneCount = 0;  // 0 on a degenerate band, else 1 or 2
+};
+
+// Resolves the surface for a waveform band. Two lanes need BOTH stereo mode and a source
+// that has a second channel to show: a mono source under stereo mode is dual-mono, so a
+// second lane would be the redundant duplicate single-lane mode exists to avoid.
+WaveformSurface waveformSurface(const Rect& band, bool stereoMode, int sourceChannels);
+
+// THE overlay rect, standalone — same value as WaveformSurface::overlay, for the hit-test
+// paths that have no channel count to hand. An overlay's rect never depends on the lane
+// split, which is exactly the contract.
+Rect waveformOverlayArea(const Rect& band);
+
+// The single-channel envelope lane `lane` draws, taken from a multi-channel envelope
+// computed in ONE computeEnvelope pass (it already envelopes channels independently, so a
+// second lane costs no second scan of the PCM). Lane 0 is the upper lane and takes channel
+// 0, lane 1 the lower and channel 1 — the L-above-R order. An out-of-range lane yields an
+// empty envelope, which draws as a bare midline.
+audio::Envelope laneEnvelope(const audio::Envelope& env, int lane);
+
 // Pixel width of a marker's grab region either side of its x line. Mirrors keyboard_strip's
 // edge-grab idiom.
 inline constexpr int kMarkerGrabWidth = 5;