Saturation.h

// DSPark - Professional Audio DSP Framework
// Copyright (c) 2026 Cristian Moresi - MIT License
 
#pragma once
 
#include "../Core/AudioBuffer.h"
#include "../Core/AudioSpec.h"
#include "../Core/Biquad.h"
#include "../Core/DryWetMixer.h"
#include "../Core/DspMath.h"
#include "../Core/Oversampling.h"
#include "../Core/Smoothers.h"
#include "../Core/AnalogRandom.h"
#include "../Core/SpscQueue.h"
#include "../Core/SpinLock.h"
#include "../Core/StateBlob.h"
#include "DCBlocker.h"
#include "MidSide.h"
 
#include <algorithm>
#include <array>
#include <atomic>
#include "../Core/detail/LogCosh.h"
 
#include <cmath>
#include <cstdint>
#include <cstring>
#include <limits>
#include <memory>
#include <type_traits>
#include <vector>
 
namespace dspark {
 
template <typename SampleType> class Saturation;
 
namespace detail {
 
template <typename T>
class SaturationAlgorithm
{
public:
    static constexpr int kAaCh = 16;
 
    virtual ~SaturationAlgorithm() = default;
 
    virtual void prepare(const AudioSpec& spec) noexcept = 0;
 
    virtual void reset() noexcept = 0;
 
    virtual void update(T /*driveGain*/, T /*character*/, const AudioSpec& /*spec*/) noexcept {}
 
    virtual typename Saturation<T>::Algorithm getType() const noexcept = 0;
 
    void setAntialias(bool on) noexcept { antialias_.store(on, std::memory_order_relaxed); }
 
protected:
    std::atomic<bool> antialias_ { false };
};
 
// -- SoftClip (tanh) ---------------------------------------------------------
// The ADAA difference quotients below run in double whatever T is: the
// antiderivative is O(1) while successive inputs can differ by 1e-5, so in
// float the quotient kept only a few correct bits (measured on 20-200 Hz
// tones: errors up to -48 dB re peak, spiking at every waveform crest).
template <typename T>
class TanhAlgorithm final : public SaturationAlgorithm<T>
{
    std::array<double, SaturationAlgorithm<T>::kAaCh> prevX_ {};
public:
    void prepare(const AudioSpec&) noexcept override { reset(); }
    void reset() noexcept override { prevX_.fill(0.0); }
    typename Saturation<T>::Algorithm getType() const noexcept override { return Saturation<T>::Algorithm::SoftClip; }
 
    inline T processSample(T sample, T drive, T character, int ch) noexcept
    {
        T x    = sample * drive;
        T bias = character * T(0.3);
        if (!this->antialias_.load(std::memory_order_relaxed))
            return fastTanh(x + bias) - fastTanh(bias);
 
        // ADAA of f(x) = tanh(x+bias) - tanh(bias); antiderivative log(cosh(x+bias)) - tanh(bias)*x.
        const int c = ch & (SaturationAlgorithm<T>::kAaCh - 1);
        const double xd = static_cast<double>(x);
        const double b  = static_cast<double>(bias);
        const double x0 = prevX_[static_cast<size_t>(c)];
        prevX_[static_cast<size_t>(c)] = xd;
        const double tb = std::tanh(b);
        const double dx = xd - x0;
        if (std::abs(dx) > 1e-7)
            return static_cast<T>((logCosh(xd + b) - logCosh(x0 + b)) / dx - tb);
        return static_cast<T>(std::tanh(0.5 * (xd + x0) + b) - tb);
    }
};
 
// -- Tube (12AX7-style asymmetric triode model) -----------------------------
template <typename T>
class TubeAlgorithm final : public SaturationAlgorithm<T>
{
    std::array<double, SaturationAlgorithm<T>::kAaCh> prevX_ {};
 
    static inline double f1(double x, double asym) noexcept
    {
        return (x >= 0.0) ? logCosh(x) : logCosh(x * asym) / asym;
    }
public:
    void prepare(const AudioSpec&) noexcept override { reset(); }
    void reset() noexcept override { prevX_.fill(0.0); }
    typename Saturation<T>::Algorithm getType() const noexcept override { return Saturation<T>::Algorithm::Tube; }
 
    inline T processSample(T sample, T drive, T character, int ch) noexcept
    {
        T x = sample * drive;
        T asym = T(1.15) + character * T(0.5);
        if (!this->antialias_.load(std::memory_order_relaxed))
            return (x >= T(0)) ? fastTanh(x) : fastTanh(x * asym);
 
        // ADAA of the asymmetric triode curve; antiderivative is piecewise log(cosh).
        const int c = ch & (SaturationAlgorithm<T>::kAaCh - 1);
        const double xd = static_cast<double>(x);
        const double a  = static_cast<double>(asym);
        const double x0 = prevX_[static_cast<size_t>(c)];
        prevX_[static_cast<size_t>(c)] = xd;
        const double dx = xd - x0;
        if (std::abs(dx) > 1e-7)
            return static_cast<T>((f1(xd, a) - f1(x0, a)) / dx);
        const double m = 0.5 * (xd + x0);
        return static_cast<T>((m >= 0.0) ? std::tanh(m) : std::tanh(m * a));
    }
};
 
// -- HardClip ----------------------------------------------------------------
template <typename T>
class HardClipAlgorithm final : public SaturationAlgorithm<T>
{
    std::array<T, SaturationAlgorithm<T>::kAaCh> prevX_ {};
 
    static inline T g(T u) noexcept
    {
        T a = std::abs(u);
        return (a <= T(1)) ? T(0.5) * u * u : a - T(0.5);
    }
public:
    void prepare(const AudioSpec&) noexcept override { reset(); }
    void reset() noexcept override { prevX_.fill(T(0)); }
    typename Saturation<T>::Algorithm getType() const noexcept override { return Saturation<T>::Algorithm::HardClip; }
 
    inline T processSample(T sample, T drive, T character, int ch) noexcept
    {
        T bias = character * T(0.3);
        T cb = std::clamp(bias, T(-1), T(1));
        T d = sample * drive;
        if (!this->antialias_.load(std::memory_order_relaxed))
            return std::clamp(d + bias, T(-1), T(1)) - cb;
 
        // ADAA of the hard clip; antiderivative is the piecewise quadratic g().
        int c = ch & (SaturationAlgorithm<T>::kAaCh - 1);
        T d0 = prevX_[c];
        prevX_[c] = d;
        T u = d + bias, u0 = d0 + bias;
        if (u >= T(-1) && u <= T(1) && u0 >= T(-1) && u0 <= T(1))
            return u - cb;     // linear body (below the clip point): pass through, no averaging (no HF roll-off)
        T dd = d - d0;
        if (std::abs(dd) > T(1e-5))
            return (g(u) - g(u0)) / dd - cb;
        return std::clamp(T(0.5) * (d + d0) + bias, T(-1), T(1)) - cb;
    }
};
 
// -- Exciter (polynomial waveshaper) -----------------------------------------
template <typename T>
class ExciterAlgorithm final : public SaturationAlgorithm<T>
{
public:
    void prepare(const AudioSpec&) noexcept override {}
    void reset() noexcept override {}
    typename Saturation<T>::Algorithm getType() const noexcept override { return Saturation<T>::Algorithm::Exciter; }
 
