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

2026-07-30 09:04:57 -04:00
parent 81f5861ba4
commit 2a0d10fab5
9 changed files with 341 additions and 77 deletions
@@ -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.
@@ -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;
@@ -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;
@@ -1,6 +1,9 @@
 // editor_input_waveform.cpp — the WAVEFORM band's input: grabbing an envelope node or a
 // 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.

 #include "shell/instrument/reasampler_editor.h"

@@ -11,7 +14,7 @@
 #include <vector>

 #include "core/instrument/ui/envelope_edit.h"   // nodeAtPoint / resolveNodeDrag
-#include "core/instrument/ui/waveform_view.h"   // markerAtPoint / resolveDragFrame / snap
+#include "core/instrument/ui/waveform_view.h"   // waveformOverlayArea / markerAtPoint / snap
 #include "shell/instrument/editor_internal.h"
 #include "shell/instrument/reasampler_processor.h"

@@ -21,10 +24,10 @@ using namespace reasampler::ui;
 using namespace reasampler::instrument::ui;

 bool ReaSamplerEditor::mouseDownWaveform(const FaceLayout& fl, int x, int y) {
-    const Rect& band = fl.bands.waveform;
    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);

    // Envelope nodes first (they sit on top of the markers), then the wave markers.
    const double rate = liveSampleRate();
