#pragma once
// sampler_core — the HEART of the Phase S MIDI-playback instrument (D3), deliberately
// free of any VST3 *and* any REAPER type so it compiles and unit-tests OUTSIDE the DAW
// and outside any plugin host. It owns the pure sampler engine: polyphonic voice
// allocation with bounded stealing, an ADSR amplitude envelope, a key/velocity keymap
// with (note, velocity) -> zone resolution, and repitch/interpolation from a root note
// with loop-point-aware sustain.
//
// PURE MODULE (CLAUDE.md §load-bearing split): NO VST3 types, NO REAPER types, NO SWELL,
// NO vendor/ includes, no include from either SDK. Standard library only. The VST3 shell
// (src/vst/reasampler_processor.cpp) marshals MIDI events + audio buffers to and from
// this core; the core never sees a VST3 ProcessData or a REAPER MediaTrack. Enforced
// structurally: sampler_core_tests links neither SDK (see CMakeLists §2i).
//
// It shares the `AudioSample` float alias from peaks — the one house precedent for a
// pure module leaning on peaks for the audio-domain type (wav_trim does the same). The
// S2 seam fields (root note, loop points) enter as plain int / frame-index inputs; the
// core does no file I/O — it is handed decoded sample frames and produces audio frames.

#include <cstddef>
#include <cstdint>
#include <vector>

#include "peaks.h"        // AudioSample (float)
#include "pitch_shift.h"  // PitchShifter (S16 Preserve engine DSP core)