    inline T processSample(T sample, T drive, T character, int) noexcept
    {
        T x      = std::clamp(sample * drive, T(-10), T(10));
        T x2     = x * x;
        T x3     = x2 * x;
        T result = x + character * T(0.25) * x2 - T(0.15) * x3;
        return std::clamp(result, T(-1), T(1));
    }
};
 
// -- Wavefolder (sin + first-order ADAA) -------------------------------------
template <typename T>
class WavefolderAlgorithm final : public SaturationAlgorithm<T>
{
    static constexpr int kMaxCh = 16;
    std::array<T, kMaxCh> lastX_ {};
 
public:
    void prepare(const AudioSpec&) noexcept override { reset(); }
    void reset() noexcept override { lastX_.fill(T(0)); }
    typename Saturation<T>::Algorithm getType() const noexcept override { return Saturation<T>::Algorithm::Wavefolder; }
 
    inline T processSample(T sample, T drive, T character, int ch) noexcept
    {
        const T bias = character * (pi<T> / T(4));
        const T x    = sample * drive + bias;
        const T sb   = std::sin(bias);
        const int c  = ch & (kMaxCh - 1);
 
        // Mean of sin over [x0, x], (cos x0 - cos x) / (x - x0), written as
        // sin(mid) * sinc(half) via the sum-to-product identity: exact, with
        // no cancellation (the difference of cosines lost most of its digits
        // in float whenever consecutive inputs were close).
        const T half = T(0.5) * (x - lastX_[static_cast<size_t>(c)]);
        const T mid  = T(0.5) * (x + lastX_[static_cast<size_t>(c)]);
        const T sinc = (std::abs(half) > T(1e-4)) ? std::sin(half) / half
                                                  : T(1) - half * half / T(6);
        lastX_[static_cast<size_t>(c)] = x;
        return std::sin(mid) * sinc - sb;
    }
};
 
// -- Bitcrusher (TPDF dither) ------------------------------------------------
template <typename T>
class BitcrusherAlgorithm final : public SaturationAlgorithm<T>
{
    // Per-sample TPDF dither needs a true white PRNG. (The previous
    // AnalogRandom-based source was a 1 Hz sample-and-hold: two consecutive
    // reads were almost always identical, so the dither was effectively zero
    // and the crusher truncated with audible quantisation distortion.)
    uint32_t rngState_ = 0x9E3779B9u;
    T steps_ = T(1);
    T invSteps_ = T(1);
 
    [[nodiscard]] inline T nextRandom() noexcept
    {
        rngState_ ^= rngState_ << 13;
        rngState_ ^= rngState_ >> 17;
        rngState_ ^= rngState_ << 5;
        constexpr T scale = T(1) / static_cast<T>(0xFFFFFFFFu);
        return static_cast<T>(rngState_) * scale - T(0.5);
    }
 
public:
    void prepare(const AudioSpec&) noexcept override
    {
        if (rngState_ == 0) rngState_ = 1; // xorshift fixed point guard
    }
    void reset() noexcept override {}
    typename Saturation<T>::Algorithm getType() const noexcept override { return Saturation<T>::Algorithm::Bitcrusher; }
 
    void update(T drive, T /*character*/, const AudioSpec&) noexcept override
    {
        T clamped  = std::clamp(drive, T(1), T(100));
        T bitDepth = mapRange(clamped, T(1), T(100), T(16), T(2));
        steps_     = std::pow(T(2), bitDepth);
        invSteps_  = T(1) / steps_;
    }
 
    inline T processSample(T sample, T, T, int) noexcept
    {
        // True TPDF: difference of two independent uniforms, +-1 LSB peak.
        T dither = (nextRandom() - nextRandom()) * invSteps_;
        return invSteps_ * std::round((sample + dither) * steps_);
    }
};
 
// -- Tape (anhysteretic Langevin magnetisation + head bump + HF rolloff) -----
template <typename T>
class TapeAlgorithm final : public SaturationAlgorithm<T>
{
    static constexpr int kMaxCh = 16;
    std::array<Biquad<T, 1>, kMaxCh> preFilters_;
    std::array<Biquad<T, 1>, kMaxCh> postFilters_;
    std::array<T, kMaxCh>            M_ {};   
    int numChannels_ = 0;
    T lastDrive_ = T(-1);
    double lastSampleRate_ = 0.0;
 
    static inline T langevin(T x) noexcept
    {
        const T ax = std::abs(x);
        if (ax < T(0.5))
        {
            const T x2 = x * x;
            return x * (T(1) / T(3) - x2 * (T(1) / T(45) - x2 * (T(2) / T(945))));
        }
        if (ax > T(20)) return std::copysign(T(1), x) - T(1) / x;
        return T(1) / std::tanh(x) - T(1) / x;
    }
 
    static inline T langevinDeriv(T x) noexcept
    {
        const T ax = std::abs(x);
        if (ax < T(0.5))
        {
            const T x2 = x * x;
            return T(1) / T(3) - x2 * (T(1) / T(15) - x2 * (T(2) / T(189)));
        }
        if (ax > T(20)) return T(1) / (x * x);
        const T s = std::sinh(x);
        return T(1) / (x * x) - T(1) / (s * s);
    }
 
public:
    void prepare(const AudioSpec& spec) noexcept override
    {
        numChannels_ = std::min(spec.numChannels, kMaxCh); // clamp per-channel state
        // Invalidate the filter-design cache: a re-prepare can widen the
        // channel count at an unchanged rate/drive, and the new channels'
        // filters must still receive coefficients on the next update().
        lastDrive_ = T(-1);
        lastSampleRate_ = 0.0;
        reset();
    }
    void reset() noexcept override
    {
        for (auto& f : preFilters_)  f.reset();
        for (auto& f : postFilters_) f.reset();
        M_.fill(T(0));
    }
    typename Saturation<T>::Algorithm getType() const noexcept override { return Saturation<T>::Algorithm::Tape; }
 
    void update(T drive, T /*character*/, const AudioSpec& spec) noexcept override
    {
        // Both filters depend only on drive and sample rate; skip the
        // trig-heavy redesign when neither changed since the last block.
        if (drive == lastDrive_ && spec.sampleRate == lastSampleRate_) return;
        lastDrive_ = drive;
        lastSampleRate_ = spec.sampleRate;
 
        auto driveDb = gainToDecibels(drive, T(-100));
        T bumpGain = T(1.5) + std::min(driveDb * T(0.05), T(3.0));
        auto peakCoeffs = BiquadCoeffs::makePeak(spec.sampleRate, 80.0, 0.6, static_cast<double>(bumpGain));
        auto lpFreq = std::max(6000.0, 19000.0 - static_cast<double>(driveDb) * 200.0);
        auto lpCoeffs = BiquadCoeffs::makeLowPass(spec.sampleRate, lpFreq, 0.55);
 
        for (int ch = 0; ch < numChannels_; ++ch)
        {
            preFilters_[ch].setCoeffs(peakCoeffs);
            postFilters_[ch].setCoeffs(lpCoeffs);
        }
    }
 
