Type-enforce the waveform overlay contract, narrow waveformLanes to LaneSplit, fix laneCount/cache/path-fallback bugs

src/core/instrument/CLAUDE.md

@@ -216,12 +216,12 @@ slider couldn't. Two pure modules split the forward (draw) and inverse (edit) ma
 
 ### `ui/`
 
-- `editor_geometry` (`core/instrument/ui`) — the shared geometry VOCABULARY every instrument UI module speaks: the `core::ui::Rect` alias + `contains()`, nothing else. Header-only (an INTERFACE CMake target), so it carries no layout of its own.
-- `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.
+- `editor_geometry` (`core/instrument/ui`) — the shared geometry VOCABULARY every instrument UI module speaks: the `core::ui::Rect` alias, `contains()`, and `OverlayArea` (a one-field `Rect` wrapper, no implicit conversion from `Rect`). Header-only (an INTERFACE CMake target), so it carries no layout of its own.
+- `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 (`waveformLanes` takes a resolved `LaneSplit`, not a raw bool — only `waveformSurface` folds the source-channel-count decision in). 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` — 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.
+- `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 area, 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 area so a grab in the lower lane reaches them. Anything drawn or hit-tested per lane is a duplicate and a defect — structurally enforced: `overlay` is the distinct `OverlayArea` type (`editor_geometry`), not `Rect`, so every overlay-consuming API (`frameToX`/`markerAtPoint`/`resolveDragFrame`, `envelope_edit`'s `nodeAtPoint`/`resolveNodeDrag`, `envelope_overlay`'s `buildEnvelopePolyline`) rejects a lane rect at compile time rather than silently accepting one.
 - `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/editor_geometry.h

@@ -1,9 +1,10 @@
 #pragma once
 // editor_geometry.h — the shared geometry vocabulary for the VST3 editor's pure modules:
-// the one concrete `Rect` (aliased from core/ui) and its half-open `contains()`. Every
-// instrument UI module speaks these types, so they live in one place rather than each
-// module reaching into core/ui separately. The Sample face's own layout lives in
-// sample_bands (the band-stack allocator) and the per-band modules.
+// the one concrete `Rect` (aliased from core/ui), its half-open `contains()`, and
+// `OverlayArea` (the waveform band's shared overlay rect — see the contract in
+// waveform_view.h). Every instrument UI module speaks these types, so they live in one
+// place rather than each module reaching into core/ui separately. The Sample face's own
+// layout lives in sample_bands (the band-stack allocator) and the per-band modules.
 
 #include "core/ui/rect.h"
 
@@ -12,4 +13,13 @@ namespace reasampler::instrument::ui {
 using Rect = ::reasampler::ui::Rect;
 using ::reasampler::ui::contains;
 
+// Distinct from Rect on purpose (no implicit Rect->OverlayArea conversion): only
+// waveformOverlayArea/WaveformSurface::overlay construct one, so an overlay-only API can
+// require this type and reject a lane rect at compile time instead of silently accepting it.
+struct OverlayArea {
+    Rect rect;
+    bool operator==(const OverlayArea& o) const { return rect == o.rect; }
+    bool operator!=(const OverlayArea& o) const { return !(*this == o); }
+};
+
 }  // namespace reasampler::instrument::ui

src/core/instrument/ui/envelope_edit.cpp

@@ -63,7 +63,8 @@ bool nodeInMode(EnvNode n, EnvMode m) {
 
 }  // namespace
 
-NodeHit nodeAtPoint(const AmpEnvelope& env, const Rect& area, double totalSeconds, int x, int y) {
+NodeHit nodeAtPoint(const AmpEnvelope& env, const OverlayArea& area, double totalSeconds, int x,
+                    int y) {
     const std::vector<EnvVertex> poly = buildEnvelopePolyline(env, area, totalSeconds);
     // Nearest draggable, mode-matching node within the pick radius wins (Chebyshev distance);
     // ties go to the earlier draw-order node. Only matters for Trigger's zero-fade-out
@@ -81,16 +82,17 @@ NodeHit nodeAtPoint(const AmpEnvelope& env, const Rect& area, double totalSecond
     return best;
 }
 
-AmpEnvelope resolveNodeDrag(const AmpEnvelope& grabEnv, EnvNode node, const Rect& area,
+AmpEnvelope resolveNodeDrag(const AmpEnvelope& grabEnv, EnvNode node, const OverlayArea& area,
                             double totalSeconds, const EnvClampBounds& bounds,
                             int dxPixels, int dyPixels) {
     AmpEnvelope out = grabEnv;
     if (!isDraggable(node) || !nodeInMode(node, grabEnv.mode)) return out;
 
-    const double secPerPx = secondsPerPixel(area, totalSeconds);
+    const Rect& rect = area.rect;
+    const double secPerPx = secondsPerPixel(rect, totalSeconds);
     if (secPerPx <= 0.0) return out;  // degenerate area / duration — no motion
     const double dSec = static_cast<double>(dxPixels) * secPerPx;
-    const double gateDSec = static_cast<double>(dxPixels) * gateSecondsPerPixel(area);
+    const double gateDSec = static_cast<double>(dxPixels) * gateSecondsPerPixel(rect);
 
     switch (node) {
         // Gate: each cumulative-time node edits its own segment duration. Non-negative durations
@@ -106,7 +108,7 @@ AmpEnvelope resolveNodeDrag(const AmpEnvelope& grabEnv, EnvNode node, const Rect
         case EnvNode::DecayEnd: {
             // X sets decay time, Y sets sustain level (drag down = higher y = lower level).
             out.decaySeconds = std::clamp(grabEnv.decaySeconds + gateDSec, 0.0, bounds.maxDecaySeconds);
-            const double lvlPerPx = levelPerPixel(area);
+            const double lvlPerPx = levelPerPixel(rect);
             const double dLevel = -static_cast<double>(dyPixels) * lvlPerPx;
             out.sustainLevel = std::clamp(grabEnv.sustainLevel + dLevel, 0.0, 1.0);
             break;

src/core/instrument/ui/envelope_edit.h

@@ -54,7 +54,9 @@ struct NodeHit {
     bool    hit  = false;
     EnvNode node = EnvNode::Origin;  // meaningful only when hit == true
 };
-NodeHit nodeAtPoint(const AmpEnvelope& env, const Rect& area, double totalSeconds, int x, int y);
+// Takes the waveform overlay (not a lane) — see waveform_view.h's overlay contract.
+NodeHit nodeAtPoint(const AmpEnvelope& env, const OverlayArea& area, double totalSeconds, int x,
+                    int y);
 
 // Resolves a drag of `node` to a new AmpEnvelope. `grabEnv` is the envelope as of grab time (the
 // shell snapshots it on button-down so the delta is absolute, not accumulated); `dxPixels`/
@@ -65,7 +67,7 @@ NodeHit nodeAtPoint(const AmpEnvelope& env, const Rect& area, double totalSecond
 //   * A non-draggable node, an other-mode node, a zero-size area, or totalSeconds <= 0 returns
 //     `grabEnv` unchanged.
 // Only the dragged node's param(s) change. Pure.
-AmpEnvelope resolveNodeDrag(const AmpEnvelope& grabEnv, EnvNode node, const Rect& area,
+AmpEnvelope resolveNodeDrag(const AmpEnvelope& grabEnv, EnvNode node, const OverlayArea& area,
                             double totalSeconds, const EnvClampBounds& bounds,
                             int dxPixels, int dyPixels);
 

src/core/instrument/ui/envelope_overlay.cpp

@@ -149,15 +149,16 @@ std::vector<EnvVertex> triggerPolyline(const AmpEnvelope& env, const Rect& area,
 
 }  // namespace
 
-std::vector<EnvVertex> buildEnvelopePolyline(const AmpEnvelope& env, const Rect& area,
+std::vector<EnvVertex> buildEnvelopePolyline(const AmpEnvelope& env, const OverlayArea& area,
                                              double totalSeconds) {
-    if (area.width <= 0 || area.height <= 0 || totalSeconds <= 0.0) {
+    const Rect& rect = area.rect;
+    if (rect.width <= 0 || rect.height <= 0 || totalSeconds <= 0.0) {
         // Degenerate surface: flat two-point baseline so the shell always has a line.
-        return {vtx(EnvNode::Origin, area, 1.0, 0.0, 0.0),
-                vtx(EnvNode::ReleaseEnd, area, 1.0, 1.0, 0.0)};
+        return {vtx(EnvNode::Origin, rect, 1.0, 0.0, 0.0),
+                vtx(EnvNode::ReleaseEnd, rect, 1.0, 1.0, 0.0)};
     }
-    return env.mode == EnvMode::Gate ? gatePolyline(env, area)
-                                     : triggerPolyline(env, area, totalSeconds);
+    return env.mode == EnvMode::Gate ? gatePolyline(env, rect)
+                                     : triggerPolyline(env, rect, totalSeconds);
 }
 
 }  // namespace reasampler::instrument::ui

src/core/instrument/ui/envelope_overlay.h

@@ -93,8 +93,9 @@ double gatePxPerSecond(const Rect& area);
 // Gate's x-axis is a bounded schematic independent of totalSeconds (does NOT line up with the
 // waveform under it); Trigger's x-axis is PCM-aligned wall-clock. Every vertex is clamped inside
 // the canvas: x in [area.x, area.right()-1], y in [area.y, area.bottom()-1]. A degenerate area
-// or totalSeconds <= 0 yields the flat two-point baseline [Origin, end at level 0].
-std::vector<EnvVertex> buildEnvelopePolyline(const AmpEnvelope& env, const Rect& area,
+// or totalSeconds <= 0 yields the flat two-point baseline [Origin, end at level 0]. Takes the
+// waveform overlay (not a lane) — see waveform_view.h's overlay contract.
+std::vector<EnvVertex> buildEnvelopePolyline(const AmpEnvelope& env, const OverlayArea& area,
                                              double totalSeconds);
 
 // Maps a time (seconds) to a pixel x inside `area`, linear and clamped at both ends. Shared

src/core/instrument/ui/sample_bands.cpp

@@ -32,10 +32,10 @@ SampleBands computeSampleBands(int w, int h, int deckHeight) {
     return b;
 }
 
-WaveformLanes waveformLanes(const Rect& waveform, bool stereo) {
+WaveformLanes waveformLanes(const Rect& waveform, LaneSplit split) {
     WaveformLanes lanes;
     if (waveform.empty()) return lanes;
-    if (!stereo) {
+    if (split == LaneSplit::Single) {
         lanes.upper = waveform;  // one lane; `lower` stays empty
         return lanes;
     }

src/core/instrument/ui/sample_bands.h

@@ -48,6 +48,12 @@ struct WaveformLanes {
     Rect upper;
     Rect lower;  // empty() in mono
 };
-WaveformLanes waveformLanes(const Rect& waveform, bool stereo);
+
+// A RESOLVED lane-split decision, not "is the instrument in stereo mode" — a mono source
+// stays Single even in stereo mode (dual-mono, no second channel to draw). Only
+// waveformSurface (waveform_view) folds the source channel count in; a bare bool here would
+// let a caller pass isStereoMode straight through and skip that check.
+enum class LaneSplit { Single, Stereo };
+WaveformLanes waveformLanes(const Rect& waveform, LaneSplit split);
 
 }  // namespace reasampler::instrument::ui

src/core/instrument/ui/waveform_view.cpp

@@ -6,6 +6,8 @@
 #include <cstddef>
 #include <cstdlib>  // std::abs (int overload)
 
+#include "core/instrument/ui/sample_bands.h"  // waveformLanes (the band's lane inventory)
+
 namespace reasampler::instrument::ui {
 
 namespace {
@@ -18,17 +20,22 @@ std::int64_t clampFrame(std::int64_t f, std::int64_t frameCount) {
 
 }  // namespace
 
-Rect waveformOverlayArea(const Rect& band) { return band.empty() ? Rect{} : band; }
+OverlayArea waveformOverlayArea(const Rect& band) {
+    return OverlayArea{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);
+    const WaveformLanes lanes =
+        waveformLanes(band, twoLanes ? LaneSplit::Stereo : LaneSplit::Single);
     s.upper = lanes.upper;
     s.lower = lanes.lower;
-    s.laneCount = twoLanes ? 2 : 1;
+    // 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).
+    s.laneCount = lanes.lower.empty() ? 1 : 2;
     return s;
 }
 
@@ -37,13 +44,13 @@ audio::Envelope laneEnvelope(const audio::Envelope& env, int lane) {
     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;
+int frameToX(const OverlayArea& area, std::int64_t frameCount, std::int64_t frame) {
+    const int w = std::max(0, area.rect.width);
+    if (frameCount <= 0 || w <= 0) return area.rect.x;
     const std::int64_t f = clampFrame(frame, frameCount);
     // x = left + round(f * w / frameCount); multiply before divide to keep this exact.
     const std::int64_t num = f * static_cast<std::int64_t>(w) + frameCount / 2;
-    return area.x + static_cast<int>(num / frameCount);
+    return area.rect.x + static_cast<int>(num / frameCount);
 }
 
 std::int64_t xToFrame(const Rect& area, std::int64_t frameCount, int x) {
@@ -57,10 +64,10 @@ std::int64_t xToFrame(const Rect& area, std::int64_t frameCount, int x) {
     return clampFrame(num / static_cast<std::int64_t>(w), frameCount);
 }
 
-int markerAtPoint(const Rect& area, std::int64_t frameCount, const std::int64_t* frames,
+int markerAtPoint(const OverlayArea& area, std::int64_t frameCount, const std::int64_t* frames,
                   int count, int x, int y) {
     if (count <= 0 || frames == nullptr) return -1;
-    if (!contains(area, x, y)) return -1;
+    if (!contains(area.rect, x, y)) return -1;
     for (int i = 0; i < count; ++i) {
         const int mx = frameToX(area, frameCount, frames[i]);
         if (x >= mx - kMarkerGrabWidth && x <= mx + kMarkerGrabWidth) return i;
@@ -68,11 +75,11 @@ int markerAtPoint(const Rect& area, std::int64_t frameCount, const std::int64_t*
     return -1;
 }
 
-std::int64_t resolveDragFrame(const Rect& area, std::int64_t frameCount, std::int64_t startFrame,
-                              int dxPixels) {
+std::int64_t resolveDragFrame(const OverlayArea& area, std::int64_t frameCount,
+                              std::int64_t startFrame, int dxPixels) {
     const std::int64_t start = clampFrame(startFrame, frameCount);
     if (dxPixels == 0) return start;
-    const int w = std::max(0, area.width);
+    const int w = std::max(0, area.rect.width);
     if (frameCount <= 0 || w <= 0) return start;  // no room to move
     // Proportional shift, rounded to the nearest frame (same linear map as frameToX/xToFrame).
     const std::int64_t magnitude =

src/core/instrument/ui/waveform_view.h

@@ -10,8 +10,7 @@
 
 #include <cstdint>
 
-#include "core/instrument/ui/editor_geometry.h"  // Rect, contains
-#include "core/instrument/ui/sample_bands.h"     // waveformLanes (the band's lane inventory)
+#include "core/instrument/ui/editor_geometry.h"  // Rect, OverlayArea, contains
 #include "core/audio/peaks.h"            // AudioSample (float), Envelope
 
 namespace reasampler::instrument::ui {
@@ -27,10 +26,12 @@ using audio::AudioSample;
 // 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
+    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)
 };
 
 // Resolves the surface for a waveform band. Two lanes need BOTH stereo mode and a source
@@ -38,10 +39,10 @@ struct WaveformSurface {
 // 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
+// THE overlay area, 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);
+OverlayArea 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
@@ -56,8 +57,8 @@ inline constexpr int kMarkerGrabWidth = 5;
 
 // x pixel of `frame` under the linear map: frame 0 -> area.x, frame frameCount -> area.right().
 // Frame is clamped to [0, frameCount] before mapping. frameCount <= 0 or a zero-width area pins
-// every frame to area.x.
-int frameToX(const Rect& area, std::int64_t frameCount, std::int64_t frame);
+// every frame to area.x. Takes the overlay (not a lane) — see the OVERLAY CONTRACT above.
+int frameToX(const OverlayArea& area, std::int64_t frameCount, std::int64_t frame);
 
 // 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.
@@ -66,14 +67,14 @@ std::int64_t xToFrame(const Rect& 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
 // its drawn x and y is inside `area`. First marker in draw order wins an overlapping tie.
-int markerAtPoint(const Rect& area, std::int64_t frameCount, const std::int64_t* frames,
+int markerAtPoint(const OverlayArea& area, std::int64_t frameCount, const std::int64_t* frames,
                   int count, int x, int y);
 
 // Resolves a drag to a new frame: `startFrame` shifted by round(dxPixels * frameCount /
 // areaWidth), clamped to [0, frameCount]. The shell applies between-marker clamps (e.g.
 // start <= loopEnd) after this per-marker resolve.
-std::int64_t resolveDragFrame(const Rect& area, std::int64_t frameCount, std::int64_t startFrame,
-                              int dxPixels);
+std::int64_t resolveDragFrame(const OverlayArea& area, std::int64_t frameCount,
+                              std::int64_t startFrame, int dxPixels);
 
 // Nearest zero-crossing frame to `target` in the mono PCM, for loop/start snap. A crossing is a
 // frame i (1 <= i < frames) where pcm[i-1] and pcm[i] differ in sign (pcm[i] == 0 snaps to i).

src/shell/instrument/editor_input_waveform.cpp

@@ -2,8 +2,7 @@
 // start/loop marker, and resolving both drags live against the pure inverse maps
 // (envelope_edit, waveform_view). Windows-only.
 //
-// Hit-test and drag both resolve against WaveformSurface::overlay — the same full-band rect
-// the overlays draw into — so a grab in the lower stereo lane reaches them.
+// Overlay contract: see waveform_view.h's WaveformSurface.
 
 #include "shell/instrument/reasampler_editor.h"
 
@@ -27,7 +26,7 @@ bool ReaSamplerEditor::mouseDownWaveform(const FaceLayout& fl, int x, int y) {
     const std::vector<AudioSample>& pcm = monoPcmFor(selectedId_);
     const std::int64_t frames = static_cast<std::int64_t>(pcm.size());
     if (frames <= 0) return false;
-    const Rect overlay = waveformOverlayArea(fl.bands.waveform);
+    const OverlayArea overlay = waveformOverlayArea(fl.bands.waveform);
 
     // Envelope nodes first (they sit on top of the markers), then the wave markers.
     const double rate = liveSampleRate();
@@ -64,7 +63,7 @@ bool ReaSamplerEditor::mouseDownWaveform(const FaceLayout& fl, int x, int y) {
 }
 
 void ReaSamplerEditor::dragWaveform(const FaceLayout& fl, int x, int y) {
-    const Rect overlay = waveformOverlayArea(fl.bands.waveform);
+    const OverlayArea overlay = waveformOverlayArea(fl.bands.waveform);
     const int dx = x - dragStartX_;
 
     if (drag_ == DragKind::kEnvNode) {

src/shell/instrument/editor_paint_waveform.cpp

@@ -1,9 +1,7 @@
 // editor_paint_waveform.cpp — the WAVEFORM band's painter: the channel lane(s), the loop
 // span + start/loop markers, and the amp-envelope overlay. Windows-only.
 //
-// Overlays that ride the waveform (the envelope trace, its node handles, the markers) draw
-// ONCE into WaveformSurface::overlay — the full band, spanning both stacked lanes in
-// stereo. Never per lane; see waveform_view.h's overlay contract.
+// Overlay contract: see waveform_view.h's WaveformSurface.
 
 #include "shell/instrument/reasampler_editor.h"
 
@@ -76,13 +74,14 @@ void ReaSamplerEditor::paintWaveform(LICE_IBitmap* bmp, const Rect& band) {
 
     // Markers and the loop span are overlays: ONE draw across the full stacked height, so a
     // stereo view reads one loop region rather than two.
-    const Rect& overlay = surface.overlay;
+    const OverlayArea& overlay = surface.overlay;
+    const Rect& overlayRect = overlay.rect;
     const SetupMarkers m = pickedMarkers(frames);
     if (m.hasLoop && m.loopEnd > m.loopStart) {
         const int lx = frameToX(overlay, frames, m.loopStart);
         const int rx = frameToX(overlay, frames, m.loopEnd);
         if (rx > lx) {
-            LICE_FillRect(bmp, lx, overlay.y, rx - lx, overlay.height,
+            LICE_FillRect(bmp, lx, overlayRect.y, rx - lx, overlayRect.height,
                           toLice(roleColor(kRoleLoopMarker)), 0.20f, 0);
         }
     }
@@ -92,16 +91,17 @@ void ReaSamplerEditor::paintWaveform(LICE_IBitmap* bmp, const Rect& band) {
         const int mx = frameToX(overlay, frames, markerFrames[i]);
         const bool loopMarker = (i != 0);
         const float alpha = (loopMarker && !m.hasLoop) ? 0.4f : 1.0f;
-        LICE_FillRect(bmp, mx - 1, overlay.y, 2, overlay.height,
+        LICE_FillRect(bmp, mx - 1, overlayRect.y, 2, overlayRect.height,
                       toLice(roleColor(markerRoles[i])), alpha, 0);
     }
 
     paintEnvelopeOverlay(bmp, overlay, frames);
 }
 
-void ReaSamplerEditor::paintEnvelopeOverlay(LICE_IBitmap* bmp, const Rect& waveArea,
+void ReaSamplerEditor::paintEnvelopeOverlay(LICE_IBitmap* bmp, const OverlayArea& waveArea,
                                             std::int64_t frames) {
-    if (frames <= 0 || waveArea.width <= 0 || waveArea.height <= 0) return;
+    const Rect& area = waveArea.rect;
+    if (frames <= 0 || area.width <= 0 || area.height <= 0) return;
     const double rate = liveSampleRate();
     if (rate <= 0.0) return;
     const double totalSeconds = static_cast<double>(frames) / rate;
@@ -113,8 +113,8 @@ void ReaSamplerEditor::paintEnvelopeOverlay(LICE_IBitmap* bmp, const Rect& waveA
     // curve over the waveform. Clip x to the wave rect (a Gate release tail maps past the right).
     const LICE_pixel line = toLice(roleColor(Role::AccentSecondary));
     for (std::size_t i = 1; i < poly.size(); ++i) {
-        const int x0 = (std::max)(waveArea.x, (std::min)(waveArea.right() - 1, poly[i - 1].x));
-        const int x1 = (std::max)(waveArea.x, (std::min)(waveArea.right() - 1, poly[i].x));
+        const int x0 = (std::max)(area.x, (std::min)(area.right() - 1, poly[i - 1].x));
+        const int x1 = (std::max)(area.x, (std::min)(area.right() - 1, poly[i].x));
         LICE_Line(bmp, x0, poly[i - 1].y, x1, poly[i].y, line, 1.0f, 0, true);
     }
     // Draggable node handles: a small square per draggable node (Origin + ReleaseStart are
@@ -128,8 +128,8 @@ void ReaSamplerEditor::paintEnvelopeOverlay(LICE_IBitmap* bmp, const Rect& waveA
         if (v.node == EnvNode::Origin || v.node == EnvNode::ReleaseStart) continue;
         const bool grabbed = (drag_ == DragKind::kEnvNode && envNode_ == v.node);
         const int r = 3;
-        const int hx = (std::max)(waveArea.x + r, (std::min)(waveArea.right() - 1 - r, v.x));
-        const int hy = (std::max)(waveArea.y + r, (std::min)(waveArea.bottom() - 1 - r, v.y));
+        const int hx = (std::max)(area.x + r, (std::min)(area.right() - 1 - r, v.x));
+        const int hy = (std::max)(area.y + r, (std::min)(area.bottom() - 1 - r, v.y));
         LICE_FillRect(bmp, hx - r, hy - r, 2 * r, 2 * r, grabbed ? handleHot : handle, 1.0f, 0);
     }
 }

src/shell/instrument/editor_session.cpp

@@ -210,7 +210,11 @@ std::string ReaSamplerEditor::samplePathFor(const std::string& sampleId) const {
     if (!processor_) return {};
     auto banksJson = processor_->bridge().readReasamplerExtState(reasampler::kProjExtBanksKey);
     if (banksJson) {
-        if (auto sel = selectSample(*banksJson, sampleId)) return sel->relativePath;
+        // An empty relativePath (found the entry, but it carries no path) falls through to
+        // the refs fallback below rather than short-circuiting on it.
+        if (auto sel = selectSample(*banksJson, sampleId); sel && !sel->relativePath.empty()) {
+            return sel->relativePath;
+        }
     }
     // Fallback: the bank blob is not readable (extension absent / not yet parsed) or the id
     // went stale there — the instance-owned ref still carries the path, so a self-contained
@@ -222,7 +226,7 @@ std::string ReaSamplerEditor::samplePathFor(const std::string& sampleId) const {
 
 const ReaSamplerEditor::ChannelPcm& ReaSamplerEditor::channelPcmFor(
     const std::string& sampleId) {
-    if (channelPcmId_ == sampleId && !sampleId.empty()) return channelPcm_;
+    if (channelPcmId_ == sampleId) return channelPcm_;
 
     // A failed decode is still cached (channelCount stays 0) so a broken/missing file is not
     // re-read on every paint.

src/shell/instrument/reasampler_editor.h

@@ -45,6 +45,7 @@ using instrument::ui::ChromeRects;
 using instrument::ui::DeckGroupDesc;
 using instrument::ui::EnvClampBounds;
 using instrument::ui::EnvNode;
+using instrument::ui::OverlayArea;
 using instrument::ui::Rect;
 using instrument::ui::SampleBands;
 
@@ -173,7 +174,7 @@ private:
     void paintVelocityCurve(LICE_IBitmap* bmp, const Rect& r);
     // Traces the amp-envelope overlay + its draggable node handles over `waveArea`, ONCE at
     // full band height (never per lane).
-    void paintEnvelopeOverlay(LICE_IBitmap* bmp, const Rect& waveArea, std::int64_t frames);
+    void paintEnvelopeOverlay(LICE_IBitmap* bmp, const OverlayArea& waveArea, std::int64_t frames);
 
     // --- Input: the mouse-down dispatch and its per-band branches ---
     void onMouseDown(int x, int y);