namespace reasampler {

// The instrument's per-instance output channel mode (S7, D-E). MONO keeps the pre-S7
// downmix path (one channel out); STEREO negotiates a 2-channel output bus and renders
// per-channel. A PERFORMANCE choice the instrument owns (component state), never written
// to the bank. Default Mono preserves current behavior. Lives in the pure core as a plain
// value so the shell (bus negotiation, state) and the engine share one spelling; the core
// itself never branches on it — the mode only picks which render overload the shell drives.
enum class ChannelMode { Mono, Stereo };

// ---------------------------------------------------------------------------
// S15/S16 per-zone play PARAMETERS (plain data). Defined up here (before SampleData) because
// SampleData carries a ZonePlayParams by value — a voice reads it at start(). The matching
// per-frame EVALUATOR classes (AHDSR AdsrEnvelope, TriggerEnvelope, PitchEnvelope) live lower
// with the rest of the engine machinery; only the value structs need to precede SampleData.
// ---------------------------------------------------------------------------

// AHDSR amplitude envelope parameters (S15 grows the S3 ADSR with a HOLD stage between Attack
// and Decay). holdFrames == 0 is EXACTLY the pre-S15 ADSR (back-compat). See AdsrEnvelope below.
struct AdsrParams {
    std::int64_t attackFrames  = 0;
    std::int64_t holdFrames    = 0;     // S15: hold at 1.0 between Attack and Decay; 0 = pre-S15 ADSR
    std::int64_t decayFrames   = 0;
    double       sustainLevel  = 1.0;   // 0..1
    std::int64_t releaseFrames = 0;
};

// S15 play mode. GATE = classic held note (AHDSR + sustain loop + note-off release, today's
// behavior grown by the hold stage). TRIGGER = one-shot: note-off-immune, no sustain loop,
// plays a % of the sample length shaped by fade-in/out. Both honor the start point. Per-zone
// (D-B); DEFAULT Gate so an instrument with no S15 params plays exactly as before.
enum class PlayMode { Gate, Trigger };

// Trigger amplitude envelope parameters (S15). Playback covers the source-frame span
// [startFrame, playEnd), playEnd = startFrame + round(lengthFraction*(frames - startFrame)),
// lengthFraction in (0,1]. Amplitude ramps 0->1 over fadeInFrames at the head and 1->0 over
// fadeOutFrames anchored to playEnd; unity between. Fades clamp so fadeIn + fadeOut <= play
// length. The voice frees when the head reaches playEnd. Note-off is a no-op in Trigger.
struct TriggerParams {
    double       lengthFraction = 1.0;  // (0,1] of the post-start span to play
    std::int64_t fadeInFrames   = 0;    // 0->1 ramp at the head
    std::int64_t fadeOutFrames  = 0;    // 1->0 ramp anchored to playEnd
};

// The fade curve for Trigger's ramps. EQUAL_POWER (constant-power sin/cos) is the default
// (click-free on one-shots, per spec); LINEAR is the build-time residual. An enum (not a bool)
// so a third curve can join without a signature change.
enum class FadeCurve { EqualPower, Linear };

// The DEFAULT fade curve (S15 spec: equal-power). One constant to flip if linear is wanted.
inline constexpr FadeCurve kDefaultFadeCurve = FadeCurve::EqualPower;

// The per-zone pitch engine. VARISPEED = today's path (readPos_ += ratio_): pitch and duration
// coupled (an octave up plays half as long). PRESERVE = duration-preserving: the read advances
// at the SOURCE rate while a PitchShifter transposes the output (an octave up keeps its length).
enum class PitchEngine { Varispeed, Preserve };

// The PRODUCT DEFAULT pitch engine (S16-F1 — Daniel's "I want duration-preserving repitching"
// directive). ONE constant to flip if Varispeed should be the default instead. This is the
// default a NEW or absent-in-the-blob zone gets — APPLIED AT THE STATE BOUNDARY (sample_map's
// deserialize / editor zone-creation), NOT the pure-core struct default. The pure-core
// ZonePlayParams.pitchEngine member defaults to VARISPEED so that "no params == the pre-S16
// engine" holds for the core's own regression tests (an octave up still halves duration in the
// bare engine); the Preserve product default is layered on above at (de)serialization.
inline constexpr PitchEngine kDefaultPitchEngine = PitchEngine::Preserve;

// The OLA window (frames) the Preserve PitchShifter uses, derived from a window in milliseconds
// at the voice's sample rate. ~50 ms is the WDL quality-0 window the spec cites; larger =
// smoother on big transpositions, more onset latency. One knob, resolved at voice allocation.
inline constexpr double kPreserveWindowMs = 50.0;

// A per-voice AD pitch-modulation envelope (S16), OFF by default (enabled=false -> offset always
// 0 -> playback bit-identical to the un-modulated engine). At note-on the pitch offset rises to
// peakSemitones over attackFrames, then falls to 0 (base pitch) over decayFrames. A zero attack
// gives the pure "start high, drop to base" percussive drop. peakSemitones is signed (+/-).
struct PitchEnvParams {
    bool         enabled       = false;
    std::int64_t attackFrames  = 0;
    std::int64_t decayFrames   = 0;
    double       peakSemitones = 0.0;  // signed depth at the peak
};

// The bundle of S15/S16 per-zone play parameters a voice reads at start(). Lives on SampleData
// (each zone owns one SampleData in the zoned keymap). DEFAULTS are EXACTLY the pre-S15/S16
// engine: Gate mode, AHDSR with hold 0 (= the S3 ADSR), VARISPEED pitch engine, pitch envelope
// disabled — so a bare-core voice with default play is byte-identical to the pre-S15 build (the
// core regression tests rely on this). The PRODUCT default of Preserve (S16-F1) is applied one
// layer up at (de)serialization for new/absent zones — see kDefaultPitchEngine.
struct ZonePlayParams {
    PlayMode       playMode = PlayMode::Gate;
    AdsrParams     adsr;                          // Gate: the AHDSR envelope
    TriggerParams  trigger;                       // Trigger: %-length + fades
    PitchEngine    pitchEngine = PitchEngine::Varispeed;
    PitchEnvParams pitchEnv;                       // AD pitch modulation, off by default
};

// ---------------------------------------------------------------------------
// Sample data the core plays. Plain, decoded PCM + the S2 bank intrinsics that
// govern playback. The shell decodes the on-disk WAV and fills this; the core
// never touches a file.
// ---------------------------------------------------------------------------

// A loop over [start, end) frames, half-open. A zero-length loop (start == end)
// is the "no sustain loop" marker — a held note past the sample end goes silent
// rather than looping a zero span. absent-loop is modeled by leaving hasLoop false.
struct SampleLoop {
    bool hasLoop = false;
    std::int64_t start = 0;  // first looped frame (inclusive)
    std::int64_t end   = 0;  // one-past-last looped frame (exclusive); start <= end
};

// One decoded audio sample the engine can voice. DEINTERLEAVED, per-channel: `frames` is
// channel 0 (always present) and `framesR` is channel 1 (present only for a STEREO sample).
// A sample is stereo iff `framesR` is non-empty AND the same length as `frames`; otherwise
// it is mono (the degenerate, byte-identical Tier 0-1 case — `framesR` stays empty). Both
// channels share `readPos_`, `rootNote`, and `loop`, so repitch/loop are per-frame identical
// across channels; only the sampled value differs. `rootNote` is the MIDI note the file was
// recorded at (S2 intrinsic) — the pitch that plays back at unity ratio.
struct SampleData {
    std::vector<AudioSample> frames;   // channel 0 PCM (mono, or L of a stereo sample)
    std::vector<AudioSample> framesR;  // channel 1 PCM (R); EMPTY for a mono sample
    int sampleRate = 44100;            // frames per second (for reference; ratio is
                                       // note-relative, so rate cancels for repitch)
    int rootNote = 60;                 // MIDI note recorded at (plays at unity here)
    SampleLoop loop;                   // sustain loop, if any
    // Initial read position (frame offset) a voice starts playback at — frame 0 by
    // default, so an unset start point is exactly the pre-S11 behavior. S11 makes this
    // an instrument-side per-zone override (the "start point" marker); S15 builds on it
    // (both play modes carry a modifiable start). Clamped into [0, frames) at note-on:
    // a start >= the sample length is a no-op (voice starts at 0), never out of bounds.
    std::int64_t startFrame = 0;

