S7: stereo channel mode — core channel dimension, v4 mode state, VST3 bus negotiation, editor toggle

Per-instance mono|stereo (default mono, byte-identical). Stereo grows SampleData a 2nd
channel + a per-channel VoiceEngine render; decodeChannels applies the cross-mode policy;
setBusArrangements pins the mode's arrangement and restartComponent(kIoChanged) re-negotiates.

src/vst/sample_map.cpp

@@ -101,10 +101,48 @@ std::vector<AudioSample> downmixToMono(const std::vector<AudioSample>& interleav
     return out;
 }
 
-Keymap buildTier0Keymap(std::vector<AudioSample> monoFrames, int sampleRate,
-                        int rootNote, const SampleLoop& loop) {
+std::vector<AudioSample> extractChannel(const std::vector<AudioSample>& interleaved,
+                                        int channelCount, int which) {
+    std::vector<AudioSample> out;
+    if (channelCount <= 0 || interleaved.empty()) return out;
+    const std::size_t stride = static_cast<std::size_t>(channelCount);
+    // Clamp the requested channel into the source's range: a channel past the last one reads
+    // the last channel (a mono source asked for channel 1 yields channel 0 — dual-mono).
+    std::size_t ch = which < 0 ? 0 : static_cast<std::size_t>(which);
+    if (ch >= stride) ch = stride - 1;
+    const std::size_t frames = interleaved.size() / stride;
+    out.resize(frames);
+    for (std::size_t f = 0; f < frames; ++f) out[f] = interleaved[f * stride + ch];
+    return out;
+}
+
+DecodedZonePcm decodeChannels(const std::vector<AudioSample>& interleaved,
+                              int sourceChannels, ChannelMode mode, int sampleRate) {
+    DecodedZonePcm out;
+    out.sampleRate = sampleRate > 0 ? sampleRate : 44100;
+    if (mode == ChannelMode::Mono) {
+        // MONO mode: the existing downmix policy (average all source channels), one channel out.
+        out.monoFrames = downmixToMono(interleaved, sourceChannels);
+        return out;  // framesR stays empty
+    }
+    // STEREO mode: channel 0 = source channel 0; channel 1 = source channel 1, or channel 0
+    // duplicated when the source is mono (dual-mono, centered). extractChannel clamps the
+    // out-of-range channel request to the last channel, so a mono source yields L == R.
+    out.monoFrames = extractChannel(interleaved, sourceChannels, 0);
+    out.framesR = extractChannel(interleaved, sourceChannels, 1);
+    return out;
+}
+
+Keymap buildTier0Keymap(std::vector<AudioSample> frames, int sampleRate,
+                        int rootNote, const SampleLoop& loop,
+                        std::vector<AudioSample> framesR) {
     SampleData data;
-    data.frames = std::move(monoFrames);
+    data.frames = std::move(frames);
+    // A second channel only counts when it length-matches channel 0 (else the sample stays
+    // mono — SampleData::channelCount() enforces the same rule, so a bad pair never half-plays).
+    if (!framesR.empty() && framesR.size() == data.frames.size()) {
+        data.framesR = std::move(framesR);
+    }
     data.sampleRate = sampleRate > 0 ? sampleRate : 44100;
     data.rootNote = rootNote;
     data.loop = loop;
@@ -158,6 +196,12 @@ Keymap buildZonedKeymap(const std::vector<ResolvedZone>& zones,
         if (decoded[i].monoFrames.empty()) continue;
         SampleData data;
         data.frames = decoded[i].monoFrames;
+        // Carry the second channel only when it length-matches channel 0 (channelCount()
+        // enforces the same rule; a mismatched pair falls back to mono rather than half-play).
+        if (!decoded[i].framesR.empty() &&
+            decoded[i].framesR.size() == data.frames.size()) {
+            data.framesR = decoded[i].framesR;
+        }
         data.sampleRate = decoded[i].sampleRate > 0 ? decoded[i].sampleRate : 44100;
         data.rootNote = zones[i].rootNote;
         data.loop = zones[i].loop;
@@ -292,6 +336,8 @@ PerformanceMap deserializePerformance(const std::vector<std::uint8_t>& bytes) {
 std::vector<std::uint8_t> serializeComponentState(const ComponentState& state) {
     std::vector<std::uint8_t> out;
     putU32le(out, kComponentStateVersion);
+    // v4 envelope addition: the channel mode (0 = mono, 1 = stereo) precedes the v3 body.
+    out.push_back(state.channelMode == ChannelMode::Stereo ? 1 : 0);
     // Length-prefixed selection id (it precedes the zones payload, so it MUST be framed —
     // unlike the v1 selection blob where the id ran to end-of-stream).
     putU32le(out, static_cast<std::uint32_t>(state.selectionId.size()));
@@ -324,10 +370,24 @@ ComponentState deserializeComponentState(const std::vector<std::uint8_t>& bytes)
     }
     if (version == kPerformanceStateVersion) {
         readZonesPayload(r, out.map);  // v2 body starts right after the version tag
-        return out;
+        return out;                    // channelMode stays Mono (pre-S7)
+    }
+    // BACK-COMPAT: a v3 blob (pre-S7 {selection, zones}, no channel mode) restores as MONO —
+    // the id length + id + zones body starts right after the version tag (no mode byte).
+    if (version == kSelectionZonesV3Version) {
+        const std::uint32_t idLen = r.u32();
+        out.selectionId = r.str(idLen);
+        if (!r.ok) { out.selectionId.clear(); return out; }  // truncated id -> empty
+        readZonesPayload(r, out.map);
+        return out;                    // channelMode stays Mono (pre-S7)
     }
     if (version != kComponentStateVersion) return out;  // unknown -> empty
 
+    // v4: the channel-mode byte precedes the v3 body. A non-{0,1} byte is treated as mono
+    // (conservative default) rather than rejected — a corrupt mode never silences the instance.
+    const std::uint8_t modeByte = r.u8();
+    if (!r.ok) return out;  // truncated before the mode byte -> empty (mono default holds)
+    out.channelMode = (modeByte == 1) ? ChannelMode::Stereo : ChannelMode::Mono;
     const std::uint32_t idLen = r.u32();
     out.selectionId = r.str(idLen);
     if (!r.ok) { out.selectionId.clear(); return out; }  // truncated id -> empty