Fix waveform_view comment accuracy, cut duplicate comments, align xToFrame to OverlayArea

src/core/instrument/ui/waveform_view.cpp

@@ -33,8 +33,10 @@ WaveformSurface waveformSurface(const Rect& band, bool stereoMode, int sourceCha
         waveformLanes(band, twoLanes ? LaneSplit::Stereo : LaneSplit::Single);
     s.upper = lanes.upper;
     s.lower = lanes.lower;
-    // Derived from the resolved lanes, not `twoLanes`, so it can never contradict them (a
-    // band barely over the two-lane floor can still yield an empty lower lane).
+    // Derived from the resolved lanes, not `twoLanes` — a stereo split's integer division
+    // rounds the lower lane to empty for a band this thin (height <= 3), far below the
+    // allocator's kWaveformMinHeight floor but reachable if this is called directly with an
+    // arbitrary rect (as tests do).
     s.laneCount = lanes.lower.empty() ? 1 : 2;
     return s;
 }
@@ -53,12 +55,13 @@ int frameToX(const OverlayArea& area, std::int64_t frameCount, std::int64_t fram
     return area.rect.x + static_cast<int>(num / frameCount);
 }
 
-std::int64_t xToFrame(const Rect& area, std::int64_t frameCount, int x) {
-    const int w = std::max(0, area.width);
+std::int64_t xToFrame(const OverlayArea& area, std::int64_t frameCount, int x) {
+    const Rect& r = area.rect;
+    const int w = std::max(0, r.width);
     if (frameCount <= 0 || w <= 0) return 0;
-    if (x <= area.x) return 0;
-    if (x >= area.right()) return frameCount;
-    const std::int64_t dx = static_cast<std::int64_t>(x - area.x);
+    if (x <= r.x) return 0;
+    if (x >= r.right()) return frameCount;
+    const std::int64_t dx = static_cast<std::int64_t>(x - r.x);
     // Inverse of frameToX: frame = round(dx * frameCount / w).
     const std::int64_t num = dx * frameCount + static_cast<std::int64_t>(w) / 2;
     return clampFrame(num / static_cast<std::int64_t>(w), frameCount);

src/core/instrument/ui/waveform_view.h

@@ -28,10 +28,11 @@ using audio::AudioSample;
 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
-    OverlayArea overlay; // the full band, both modes — a distinct type (not Rect) so an
-                         // overlay-only API can't accept a lane rect by mistake
-    int laneCount = 0;  // 0 on a degenerate band, else 1 or 2 — derived from the resolved
-                        // lanes (never contradicts upper/lower)
+    OverlayArea overlay; // the full band, both modes
+    int laneCount = 0;  // 0 on a degenerate band, else 1 or 2 — matches `lower`'s emptiness
+                        // (2 iff lower non-empty). For a non-empty band <= 2px tall, `upper`
+                        // can be empty too while this still reports 1 — unreachable through
+                        // the band-stack allocator's kWaveformMinHeight floor.
 };
 
 // Resolves the surface for a waveform band. Two lanes need BOTH stereo mode and a source
@@ -62,7 +63,7 @@ int frameToX(const OverlayArea& area, std::int64_t frameCount, std::int64_t fram
 
 // Inverse of frameToX: the frame a point x maps to, clamped to [0, frameCount]. A point left of
 // area.x yields 0; right of area.right() yields frameCount.
-std::int64_t xToFrame(const Rect& area, std::int64_t frameCount, int x);
+std::int64_t xToFrame(const OverlayArea& area, std::int64_t frameCount, int x);
 
 // Which marker (index into the caller's parallel `frames` array, in draw order) a grab at
 // (x, y) lands on, or -1 for a miss. A marker is grabbed when x is within kMarkerGrabWidth of