    // S15/S16 per-zone play parameters (play mode, AHDSR/Trigger envelope, pitch engine, pitch
    // envelope). Defaults reproduce the pre-S15 engine EXCEPT the pitch engine default is
    // Preserve (S16-F1). A voice reads this at start(). Struct defined above SampleData.
    ZonePlayParams play;

    // 2 iff a matching-length second channel exists; else 1. A framesR of a different
    // length than frames is treated as absent (mono) — a malformed pair never half-plays.
    int channelCount() const {
        return (!framesR.empty() && framesR.size() == frames.size()) ? 2 : 1;
    }

};

// ---------------------------------------------------------------------------
// Keymap — the performance map (instrument-owned, D-B). A note+velocity resolves
// to at most one zone; a zone names which SampleData to play and the root note to
// repitch from. Tier-0 degenerate case: a single zone spanning [0,127] with the
// sample's own root. Tier-1: several zones, each a key range with its own root.
//
// TIER-2 EXTENSION (velocity layers / round-robin) — designed for, not built:
// resolution returns a zone; a zone today owns one sampleIndex. Tier 2 makes a zone
// own a *list* of (velocity-range, sampleIndex) layers (and round-robin sets), and
// resolve() gains the velocity dimension it already receives but currently ignores
// for selection. The (note, velocity) signature and the "resolve to a zone, then a
// sample within it" shape are already in place — Tier 2 fills in the second step
// without changing callers or the voice engine. See the report note.
// ---------------------------------------------------------------------------

// A key range [lowNote, highNote] (inclusive both ends) mapping to one sample, with
// the root note to repitch from (defaults to the sample's own root, overridable in
// the performance map per S5). velocityLow/High reserved for Tier-2 layers; today a
// zone accepts the full 1..127 velocity range (0 is note-off by MIDI convention).
struct KeyZone {
    int lowNote = 0;
    int highNote = 127;
    int rootNote = 60;        // repitch reference for this zone
    std::size_t sampleIndex = 0;  // index into Keymap::samples
};

// Result of resolving a (note, velocity). `matched == false` means the note falls in
// no zone (out-of-zone) — a defined no-play result, NOT an error and NOT voice 0.
struct ZoneResolution {
    bool matched = false;
    std::size_t zoneIndex = 0;   // valid only when matched
};

// The keymap: the decoded samples plus the zones that map keys onto them. Owns
// resolution. Pure: no host types. Zones are tested first-match in order, so an
// earlier zone wins an overlap (deterministic, documented).
struct Keymap {
    std::vector<SampleData> samples;
    std::vector<KeyZone> zones;

    // Resolves (note, velocity) to a zone. First zone (in order) whose [low,high]
    // contains `note` wins. velocity is accepted now (Tier-2 seam) but does not
    // affect zone choice at Tier 0-1. Returns {matched=false} when no zone contains
    // the note.
    ZoneResolution resolve(int note, int velocity) const;