    inline T processSample(T sample, T drive, T character, int ch) noexcept
    {
        const T filtered = preFilters_[ch].processSample(sample, 0);
        const T H = filtered * drive;
 
        // character (clamped [-1,1] upstream) sets the mean-field coupling:
        // harder knee and more mid-level bloom as alpha rises.
        const T alpha = T(0.35) + T(0.15) * character;
        const T a     = T(1) / (T(3) * (T(1) - alpha));
        const T Ms    = T(3) * a;
 
        T M = M_[ch];
        for (int it = 0; it < 3; ++it)
        {
            const T x  = (H + alpha * M) / a;
            const T f  = M - Ms * langevin(x);
            const T fp = T(1) - T(3) * alpha * langevinDeriv(x);
            M -= f / fp;
        }
        M = std::clamp(M, -Ms, Ms);
        M_[ch] = M;
 
        return postFilters_[ch].processSample((T(1) - alpha) * M, 0);
    }
};
 
// -- Transformer (frequency-dependent: heavy LF, light HF) ------------------
template <typename T>
class TransformerAlgorithm final : public SaturationAlgorithm<T>
{
    static constexpr int kMaxCh = 16;
    std::array<Biquad<T, 1>, kMaxCh> lpFilters_;
    int numChannels_ = 0;
    double lastSampleRate_ = 0.0;
 
public:
    void prepare(const AudioSpec& spec) noexcept override
    {
        numChannels_ = std::min(spec.numChannels, kMaxCh); // clamp per-channel state
        lastSampleRate_ = 0.0; // force a redesign so channels added by a re-prepare get coefficients
        reset();
    }
    void reset() noexcept override
    {
        for (auto& f : lpFilters_) f.reset();
    }
    typename Saturation<T>::Algorithm getType() const noexcept override { return Saturation<T>::Algorithm::Transformer; }
 
    void update(T /*drive*/, T /*character*/, const AudioSpec& spec) noexcept override
    {
        // The crossover is fixed at 250 Hz: only recompute when the effective
        // sample rate changes (update() runs every block from the pipeline).
        if (spec.sampleRate == lastSampleRate_) return;
        lastSampleRate_ = spec.sampleRate;
 
        auto c = BiquadCoeffs::makeLowPass(spec.sampleRate, 250.0, 0.707);
        for (int ch = 0; ch < numChannels_; ++ch)
            lpFilters_[ch].setCoeffs(c);
    }
 
    inline T processSample(T sample, T drive, T character, int ch) noexcept
    {
        const T low  = lpFilters_[ch].processSample(sample, 0);
        const T high = sample - low;
        const T bias = character * T(0.2);
        const T kLo  = drive * T(1.4);
        const T kHi  = drive * T(0.85);
        const T satLow  = (fastTanh((low  + bias) * kLo) - fastTanh(bias * kLo)) / T(1.4);
        const T satHigh = (fastTanh((high + bias) * kHi) - fastTanh(bias * kHi)) / T(0.85);
        return satLow + satHigh;
    }
};
 
// -- Downsample (sample rate reduction) --------------------------------------
template <typename T>
class DownsampleAlgorithm final : public SaturationAlgorithm<T>
{
    static constexpr int kMaxCh = 16;
    std::array<Biquad<T, 1>, kMaxCh> aaFilters_;
    std::array<T, kMaxCh>            lastSample_ {};
    std::array<int, kMaxCh>          counter_    {};
    int numChannels_ = 0;
    int reduction_   = 1;
 
public:
    void prepare(const AudioSpec& spec) noexcept override
    {
        numChannels_ = std::min(spec.numChannels, kMaxCh); // clamp per-channel state
        reset();
    }
    void reset() noexcept override
    {
        for (auto& f : aaFilters_) f.reset();
        lastSample_.fill(T(0));
        counter_.fill(0);
    }
    typename Saturation<T>::Algorithm getType() const noexcept override { return Saturation<T>::Algorithm::Downsample; }
 
    void update(T drive, T, const AudioSpec& spec) noexcept override
    {
        T clamped = std::clamp(drive, T(1), T(100));
        reduction_ = std::max(1, static_cast<int>(mapRange(clamped, T(1), T(100), T(1), T(50))));
        
        auto c = BiquadCoeffs::makeLowPass(spec.sampleRate, spec.sampleRate / (2.5 * reduction_), 0.707);
        for (int ch = 0; ch < numChannels_; ++ch)
            aaFilters_[ch].setCoeffs(c);
    }
 
    inline T processSample(T sample, T, T, int ch) noexcept
    {
        T filtered = aaFilters_[ch].processSample(sample, 0);
        if (++counter_[ch] >= reduction_)
        {
            counter_[ch] = 0;
            lastSample_[ch] = filtered;
        }
        return lastSample_[ch];
    }
};
 
// -- MultiStage (Tube -> Tape -> Transformer cascade) -------------------------
template <typename T>
class MultiStageAlgorithm final : public SaturationAlgorithm<T>
{
    TubeAlgorithm<T>        tube_;
    TapeAlgorithm<T>        tape_;
    TransformerAlgorithm<T> xfmr_;
 
public:
    void prepare(const AudioSpec& spec) noexcept override
    {
        tube_.prepare(spec);
        tape_.prepare(spec);
        xfmr_.prepare(spec);
    }
    void reset() noexcept override { tube_.reset(); tape_.reset(); xfmr_.reset(); }
    typename Saturation<T>::Algorithm getType() const noexcept override { return Saturation<T>::Algorithm::MultiStage; }
 
    void update(T drive, T character, const AudioSpec& spec) noexcept override
    {
        // The stages are private instances (not the pool's), so the owner's
        // setAntialiasing() never reaches them directly: forward the flag to
        // the one memoryless stage that implements ADAA.
        tube_.setAntialias(this->antialias_.load(std::memory_order_relaxed));
        tape_.update(drive * T(0.6), character, spec);
        xfmr_.update(drive * T(0.8), character, spec);
    }
 
    inline T processSample(T sample, T drive, T character, int ch) noexcept
    {
        // Inter-stage makeup undoes each stage's fixed small-signal factor
        // (1/0.5, 1/0.6) so the cascade is gain-staged: roughly transparent
        // at neutral drive instead of a flat -15 dB drop, and every stage
        // keeps receiving a healthy level.
        T tubeOut  = tube_.processSample(sample,  drive * T(0.5), character, ch) * T(2);
        T tapeOut  = tape_.processSample(tubeOut, drive * T(0.6), character, ch) * (T(1) / T(0.6));
        return       xfmr_.processSample(tapeOut, drive * T(0.8), character, ch);
    }
};
 
} // namespace detail
 
// ============================================================================
// Saturation - Public API
// ============================================================================
 
template <typename SampleType>
class Saturation
{
    static_assert(std::is_floating_point_v<SampleType>,
                  "Saturation: SampleType must be float or double.");
 
public:
    // -- Enums ---------------------------------------------------------------
 
    enum class Algorithm
    {
        Tube,        
        Tape,        
        Transformer, 
        SoftClip,    
        HardClip,    
        Exciter,     
        Wavefolder,  
        Bitcrusher,  
        Downsample,  
        MultiStage   
    };
 
    enum class ProcessingMode { Stereo, MidOnly, SideOnly, MidSide };
 
    enum class OutputMode { Normal, WetOnly, Delta };
 
    // -- Lifecycle -----------------------------------------------------------
 
    Saturation()
    {
        pool_[0]  = std::make_unique<detail::TubeAlgorithm<SampleType>>();
        pool_[1]  = std::make_unique<detail::TapeAlgorithm<SampleType>>();
        pool_[2]  = std::make_unique<detail::TransformerAlgorithm<SampleType>>();
        pool_[3]  = std::make_unique<detail::TanhAlgorithm<SampleType>>();
        pool_[4]  = std::make_unique<detail::HardClipAlgorithm<SampleType>>();
        pool_[5]  = std::make_unique<detail::ExciterAlgorithm<SampleType>>();
        pool_[6]  = std::make_unique<detail::WavefolderAlgorithm<SampleType>>();
        pool_[7]  = std::make_unique<detail::BitcrusherAlgorithm<SampleType>>();
        pool_[8]  = std::make_unique<detail::DownsampleAlgorithm<SampleType>>();
        pool_[9]  = std::make_unique<detail::MultiStageAlgorithm<SampleType>>();
 
        active_.store(pool_[static_cast<int>(Algorithm::SoftClip)].get());
        next_.store(nullptr);
    }
 