@@ -32,7 +35,7 @@ bool ReaSamplerEditor::mouseDownWaveform(const FaceLayout& fl, int x, int y) {
        const std::int64_t startFrame = params_.startPoint.value_or(0);
        const AmpEnvelope env = packEnvelope(params_.play, frames, startFrame);
        const double totalSeconds = static_cast<double>(frames) / rate;
-        const NodeHit nh = nodeAtPoint(env, band, totalSeconds, x, y);
+        const NodeHit nh = nodeAtPoint(env, overlay, totalSeconds, x, y);
        if (nh.hit) {
            drag_ = DragKind::kEnvNode;
            envNode_ = nh.node;
@@ -47,7 +50,7 @@ bool ReaSamplerEditor::mouseDownWaveform(const FaceLayout& fl, int x, int y) {
    }
    const SetupMarkers m = pickedMarkers(frames);
    const std::int64_t markerFrames[3] = {m.start, m.loopStart, m.loopEnd};
-    const int hit = markerAtPoint(band, frames, markerFrames, 3, x, y);
+    const int hit = markerAtPoint(overlay, frames, markerFrames, 3, x, y);
    if (hit >= 0) {
        drag_ = DragKind::kWaveMarker;
        waveMarker_ = static_cast<WaveMarker>(hit);
@@ -61,7 +64,7 @@ bool ReaSamplerEditor::mouseDownWaveform(const FaceLayout& fl, int x, int y) {
 }

 void ReaSamplerEditor::dragWaveform(const FaceLayout& fl, int x, int y) {
-    const Rect& band = fl.bands.waveform;
+    const Rect overlay = waveformOverlayArea(fl.bands.waveform);
    const int dx = x - dragStartX_;

    if (drag_ == DragKind::kEnvNode) {
@@ -73,7 +76,7 @@ void ReaSamplerEditor::dragWaveform(const FaceLayout& fl, int x, int y) {
        const double rate = liveSampleRate();
        if (frames <= 0 || rate <= 0.0) return;
        const double totalSeconds = static_cast<double>(frames) / rate;
-        const AmpEnvelope edited = resolveNodeDrag(dragStartEnv_, envNode_, band, totalSeconds,
+        const AmpEnvelope edited = resolveNodeDrag(dragStartEnv_, envNode_, overlay, totalSeconds,
                                                   envClampBounds(), dx, y - dragStartY_);
        unpackEnvelope(edited, frames, dragStartFrame_, params_.play);
        invalidate();  // live feedback; commit on WM_LBUTTONUP
@@ -90,7 +93,7 @@ void ReaSamplerEditor::dragWaveform(const FaceLayout& fl, int x, int y) {
    const int idx = static_cast<int>(waveMarker_);
    const std::int64_t startVals[3] = {dragStartMarkers_.start, dragStartMarkers_.loopStart,
                                       dragStartMarkers_.loopEnd};
-    std::int64_t newFrame = resolveDragFrame(band, frames, startVals[idx], dx);
+    std::int64_t newFrame = resolveDragFrame(overlay, frames, startVals[idx], dx);

    // Snap to the nearest zero crossing in the decoded PCM. Pure over the cached mono
    // frames — no host types, no file I/O.
@@ -2,20 +2,20 @@
 // 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 across the full band height, never per lane — the landed contract the stacked-lane
-// work consumes.
+// ONCE into WaveformSurface::overlay — the full band, spanning both stacked lanes in
+// stereo. Never per lane; see waveform_view.h's overlay contract.

 #include "shell/instrument/reasampler_editor.h"

 #ifdef _WIN32

 #include <algorithm>
+#include <cstddef>
 #include <cstdint>
 #include <vector>

 #include "core/audio/peaks.h"                   // computeEnvelope (waveform binning)
-#include "core/instrument/ui/sample_bands.h"    // waveformLanes (the band's lane inventory)
-#include "core/instrument/ui/waveform_view.h"   // frameToX (waveform markers)
+#include "core/instrument/ui/waveform_view.h"   // waveformSurface / laneEnvelope / frameToX
 #include "shell/instrument/editor_internal.h"   // kit adapters
 #include "shell/instrument/reasampler_processor.h"

@@ -36,52 +36,67 @@ void ReaSamplerEditor::paintWaveform(LICE_IBitmap* bmp, const Rect& band) {
    fillSurface(bmp, toKitBox(band), Role::BgBase, InteractionState::Rest);
    if (band.empty()) return;

-    const std::vector<AudioSample>& pcm = monoPcmFor(selectedId_);
-    const std::int64_t frames = static_cast<std::int64_t>(pcm.size());
+    const std::vector<AudioSample>& mono = monoPcmFor(selectedId_);
+    const std::int64_t frames = static_cast<std::int64_t>(mono.size());
    if (frames <= 0) {
        kitTextCentered(bmp, band, "(decoding...)", Font::Label, Role::TextDim);
        return;
    }

-    // One lane today: the cached PCM is a mono downmix, so there is no second channel to
-    // draw. The band is already sized for two, and the second lane lights up when the
-    // per-channel decode lands.
-    const WaveformLanes lanes = waveformLanes(band, /*stereo=*/false);
-    const Rect& lane = lanes.upper;
-    if (lane.width > 0) {
+    const ChannelPcm& src = channelPcmFor(selectedId_);
+    const WaveformSurface surface = waveformSurface(
+        band, channelMode_ == ChannelMode::Stereo, src.channelCount);
+
+    if (!surface.upper.empty()) {
        // Gap-free: one bin per drawn pixel column (kWaveformOversample == 1, so this
        // multiplies by 1). The gap-free draw comes from peaks::columnMinMax's exact
        // partition — extra bins produce no visible change. Clamped to frame count below.
+        // Both lanes share a width, so one bin count serves both.
        const std::int64_t wantBins =
-            static_cast<std::int64_t>((std::max)(1, waveformColumnCount(toKitBox(lane)))) *
+            static_cast<std::int64_t>(
+                (std::max)(1, waveformColumnCount(toKitBox(surface.upper)))) *
            kWaveformOversample;
        const std::size_t bins =
            static_cast<std::size_t>(wantBins < frames ? wantBins : frames);
-        drawEnvelope(bmp, lane, computeEnvelope(pcm, 1, pcm.size(), bins));
+
+        if (surface.laneCount == 2) {
+            // ONE pass over the interleaved source: computeEnvelope already envelopes each
+            // channel independently, so the second lane costs no second scan of the PCM.
+            const Envelope env =
+                computeEnvelope(src.interleaved, static_cast<std::size_t>(src.channelCount),
+                                static_cast<std::size_t>(src.frameCount()), bins);
+            drawEnvelope(bmp, surface.upper, laneEnvelope(env, 0));
+            drawEnvelope(bmp, surface.lower, laneEnvelope(env, 1));
+        } else {
+            // One lane draws what one lane plays: the downmix, not channel 0 of a stereo
+            // source.
+            drawEnvelope(bmp, surface.upper, computeEnvelope(mono, 1, mono.size(), bins));
+        }
    }

-    // Markers and the loop span run the FULL band height (both lanes), so a stacked view
-    // reads one loop region rather than two.
+    // 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 SetupMarkers m = pickedMarkers(frames);
    if (m.hasLoop && m.loopEnd > m.loopStart) {
-        const int lx = frameToX(band, frames, m.loopStart);
-        const int rx = frameToX(band, frames, m.loopEnd);
+        const int lx = frameToX(overlay, frames, m.loopStart);
+        const int rx = frameToX(overlay, frames, m.loopEnd);
        if (rx > lx) {
-            LICE_FillRect(bmp, lx, band.y, rx - lx, band.height,
+            LICE_FillRect(bmp, lx, overlay.y, rx - lx, overlay.height,
                          toLice(roleColor(kRoleLoopMarker)), 0.20f, 0);
        }
    }
    const std::int64_t markerFrames[3] = {m.start, m.loopStart, m.loopEnd};
    const Role markerRoles[3] = {kRoleStartMarker, kRoleLoopMarker, kRoleLoopMarker};
    for (int i = 0; i < 3; ++i) {
-        const int mx = frameToX(band, frames, markerFrames[i]);
+        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, band.y, 2, band.height,
+        LICE_FillRect(bmp, mx - 1, overlay.y, 2, overlay.height,
                      toLice(roleColor(markerRoles[i])), alpha, 0);
    }

-    paintEnvelopeOverlay(bmp, band, frames);
+    paintEnvelopeOverlay(bmp, overlay, frames);
 }

 void ReaSamplerEditor::paintEnvelopeOverlay(LICE_IBitmap* bmp, const Rect& waveArea,
@@ -48,6 +48,8 @@ void ReaSamplerEditor::refreshFromBank() {
    // Main/UI thread only — reads the live bank over the bridge (allocates, calls REAPER).
    thumbCache_.clear();  // a bank edit may have re-captured/removed a sample; drop stale peaks
    pcmCache_.clear();    // and its decoded PCM (the waveform + snap source)
+    channelPcmId_.clear();
+    channelPcm_ = ChannelPcm{};
    if (!processor_) {
        samples_.clear();
        banks_.clear();
@@ -202,42 +204,62 @@ int ReaSamplerEditor::effectiveRoot() const {
    return 60;
 }

+std::string ReaSamplerEditor::samplePathFor(const std::string& sampleId) const {
+    // SampleChoice is the browser's metadata projection and does not carry the WAV path, so
+    // resolve it from the live bank blob (selectSample).
+    if (!processor_) return {};
+    auto banksJson = processor_->bridge().readReasamplerExtState(reasampler::kProjExtBanksKey);
+    if (banksJson) {
+        if (auto sel = selectSample(*banksJson, sampleId)) 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
+    // instance draws its loaded sound's waveform regardless.
+    const SampleRefs refs = processor_->sampleRefs();
+    if (const SelectedSample* r = findRef(refs, sampleId)) return r->relativePath;
+    return {};
+}
+
+const ReaSamplerEditor::ChannelPcm& ReaSamplerEditor::channelPcmFor(
+    const std::string& sampleId) {
+    if (channelPcmId_ == sampleId && !sampleId.empty()) return channelPcm_;
+
+    // A failed decode is still cached (channelCount stays 0) so a broken/missing file is not
+    // re-read on every paint.
+    channelPcmId_ = sampleId;
+    channelPcm_ = ChannelPcm{};
+    const std::string relativePath = samplePathFor(sampleId);
+    if (relativePath.empty()) return channelPcm_;
+
+    const std::string projectDir = processor_->bridge().activeProjectDir();
+    const std::vector<std::uint8_t> bytes =
+        readFileBytes(resolveBankFile(projectDir, relativePath));  // empty on any failure
+    const WavLayout layout = parseWavLayout(bytes);
+    if (layout.valid) {
+        channelPcm_.interleaved = extractFloatFrames(bytes, layout, 0, layout.frameCount());
+        channelPcm_.channelCount = static_cast<int>(layout.channelCount);
+    }
+    return channelPcm_;
+}
+
 const std::vector<AudioSample>& ReaSamplerEditor::monoPcmFor(const std::string& sampleId) {
    auto it = pcmCache_.find(sampleId);
    if (it != pcmCache_.end()) return it->second;

-    // SampleChoice is the browser's metadata projection and does not carry the WAV path, so
-    // resolve the path from the live bank blob (selectSample) and decode via the shared WAV
-    // parse. Every failure path caches an empty vector so a broken/missing file is not
-    // re-decoded on every paint. Keyed by id (width-independent) — the thumbnail bins this at
-    // whatever width, the snap scans it directly.
-    std::string relativePath;
+    // Every failure path caches an empty vector so a broken/missing file is not re-decoded on
+    // every paint. Keyed by id (width-independent) — the thumbnail bins this at whatever
+    // width, the snap scans it directly.
    std::vector<AudioSample> mono;
-    if (processor_) {
-        auto banksJson =
-            processor_->bridge().readReasamplerExtState(reasampler::kProjExtBanksKey);
-        if (banksJson) {
-            if (auto sel = selectSample(*banksJson, sampleId)) relativePath = sel->relativePath;
-        }
-        if (relativePath.empty()) {
-            // 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 instance draws its loaded sound's waveform regardless.
-            const SampleRefs refs = processor_->sampleRefs();
-            if (const SelectedSample* r = findRef(refs, sampleId)) {
-                relativePath = r->relativePath;
-            }
-        }
-        if (!relativePath.empty()) {
-            const std::string projectDir = processor_->bridge().activeProjectDir();
-            const std::string abs = resolveBankFile(projectDir, relativePath);
-            const std::vector<std::uint8_t> bytes = readFileBytes(abs);  // empty on any failure
-            const WavLayout layout = parseWavLayout(bytes);
-            if (layout.valid) {
-                std::vector<AudioSample> interleaved =
-                    extractFloatFrames(bytes, layout, 0, layout.frameCount());
-                mono = downmixToMono(interleaved, layout.channelCount);
-            }
+    const std::string relativePath = samplePathFor(sampleId);
+    if (!relativePath.empty()) {
+        const std::string projectDir = processor_->bridge().activeProjectDir();
+        const std::string abs = resolveBankFile(projectDir, relativePath);
+        const std::vector<std::uint8_t> bytes = readFileBytes(abs);  // empty on any failure
+        const WavLayout layout = parseWavLayout(bytes);
+        if (layout.valid) {
+            std::vector<AudioSample> interleaved =
+                extractFloatFrames(bytes, layout, 0, layout.frameCount());
+            mono = downmixToMono(interleaved, layout.channelCount);
        }
    }
    auto ins = pcmCache_.emplace(sampleId, std::move(mono));
@@ -262,6 +262,28 @@ private:
    // thread only (file I/O); cleared with the thumbnail cache on refresh.
    const std::vector<AudioSample>& monoPcmFor(const std::string& sampleId);

+    // The interleaved source PCM behind the stereo waveform lanes.
+    struct ChannelPcm {
+        std::vector<AudioSample> interleaved;  // frame-interleaved source frames
+        int channelCount = 0;                  // 0 = nothing decoded
+        std::int64_t frameCount() const {
+            return channelCount > 0
+                       ? static_cast<std::int64_t>(interleaved.size()) / channelCount
+                       : 0;
+        }
+    };
+
+    // The interleaved PCM + channel count for a bank sample id. SINGLE-SLOT by design: the
+    // waveform band draws one capture at a time, while monoPcmFor's cache spans every
+    // browsed card — holding interleaved PCM there would pin a whole bank at multi-channel
+    // size. A miss re-decodes (only on selection change or a bank refresh; an edit commit
+    // does not clear it). UI thread only (file I/O).
+    const ChannelPcm& channelPcmFor(const std::string& sampleId);
+
+    // The project-relative WAV path for a bank sample id: the live bank blob first, the
+    // instance's own SampleRefs as the self-contained fallback. "" when unresolvable.
+    std::string samplePathFor(const std::string& sampleId) const;
+
    // The effective loop + start markers for the loaded capture: the parameter set's
    // override when one is set, else the bank's loop intrinsic / frame 0. Absent loop ->
    // loopStart==loopEnd==0. `frames` defaults loopEnd when the bank left the loop empty.
@@ -434,6 +456,11 @@ private:
    // Decoded mono-PCM cache, keyed by id (width-independent). Feeds the waveform envelope
    // binning + zero-crossing snap. Cleared alongside thumbCache_ on refresh.
    std::unordered_map<std::string, std::vector<AudioSample>> pcmCache_;
+
+    // The single-slot interleaved-PCM cache behind channelPcmFor (see its note on why this
+    // is not keyed into pcmCache_). Cleared alongside pcmCache_ on refresh.
+    std::string channelPcmId_;
+    ChannelPcm channelPcm_;
 };

 }  // namespace reasampler::vst