    // Convenience: build the Tier-0 degenerate keymap — one sample mapped
    // chromatically across the whole keyboard from its own root note.
    static Keymap singleSampleChromatic(SampleData sample);
};

// The chromatic pitch ratio to play `note` given a sample recorded at `rootNote`:
// 2^((note - rootNote) / 12). note == rootNote -> 1.0 (unity). One octave up -> 2.0,
// one octave down -> 0.5. Pure equal-temperament; no reference-frequency needed.
double pitchRatio(int note, int rootNote);

// ---------------------------------------------------------------------------
// AHDSR amplitude envelope (S15 grows the S3 ADSR with a HOLD stage). Sample-based
// (times in frames), linear segments. A gate: noteOn() enters Attack; noteOff() enters
// Release from wherever it is. Asserted against a known signal in the tests (mirror of peaks).
//
// Segment math (all linear ramps):
//   Attack:  0 -> 1 over attackFrames
//   Hold:    hold 1 over holdFrames                     (S15: NEW stage between A and D)
//   Decay:   1 -> sustainLevel over decayFrames
//   Sustain: hold sustainLevel until noteOff
//   Release: currentLevel -> 0 over releaseFrames
// A zero-length attack jumps straight to 1 on the first frame; HOLDFRAMES == 0 skips Hold
// entirely, which is EXACTLY the pre-S15 ADSR (back-compat — existing Gate play is unchanged);
// zero decay jumps to sustain; a noteOff during attack/hold/decay (release-before-sustain)
// releases from the current partial level, not from sustainLevel. AdsrParams is defined above
// (with the other per-zone value structs); this section holds only the per-frame evaluator.
// ---------------------------------------------------------------------------

class AdsrEnvelope {
public:
    enum class Stage { Idle, Attack, Hold, Decay, Sustain, Release, Finished };

    void configure(const AdsrParams& params) { params_ = params; }

    // Gate on: (re)start from Attack.
    void noteOn();
    // Gate off: enter Release from the current level.
    void noteOff();

    // Advances one frame and returns the amplitude for THIS frame (before advancing).
    // Once Release completes the envelope latches Finished and returns 0.0 forever
    // (until the next noteOn). A single, monotonic per-frame step — the caller pulls
    // one value per output frame.
    double tick();

    Stage stage() const { return stage_; }
    bool finished() const { return stage_ == Stage::Finished; }
    double level() const { return level_; }

private:
    AdsrParams params_;
    Stage stage_ = Stage::Idle;
    double level_ = 0.0;
    std::int64_t framesInStage_ = 0;
    double releaseFrom_ = 0.0;  // level at the moment noteOff() was called
};

// ---------------------------------------------------------------------------
// S15 Trigger amplitude envelope (per-frame evaluator). The PlayMode / TriggerParams /
// FadeCurve value structs are defined above with the other per-zone params.
// ---------------------------------------------------------------------------

// Trigger amplitude envelope: a stateless-shape amplitude function over the play span, evaluated
// at a SOURCE-frame offset into the span. Anchoring the fades to SOURCE frames (not output
// frames) is what makes S15 compose with S16: under Preserve the read advances at source rate so
// output and source frames coincide, but under Varispeed a transposed voice consumes source
// faster — driving the fades off the read position keeps the fade-in/out anchored to the SAME
// source frames regardless of engine (the play-length end is a source-frame fact, S15×S16). The
// voice reports the read offset; this maps it to amplitude. Distinct from AHDSR — time-boxed by
// the play length and note-off-immune. Reports finished() once the offset reaches the play length.
class TriggerEnvelope {
public:
    // Configure from the play span + fades. `playLengthFrames` is (playEnd - startFrame): the
    // SOURCE-frame length of the play span. Fades are clamped so fadeIn + fadeOut <= playLength
    // (fadeOut anchored to the end). A zero/negative play length finishes immediately.
    void configure(std::int64_t playLengthFrames, std::int64_t fadeInFrames,
                   std::int64_t fadeOutFrames, FadeCurve curve = kDefaultFadeCurve);

    // Amplitude in [0,1] at `sourceOffset` = (readPos - startFrame) source frames into the play
    // span. Latches finished() once the offset reaches the play length (>= playLength). Pure over
    // the offset (no internal advance) so it composes with either pitch engine's read rate.
    double amplitudeAt(double sourceOffset);