    ~Saturation() = default;
    Saturation(const Saturation&)            = delete;
    Saturation& operator=(const Saturation&) = delete;
 
    void prepare(const AudioSpec& spec)
    {
        if (!spec.isValid()) return;
        spec_ = spec;
        for (auto& algo : pool_)
            if (algo) algo->prepare(spec);
 
        preFilter_.reset();
        postFilter_.reset();
        // Order 2 at 5 Hz: the same Butterworth design this stage always used,
        // now run in the double core (see DCBlocker.h). Prepared for the full
        // channel range so it covers every channel the pipeline touches, not
        // just the first eight.
        dcBlocker_.setOrder(2);
        dcBlocker_.prepare(spec.sampleRate, DCBlocker<SampleType>::kMaxChannels, 5.0);
        
        lastPreHpFreq_    = -1.0f;
        lastPostTiltFreq_ = -1.0f;
        lastPostTiltGain_ = std::numeric_limits<float>::quiet_NaN();
        dryWetMixer_.prepare(spec);
        
        if (oversamplingFactor_ > 1 && !oversampler_)
            oversampler_ = std::make_unique<Oversampling<SampleType>>(oversamplingFactor_);
        if (oversampler_) oversampler_->prepare(spec);
 
        tempBuffer_.resize(spec.numChannels, spec.maxBlockSize * std::max(1, oversamplingFactor_));
        driftBuffer_.resize(spec.numChannels, spec.maxBlockSize * std::max(1, oversamplingFactor_));
        msKeepBuffer_.resize(1, spec.maxBlockSize * std::max(1, oversamplingFactor_));
 
        // Keep the dry path aligned with the (latent) oversampled wet path so the
        // dry/wet, Delta and adaptive-blend mixes do not comb-filter.
        dryWetMixer_.setLatencyCompensation(
            (oversampler_ && oversamplingFactor_ > 1) ? oversampler_->getLatency() : 0);
 
        auto sr = spec.sampleRate;
        driveSmoother_.reset(sr, 20.0f, 0.707f, 0.0f);
        mixSmoother_.reset(sr, 20.0f, 1.0f);
        characterSmoother_.reset(sr, 20.0f, 0.0f);
        driftSmoother_.reset(sr, 500.0f, 0.0f);
        preHpSmoother_.reset(sr, 30.0f, 0.707f, 20.0f);
        postTiltFreqSmoother_.reset(sr, 30.0f, 0.707f, 1000.0f);
        postTiltGainSmoother_.reset(sr, 30.0f, 0.0f);
        outputGainSmoother_.reset(sr, 20.0f, 0.0f);
        crossfader_.reset(sr, 10.0f, 1.0f);
 
        leftDrift_.prepare(sr);
        rightDrift_.prepare(sr);
        leftDrift_.reseed(0x9E3779B97F4A7C15ULL);
        rightDrift_.reseed(0xBF58476D1CE4E5B9ULL);
        // Smooth the random drift targets (~100 ms): without smoothing the
        // generators step once per second, modulating the drive in audible
        // jumps instead of an analog-style slow wander.
        leftDrift_.setSmoothing(true, SampleType(100));
        rightDrift_.setSmoothing(true, SampleType(100));
 
        reset();
        prepared_ = true;
    }
 
    void reset() noexcept
    {
        // Complete any pending algorithm switch instantly: every algorithm's
        // state is cleared below anyway, and after a reset the most recently
        // requested algorithm must be the one playing. (Leaving next_ armed
        // made a later request of that same algorithm a silent no-op.)
        if (auto* pending = next_.load())
        {
            active_.store(pending);
            next_.store(nullptr);
        }
 
        for (auto& algo : pool_)
            if (algo) algo->reset();
 
        preFilter_.reset();
        postFilter_.reset();
        dcBlocker_.reset();
        dryWetMixer_.reset();
        if (oversampler_) oversampler_->reset();
 
        driveSmoother_.skip();
        mixSmoother_.skip();
        characterSmoother_.skip();
        driftSmoother_.skip();
        preHpSmoother_.skip();
        postTiltFreqSmoother_.skip();
        postTiltGainSmoother_.skip();
        outputGainSmoother_.skip();
        crossfader_.setCurrentAndTargetValue(1.0f);
 
        prevBlendSample_.fill(SampleType(0));
        prevSlewSample_.fill(SampleType(0));
    }
 
    // -- Audio Processing ----------------------------------------------------
 
    void process(AudioBufferView<SampleType> buffer) noexcept { processBlock(buffer); }
 