    bool finished() const { return finished_; }

private:
    std::int64_t playLength_ = 0;
    std::int64_t fadeIn_ = 0;
    std::int64_t fadeOut_ = 0;
    FadeCurve curve_ = kDefaultFadeCurve;
    bool finished_ = false;
};

// ---------------------------------------------------------------------------
// S16 pitch envelope (per-frame evaluator). The PitchEngine / PitchEnvParams value structs
// and the kDefaultPitchEngine / kPreserveWindowMs constants are defined above.
// ---------------------------------------------------------------------------

// Per-frame AD pitch-envelope evaluator. tick() returns the CURRENT pitch offset in semitones
// (0 when disabled or past attack+decay), advancing one frame. The voice converts the semitone
// offset to a ratio multiply (Varispeed) or a shift-amount add (Preserve). Pure, unit-tested
// for offset at t=0, peak at t=attack, and 0 at t=attack+decay.
class PitchEnvelope {
public:
    void configure(const PitchEnvParams& params) { params_ = params; pos_ = 0; }
    void noteOn() { pos_ = 0; }

    // Advance one frame, return this frame's pitch offset in semitones.
    double tick();

private:
    PitchEnvParams params_;
    std::int64_t pos_ = 0;
};

// ---------------------------------------------------------------------------
// A single voice: one active note playing one repitched, enveloped sample. Reads
// the sample by fractional frame position with linear interpolation, advancing by
// the pitch ratio; loops the sustain region for held notes past the loop end.
// ---------------------------------------------------------------------------

class Voice {
public:
    // Starts this voice on `note` at `velocity`, playing `sample` (a stable reference
    // the caller must keep alive for the voice's lifetime — the Keymap owns it), repitched
    // from `rootNote`. `gateAdsr` is the effective Gate AHDSR (the engine supplies the
    // instrument-wide attack/decay/sustain/release timing; the per-zone HOLD stage comes from
    // sample.play.adsr.holdFrames, folded in here). The S15 play MODE + Trigger params and the
    // S16 pitch ENGINE + pitch envelope are read from `sample.play`. The Preserve shifters MUST
    // already be pre-sized (presizePreserveShifters, off-thread) — start() only reset()s + warm()s
    // them (RT-safe, no allocation) since it runs on the audio thread inside process(). The warm
    // silence pass settles the OLA taps before the first output frame (no cold-start click).
    // Byte-identical to the pre-S15 engine when sample.play is default (Gate + Varispeed + no
    // pitch env).
    void start(int note, int velocity, const SampleData& sample, int rootNote,
               const AdsrParams& gateAdsr);

    // Gate off — begins the amplitude release. In GATE mode this enters the AHDSR release; in
    // TRIGGER mode it is a NO-OP (Trigger ignores note-off and plays through to its play length).
    void release();

    // True while this voice is producing (or about to produce) sound.
    bool active() const { return active_; }
    // The note this voice was started on (for note-off routing). Meaningless if idle.
    int note() const { return note_; }
    // Monotonic age counter — higher = started earlier relative to others. The voice
    // engine uses this for its stealing policy (oldest first). Set by the engine.
    std::uint64_t startOrder() const { return startOrder_; }
    void setStartOrder(std::uint64_t order) { startOrder_ = order; }
    bool releasing() const { return releasing_; }
    // The S16 pitch engine this voice is running (for the engine's Preserve-voice tally). Only
    // meaningful while active().
    PitchEngine pitchEngine() const { return pitchEngine_; }

    // Pre-SIZE this voice's Preserve pitch shifters (both channels) to `windowFrames`, OFF the
    // audio thread (this allocates). The engine calls it once at construction so start() — which
    // runs on the audio thread inside process() — never allocates: start() only reset()s + warm()s
    // the already-sized rings. `windowFrames` <= 1 leaves the shifters as pass-through (Varispeed
    // instruments pay no ring cost). Idempotent: a re-presize to the same window is a cheap no-op
    // in the underlying vector.
    void presizePreserveShifters(std::int64_t windowFrames);

    // Renders one frame's contribution, advancing the read head and envelope by one
    // output frame. Returns 0.0 (and goes idle) once the envelope finishes or the
    // sample runs out with no loop. The value is already velocity- and
    // envelope-scaled — the engine sums voices directly. This is the MONO path (channel
    // 0 only) — byte-identical to the pre-S7 engine, so mono play is unchanged.
    AudioSample renderFrame();

    // STEREO render: writes THIS frame's per-channel contribution into `l`/`r` and advances
    // the read head + envelope by exactly one frame (the same single advance the mono path
    // performs — the envelope ticks ONCE per frame, shared across both channels). For a mono
    // sample (channelCount()==1) both `l` and `r` receive the same value (dual-mono / centered).
    // Both outputs are already velocity- and envelope-scaled. Goes idle on the same conditions
    // as the mono path (envelope finished / sample exhausted with no loop) writing 0 to both.
    void renderFrameStereo(AudioSample& l, AudioSample& r);

private:
    // Shared read/advance for both render paths: computes the interpolated per-channel
    // value(s) at the current read head, ticks the amplitude + pitch envelopes once, applies
    // the pitch engine (Varispeed read-rate bias OR Preserve shift), advances the head, and
    // latches idle on exhaustion. `stereo` selects whether the second channel is read (and
    // returned in `outR`); when false `outR` is left untouched. Returns the channel-0 value.
    AudioSample advanceFrame(bool stereo, AudioSample& outR);

    // This frame's amplitude in [0,1] from the active envelope. GATE: the AHDSR ticks once per
    // output frame (independent of the read rate — envelope time is wall-clock). TRIGGER: the
    // fade shape is evaluated at the SOURCE offset (readPos - startFrame) so the fades anchor to
    // source frames and compose with either pitch engine. Sets amplitudeDone_ when the envelope
    // finishes (Gate: release complete; Trigger: play length reached) so advanceFrame frees the voice.
    double tickAmplitude();

    bool active_ = false;
    bool releasing_ = false;
    int note_ = 0;
    double velocityGain_ = 1.0;
    double baseRatio_ = 1.0;     // 2^((note-root)/12): the un-modulated repitch ratio
    double ratio_ = 1.0;         // fractional SOURCE frames advanced per output frame (this frame)
    double readPos_ = 0.0;       // fractional frame index into the sample
    const SampleData* sample_ = nullptr;

    // S15 play mode + amplitude envelopes. Gate uses env_ (AHDSR); Trigger uses trigEnv_. Only
    // one is active per voice (selected by playMode_ at start). playEnd_ is Trigger's source-frame
    // stop (the voice frees when readPos_ >= playEnd_, mirroring the run-off-end idle).
    PlayMode playMode_ = PlayMode::Gate;
    AdsrEnvelope env_;
    TriggerEnvelope trigEnv_;
    std::int64_t startFrame_ = 0;  // clamped initial read frame; Trigger fade offset origin
    std::int64_t playEnd_ = 0;   // Trigger: source-frame end; Gate: unused
    bool amplitudeDone_ = false; // set when the active amplitude envelope finished

    // S16 pitch engine + pitch envelope. pitchEngine_ selects Varispeed (ratio bias) vs Preserve
    // (source-rate read + shifter). shiftL_/shiftR_ transpose the Preserve output per channel
    // (one read head, per-channel shift — S7 compose). pitchEnv_ rides EITHER engine.
    PitchEngine pitchEngine_ = PitchEngine::Varispeed;
    PitchEnvelope pitchEnv_;
    PitchShifter shiftL_;
    PitchShifter shiftR_;

    std::uint64_t startOrder_ = 0;
};

// ---------------------------------------------------------------------------
// The polyphonic voice engine: a fixed pool of voices, note-on allocation with
// bounded voice stealing, note-off routing, and block rendering (sum of voices).
//
// VOICE-STEALING POLICY (deterministic, documented): when all voices are busy and a
// new note-on arrives, steal in this priority order:
//   1. the oldest voice already in RELEASE (finishing anyway — cheapest to cut),
//   2. else the oldest voice overall (longest-held note gives way to the new one).
// "Oldest" = smallest startOrder (assigned monotonically at note-on). This is the
// standard hardware-sampler policy: prefer to sacrifice a dying tail, and failing
// that, the note that has already had the most time.
// ---------------------------------------------------------------------------

class VoiceEngine {
public:
    // Builds an engine with `maxVoices` voices (the polyphony bound) playing from
    // `keymap`. The keymap must outlive the engine (the engine holds a reference — it
    // reads zones and sample data through it, never copies PCM). `adsr` is the instrument-wide
    // Gate AHDSR timing (attack/decay/sustain/release); each zone's HOLD stage + play mode +
    // pitch engine ride on its SampleData::play. `preserveVoiceCap` (S16) bounds how many
    // Preserve-engine voices may sound at once (the shifter is materially heavier than
    // Varispeed) — a Preserve note-on beyond the cap is dropped rather than glitching; 0 means
    // "no separate Preserve cap" (bounded only by maxVoices). `preserveWindowFrames` is the OLA
    // window (in OUTPUT frames) every voice's Preserve pitch shifters are PRE-SIZED to at
    // construction (OFF the audio thread), so note-on (which runs in process()) never allocates;
    // 0 leaves them pass-through (a Varispeed-only instrument pays no ring cost). The processor
    // derives it from the host sample rate (kPreserveWindowMs). Defaulted so existing callers
    // (and the pure-core tests) are unaffected.
    VoiceEngine(std::size_t maxVoices, const Keymap& keymap, const AdsrParams& adsr,
                std::size_t preserveVoiceCap = 0, std::int64_t preserveWindowFrames = 0);