    void processBlock(AudioBufferView<SampleType> buffer) noexcept
    {
        if (!prepared_) return;
        handleParameterChanges();
 
        dryWetMixer_.pushDry(buffer);
 
        // Pre-filter
        {
            const int numSamples = buffer.getNumSamples();
            constexpr int kCoefRefresh = 16;
            for (int i = 0; i < numSamples; i += kCoefRefresh)
            {
                const int chunk = std::min(kCoefRefresh, numSamples - i);
                float curFreq = lastPreHpFreq_;
                for (int k = 0; k < chunk; ++k)
                    curFreq = preHpSmoother_.getNextValue();
 
                if (curFreq != lastPreHpFreq_)
                {
                    auto c = BiquadCoeffs::makeHighPass(spec_.sampleRate, static_cast<double>(curFreq));
                    preFilter_.setCoeffs(c);
                    lastPreHpFreq_ = curFreq;
                }
                auto subView = buffer.getSubView(i, chunk);
                preFilter_.processBlock(subView);
            }
        }
 
        const bool isMidSide = (procMode_ == ProcessingMode::MidOnly || procMode_ == ProcessingMode::SideOnly || procMode_ == ProcessingMode::MidSide) && buffer.getNumChannels() == 2;
        if (isMidSide) MidSide<SampleType>::encode(buffer);
 
        // MidOnly / SideOnly: snapshot the channel that must stay UNPROCESSED
        // and restore it after the saturation pipeline. The snapshot lives in
        // the SAME domain the pipeline runs in (oversampled when OS is active),
        // so the restored channel shares the wet path's half-band round-trip
        // and group delay - perfectly time-aligned with the processed channel.
        // (The old in-pipeline routing read the DryWetMixer's base-rate L/R
        // capture from inside the oversampled loop: wrong domain AND an
        // out-of-bounds read, caught by AddressSanitizer.)
        const int keepChannel =
            (isMidSide && procMode_ == ProcessingMode::MidOnly)  ? 1 :
            (isMidSide && procMode_ == ProcessingMode::SideOnly) ? 0 : -1;
 
        if (oversamplingFactor_ > 1 && oversampler_)
        {
            auto upView = oversampler_->upsample(buffer);
 
            const int upSamples = std::min(upView.getNumSamples(), msKeepBuffer_.getNumSamples());
            if (keepChannel >= 0 && keepChannel < upView.getNumChannels() && upSamples > 0)
                std::memcpy(msKeepBuffer_.getChannel(0), upView.getChannel(keepChannel),
                            static_cast<std::size_t>(upSamples) * sizeof(SampleType));
 
            processSaturationPipeline(upView);
 
            if (keepChannel >= 0 && keepChannel < upView.getNumChannels() && upSamples > 0)
                std::memcpy(upView.getChannel(keepChannel), msKeepBuffer_.getChannel(0),
                            static_cast<std::size_t>(upSamples) * sizeof(SampleType));
 
            oversampler_->downsample(buffer);
        }
        else
        {
            const int baseSamples = std::min(buffer.getNumSamples(), msKeepBuffer_.getNumSamples());
            if (keepChannel >= 0 && keepChannel < buffer.getNumChannels() && baseSamples > 0)
                std::memcpy(msKeepBuffer_.getChannel(0), buffer.getChannel(keepChannel),
                            static_cast<std::size_t>(baseSamples) * sizeof(SampleType));
 
            processSaturationPipeline(buffer);
 
            if (keepChannel >= 0 && keepChannel < buffer.getNumChannels() && baseSamples > 0)
                std::memcpy(buffer.getChannel(keepChannel), msKeepBuffer_.getChannel(0),
                            static_cast<std::size_t>(baseSamples) * sizeof(SampleType));
        }
 
        if (isMidSide) MidSide<SampleType>::decode(buffer);
 
        // Program-dependent adaptive blend, applied at BASE rate in the L/R
        // domain where the latency-compensated dry capture is valid.
        if (adaptiveBlend_.load(std::memory_order_relaxed))
            applyAdaptiveBlend(buffer);
 
        // Post-filter
        {
            const int numSamples = buffer.getNumSamples();
            constexpr int kCoefRefresh = 16;
            for (int i = 0; i < numSamples; i += kCoefRefresh)
            {
                const int chunk = std::min(kCoefRefresh, numSamples - i);
                float curFreq = lastPostTiltFreq_;
                float curGain = lastPostTiltGain_;
                for (int k = 0; k < chunk; ++k)
                {
                    curFreq = postTiltFreqSmoother_.getNextValue();
                    curGain = postTiltGainSmoother_.getNextValue();
                }
 
                if (curFreq != lastPostTiltFreq_ || curGain != lastPostTiltGain_)
                {
                    // A genuine tilt shelf, as the setter documents. (This used
                    // to be makePeak: a bell AT the pivot, which mid-boosted
                    // instead of brightening/darkening.)
                    auto c = BiquadCoeffs::makeTilt(spec_.sampleRate, static_cast<double>(curFreq), static_cast<double>(curGain));
                    postFilter_.setCoeffs(c);
                    lastPostTiltFreq_ = curFreq;
                    lastPostTiltGain_ = curGain;
                }
                auto subView = buffer.getSubView(i, chunk);
                postFilter_.processBlock(subView);
            }
        }
 
        if (dcBlockingEnabled_) dcBlocker_.processBlock(buffer);
        applyOutputGain(buffer);
 
        // Mix Output
        if (outputMode_ == OutputMode::WetOnly) {} 
        else if (outputMode_ == OutputMode::Delta)
        {
            const int nCh = std::min(buffer.getNumChannels(), dryWetMixer_.getDryNumChannels());
            const int nS  = std::min(buffer.getNumSamples(), dryWetMixer_.getDryCapturedSamples());
            for (int ch = 0; ch < nCh; ++ch)
            {
                SampleType*       wet = buffer.getChannel(ch);
                const SampleType* dry = dryWetMixer_.getDryChannel(ch);
                for (int i = 0; i < nS; ++i) wet[i] -= dry[i];
            }
        }
        else 
        {
            dryWetMixer_.mixWet(buffer, static_cast<SampleType>(mixSmoother_.getTargetValue()));
        }
    }
 
    // -- Thread-Safe Setters (GUI / Automation Thread) -----------------------
 
    void setAlgorithm(Algorithm algo)       { pushParam([&](auto& p){ p.algorithm = algo; }); }
 
    void setDrive(SampleType dB)            { pushParam([&](auto& p){ p.driveDb = dB; }); }
 
    void setMix(SampleType mix01)           { pushParam([&](auto& p){ p.mix = mix01; }); }
 
    void setCharacter(SampleType c)         { pushParam([&](auto& p){ p.character = c; }); }
 
    void setProcessingMode(ProcessingMode m){ pushParam([&](auto& p){ p.processingMode = m; }); }
 
    void setOutputMode(OutputMode m)        { pushParam([&](auto& p){ p.outputMode = m; }); }
 
    void setAnalogDrift(SampleType i)       { pushParam([&](auto& p){ p.analogDrift = i; }); }
 
    void setPreFilterHpFrequency(SampleType hz) { pushParam([&](auto& p){ p.preFilterHpFreq = hz; }); }
 
    void setOutputGain(SampleType dB)       { pushParam([&](auto& p){ p.outputGain = dB; }); }
 
    void setDcBlocking(bool on)             { pushParam([&](auto& p){ p.dcBlocking = on; }); }
 
    void setAdaptiveBlend(bool on) noexcept { adaptiveBlend_.store(on, std::memory_order_relaxed); }
 
    void setAntialiasing(bool on) noexcept
    {
        antialiasShadow_.store(on, std::memory_order_relaxed);   // serialization readback
        for (auto& a : pool_) if (a) a->setAntialias(on);
    }
 
    void setSlewSensitivity(SampleType amount) noexcept
    {
        if (!std::isfinite(amount)) return;
        slewSensitivity_.store(std::clamp(amount, SampleType(0), SampleType(1)), std::memory_order_relaxed);
    }
    
    void setPostFilterTilt(SampleType centerHz, SampleType amountDb)
    {
        pushParam([&](auto& p){ p.postFilterTiltFreq = centerHz; p.postFilterTiltGain = amountDb; });
    }
 
    void setOversampling(int factor)
    {
        if (factor < 1 || (factor & (factor - 1)) != 0) return;
        oversamplingFactor_ = factor;
        if (factor > 1)
        {
            oversampler_ = std::make_unique<Oversampling<SampleType>>(factor);
            if (spec_.sampleRate > 0) oversampler_->prepare(spec_);
        }
        else
            oversampler_.reset();
 
        // If prepare() already ran, grow the scratch buffers to hold the
        // upsampled block and realign the dry path; otherwise prepare() does it.
        if (prepared_)
        {
            const int upBlock = spec_.maxBlockSize * std::max(1, oversamplingFactor_);
            if (tempBuffer_.getNumSamples() < upBlock)
                tempBuffer_.resize(spec_.numChannels, upBlock);
            if (driftBuffer_.getNumSamples() < upBlock)
                driftBuffer_.resize(spec_.numChannels, upBlock);
            if (msKeepBuffer_.getNumSamples() < upBlock)
                msKeepBuffer_.resize(1, upBlock);
 
            dryWetMixer_.setLatencyCompensation(
                (oversampler_ && oversamplingFactor_ > 1) ? oversampler_->getLatency() : 0);
        }
    }
 
    // -- Thread-Safe Getters (GUI / Metering) --------------------------------
 
    [[nodiscard]] int getOversamplingFactor() const noexcept { return oversamplingFactor_; }
 
    [[nodiscard]] int getLatency() const noexcept
    {
        return (oversampler_ && oversamplingFactor_ > 1) ? oversampler_->getLatency() : 0;
    }
 
    [[nodiscard]] int getLatencySamples() const noexcept { return getLatency(); }
 
    [[nodiscard]] Algorithm getCurrentAlgorithm() const noexcept { return currentAlgoType_.load(std::memory_order_relaxed); }
 
    [[nodiscard]] SampleType getGainReductionDb() const noexcept { return gainReductionDb_.load(std::memory_order_relaxed); }
 
 
    [[nodiscard]] std::vector<uint8_t> getState() const
    {
        Params p;
        {
            SpinLock::ScopedLock guard(paramsLock_);
            p = lastParams_;
        }
        StateWriter w(stateId("SATU"), 1);
        w.write("algorithm", static_cast<int32_t>(p.algorithm));
        w.write("procMode", static_cast<int32_t>(p.processingMode));
        w.write("outMode", static_cast<int32_t>(p.outputMode));
        w.write("drive", static_cast<float>(p.driveDb));
        w.write("mix", static_cast<float>(p.mix));
        w.write("character", static_cast<float>(p.character));
        w.write("drift", static_cast<float>(p.analogDrift));
        w.write("preHp", static_cast<float>(p.preFilterHpFreq));
        w.write("tiltFreq", static_cast<float>(p.postFilterTiltFreq));
        w.write("tiltGain", static_cast<float>(p.postFilterTiltGain));
        w.write("outputGain", static_cast<float>(p.outputGain));
        w.write("dcBlocking", p.dcBlocking);
        w.write("antialias", antialiasShadow_.load(std::memory_order_relaxed));
        w.write("adaptiveBlend", adaptiveBlend_.load(std::memory_order_relaxed));
        w.write("slewSens", slewSensitivity_.load(std::memory_order_relaxed));
        w.write("oversampling", oversamplingFactor_);
        return w.blob();
    }
 
    bool setState(const uint8_t* data, size_t size)
    {
        StateReader r(data, size);
        if (!r.isValid() || r.processorId() != stateId("SATU")) return false;
        setAlgorithm(static_cast<Algorithm>(r.read("algorithm", 0)));
        setProcessingMode(static_cast<ProcessingMode>(r.read("procMode", 0)));
        setOutputMode(static_cast<OutputMode>(r.read("outMode", 0)));
        setDrive(static_cast<SampleType>(r.read("drive", 0.0f)));
        setMix(static_cast<SampleType>(r.read("mix", 1.0f)));
        setCharacter(static_cast<SampleType>(r.read("character", 0.0f)));
        setAnalogDrift(static_cast<SampleType>(r.read("drift", 0.0f)));
        setPreFilterHpFrequency(static_cast<SampleType>(r.read("preHp", 20.0f)));
        setPostFilterTilt(static_cast<SampleType>(r.read("tiltFreq", 1000.0f)),
                          static_cast<SampleType>(r.read("tiltGain", 0.0f)));
        setOutputGain(static_cast<SampleType>(r.read("outputGain", 0.0f)));
        setDcBlocking(r.read("dcBlocking", true));
        setAntialiasing(r.read("antialias", false));
        setAdaptiveBlend(r.read("adaptiveBlend", false));
        setSlewSensitivity(static_cast<SampleType>(r.read("slewSens", 0.0f)));
        setOversampling(r.read("oversampling", 1));
        return true;
    }
 
protected:
    struct Params
    {
        Algorithm      algorithm      = Algorithm::SoftClip;
        ProcessingMode processingMode = ProcessingMode::Stereo;
        OutputMode     outputMode     = OutputMode::Normal;
        SampleType     driveDb        = SampleType(0);
        SampleType     mix            = SampleType(1);
        SampleType     character      = SampleType(0);
        SampleType     analogDrift    = SampleType(0);
        SampleType     preFilterHpFreq    = SampleType(20);
        SampleType     postFilterTiltFreq = SampleType(1000);
        SampleType     postFilterTiltGain = SampleType(0);
        SampleType     outputGain         = SampleType(0);
        bool           dcBlocking         = true;
    };
 
    static void sanitizeParams(Params& p, const Params& prev) noexcept
    {
        const auto keepFinite = [](SampleType& v, SampleType old) noexcept
        {
            if (!std::isfinite(v)) v = old;
        };
        keepFinite(p.driveDb,            prev.driveDb);
        keepFinite(p.mix,                prev.mix);
        keepFinite(p.character,          prev.character);
        keepFinite(p.analogDrift,        prev.analogDrift);
        keepFinite(p.preFilterHpFreq,    prev.preFilterHpFreq);
        keepFinite(p.postFilterTiltFreq, prev.postFilterTiltFreq);
        keepFinite(p.postFilterTiltGain, prev.postFilterTiltGain);
        keepFinite(p.outputGain,         prev.outputGain);
 
        const auto clampEnum = [](auto& e, int hi) noexcept
        {
            using E = std::remove_reference_t<decltype(e)>;
            e = static_cast<E>(std::clamp(static_cast<int>(e), 0, hi));
        };
        clampEnum(p.algorithm,      kNumAlgorithms - 1);
        clampEnum(p.processingMode, static_cast<int>(ProcessingMode::MidSide));
        clampEnum(p.outputMode,     static_cast<int>(OutputMode::Delta));
    }
 
    template <typename Fn>
    void pushParam(Fn&& mutate)
    {
        SpinLock::ScopedLock guard(paramsLock_);
        const Params prev = lastParams_;
        mutate(lastParams_);
        sanitizeParams(lastParams_, prev);
        if (!paramQueue_.push(lastParams_))
        {
            // Queue full (a burst of GUI edits within one audio block).
            // lastParams_ already holds the complete state, so flag the audio
            // thread to fetch it directly; without this the newest edit would
            // silently wait for the NEXT parameter change to become audible.
            paramsPending_.store(true, std::memory_order_release);
        }
    }
 
    void handleParameterChanges()
    {
        Params p;
        while (paramQueue_.pop(p))
            applyParamSnapshot(p);
 
        // Recover an edit that could not be queued. lastParams_ is always the
        // newest complete state, so applying it can never move backwards.
        if (paramsPending_.exchange(false, std::memory_order_acquire))
        {
            SpinLock::ScopedTryLock guard(paramsLock_);
            if (guard.isLocked())
                applyParamSnapshot(lastParams_);
            else
                paramsPending_.store(true, std::memory_order_release); // retry next block
        }
    }
 
    void applyParamSnapshot(const Params& p)
    {
        driveSmoother_.setTargetValue(std::clamp(static_cast<float>(p.driveDb), -24.0f, 48.0f));
        mixSmoother_.setTargetValue(std::clamp(static_cast<float>(p.mix), 0.0f, 1.0f));
        characterSmoother_.setTargetValue(std::clamp(static_cast<float>(p.character), -1.0f, 1.0f));
        driftSmoother_.setTargetValue(std::clamp(static_cast<float>(p.analogDrift), 0.0f, 1.0f));
        outputGainSmoother_.setTargetValue(static_cast<float>(p.outputGain));
 
        float nyquist = static_cast<float>(spec_.sampleRate) / 2.0f;
        preHpSmoother_.setTargetValue(std::clamp(static_cast<float>(p.preFilterHpFreq), 10.0f, nyquist));
        postTiltFreqSmoother_.setTargetValue(std::clamp(static_cast<float>(p.postFilterTiltFreq), 100.0f, nyquist));
        postTiltGainSmoother_.setTargetValue(std::clamp(static_cast<float>(p.postFilterTiltGain), -12.0f, 12.0f));
 
        dcBlockingEnabled_ = p.dcBlocking;
        procMode_   = p.processingMode;
        outputMode_ = p.outputMode;
        currentAlgoType_.store(p.algorithm, std::memory_order_relaxed);
 
        // Algorithm switching state machine. The crossfader fades active_ out
        // towards next_ (1 -> 0); processSaturationPipeline resolves the end
        // of the fade by its final value (0 = promote next_, 1 = discard it).
        auto* requested = pool_[static_cast<int>(p.algorithm)].get();
        auto* act = active_.load();
        auto* nxt = next_.load();
        if (requested == act)
        {
            // Return to the algorithm still playing: steer any running fade
            // back to 1 so the pending algorithm is discarded when it lands.
            // (Ignoring this case made a quick B-then-back-to-A edit complete
            // the fade to B: the wrong algorithm played forever while
            // getCurrentAlgorithm() reported A.)
            if (nxt != nullptr)
            {
                crossfader_.setTargetValue(1.0f);
                if (!crossfader_.isSmoothing())
                {
                    // The fade had not moved yet (still at 1): discard now, or
                    // the un-smoothing crossfader would leave nxt armed and a
                    // later reset() would wrongly promote it.
                    nxt->reset();
                    next_.store(nullptr);
                }
            }
        }
        else if (requested == nxt)
        {
            // Re-request of the incoming algorithm (e.g. after a revert
            // started): make sure the fade heads towards it again.
            crossfader_.setTargetValue(0.0f);
        }
        else
        {
            // New target. It has not been audible for a while, so clear its
            // state: stale filter/ADAA history would leak an old-signal
            // transient into the fade-in. If a fade was already running, its
            // pending algorithm is simply replaced (one fade-weighted step,
            // bounded like a hard switch; the abandoned one is re-cleared
            // here whenever it is next requested).
            requested->reset();
            next_.store(requested);
            crossfader_.setTargetValue(0.0f);
        }
    }
 