    // MIDI note-on. Resolves the note+velocity to a zone; if none matches (out of
    // zone) it is a defined no-op (no voice consumed). Otherwise allocates a free
    // voice, or steals one per the policy above. Returns the index of the voice used,
    // or kNoVoice for an out-of-zone (unplayed) note.
    std::size_t noteOn(int note, int velocity);

    // MIDI note-off. Releases the most-recently-started active, non-releasing voice
    // playing `note` (so a re-triggered same note releases the newest first, leaving
    // the older tail to ring — matches hardware behavior). No-op if none match.
    void noteOff(int note);

    // REAL-TIME render (S4): sums all active voices into the caller-provided buffer
    // `out[0..frameCount)`, ADDING to whatever is there (the caller clears or mixes —
    // this never touches memory it does not own and NEVER allocates). This is the
    // audio-thread entry point: the VST3 process callback passes the host's own output
    // channel buffer, so no allocation, resize, or heap traffic happens under process.
    // Voices that finish mid-block go idle and stop contributing. `out` must point at
    // at least `frameCount` writable samples; a null `out` or zero count is a no-op.
    void render(AudioSample* out, std::size_t frameCount);

    // REAL-TIME stereo render (S7): sums all active voices per-channel into the caller's two
    // buffers `left`/`right` (each `frameCount` writable samples), ADDING to whatever is there
    // (the caller clears/mixes). Same RT discipline as the mono overload — no allocation, no
    // resize, no lock. A mono sample plays dual-mono (same value to both channels, centered);
    // a stereo sample plays its two channels. A null buffer or zero count is a no-op. The mono
    // and stereo render paths are independent output shapes over the SAME voice pool; the active
    // channel mode (mono vs stereo bus) picks which one the process callback drives per block.
    void render(AudioSample* left, AudioSample* right, std::size_t frameCount);

    // TEST / off-thread convenience: appends `frameCount` summed frames to `out`
    // (grows it — DO NOT call on the audio thread; it allocates). Delegates to the
    // real-time overload after sizing the buffer, so both paths share one mix loop.
    // Does not clear existing contents — appends, matching the pre-S4 contract the
    // unit tests rely on.
    void render(std::vector<AudioSample>& out, std::size_t frameCount);

    // Count of currently active voices (for tests / diagnostics).
    std::size_t activeVoiceCount() const;

    std::size_t maxVoices() const { return voices_.size(); }

    static constexpr std::size_t kNoVoice = static_cast<std::size_t>(-1);

private:
    // Picks a voice to (re)use for a new note-on: a free voice if any, else a stolen
    // one per the documented policy. Always returns a valid index (maxVoices >= 1).
    std::size_t allocateVoice();

    // Count of active Preserve-engine voices (for the S16 Preserve cap). Rescanned per note-on
    // (cheap: bounded by maxVoices) rather than maintained as a running tally.
    std::size_t activePreserveVoices() const;

    std::vector<Voice> voices_;
    const Keymap& keymap_;
    AdsrParams adsr_;
    std::size_t preserveVoiceCap_ = 0;  // S16: max simultaneous Preserve voices (0 = no separate cap)
    std::uint64_t nextStartOrder_ = 1;  // monotonic; 0 reserved for "never started"
};

} // namespace reasampler