    // Data-Oriented Pipeline to eliminate per-sample virtual dispatch
    void processSaturationPipeline(AudioBufferView<SampleType> buffer) noexcept
    {
        auto* primary   = active_.load();
        auto* secondary = next_.load();
        bool  xfading   = secondary != nullptr && crossfader_.isSmoothing();
 
        // Clamp to per-channel state capacity (prevSlewSample_/prevBlendSample_
        // are kMaxCh) AND to the prepared channel count: driftBuffer_ and
        // tempBuffer_ only hold spec_.numChannels channels, so a caller view
        // with more channels used to read/write past them (out of bounds in
        // release) as soon as drift or an algorithm crossfade was active.
        // Channels beyond the prepared spec now bypass the saturation stage.
        const int nCh = std::min({ buffer.getNumChannels(), kMaxCh, spec_.numChannels });
        const int nS  = buffer.getNumSamples();
 
        auto driveDbTarget = static_cast<SampleType>(driveSmoother_.getTargetValue());
        auto driveGainTarget = decibelsToGain(driveDbTarget);
        auto characterTarget = static_cast<SampleType>(characterSmoother_.getTargetValue());
 
        AudioSpec updateSpec = spec_;
        if (oversamplingFactor_ > 1) updateSpec.sampleRate *= oversamplingFactor_;
 
        if (primary)   primary->update(driveGainTarget, characterTarget, updateSpec);
        if (secondary) secondary->update(driveGainTarget, characterTarget, updateSpec);
 
        SampleType peakInOriginal = SampleType(0);
        for (int ch = 0; ch < nCh; ++ch) {
            const SampleType* d = buffer.getChannel(ch);
            for (int i = 0; i < nS; ++i) peakInOriginal = std::max(peakInOriginal, std::abs(d[i]));
        }
 
        // 1. Slew (In-place)
        auto slewAmt = slewSensitivity_.load(std::memory_order_relaxed);
        if (slewAmt > SampleType(0))
        {
            for (int ch = 0; ch < nCh; ++ch) {
                SampleType* data = buffer.getChannel(ch);
                for (int i = 0; i < nS; ++i) {
                    SampleType dry = data[i];
                    SampleType delta = dry - prevSlewSample_[ch];
                    data[i] += std::tanh(std::abs(delta)) * slewAmt * dry;
                    prevSlewSample_[ch] = dry;
                }
            }
        }
 
        // 2. Pre-generate Drift
        auto driftIntensity = driftSmoother_.getTargetValue();
        bool useDrift = driftIntensity > 0.01f;
        if (useDrift)
        {
            auto driftView = driftBuffer_.toView();
            for (int i = 0; i < nS; ++i) {
                auto driftS = driftSmoother_.getNextValue();
                // Exactly one draw per generator per sample (stereo-identical
                // to drawing inside the channel loop). Channels beyond the
                // second share the right generator's value; drawing per
                // channel instead advanced its clock nCh-1 times per sample,
                // speeding the wander up with the channel count.
                const SampleType noiseL = leftDrift_.getNextSample();
                const SampleType noiseR = (nCh > 1) ? rightDrift_.getNextSample() : SampleType(0);
                for (int ch = 0; ch < nCh; ++ch) {
                    driftView.getChannel(ch)[i] =
                        SampleType(1) + static_cast<SampleType>(driftS) * (ch == 0 ? noiseL : noiseR);
                }
            }
        }
 
        // 3. Primary Saturation (and secondary if xfade)
        if (xfading)
        {
            auto tempView = tempBuffer_.toView().getSubView(0, nS);
            for (int ch = 0; ch < nCh; ++ch)
                std::memcpy(tempView.getChannel(ch), buffer.getChannel(ch), static_cast<std::size_t>(nS) * sizeof(SampleType));
            
            dispatchSaturator(primary, buffer, useDrift);
            dispatchSaturator(secondary, tempView, useDrift);
 
            for (int i = 0; i < nS; ++i) {
                auto fade = static_cast<SampleType>(crossfader_.getNextValue());
                for (int ch = 0; ch < nCh; ++ch) {
                    SampleType* out = buffer.getChannel(ch);
                    const SampleType* alt = tempView.getChannel(ch);
                    out[i] = out[i] * fade + alt[i] * (SampleType(1) - fade);
                }
            }
 
            if (!crossfader_.isSmoothing()) {
                if (crossfader_.getCurrentValue() < 0.5f) {
                    // Fade ran to 0: the pending algorithm takes over.
                    active_.store(secondary);
                    next_.store(nullptr);
                    if (primary) primary->reset();
                } else {
                    // Reverted fade landed back on the active algorithm:
                    // discard the pending one.
                    secondary->reset();
                    next_.store(nullptr);
                }
                crossfader_.setCurrentAndTargetValue(1.0f);
            }
        }
        else
        {
            dispatchSaturator(primary, buffer, useDrift);
        }
 
        // (Adaptive blend and the MidOnly/SideOnly channel passthrough run at
        //  BASE rate in process() - see the snapshot/restore logic there.)
 
        // Gain Reduction Tracking
        SampleType peakOut = SampleType(0);
        for (int ch = 0; ch < nCh; ++ch) {
            const SampleType* d = buffer.getChannel(ch);
            for (int i = 0; i < nS; ++i) peakOut = std::max(peakOut, std::abs(d[i]));
        }
 
        SampleType peakInDriven = peakInOriginal * driveGainTarget;
        if (peakInDriven > SampleType(1e-6)) {
            SampleType ratio = std::min(peakOut / peakInDriven, SampleType(1));
            gainReductionDb_.store(gainToDecibels(ratio, SampleType(-100)), std::memory_order_relaxed);
        } else {
            gainReductionDb_.store(SampleType(0), std::memory_order_relaxed);
        }
    }
 
    void applyAdaptiveBlend(AudioBufferView<SampleType> buffer) noexcept
    {
        const int nCh = std::min({ buffer.getNumChannels(),
                                   dryWetMixer_.getDryNumChannels(), kMaxCh });
        const int nS  = std::min(buffer.getNumSamples(),
                                 dryWetMixer_.getDryCapturedSamples());
 
        for (int ch = 0; ch < nCh; ++ch)
        {
            SampleType* wetData = buffer.getChannel(ch);
            const SampleType* dryData = dryWetMixer_.getDryChannel(ch);
            for (int i = 0; i < nS; ++i)
            {
                SampleType dry = dryData[i];
                SampleType wet = wetData[i];
                SampleType avg = (std::abs(prevBlendSample_[ch]) + std::abs(dry)) * SampleType(0.5);
                SampleType apply = std::clamp(avg, SampleType(0), SampleType(1));
                wetData[i] = dry * (SampleType(1) - apply) + wet * apply;
                prevBlendSample_[ch] = dry;
            }
        }
    }
 
    // Compile-time resolver (Zero virtual dispatch in hot path)
    void dispatchSaturator(detail::SaturationAlgorithm<SampleType>* baseAlgo, AudioBufferView<SampleType> buffer, bool useDrift) noexcept
    {
        if (!baseAlgo) return;
        switch (baseAlgo->getType())
        {
            case Algorithm::Tube:        processCore(static_cast<detail::TubeAlgorithm<SampleType>*>(baseAlgo), buffer, useDrift); break;
            case Algorithm::Tape:        processCore(static_cast<detail::TapeAlgorithm<SampleType>*>(baseAlgo), buffer, useDrift); break;
            case Algorithm::Transformer: processCore(static_cast<detail::TransformerAlgorithm<SampleType>*>(baseAlgo), buffer, useDrift); break;
            case Algorithm::SoftClip:    processCore(static_cast<detail::TanhAlgorithm<SampleType>*>(baseAlgo), buffer, useDrift); break;
            case Algorithm::HardClip:    processCore(static_cast<detail::HardClipAlgorithm<SampleType>*>(baseAlgo), buffer, useDrift); break;
            case Algorithm::Exciter:     processCore(static_cast<detail::ExciterAlgorithm<SampleType>*>(baseAlgo), buffer, useDrift); break;
            case Algorithm::Wavefolder:  processCore(static_cast<detail::WavefolderAlgorithm<SampleType>*>(baseAlgo), buffer, useDrift); break;
            case Algorithm::Bitcrusher:  processCore(static_cast<detail::BitcrusherAlgorithm<SampleType>*>(baseAlgo), buffer, useDrift); break;
            case Algorithm::Downsample:  processCore(static_cast<detail::DownsampleAlgorithm<SampleType>*>(baseAlgo), buffer, useDrift); break;
            case Algorithm::MultiStage:  processCore(static_cast<detail::MultiStageAlgorithm<SampleType>*>(baseAlgo), buffer, useDrift); break;
        }
    }
 
    template <typename ExactAlgo>
    void processCore(ExactAlgo* algo, AudioBufferView<SampleType> buffer, bool useDrift) noexcept
    {
        // Same channel clamp as processSaturationPipeline: per-channel algorithm
        // state is bounded to kMaxCh and driftBuffer_ to spec_.numChannels.
        const int nCh = std::min({ buffer.getNumChannels(), kMaxCh, spec_.numChannels });
        const int nS  = buffer.getNumSamples();
        auto driftView = driftBuffer_.toView();
 
        for (int i = 0; i < nS; ++i)
        {
            auto driveGainS = decibelsToGain(static_cast<SampleType>(driveSmoother_.getNextValue()));
            auto charS      = static_cast<SampleType>(characterSmoother_.getNextValue());
 
            for (int ch = 0; ch < nCh; ++ch)
            {
                SampleType drift = useDrift ? driftView.getChannel(ch)[i] : SampleType(1);
                SampleType* data = buffer.getChannel(ch);
                data[i] = algo->processSample(data[i], driveGainS * drift, charS * drift, ch);
            }
        }
    }
 
    void applyOutputGain(AudioBufferView<SampleType> buffer) noexcept
    {
        auto targetGainDb = outputGainSmoother_.getTargetValue();
        if (std::abs(targetGainDb - outputGainSmoother_.getCurrentValue()) < 0.001f)
        {
            buffer.applyGain(decibelsToGain(static_cast<SampleType>(targetGainDb)));
        }
        else
        {
            const int nCh = buffer.getNumChannels();
            const int nS  = buffer.getNumSamples();
            for (int i = 0; i < nS; ++i)
            {
                auto gain = decibelsToGain(static_cast<SampleType>(outputGainSmoother_.getNextValue()));
                for (int ch = 0; ch < nCh; ++ch) buffer.getChannel(ch)[i] *= gain;
            }
        }
    }
 
    AudioSpec spec_ {};
    bool prepared_ = false;
 
    static constexpr int kNumAlgorithms = 10;
    std::array<std::unique_ptr<detail::SaturationAlgorithm<SampleType>>, kNumAlgorithms> pool_;
    std::atomic<detail::SaturationAlgorithm<SampleType>*> active_ { nullptr };
    std::atomic<detail::SaturationAlgorithm<SampleType>*> next_   { nullptr };
 
    SpscQueue<Params>  paramQueue_;
    Params             lastParams_;
    mutable SpinLock   paramsLock_;
    std::atomic<bool>  paramsPending_ { false }; // set when a full queue dropped a snapshot
    std::atomic<bool>  antialiasShadow_ { false };  
 
    ProcessingMode procMode_   = ProcessingMode::Stereo;
    OutputMode     outputMode_ = OutputMode::Normal;
    bool           dcBlockingEnabled_ = true;
    std::atomic<Algorithm> currentAlgoType_ { Algorithm::SoftClip };
 
    Smoothers::StateVariableSmoother driveSmoother_, preHpSmoother_, postTiltFreqSmoother_;
    Smoothers::LinearSmoother        mixSmoother_, characterSmoother_, driftSmoother_,
                                     outputGainSmoother_, postTiltGainSmoother_;
    Smoothers::LinearSmoother        crossfader_;
 
    Biquad<SampleType> preFilter_, postFilter_;
    // A dedicated DCBlocker, not a Biquad: a 5 Hz high-pass keeps its poles
    // 1e-4 from the unit circle, where a float biquad recursion cannot hold
    // the zero at DC (it degenerates into an integrator of its own rounding
    // error above ~96 kHz and sources the very offset it is here to remove).
    DCBlocker<SampleType> dcBlocker_;
    DryWetMixer<SampleType> dryWetMixer_;
 
    AnalogRandom::Generator<SampleType> leftDrift_, rightDrift_;
 
    AudioBuffer<SampleType> tempBuffer_;
    AudioBuffer<SampleType> driftBuffer_;
    AudioBuffer<SampleType> msKeepBuffer_;  
 
    std::unique_ptr<Oversampling<SampleType>> oversampler_;
    int oversamplingFactor_ = 2;   
 
    std::atomic<SampleType> gainReductionDb_ { SampleType(0) };
 
    std::atomic<bool> adaptiveBlend_ { false };
    static constexpr int kMaxCh = 16;
    std::array<SampleType, kMaxCh> prevBlendSample_ {};
 
    std::atomic<SampleType> slewSensitivity_ { SampleType(0) };
    std::array<SampleType, kMaxCh> prevSlewSample_ {};
 
    float lastPreHpFreq_    = -1.0f;
    float lastPostTiltFreq_ = -1.0f;
    float lastPostTiltGain_ = std::numeric_limits<float>::quiet_NaN();
};
 
} // namespace dspark