DSParkVst3.h

// DSPark - Professional Audio DSP Framework
// Copyright (c) 2026 Cristian Moresi - MIT License
 
#pragma once
 
#define DSPARK_PLUGIN_VST3_INCLUDED 1
 
#include "../DSParkPlugin.h"
 
#include "vst3_c_api.h"
 
#include <atomic>
#include <cstdint>
#include <cstring>
#include <new>
#include <thread>
#include <utility>
#include <vector>
 
#if defined(__APPLE__)
    #include <dispatch/dispatch.h>   // libSystem: no extra link flag
#elif defined(_WIN32)
// The two user32 calls the UI tick needs, declared exactly as <windows.h>
// declares them (so either include order compiles) instead of pulling the
// whole Windows header - and its macros - into every plugin translation unit.
struct HWND__;
extern "C" __declspec(dllimport) std::uintptr_t __stdcall SetTimer(
    HWND__* window, std::uintptr_t id, unsigned int milliseconds,
    void (__stdcall* callback)(HWND__*, unsigned int, std::uintptr_t, unsigned long));
extern "C" __declspec(dllimport) int __stdcall KillTimer(HWND__* window, std::uintptr_t id);
#if defined(_MSC_VER)
#pragma comment(lib, "user32.lib")
#endif
#endif
 
namespace dspark::plugin::vst3 {
 
// -- UI-thread tick ------------------------------------------------------------------
 
class UiTicker
{
public:
    using Callback = void (*)(void* context) noexcept;
 
    UiTicker() noexcept = default;
    UiTicker(const UiTicker&) = delete;
    UiTicker& operator=(const UiTicker&) = delete;
    ~UiTicker() { stop(); }
 
    bool start(Steinberg_FUnknown* hostContext, Callback callback, void* context) noexcept
    {
        if (running_.load(std::memory_order_relaxed)) return true;
        callback_ = callback;
        context_ = context;
#if defined(__APPLE__)
        (void) hostContext;
        source_ = dispatch_source_create(DISPATCH_SOURCE_TYPE_TIMER, 0, 0,
                                         dispatch_get_main_queue());
        if (source_ == nullptr) return false;
        dispatch_set_context(source_, this);
        dispatch_source_set_event_handler_f(source_, &onDispatchTick);
        dispatch_source_set_timer(source_,
                                  dispatch_time(DISPATCH_TIME_NOW,
                                                static_cast<int64_t>(kPeriodMs) * 1000000),
                                  static_cast<uint64_t>(kPeriodMs) * 1000000u,
                                  5u * 1000000u);
        dispatch_resume(source_);
#elif defined(_WIN32)
        (void) hostContext;
        timerId_ = SetTimer(nullptr, 0, kPeriodMs, &onWindowsTick);
        if (timerId_ == 0) return false;
        registry().emplace_back(timerId_, this);
#elif defined(__linux__)
        if (hostContext == nullptr) return false;
        void* loop = nullptr;
        if (hostContext->lpVtbl->queryInterface(hostContext, Steinberg_Linux_IRunLoop_iid,
                                                &loop) != Steinberg_kResultOk
            || loop == nullptr)
            return false;
        runLoop_ = static_cast<Steinberg_Linux_IRunLoop*>(loop);
        if (runLoop_->lpVtbl->registerTimer(
                runLoop_, reinterpret_cast<Steinberg_Linux_ITimerHandler*>(&timer_),
                kPeriodMs) != Steinberg_kResultOk)
        {
            reinterpret_cast<Steinberg_FUnknown*>(runLoop_)->lpVtbl->release(runLoop_);
            runLoop_ = nullptr;
            return false;
        }
#else
        (void) hostContext;
        return false;
#endif
        running_.store(true, std::memory_order_release);
        return true;
    }
 
    void stop() noexcept
    {
        if (!running_.load(std::memory_order_relaxed)) return;
        running_.store(false, std::memory_order_release);
#if defined(__APPLE__)
        // Cancel on the main queue's own thread: no handler is mid-flight,
        // and none is invoked after cancellation.
        dispatch_source_cancel(source_);
        dispatch_release(source_);
        source_ = nullptr;
#elif defined(_WIN32)
        KillTimer(nullptr, timerId_);
        auto& entries = registry();
        for (size_t i = 0; i < entries.size(); ++i)
            if (entries[i].first == timerId_)
            {
                entries.erase(entries.begin() + static_cast<std::ptrdiff_t>(i));
                break;
            }
        timerId_ = 0;
#elif defined(__linux__)
        runLoop_->lpVtbl->unregisterTimer(
            runLoop_, reinterpret_cast<Steinberg_Linux_ITimerHandler*>(&timer_));
        reinterpret_cast<Steinberg_FUnknown*>(runLoop_)->lpVtbl->release(runLoop_);
        runLoop_ = nullptr;
#endif
    }
 
    [[nodiscard]] bool running() const noexcept
    {
        return running_.load(std::memory_order_acquire);
    }
 
private:
    static constexpr unsigned int kPeriodMs = 33;
 
    void tick() noexcept
    {
        if (running_.load(std::memory_order_relaxed) && callback_ != nullptr)
            callback_(context_);
    }
 
    std::atomic<bool> running_ { false };
    Callback callback_ = nullptr;
    void* context_ = nullptr;
 
#if defined(__APPLE__)
    dispatch_source_t source_ = nullptr;
    static void onDispatchTick(void* self) { static_cast<UiTicker*>(self)->tick(); }
#elif defined(_WIN32)
    std::uintptr_t timerId_ = 0;
    // Thread timers carry no user pointer: map the id back (UI thread only).
    static std::vector<std::pair<std::uintptr_t, UiTicker*>>& registry()
    {
        static std::vector<std::pair<std::uintptr_t, UiTicker*>> entries;
        return entries;
    }
    static void __stdcall onWindowsTick(HWND__*, unsigned int, std::uintptr_t id,
                                        unsigned long)
    {
        for (const auto& entry : registry())
            if (entry.first == id)
            {
                entry.second->tick();
                return;
            }
    }
#elif defined(__linux__)
    // A minimal ITimerHandler (static lifetime: owned by this ticker).
    struct TimerObject
    {
        const Steinberg_Linux_ITimerHandlerVtbl* vtbl;
        UiTicker* owner;
    };
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE timerQuery(void* self_,
        const Steinberg_TUID iid, void** obj)
    {
        if (obj == nullptr) return Steinberg_kInvalidArgument;
        if (std::memcmp(iid, Steinberg_FUnknown_iid, sizeof(Steinberg_TUID)) == 0
            || std::memcmp(iid, Steinberg_Linux_ITimerHandler_iid,
                           sizeof(Steinberg_TUID)) == 0)
        {
            *obj = self_;
            return Steinberg_kResultOk;
        }
        *obj = nullptr;
        return Steinberg_kNoInterface;
    }
    static Steinberg_uint32 SMTG_STDMETHODCALLTYPE timerRef(void*) { return 1; }
    static void SMTG_STDMETHODCALLTYPE timerTick(void* self_)
    {
        static_cast<TimerObject*>(self_)->owner->tick();
    }
    inline static const Steinberg_Linux_ITimerHandlerVtbl kTimerVtbl = {
        &timerQuery, &timerRef, &timerRef, &timerTick
    };
    TimerObject timer_ { &kTimerVtbl, this };
    Steinberg_Linux_IRunLoop* runLoop_ = nullptr;
#endif
};
 
// -- small helpers -------------------------------------------------------------
 
inline bool tuidEqual(const Steinberg_TUID a, const Steinberg_TUID b) noexcept
{
    return std::memcmp(a, b, sizeof(Steinberg_TUID)) == 0;
}
 
inline void asciiToString128(const char* src, Steinberg_Vst_String128 dst) noexcept
{
    int i = 0;
    if (src != nullptr)
        for (; i < 127 && src[i] != '\0'; ++i)
            dst[i] = static_cast<Steinberg_char16>(static_cast<unsigned char>(src[i]));
    dst[i] = 0;
}
 
inline void copyAscii(const char* src, char* dst, size_t cap) noexcept
{
    std::snprintf(dst, cap, "%s", src ? src : "");
}
 
inline bool streamRead(Steinberg_IBStream* s, void* dst, Steinberg_int32 bytes) noexcept
{
    auto* p = static_cast<char*>(dst);
    while (bytes > 0)
    {
        Steinberg_int32 got = 0;
        if (s->lpVtbl->read(s, p, bytes, &got) != Steinberg_kResultOk || got <= 0)
            return false;
        p += got;
        bytes -= got;
    }
    return true;
}
 
inline bool streamWrite(Steinberg_IBStream* s, const void* src, Steinberg_int32 bytes) noexcept
{
    auto* p = static_cast<const char*>(src);
    while (bytes > 0)
    {
        Steinberg_int32 put = 0;
        if (s->lpVtbl->write(s, const_cast<char*>(p), bytes, &put) != Steinberg_kResultOk
            || put <= 0)
            return false;
        p += put;
        bytes -= put;
    }
    return true;
}
 
// -- the plugin object ----------------------------------------------------------
 
inline constexpr uint32_t kBypassParamId  = 0x42595053u;   // 'BYPS'
inline constexpr uint32_t kProgramParamId = 0x5052474Du;   // 'PRGM'
inline constexpr int      kBypassRampSamples = 256;
inline constexpr Steinberg_int32 kPresetProgramListId = 1;
 
// MIDI controllers travel as proxy parameters in VST3 (the IMidiMapping
// scheme): one hidden ParamID per (channel, controller). Four controllers
// cover playable MIDI: mod wheel, sustain, channel pressure, pitch bend.
inline constexpr uint32_t kMidiProxyBase = 0x4D440000u;    // 'MD' marker
inline constexpr int      kMidiProxyControllers[4] = { 1, 64, 128, 129 };
inline constexpr int      kNumMidiProxies = 16 * 4;        // channels x controllers
 
inline constexpr bool isMidiProxyId(uint32_t id) noexcept
{
    if ((id & 0xFFFF0000u) != kMidiProxyBase) return false;
    const uint32_t ctrl = id & 0xFFu;
    const uint32_t channel = (id >> 8) & 0xFFu;
    return channel < 16
        && (ctrl == 1 || ctrl == 64 || ctrl == 128 || ctrl == 129);
}
 
inline constexpr uint32_t midiProxyId(int channel, int controller) noexcept
{
    return kMidiProxyBase | (static_cast<uint32_t>(channel) << 8)
         | static_cast<uint32_t>(controller);
}
 
inline MidiEvent midiProxyToEvent(uint32_t id, double normalized, int offset) noexcept
{
    MidiEvent ev {};
    ev.channel = static_cast<uint8_t>((id >> 8) & 0x0Fu);
    ev.sampleOffset = offset;
    const uint32_t ctrl = id & 0xFFu;
    if (ctrl == 129)
    {
        ev.type = MidiEvent::Type::PitchBend;
        ev.value = static_cast<float>(normalized * 2.0 - 1.0);
    }
    else if (ctrl == 128)
    {
        ev.type = MidiEvent::Type::ChannelPressure;
        ev.value = static_cast<float>(normalized);
    }
    else
    {
        ev.type = MidiEvent::Type::ControlChange;
        ev.note = static_cast<uint8_t>(ctrl);
        ev.value = static_cast<float>(normalized);
    }
    return ev;
}
 
template <typename P>
struct Plugin
{
    static constexpr size_t kNumParams = P::parameters.size();
    static constexpr bool kIsInstrument =
        P::descriptor.category == Category::Instrument;
    static constexpr int kNumPresets = factoryPresetCountOf<P>();
    static_assert(!(kIsInstrument && HasSidechain<P>),
                  "an Instrument has no audio inputs; remove the sidechain "
                  "processBlock or use Category::Fx");
    static_assert(!kIsInstrument || HasMidi<P>,
                  "an Instrument needs handleMidiEvent (see HasMidi): it has "
                  "no audio input to process");
    static_assert(paramIdsUnique<P>(),
                  "two parameter ids share a hash32 (or collide with the "
                  "reserved PRGM/BYPS state ids): automation and state would "
                  "cross-wire. Rename one id.");
 
    // COM lenses - consecutive vtable pointers; queryInterface returns the
    // address of the matching slot. Standard layout is asserted below. The
    // last two lenses surface only for the matching capability.
    const Steinberg_Vst_IComponentVtbl*       componentVtbl;
    const Steinberg_Vst_IAudioProcessorVtbl*  processorVtbl;
    const Steinberg_Vst_IEditControllerVtbl*  controllerVtbl;
    const Steinberg_Vst_IProcessContextRequirementsVtbl* contextReqVtbl;
    const Steinberg_Vst_IUnitInfoVtbl*        unitVtbl;
    const Steinberg_Vst_IMidiMappingVtbl*     midiMapVtbl;
 
    std::atomic<Steinberg_uint32> refs { 1 };
 
    P user {};
    Steinberg_Vst_ProcessSetup setup { 0, 0, 0, 48000.0 };
    bool prepared = false;
    std::atomic<int> cachedLatency { 0 };
    int  currentChannels = defaultChannelCount<P>();   // negotiated bus width
 
    std::atomic<double> shadow[kNumParams == 0 ? 1 : kNumParams] {};
    std::atomic<double> midiProxyShadow[HasMidi<P> ? kNumMidiProxies : 1] {};
    std::atomic<bool>   bypass { false };
    std::atomic<int>    currentProgram { 0 };
    float bypassMix = 0.0f;            // audio-thread crossfade state
    std::vector<float> dryL, dryR;     // pre-process copy for the bypass blend
    std::vector<float> silence;        // stand-in sidechain when not connected
    DryDelay dryDelay;                 // latency-aligned dry path of the bypass
 
    // Atomic pointer: refreshLatency() reads it from the audio thread while
    // setComponentHandler writes it from the main thread. Per the VST3
    // lifecycle the host swaps handlers only while the component is inactive,
    // so the atomic removes the formally torn read without needing a lock.
    std::atomic<Steinberg_Vst_IComponentHandler*> handler { nullptr };
 
    // restartComponent() is a UI-thread call. The thread that creates and
    // initializes the plugin is the host's UI thread; requests raised on any
    // other thread (the audio thread, when automation moves the latency)
    // wait in pendingRestart until the UI tick delivers them.
    std::atomic<std::thread::id> uiThread { std::this_thread::get_id() };
    std::atomic<Steinberg_int32> pendingRestart { 0 };
    UiTicker uiTicker;
 
    Plugin() noexcept
    {
        componentVtbl  = &kComponentVtbl;
        processorVtbl  = &kProcessorVtbl;
        controllerVtbl = &kControllerVtbl;
        contextReqVtbl = &kContextReqVtbl;
        unitVtbl       = &kUnitVtbl;
        midiMapVtbl    = &kMidiMapVtbl;
        for (size_t i = 0; i < kNumParams; ++i)
            shadow[i].store(toNormalized(P::parameters[i], P::parameters[i].defValue),
                            std::memory_order_relaxed);
    }
 
    // --- lens recovery ---------------------------------------------------------
 
    static Plugin* fromLens(void* iface, int lens) noexcept
    {
        return reinterpret_cast<Plugin*>(static_cast<char*>(iface)
                                         - static_cast<ptrdiff_t>(lens) * sizeof(void*));
    }
 
    void* lensPtr(int lens) noexcept
    {
        return reinterpret_cast<char*>(this) + static_cast<ptrdiff_t>(lens) * sizeof(void*);
    }
 
    // --- shared FUnknown --------------------------------------------------------
 
    Steinberg_tresult query(const Steinberg_TUID iid, void** obj) noexcept
    {
        if (obj == nullptr) return Steinberg_kInvalidArgument;
        *obj = nullptr;
        if (tuidEqual(iid, Steinberg_FUnknown_iid)
            || tuidEqual(iid, Steinberg_IPluginBase_iid)
            || tuidEqual(iid, Steinberg_Vst_IComponent_iid))
            *obj = lensPtr(0);
        else if (tuidEqual(iid, Steinberg_Vst_IAudioProcessor_iid))
            *obj = lensPtr(1);
        else if (tuidEqual(iid, Steinberg_Vst_IEditController_iid))
            *obj = lensPtr(2);
        else if (tuidEqual(iid, Steinberg_Vst_IProcessContextRequirements_iid))
            *obj = lensPtr(3);
        else if (kNumPresets > 0 && tuidEqual(iid, Steinberg_Vst_IUnitInfo_iid))
            *obj = lensPtr(4);
        else if (HasMidi<P> && tuidEqual(iid, Steinberg_Vst_IMidiMapping_iid))
            *obj = lensPtr(5);
        if (*obj == nullptr) return Steinberg_kNoInterface;
        refs.fetch_add(1, std::memory_order_relaxed);
        return Steinberg_kResultOk;
    }
 
    Steinberg_uint32 addRefImpl() noexcept
    {
        return refs.fetch_add(1, std::memory_order_relaxed) + 1;
    }
 
    Steinberg_uint32 releaseImpl() noexcept
    {
        const Steinberg_uint32 left = refs.fetch_sub(1, std::memory_order_acq_rel) - 1;
        if (left == 0) delete this;
        return left;
    }
 
    template <int Lens>
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sQuery(void* self_,
                                                           const Steinberg_TUID iid,
                                                           void** obj)
    { return fromLens(self_, Lens)->query(iid, obj); }
 
    template <int Lens>
    static Steinberg_uint32 SMTG_STDMETHODCALLTYPE sAddRef(void* self_)
    { return fromLens(self_, Lens)->addRefImpl(); }
 
    template <int Lens>
    static Steinberg_uint32 SMTG_STDMETHODCALLTYPE sRelease(void* self_)
    { return fromLens(self_, Lens)->releaseImpl(); }
 
    // --- parameter plumbing ------------------------------------------------------
 
    static int indexOfParamId(Steinberg_Vst_ParamID id) noexcept
    {
        for (size_t i = 0; i < kNumParams; ++i)
            if (hash32(P::parameters[i].id) == id) return static_cast<int>(i);
        return -1;
    }
 
    void applyNormalized(int index, double normalized) noexcept
    {
        // Host values are untrusted doubles: a NaN would pass both range
        // clamps, poison the shadow and reach the user's setter. Ignore it.
        if (normalized != normalized) return;
        const auto& spec = P::parameters[static_cast<size_t>(index)];
        shadow[static_cast<size_t>(index)].store(normalized, std::memory_order_relaxed);
        user.setParameter(index, static_cast<float>(toPlain(spec, normalized)));
    }
 
    void applyAllShadows() noexcept
    {
        for (size_t i = 0; i < kNumParams; ++i)
            user.setParameter(static_cast<int>(i),
                static_cast<float>(toPlain(P::parameters[i],
                                           shadow[i].load(std::memory_order_relaxed))));
    }
 
    void applyFactoryPresetIdx(int idx) noexcept
    {
        if constexpr (kNumPresets > 0)
        {
            if (idx < 0 || idx >= kNumPresets) return;
            for (size_t i = 0; i < kNumParams; ++i)
                applyNormalized(static_cast<int>(i), presetNormalized<P>(idx, i));
            currentProgram.store(idx, std::memory_order_relaxed);
        }
        else
            (void) idx;
    }
 
    static int programIndexOf(Steinberg_Vst_ParamValue normalized) noexcept
    {
        if constexpr (kNumPresets <= 0)
            return 0;
        else
            return toBoundedInt(normalized * (kNumPresets - 1) + 0.5,
                                0, kNumPresets - 1);
    }
 
    ~Plugin()
    {
        uiTicker.stop();
        if (auto* h = handler.exchange(nullptr, std::memory_order_relaxed); h != nullptr)
            reinterpret_cast<Steinberg_FUnknown*>(h)->lpVtbl->release(h);
    }
 
    void refreshLatency(Steinberg_int32 extraFlags = 0) noexcept
    {
        Steinberg_int32 flags = extraFlags;
        if constexpr (HasLatency<P>)
        {
            const int now = user.getLatency();
            if (prepared && now != cachedLatency.load(std::memory_order_relaxed))
            {
                cachedLatency.store(now, std::memory_order_relaxed);
                flags |= Steinberg_Vst_RestartFlags_kLatencyChanged;
            }
        }
        if (flags != 0) requestRestart(flags);
    }
 
    [[nodiscard]] bool onUiThread() const noexcept
    {
        return std::this_thread::get_id() == uiThread.load(std::memory_order_relaxed);
    }
 
    void requestRestart(Steinberg_int32 flags) noexcept
    {
        if (onUiThread() || !uiTicker.running())
        {
            flags |= pendingRestart.exchange(0, std::memory_order_acq_rel);
            if (auto* h = handler.load(std::memory_order_relaxed); h != nullptr)
                h->lpVtbl->restartComponent(h, flags);
            return;
        }
        pendingRestart.fetch_or(flags, std::memory_order_release);
    }
 
    void deliverPendingRestart() noexcept
    {
        if (!onUiThread()) return;
        const Steinberg_int32 flags = pendingRestart.exchange(0, std::memory_order_acq_rel);
        if (flags != 0)
            if (auto* h = handler.load(std::memory_order_relaxed); h != nullptr)
                h->lpVtbl->restartComponent(h, flags);
    }
 
    static void onUiTick(void* self) noexcept
    {
        static_cast<Plugin*>(self)->deliverPendingRestart();
    }
 
    void attachToHost(Steinberg_FUnknown* context) noexcept
    {
        uiThread.store(std::this_thread::get_id(), std::memory_order_relaxed);
        if constexpr (HasLatency<P> || kNumPresets > 0)
            uiTicker.start(context, &onUiTick, this);
        else
            (void) context;
    }
 
    void detachFromHost() noexcept
    {
        deliverPendingRestart();
        uiTicker.stop();
    }
 
    // --- block event plumbing -------------------------------------------------------
    //
    // Every host input lands in ONE timestamped stream (parameter points,
    // bypass points, note events), sorted and applied either at sub-block
    // boundaries (sample-accurate, the default) or all up front.
 
    void collectParameterChanges(Steinberg_Vst_IParameterChanges* changes,
                                 Steinberg_int32 numSamples,
                                 BlockEvent* events, int& count) noexcept
    {
        if (changes == nullptr) return;
        const Steinberg_int32 queues = changes->lpVtbl->getParameterCount(changes);
        for (Steinberg_int32 q = 0; q < queues; ++q)
        {
            Steinberg_Vst_IParamValueQueue* queue =
                changes->lpVtbl->getParameterData(changes, q);
            if (queue == nullptr) continue;
            const Steinberg_int32 points = queue->lpVtbl->getPointCount(queue);
            if (points <= 0) continue;
            const Steinberg_Vst_ParamID id = queue->lpVtbl->getParameterId(queue);
            const Steinberg_int32 first = sampleAccurateOf<P>() ? 0 : points - 1;
            for (Steinberg_int32 i = first; i < points; ++i)
            {
                Steinberg_int32 offset = 0;
                Steinberg_Vst_ParamValue value = 0.0;
                if (queue->lpVtbl->getPoint(queue, i, &offset, &value)
                    != Steinberg_kResultOk)
                    continue;
                if (offset < 0) offset = 0;
                if (numSamples > 0 && offset >= numSamples) offset = numSamples - 1;
                BlockEvent ev {};
                ev.offset = offset;
                ev.kind = id == kBypassParamId ? BlockEvent::Kind::Bypass
                                               : BlockEvent::Kind::Param;
                ev.paramId = id;
                ev.value = value;
                if (count < kMaxBlockEvents) events[count++] = ev;
                else events[kMaxBlockEvents - 1] = ev;   // overflow: keep the latest
            }
        }
    }
 
    void collectInputEvents(Steinberg_Vst_IEventList* list,
                            Steinberg_int32 numSamples,
                            BlockEvent* events, int& count) noexcept
    {
        if constexpr (HasMidi<P>)
        {
            if (list == nullptr) return;
            const Steinberg_int32 n = list->lpVtbl->getEventCount(list);
            for (Steinberg_int32 i = 0; i < n; ++i)
            {
                Steinberg_Vst_Event raw {};
                if (list->lpVtbl->getEvent(list, i, &raw) != Steinberg_kResultOk)
                    continue;
                MidiEvent midi {};
                if (raw.type == Steinberg_Vst_Event_EventTypes_kNoteOnEvent)
                {
                    midi.type = MidiEvent::Type::NoteOn;
                    midi.channel = static_cast<uint8_t>(
                        raw.Steinberg_Vst_Event_noteOn.channel & 0x0F);
                    midi.note = static_cast<uint8_t>(
                        raw.Steinberg_Vst_Event_noteOn.pitch & 0x7F);
                    midi.value = raw.Steinberg_Vst_Event_noteOn.velocity;
                }
                else if (raw.type == Steinberg_Vst_Event_EventTypes_kNoteOffEvent)
                {
                    midi.type = MidiEvent::Type::NoteOff;
                    midi.channel = static_cast<uint8_t>(
                        raw.Steinberg_Vst_Event_noteOff.channel & 0x0F);
                    midi.note = static_cast<uint8_t>(
                        raw.Steinberg_Vst_Event_noteOff.pitch & 0x7F);
                    midi.value = raw.Steinberg_Vst_Event_noteOff.velocity;
                }
                else if (raw.type == Steinberg_Vst_Event_EventTypes_kPolyPressureEvent)
                {
                    midi.type = MidiEvent::Type::PolyPressure;
                    midi.channel = static_cast<uint8_t>(
                        raw.Steinberg_Vst_Event_polyPressure.channel & 0x0F);
                    midi.note = static_cast<uint8_t>(
                        raw.Steinberg_Vst_Event_polyPressure.pitch & 0x7F);
                    midi.value = raw.Steinberg_Vst_Event_polyPressure.pressure;
                }
                else
                    continue;
                Steinberg_int32 offset = raw.sampleOffset;
                if (offset < 0) offset = 0;
                if (numSamples > 0 && offset >= numSamples) offset = numSamples - 1;
                BlockEvent ev {};
                ev.offset = offset;
                ev.kind = BlockEvent::Kind::Midi;
                ev.midi = midi;
                if (count < kMaxBlockEvents) events[count++] = ev;
                else events[kMaxBlockEvents - 1] = ev;
            }
        }
        else
        {
            (void) list;
            (void) numSamples;
            (void) events;
            (void) count;
        }
    }
 
    bool applyBlockEvent(const BlockEvent& ev, int blockStart,
                         bool& programChanged) noexcept
    {
        switch (ev.kind)
        {
        case BlockEvent::Kind::Bypass:
            bypass.store(ev.value >= 0.5, std::memory_order_relaxed);
            return false;
        case BlockEvent::Kind::Midi:
            if constexpr (HasMidi<P>)
            {
                MidiEvent midi = ev.midi;
                midi.sampleOffset = ev.offset - blockStart;
                if (midi.sampleOffset < 0) midi.sampleOffset = 0;
                user.handleMidiEvent(midi);
            }
            return false;
        case BlockEvent::Kind::Param:
        default:
            if constexpr (kNumPresets > 0)
            {
                if (ev.paramId == kProgramParamId)
                {
                    applyFactoryPresetIdx(programIndexOf(ev.value));
                    programChanged = true;
                    return true;
                }
            }
            if constexpr (HasMidi<P>)
            {
                if (isMidiProxyId(ev.paramId))
                {
                    const int slot = midiProxySlot(ev.paramId);
                    midiProxyShadow[static_cast<size_t>(slot)].store(
                        ev.value, std::memory_order_relaxed);
                    MidiEvent midi = midiProxyToEvent(ev.paramId, ev.value,
                                                      ev.offset - blockStart);
                    if (midi.sampleOffset < 0) midi.sampleOffset = 0;
                    user.handleMidiEvent(midi);
                    return false;
                }
            }
            if (const int idx = indexOfParamId(ev.paramId); idx >= 0)
            {
                applyNormalized(idx, ev.value);
                return true;
            }
            return false;
        }
    }
 
    static int midiProxySlot(uint32_t id) noexcept
    {
        const int channel = static_cast<int>((id >> 8) & 0x0Fu);
        const uint32_t ctrl = id & 0xFFu;
        const int slot = ctrl == 1 ? 0 : (ctrl == 64 ? 1 : (ctrl == 128 ? 2 : 3));
        return channel * 4 + slot;
    }
 
    // ==========================================================================
    // Lens 0 - IComponent (+ IPluginBase)
    // ==========================================================================
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sInitialize(void* self_,
                                                                Steinberg_FUnknown* context)
    {
        fromLens(self_, 0)->attachToHost(context);
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sTerminate(void* self_)
    {
        fromLens(self_, 0)->detachFromHost();
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetControllerClassId(void*, Steinberg_TUID)
    { return Steinberg_kResultFalse; }   // single component: no separate controller
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sSetIoMode(void*, Steinberg_Vst_IoMode)
    { return Steinberg_kResultOk; }
 
    static Steinberg_int32 numInputBuses() noexcept
    {
        if (kIsInstrument) return 0;
        return HasSidechain<P> ? 2 : 1;
    }
 
    static Steinberg_int32 SMTG_STDMETHODCALLTYPE sGetBusCount(void*,
        Steinberg_Vst_MediaType type, Steinberg_Vst_BusDirection dir)
    {
        if (type == Steinberg_Vst_MediaTypes_kEvent)
            return (HasMidi<P> && dir == Steinberg_Vst_BusDirections_kInput) ? 1 : 0;
        if (type != Steinberg_Vst_MediaTypes_kAudio) return 0;
        return dir == Steinberg_Vst_BusDirections_kInput ? numInputBuses() : 1;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetBusInfo(void* self_,
        Steinberg_Vst_MediaType type, Steinberg_Vst_BusDirection dir,
        Steinberg_int32 index, Steinberg_Vst_BusInfo* bus)
    {
        if (bus == nullptr) return Steinberg_kInvalidArgument;
        if (type == Steinberg_Vst_MediaTypes_kEvent)
        {
            if (!HasMidi<P> || dir != Steinberg_Vst_BusDirections_kInput
                || index != 0)
                return Steinberg_kInvalidArgument;
            bus->mediaType = Steinberg_Vst_MediaTypes_kEvent;
            bus->direction = dir;
            bus->channelCount = 16;
            bus->busType = Steinberg_Vst_BusTypes_kMain;
            bus->flags = Steinberg_Vst_BusInfo_BusFlags_kDefaultActive;
            asciiToString128("MIDI In", bus->name);
            return Steinberg_kResultOk;
        }
        const Steinberg_int32 count =
            dir == Steinberg_Vst_BusDirections_kInput ? numInputBuses() : 1;
        if (type != Steinberg_Vst_MediaTypes_kAudio || index < 0 || index >= count)
            return Steinberg_kInvalidArgument;
        bus->mediaType = Steinberg_Vst_MediaTypes_kAudio;
        bus->direction = dir;
        bus->channelCount = fromLens(self_, 0)->currentChannels;
        bus->busType = index == 0 ? Steinberg_Vst_BusTypes_kMain
                                  : Steinberg_Vst_BusTypes_kAux;
        bus->flags = Steinberg_Vst_BusInfo_BusFlags_kDefaultActive;
        asciiToString128(index == 1 ? "Sidechain"
                         : (dir == Steinberg_Vst_BusDirections_kInput ? "Input"
                                                                      : "Output"),
                         bus->name);
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetRoutingInfo(void*,
        Steinberg_Vst_RoutingInfo*, Steinberg_Vst_RoutingInfo*)
    { return Steinberg_kNotImplemented; }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sActivateBus(void*,
        Steinberg_Vst_MediaType, Steinberg_Vst_BusDirection, Steinberg_int32,
        Steinberg_TBool)
    { return Steinberg_kResultOk; }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sSetActive(void* self_, Steinberg_TBool state)
    {
        auto* p = fromLens(self_, 0);
        if (state)
        {
            const int maxBlock = p->setup.maxSamplesPerBlock > 0
                               ? p->setup.maxSamplesPerBlock : 512;
            const double sr = p->setup.sampleRate > 0.0 ? p->setup.sampleRate : 48000.0;
            dspark::AudioSpec spec { sr, maxBlock, p->currentChannels };
            p->user.prepare(spec);
            if constexpr (HasOfflineMode<P>)
                p->user.setOfflineRendering(
                    p->setup.processMode == Steinberg_Vst_ProcessModes_kOffline);
            p->applyAllShadows();
            p->dryL.assign(static_cast<size_t>(maxBlock), 0.0f);
            p->dryR.assign(static_cast<size_t>(maxBlock), 0.0f);
            if constexpr (HasSidechain<P>)
                p->silence.assign(static_cast<size_t>(maxBlock), 0.0f);
            p->bypassMix = p->bypass.load(std::memory_order_relaxed) ? 1.0f : 0.0f;
            if constexpr (HasLatency<P>)
            {
                const int latency = p->user.getLatency();
                p->cachedLatency.store(latency, std::memory_order_relaxed);
                p->dryDelay.prepare(std::max(2 * latency, kDryDelayMinCapacity), maxBlock);
            }
            p->prepared = true;
        }
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sComponentSetState(void* self_,
                                                                       Steinberg_IBStream* state)
    {
        auto* p = fromLens(self_, 0);
        if (state == nullptr) return Steinberg_kInvalidArgument;
        // Read whatever the host hands us (chunked); cap defensively at 16 MB.
        std::vector<uint8_t> blob;
        char chunk[4096];
        for (;;)
        {
            Steinberg_int32 got = 0;
            if (state->lpVtbl->read(state, chunk, static_cast<Steinberg_int32>(sizeof(chunk)),
                                    &got) != Steinberg_kResultOk || got <= 0)
                break;
            blob.insert(blob.end(), chunk, chunk + got);
            if (blob.size() > (16u << 20)) return Steinberg_kResultFalse;
        }
        double norm[kNumParams == 0 ? 1 : kNumParams];
        for (size_t i = 0; i < kNumParams; ++i)
            norm[i] = p->shadow[i].load(std::memory_order_relaxed);
        int program = -1;
        int bypassState = -1;
        if (!applyState(p->user, blob.data(), blob.size(), norm, &program,
                        &bypassState))
            return Steinberg_kResultFalse;
        for (size_t i = 0; i < kNumParams; ++i)
            p->applyNormalized(static_cast<int>(i), norm[i]);
        if (kNumPresets > 0 && program >= 0 && program < kNumPresets)
            p->currentProgram.store(program, std::memory_order_relaxed);
        if (bypassState >= 0)
            p->bypass.store(bypassState != 0, std::memory_order_relaxed);
        p->refreshLatency();   // restored state may imply a new lookahead
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sComponentGetState(void* self_,
                                                                       Steinberg_IBStream* state)
    {
        auto* p = fromLens(self_, 0);
        if (state == nullptr) return Steinberg_kInvalidArgument;
        double norm[kNumParams == 0 ? 1 : kNumParams];
        for (size_t i = 0; i < kNumParams; ++i)
            norm[i] = p->shadow[i].load(std::memory_order_relaxed);
        const std::vector<uint8_t> blob = buildState(
            p->user, norm, kNumParams,
            kNumPresets > 0 ? p->currentProgram.load(std::memory_order_relaxed) : -1,
            p->bypass.load(std::memory_order_relaxed) ? 1 : 0);
        return streamWrite(state, blob.data(), static_cast<Steinberg_int32>(blob.size()))
             ? Steinberg_kResultOk : Steinberg_kResultFalse;
    }
 
    inline static const Steinberg_Vst_IComponentVtbl kComponentVtbl = {
        &sQuery<0>, &sAddRef<0>, &sRelease<0>,
        &sInitialize, &sTerminate,
        &sGetControllerClassId, &sSetIoMode, &sGetBusCount, &sGetBusInfo,
        &sGetRoutingInfo, &sActivateBus, &sSetActive,
        &sComponentSetState, &sComponentGetState
    };
 
    // ==========================================================================
    // Lens 1 - IAudioProcessor
    // ==========================================================================
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sSetBusArrangements(void* self_,
        Steinberg_Vst_SpeakerArrangement* inputs, Steinberg_int32 numIns,
        Steinberg_Vst_SpeakerArrangement* outputs, Steinberg_int32 numOuts)
    {
        if (numIns != numInputBuses() || numOuts != 1
            || (numIns > 0 && inputs == nullptr) || outputs == nullptr)
            return Steinberg_kResultFalse;
        const Steinberg_Vst_SpeakerArrangement want = outputs[0];
        int channels = 0;
        if (want == Steinberg_Vst_SpeakerArr_kMono) channels = 1;
        else if (want == Steinberg_Vst_SpeakerArr_kStereo) channels = 2;
        if (channels == 0 || !supportsChannelCount<P>(channels))
            return Steinberg_kResultFalse;
        for (Steinberg_int32 i = 0; i < numIns; ++i)
            if (inputs[i] != want)
                return Steinberg_kResultFalse;
        fromLens(self_, 1)->currentChannels = channels;
        return Steinberg_kResultTrue;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetBusArrangement(void* self_,
        Steinberg_Vst_BusDirection dir, Steinberg_int32 index,
        Steinberg_Vst_SpeakerArrangement* arr)
    {
        const Steinberg_int32 count =
            dir == Steinberg_Vst_BusDirections_kInput ? numInputBuses() : 1;
        if (index < 0 || index >= count || arr == nullptr)
            return Steinberg_kInvalidArgument;
        *arr = fromLens(self_, 1)->currentChannels == 1
             ? Steinberg_Vst_SpeakerArr_kMono : Steinberg_Vst_SpeakerArr_kStereo;
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sCanProcessSampleSize(void*,
                                                                          Steinberg_int32 size)
    {
        return size == Steinberg_Vst_SymbolicSampleSizes_kSample32
             ? Steinberg_kResultTrue : Steinberg_kResultFalse;
    }
 
    static Steinberg_uint32 SMTG_STDMETHODCALLTYPE sGetLatencySamples(void* self_)
    {
        return static_cast<Steinberg_uint32>(
            fromLens(self_, 1)->cachedLatency.load(std::memory_order_relaxed));
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sSetupProcessing(void* self_,
        Steinberg_Vst_ProcessSetup* setup)
    {
        if (setup == nullptr) return Steinberg_kInvalidArgument;
        fromLens(self_, 1)->setup = *setup;
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sSetProcessing(void*, Steinberg_TBool)
    { return Steinberg_kResultOk; }
 
    void forwardTransport(const Steinberg_Vst_ProcessContext* ctx) noexcept
    {
        if constexpr (HasTransport<P>)
        {
            if (ctx == nullptr) return;
            TransportInfo t {};
            const Steinberg_uint32 s = ctx->state;
            t.playing  = (s & Steinberg_Vst_ProcessContext_StatesAndFlags_kPlaying) != 0;
            t.recording = (s & Steinberg_Vst_ProcessContext_StatesAndFlags_kRecording) != 0;
            t.looping  = (s & Steinberg_Vst_ProcessContext_StatesAndFlags_kCycleActive) != 0;
            if ((s & Steinberg_Vst_ProcessContext_StatesAndFlags_kTempoValid) != 0)
            {
                t.tempoBpm = ctx->tempo;
                t.tempoValid = true;
            }
            if ((s & Steinberg_Vst_ProcessContext_StatesAndFlags_kProjectTimeMusicValid) != 0)
            {
                t.ppqPosition = ctx->projectTimeMusic;
                t.positionValid = true;
            }
            if ((s & Steinberg_Vst_ProcessContext_StatesAndFlags_kBarPositionValid) != 0)
                t.barStartPpq = ctx->barPositionMusic;
            if ((s & Steinberg_Vst_ProcessContext_StatesAndFlags_kTimeSigValid) != 0)
            {
                t.timeSigNumerator = ctx->timeSigNumerator;
                t.timeSigDenominator = ctx->timeSigDenominator;
                t.timeSigValid = true;
            }
            if ((s & Steinberg_Vst_ProcessContext_StatesAndFlags_kCycleValid) != 0)
            {
                t.loopStartPpq = ctx->cycleStartMusic;
                t.loopEndPpq = ctx->cycleEndMusic;
                t.loopValid = true;
            }
            user.setTransport(t);
        }
        else
            (void) ctx;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sProcess(void* self_,
                                                             Steinberg_Vst_ProcessData* data)
    {
        auto* p = fromLens(self_, 1);
        if (data == nullptr) return Steinberg_kInvalidArgument;
 
        // FTZ/DAZ for the whole callback: DSPark processors guard their own
        // hot loops, this covers user DSP in hosts that do not set it.
        dspark::DenormalGuard denormalGuard;
 
        const Steinberg_int32 n = data->numSamples;
 
        // One timestamped stream for everything the host handed us.
        BlockEvent events[kMaxBlockEvents];
        int eventCount = 0;
        p->collectParameterChanges(data->inputParameterChanges, n, events, eventCount);
        p->collectInputEvents(data->inputEvents, n, events, eventCount);
        sortBlockEvents(events, eventCount);
 
        bool paramsChanged = false;
        bool programChanged = false;
 
        const bool canRender = n > 0
            && data->symbolicSampleSize == Steinberg_Vst_SymbolicSampleSizes_kSample32
            && data->numOutputs >= 1 && data->outputs != nullptr && p->prepared;
        if (!canRender)
        {
            // Parameter flush (n == 0) or unrenderable block: still apply
            // every event so automation/state never desynchronises.
            for (int i = 0; i < eventCount; ++i)
                paramsChanged |= p->applyBlockEvent(events[i], events[i].offset,
                                                    programChanged);
            if (paramsChanged || programChanged)
                p->refreshLatency(programChanged
                    ? Steinberg_Vst_RestartFlags_kParamValuesChanged : 0);
            if (n <= 0) return Steinberg_kResultOk;
            return data->symbolicSampleSize
                       == Steinberg_Vst_SymbolicSampleSizes_kSample32
                 ? Steinberg_kResultOk : Steinberg_kResultFalse;
        }
 
        p->forwardTransport(data->processContext);
 
        auto& outBus = data->outputs[0];
        float** out = outBus.Steinberg_Vst_AudioBusBuffers_channelBuffers32;
        if (out == nullptr || outBus.numChannels < 1) return Steinberg_kResultOk;
        const int width = p->currentChannels;
        int nCh = outBus.numChannels < width ? outBus.numChannels : width;
        while (nCh > 0 && out[nCh - 1] == nullptr) --nCh;   // degenerate hosts
        if (nCh < 1) return Steinberg_kResultOk;
 
        const bool haveIn = !kIsInstrument
            && data->numInputs >= 1 && data->inputs != nullptr
            && data->inputs[0].Steinberg_Vst_AudioBusBuffers_channelBuffers32 != nullptr
            && data->inputs[0].numChannels >= 1;
        float** in = haveIn
            ? data->inputs[0].Steinberg_Vst_AudioBusBuffers_channelBuffers32 : nullptr;
        const int inCh = haveIn ? static_cast<int>(data->inputs[0].numChannels) : 0;
 
        // Sidechain: aux bus 1, pre-allocated silence when nothing is
        // routed (same frame count, no branches user-side). Read-only.
        float* scHost[2] = { nullptr, nullptr };
        if constexpr (HasSidechain<P>)
        {
            if (data->numInputs >= 2 && data->inputs != nullptr
                && data->inputs[1].Steinberg_Vst_AudioBusBuffers_channelBuffers32
                       != nullptr)
            {
                const auto& scBus = data->inputs[1];
                float** sc = scBus.Steinberg_Vst_AudioBusBuffers_channelBuffers32;
                const int scCh = scBus.numChannels < 2 ? scBus.numChannels : 2;
                for (int ch = 0; ch < scCh; ++ch)
                    scHost[ch] = sc[ch];
                if (scCh == 1)
                    scHost[1] = sc[0];   // mono key feeds both detector ears
            }
        }
 
        // A block longer than the prepared maximum (hosts that ignore
        // maxSamplesPerBlock) runs as consecutive chunks of at most that
        // size: the user DSP never sees more frames than it prepared for.
        const int chunkMax = static_cast<int>(p->dryL.size());
        if (chunkMax < 1) return Steinberg_kResultOk;
        float* dry[2] = { p->dryL.data(), p->dryR.data() };
        int evIdx = 0;
 
        for (int c0 = 0; c0 < n; c0 += chunkMax)
        {
            const int len = n - c0 < chunkMax ? n - c0 : chunkMax;
            const int cEnd = c0 + len;
 
            // Keep the dry signal for the bypass blend, then process the
            // output buffers in place (copying input over first when
            // distinct). An instrument has no input: its output starts
            // cleared (voices ADD) and its bypass blends toward silence (the
            // dry vectors stay zero). Output channels past a narrower input
            // bus (a host that ignored the arrangement) repeat its last one.
            const size_t bytes = sizeof(float) * static_cast<size_t>(len);
            for (int ch = 0; ch < nCh; ++ch)
            {
                if (kIsInstrument)
                {
                    std::memset(out[ch] + c0, 0, bytes);
                    continue;
                }
                const float* src = out[ch];
                if (haveIn)
                {
                    const float* s = in[ch < inCh ? ch : inCh - 1];
                    if (s != nullptr) src = s;
                }
                std::memcpy(dry[ch], src + c0, bytes);
                if (out[ch] != src)
                    std::memcpy(out[ch] + c0, src + c0, bytes);
            }
            if constexpr (HasLatency<P> && !kIsInstrument)
                p->dryDelay.process(dry, nCh, len,
                                    p->cachedLatency.load(std::memory_order_relaxed));
 
            float* scChunk[2] = { nullptr, nullptr };
            if constexpr (HasSidechain<P>)
                for (int ch = 0; ch < 2; ++ch)
                    scChunk[ch] = scHost[ch] != nullptr ? scHost[ch] + c0
                                                        : p->silence.data();
 
            // Process in sub-blocks split at quantum-aligned event positions
            // (sample-accurate default); without splitting, apply the
            // chunk's events up front and run it in one call.
            auto processSegment = [&](int start, int length) noexcept {
                float* sub[2] = { out[0] + start,
                                  nCh > 1 ? out[1] + start : out[0] + start };
                dspark::AudioBufferView<float> view(sub, nCh, length);
                if constexpr (HasSidechain<P>)
                {
                    // The key view mirrors the main width (mono main, mono key).
                    float* scSub[2] = { scChunk[0] + (start - c0),
                                        scChunk[1] + (start - c0) };
                    dspark::AudioBufferView<float> scView(scSub, nCh, length);
                    p->user.processBlock(view, scView);
                }
                else
                    p->user.processBlock(view);
            };
 
            if (!sampleAccurateOf<P>())
            {
                for (; evIdx < eventCount && events[evIdx].offset < cEnd; ++evIdx)
                    paramsChanged |= p->applyBlockEvent(events[evIdx], c0, programChanged);
                processSegment(c0, len);
            }
            else
            {
                int pos = c0;
                while (pos < cEnd)
                {
                    while (evIdx < eventCount
                           && (events[evIdx].offset / kAutomationQuantum)
                                  * kAutomationQuantum <= pos)
                        paramsChanged |= p->applyBlockEvent(events[evIdx++], pos,
                                                            programChanged);
                    int next = cEnd;
                    if (evIdx < eventCount)
                    {
                        const int snapped = (events[evIdx].offset / kAutomationQuantum)
                                          * kAutomationQuantum;
                        if (snapped < next) next = snapped;
                    }
                    if (next <= pos) next = pos + kAutomationQuantum < cEnd
                                          ? pos + kAutomationQuantum : cEnd;
                    processSegment(pos, next - pos);
                    pos = next;
                }
            }
 
            // Soft bypass: short linear crossfade toward the (latency-
            // aligned) dry signal.
            const float target = p->bypass.load(std::memory_order_relaxed) ? 1.0f : 0.0f;
            if (p->bypassMix != target || target > 0.0f)
            {
                const float step = 1.0f / static_cast<float>(kBypassRampSamples);
                float mix = p->bypassMix;
                for (int i = 0; i < len; ++i)
                {
                    mix += (target > mix) ? step : ((target < mix) ? -step : 0.0f);
                    mix = mix < 0.0f ? 0.0f : (mix > 1.0f ? 1.0f : mix);
                    for (int ch = 0; ch < nCh; ++ch)
                        out[ch][c0 + i] += (dry[ch][i] - out[ch][c0 + i]) * mix;
                }
                p->bypassMix = mix;
            }
        }
        for (; evIdx < eventCount; ++evIdx)   // safety: events at block end
            paramsChanged |= p->applyBlockEvent(events[evIdx], n, programChanged);
 
        if (paramsChanged || programChanged)
            p->refreshLatency(programChanged
                ? Steinberg_Vst_RestartFlags_kParamValuesChanged : 0);
 
        outBus.silenceFlags = 0;
        return Steinberg_kResultOk;
    }
 
    static Steinberg_uint32 SMTG_STDMETHODCALLTYPE sGetTailSamples(void* self_)
    {
        auto* p = fromLens(self_, 1);
        if constexpr (HasTail<P>)
        {
            const double seconds = p->user.getTailSeconds();
            if (!(seconds > 0.0)) return 0;   // negative/NaN -> no tail
            const double samples = seconds
                * (p->setup.sampleRate > 0 ? p->setup.sampleRate : 48000.0);
            // Infinite or absurd tails map to kInfiniteTail instead of a
            // double->uint32 overflow (UB).
            if (samples >= 4294967295.0) return 0xFFFFFFFFu;
            return static_cast<Steinberg_uint32>(samples);
        }
        else
        {
            (void) p;
            return 0;
        }
    }
 
    inline static const Steinberg_Vst_IAudioProcessorVtbl kProcessorVtbl = {
        &sQuery<1>, &sAddRef<1>, &sRelease<1>,
        &sSetBusArrangements, &sGetBusArrangement, &sCanProcessSampleSize,
        &sGetLatencySamples, &sSetupProcessing, &sSetProcessing, &sProcess,
        &sGetTailSamples
    };
 
    // ==========================================================================
    // Lens 2 - IEditController (+ IPluginBase)
    // ==========================================================================
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sCtrlInitialize(void* self_,
                                                                    Steinberg_FUnknown* context)
    {
        fromLens(self_, 2)->attachToHost(context);
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sCtrlTerminate(void* self_)
    {
        fromLens(self_, 2)->detachFromHost();
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sSetComponentState(void* self_,
                                                                       Steinberg_IBStream* state)
    {
        // Single component: identical to IComponent::setState (lens offset!).
        return sComponentSetState(fromLens(self_, 2)->lensPtr(0), state);
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sCtrlSetState(void*, Steinberg_IBStream*)
    { return Steinberg_kResultOk; }   // no controller-only state
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sCtrlGetState(void*, Steinberg_IBStream*)
    { return Steinberg_kResultOk; }
 
    // Parameter index layout: [0, N) the user table, N the bypass, N+1 the
    // program change (factory presets only), then the hidden MIDI proxies.
    static constexpr Steinberg_int32 kBypassIndex =
        static_cast<Steinberg_int32>(kNumParams);
    static constexpr Steinberg_int32 kProgramIndex =
        kNumPresets > 0 ? kBypassIndex + 1 : -1;
    static constexpr Steinberg_int32 kFirstProxyIndex =
        kBypassIndex + 1 + (kNumPresets > 0 ? 1 : 0);
 
    static Steinberg_int32 SMTG_STDMETHODCALLTYPE sGetParameterCount(void*)
    {
        return kFirstProxyIndex + (HasMidi<P> ? kNumMidiProxies : 0);
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetParameterInfo(void* self_,
        Steinberg_int32 index, Steinberg_Vst_ParameterInfo* info)
    {
        (void) self_;
        if (info == nullptr || index < 0 || index >= sGetParameterCount(self_))
            return Steinberg_kInvalidArgument;
        std::memset(info, 0, sizeof(*info));
        if (index == kBypassIndex)
        {
            info->id = kBypassParamId;
            asciiToString128("Bypass", info->title);
            asciiToString128("Byp", info->shortTitle);
            info->stepCount = 1;
            info->defaultNormalizedValue = 0.0;
            info->flags = Steinberg_Vst_ParameterInfo_ParameterFlags_kCanAutomate
                        | Steinberg_Vst_ParameterInfo_ParameterFlags_kIsBypass;
            return Steinberg_kResultOk;
        }
        if (kNumPresets > 0 && index == kProgramIndex)
        {
            info->id = kProgramParamId;
            asciiToString128("Program", info->title);
            asciiToString128("Prog", info->shortTitle);
            info->stepCount = kNumPresets - 1;
            info->defaultNormalizedValue = 0.0;
            info->unitId = Steinberg_Vst_kRootUnitId;
            info->flags = Steinberg_Vst_ParameterInfo_ParameterFlags_kCanAutomate
                        | Steinberg_Vst_ParameterInfo_ParameterFlags_kIsList
                        | Steinberg_Vst_ParameterInfo_ParameterFlags_kIsProgramChange;
            return Steinberg_kResultOk;
        }
        if (HasMidi<P> && index >= kFirstProxyIndex)
        {
            // Hidden conduits for IMidiMapping: hosts write MIDI controller
            // motion into them; they never show in generic UIs.
            const int slot = index - kFirstProxyIndex;
            const int channel = slot / 4;
            const int ctrl = kMidiProxyControllers[slot % 4];
            info->id = midiProxyId(channel, ctrl);
            asciiToString128("MIDI", info->title);
            asciiToString128("MIDI", info->shortTitle);
            info->stepCount = 0;
            info->defaultNormalizedValue = ctrl == 129 ? 0.5 : 0.0;
            info->flags = Steinberg_Vst_ParameterInfo_ParameterFlags_kIsHidden;
            return Steinberg_kResultOk;
        }
        const auto& spec = P::parameters[static_cast<size_t>(index)];
        info->id = hash32(spec.id);
        asciiToString128(spec.name, info->title);
        asciiToString128(spec.name, info->shortTitle);
        asciiToString128(spec.unit, info->units);
        info->stepCount = spec.steps;
        info->defaultNormalizedValue = toNormalized(spec, spec.defValue);
        info->flags = Steinberg_Vst_ParameterInfo_ParameterFlags_kCanAutomate;
        if (spec.labels != nullptr)   // named choice: hosts offer a list
            info->flags |= Steinberg_Vst_ParameterInfo_ParameterFlags_kIsList;
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetParamStringByValue(void* self_,
        Steinberg_Vst_ParamID id, Steinberg_Vst_ParamValue normalized,
        Steinberg_Vst_String128 out)
    {
        (void) self_;
        if (out == nullptr) return Steinberg_kInvalidArgument;
        char text[64] = "";
        if (id == kBypassParamId)
            std::snprintf(text, sizeof(text), "%s", normalized >= 0.5 ? "On" : "Off");
        else if (kNumPresets > 0 && id == kProgramParamId)
        {
            if constexpr (HasFactoryPresets<P>)
            {
                const int idx = programIndexOf(normalized);
                std::snprintf(text, sizeof(text), "%s",
                              P::factoryPresets[static_cast<size_t>(idx)].name);
            }
        }
        else if (HasMidi<P> && isMidiProxyId(id))
            std::snprintf(text, sizeof(text), "%.3f", normalized);
        else
        {
            const int idx = indexOfParamId(id);
            if (idx < 0) return Steinberg_kInvalidArgument;
            const auto& spec = P::parameters[static_cast<size_t>(idx)];
            formatValue(spec, toPlain(spec, normalized), text, sizeof(text));
        }
        asciiToString128(text, out);
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetParamValueByString(void* self_,
        Steinberg_Vst_ParamID id, Steinberg_Vst_TChar* string,
        Steinberg_Vst_ParamValue* normalized)
    {
        (void) self_;
        if (string == nullptr || normalized == nullptr) return Steinberg_kInvalidArgument;
        char ascii[64];
        int i = 0;
        for (; i < 63 && string[i] != 0; ++i)
            ascii[i] = static_cast<char>(string[i]);
        ascii[i] = '\0';
        const int toggle = parseToggleText(ascii);
        if (id == kBypassParamId)
        {
            *normalized = toggle >= 0 ? toggle
                                      : (std::strtod(ascii, nullptr) >= 0.5 ? 1.0 : 0.0);
            return Steinberg_kResultOk;
        }
        if (kNumPresets > 0 && id == kProgramParamId)
        {
            if constexpr (HasFactoryPresets<P>)
            {
                for (int presetIdx = 0; presetIdx < kNumPresets; ++presetIdx)
                    if (std::strcmp(ascii,
                            P::factoryPresets[static_cast<size_t>(presetIdx)].name)
                        == 0)
                    {
                        *normalized = kNumPresets > 1
                            ? static_cast<double>(presetIdx) / (kNumPresets - 1)
                            : 0.0;
                        return Steinberg_kResultOk;
                    }
            }
            const double v = std::strtod(ascii, nullptr);
            *normalized = kNumPresets > 1 ? v / (kNumPresets - 1) : 0.0;
            return Steinberg_kResultOk;
        }
        if (HasMidi<P> && isMidiProxyId(id))
        {
            const double v = std::strtod(ascii, nullptr);
            *normalized = v < 0.0 ? 0.0 : (v > 1.0 ? 1.0 : v);
            return Steinberg_kResultOk;
        }
        const int idx = indexOfParamId(id);
        if (idx < 0) return Steinberg_kInvalidArgument;
        const Param& spec = P::parameters[static_cast<size_t>(idx)];
        double plain = 0.0;
        if (!parseValue(spec, ascii, plain)) return Steinberg_kResultFalse;
        *normalized = toNormalized(spec, plain);
        return Steinberg_kResultOk;
    }
 
    static Steinberg_Vst_ParamValue SMTG_STDMETHODCALLTYPE sNormalizedParamToPlain(void*,
        Steinberg_Vst_ParamID id, Steinberg_Vst_ParamValue normalized)
    {
        if (id == kBypassParamId) return normalized >= 0.5 ? 1.0 : 0.0;
        if (kNumPresets > 0 && id == kProgramParamId)
            return static_cast<double>(programIndexOf(normalized));
        if (HasMidi<P> && isMidiProxyId(id)) return normalized;
        const int idx = indexOfParamId(id);
        return idx < 0 ? 0.0 : toPlain(P::parameters[static_cast<size_t>(idx)], normalized);
    }
 
    static Steinberg_Vst_ParamValue SMTG_STDMETHODCALLTYPE sPlainParamToNormalized(void*,
        Steinberg_Vst_ParamID id, Steinberg_Vst_ParamValue plain)
    {
        if (id == kBypassParamId) return plain >= 0.5 ? 1.0 : 0.0;
        if (kNumPresets > 0 && id == kProgramParamId)
            return kNumPresets > 1 ? plain / (kNumPresets - 1) : 0.0;
        if (HasMidi<P> && isMidiProxyId(id)) return plain;
        const int idx = indexOfParamId(id);
        return idx < 0 ? 0.0 : toNormalized(P::parameters[static_cast<size_t>(idx)], plain);
    }
 
    static Steinberg_Vst_ParamValue SMTG_STDMETHODCALLTYPE sGetParamNormalized(void* self_,
        Steinberg_Vst_ParamID id)
    {
        auto* p = fromLens(self_, 2);
        p->deliverPendingRestart();   // hosts poll this from the UI thread
        if (id == kBypassParamId)
            return p->bypass.load(std::memory_order_relaxed) ? 1.0 : 0.0;
        if (kNumPresets > 0 && id == kProgramParamId)
            return kNumPresets > 1
                 ? static_cast<double>(p->currentProgram.load(std::memory_order_relaxed))
                       / (kNumPresets - 1)
                 : 0.0;
        if constexpr (HasMidi<P>)
        {
            if (isMidiProxyId(id))
                return p->midiProxyShadow[static_cast<size_t>(midiProxySlot(id))]
                    .load(std::memory_order_relaxed);
        }
        const int idx = indexOfParamId(id);
        return idx < 0 ? 0.0
                       : p->shadow[static_cast<size_t>(idx)].load(std::memory_order_relaxed);
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sSetParamNormalized(void* self_,
        Steinberg_Vst_ParamID id, Steinberg_Vst_ParamValue value)
    {
        auto* p = fromLens(self_, 2);
        if (id == kBypassParamId)
        {
            p->bypass.store(value >= 0.5, std::memory_order_relaxed);
            return Steinberg_kResultOk;
        }
        if (kNumPresets > 0 && id == kProgramParamId)
        {
            // A program change from the host UI: apply the preset and tell
            // the host every other parameter moved (main-thread call).
            p->applyFactoryPresetIdx(programIndexOf(value));
            p->refreshLatency(Steinberg_Vst_RestartFlags_kParamValuesChanged);
            return Steinberg_kResultOk;
        }
        if constexpr (HasMidi<P>)
        {
            // Live MIDI rides the process() queues; a main-thread write only
            // keeps the proxy shadow coherent for host round-trips.
            if (isMidiProxyId(id))
            {
                p->midiProxyShadow[static_cast<size_t>(midiProxySlot(id))]
                    .store(value, std::memory_order_relaxed);
                return Steinberg_kResultOk;
            }
        }
        const int idx = indexOfParamId(id);
        if (idx < 0) return Steinberg_kInvalidArgument;
        p->applyNormalized(idx, value);   // user setters are atomic by contract
        p->refreshLatency();
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sSetComponentHandler(void* self_,
        Steinberg_Vst_IComponentHandler* handler)
    {
        auto* p = fromLens(self_, 2);
        // Take the new reference before dropping the old one: a host that
        // re-sets the same handler must not see it released to zero first.
        if (handler != nullptr)
            reinterpret_cast<Steinberg_FUnknown*>(handler)->lpVtbl->addRef(handler);
        auto* old = p->handler.exchange(handler, std::memory_order_relaxed);
        if (old != nullptr)
            reinterpret_cast<Steinberg_FUnknown*>(old)->lpVtbl->release(old);
        p->deliverPendingRestart();
        return Steinberg_kResultOk;
    }
 
    static Steinberg_IPlugView* SMTG_STDMETHODCALLTYPE sCreateView(void* self_,
                                                                   Steinberg_FIDString name);
 
    inline static const Steinberg_Vst_IEditControllerVtbl kControllerVtbl = {
        &sQuery<2>, &sAddRef<2>, &sRelease<2>,
        &sCtrlInitialize, &sCtrlTerminate,
        &sSetComponentState, &sCtrlSetState, &sCtrlGetState,
        &sGetParameterCount, &sGetParameterInfo,
        &sGetParamStringByValue, &sGetParamValueByString,
        &sNormalizedParamToPlain, &sPlainParamToNormalized,
        &sGetParamNormalized, &sSetParamNormalized,
        &sSetComponentHandler, &sCreateView
    };
 
    // ==========================================================================
    // Lens 3 - IProcessContextRequirements
    // ==========================================================================
 
    static Steinberg_uint32 SMTG_STDMETHODCALLTYPE sGetProcessContextRequirements(void*)
    {
        if constexpr (HasTransport<P>)
            return Steinberg_Vst_IProcessContextRequirements_Flags_kNeedTempo
                 | Steinberg_Vst_IProcessContextRequirements_Flags_kNeedTransportState
                 | Steinberg_Vst_IProcessContextRequirements_Flags_kNeedProjectTimeMusic
                 | Steinberg_Vst_IProcessContextRequirements_Flags_kNeedBarPositionMusic
                 | Steinberg_Vst_IProcessContextRequirements_Flags_kNeedTimeSignature
                 | Steinberg_Vst_IProcessContextRequirements_Flags_kNeedCycleMusic;
        else
            return 0;
    }
 
    inline static const Steinberg_Vst_IProcessContextRequirementsVtbl kContextReqVtbl = {
        &sQuery<3>, &sAddRef<3>, &sRelease<3>,
        &sGetProcessContextRequirements
    };
 
    // ==========================================================================
    // Lens 4 - IUnitInfo (factory presets as a program list; surfaced by
    // queryInterface only when the class declares factoryPresets)
    // ==========================================================================
 
    static Steinberg_int32 SMTG_STDMETHODCALLTYPE sGetUnitCount(void*) { return 1; }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetUnitInfo(void*,
        Steinberg_int32 unitIndex, Steinberg_Vst_UnitInfo* info)
    {
        if (unitIndex != 0 || info == nullptr) return Steinberg_kInvalidArgument;
        std::memset(info, 0, sizeof(*info));
        info->id = Steinberg_Vst_kRootUnitId;
        info->parentUnitId = Steinberg_Vst_kNoParentUnitId;
        info->programListId = kNumPresets > 0 ? kPresetProgramListId
                                              : Steinberg_Vst_kNoProgramListId;
        asciiToString128("Root", info->name);
        return Steinberg_kResultOk;
    }
 
    static Steinberg_int32 SMTG_STDMETHODCALLTYPE sGetProgramListCount(void*)
    {
        return kNumPresets > 0 ? 1 : 0;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetProgramListInfo(void*,
        Steinberg_int32 listIndex, Steinberg_Vst_ProgramListInfo* info)
    {
        if (listIndex != 0 || info == nullptr || kNumPresets == 0)
            return Steinberg_kInvalidArgument;
        std::memset(info, 0, sizeof(*info));
        info->id = kPresetProgramListId;
        info->programCount = kNumPresets;
        asciiToString128("Factory Presets", info->name);
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetProgramName(void*,
        Steinberg_Vst_ProgramListID listId, Steinberg_int32 programIndex,
        Steinberg_Vst_String128 name)
    {
        if constexpr (HasFactoryPresets<P>)
        {
            if (listId != kPresetProgramListId || name == nullptr
                || programIndex < 0 || programIndex >= kNumPresets)
                return Steinberg_kInvalidArgument;
            asciiToString128(
                P::factoryPresets[static_cast<size_t>(programIndex)].name, name);
            return Steinberg_kResultOk;
        }
        else
        {
            (void) listId;
            (void) programIndex;
            (void) name;
            return Steinberg_kInvalidArgument;
        }
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetProgramInfo(void*,
        Steinberg_Vst_ProgramListID, Steinberg_int32, Steinberg_Vst_CString,
        Steinberg_Vst_String128)
    { return Steinberg_kResultFalse; }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sHasProgramPitchNames(void*,
        Steinberg_Vst_ProgramListID, Steinberg_int32)
    { return Steinberg_kResultFalse; }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetProgramPitchName(void*,
        Steinberg_Vst_ProgramListID, Steinberg_int32, Steinberg_int16,
        Steinberg_Vst_String128)
    { return Steinberg_kResultFalse; }
 
    static Steinberg_Vst_UnitID SMTG_STDMETHODCALLTYPE sGetSelectedUnit(void*)
    { return Steinberg_Vst_kRootUnitId; }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sSelectUnit(void*,
        Steinberg_Vst_UnitID unitId)
    { return unitId == Steinberg_Vst_kRootUnitId ? Steinberg_kResultOk
                                                 : Steinberg_kInvalidArgument; }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetUnitByBus(void*,
        Steinberg_Vst_MediaType, Steinberg_Vst_BusDirection, Steinberg_int32,
        Steinberg_int32, Steinberg_Vst_UnitID* unitId)
    {
        if (unitId == nullptr) return Steinberg_kInvalidArgument;
        *unitId = Steinberg_Vst_kRootUnitId;
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sSetUnitProgramData(void*,
        Steinberg_int32, Steinberg_int32, struct Steinberg_IBStream*)
    { return Steinberg_kNotImplemented; }
 
    inline static const Steinberg_Vst_IUnitInfoVtbl kUnitVtbl = {
        &sQuery<4>, &sAddRef<4>, &sRelease<4>,
        &sGetUnitCount, &sGetUnitInfo, &sGetProgramListCount, &sGetProgramListInfo,
        &sGetProgramName, &sGetProgramInfo, &sHasProgramPitchNames,
        &sGetProgramPitchName, &sGetSelectedUnit, &sSelectUnit, &sGetUnitByBus,
        &sSetUnitProgramData
    };
 
    // ==========================================================================
    // Lens 5 - IMidiMapping (pitch bend / mod / sustain / channel pressure
    // arrive as proxy-parameter automation; surfaced only for HasMidi)
    // ==========================================================================
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetMidiControllerAssignment(void*,
        Steinberg_int32 busIndex, Steinberg_int16 channel,
        Steinberg_Vst_CtrlNumber midiControllerNumber, Steinberg_Vst_ParamID* id)
    {
        if (!HasMidi<P> || id == nullptr || busIndex != 0
            || channel < 0 || channel >= 16)
            return Steinberg_kResultFalse;
        const int ctrl = midiControllerNumber;
        if (ctrl != 1 && ctrl != 64 && ctrl != 128 && ctrl != 129)
            return Steinberg_kResultFalse;
        *id = midiProxyId(channel, ctrl);
        return Steinberg_kResultTrue;
    }
 
    inline static const Steinberg_Vst_IMidiMappingVtbl kMidiMapVtbl = {
        &sQuery<5>, &sAddRef<5>, &sRelease<5>,
        &sGetMidiControllerAssignment
    };
};
 
// -- the editor view (WebView editor layer) ---------------------------------------
//
// Compiled only when plugin/webview/DSParkWebViewEditor.h was included before
// this header, and created only for plugin classes that declare an editor.
// Without either, createView answers nullptr and hosts show their generic UI.
 
#if defined(DSPARK_PLUGIN_WEBVIEW)
 
template <typename P>
struct View
{
    static constexpr size_t kNumParams = Plugin<P>::kNumParams;
 
    // COM lenses, same layout trick as the plugin object. The timer lens is
    // Linux-only: it receives the host IRunLoop ticks that drive GTK.
    const Steinberg_IPlugViewVtbl*                    viewVtbl;
    const Steinberg_IPlugViewContentScaleSupportVtbl* scaleVtbl;
#if defined(__linux__)
    const Steinberg_Linux_ITimerHandlerVtbl*          timerVtbl;
#endif
 
    std::atomic<Steinberg_uint32> refs { 1 };
    Plugin<P>* owner;
    Steinberg_IPlugFrame* frame = nullptr;
    webview_ui::Editor<P> editor;
    int width;                 // current physical size (host units)
    int height;
    double scale = 1.0;
    bool correctingSize = false;   // re-entrancy guard for resizeView round-trips
    bool editActive[kNumParams == 0 ? 1 : kNumParams] {};
#if defined(__linux__)
    Steinberg_Linux_IRunLoop* runLoop = nullptr;
    bool timerRegistered = false;
#endif
 
    explicit View(Plugin<P>* plugin) noexcept : owner(plugin)
    {
        viewVtbl  = &kViewVtbl;
        scaleVtbl = &kScaleVtbl;
#if defined(__linux__)
        timerVtbl = &kTimerVtbl;
#endif
        owner->addRefImpl();
        const EditorSize logical = editorSizeOf<P>();
        width  = logical.width;
        height = logical.height;
    }
 
    ~View()
    {
#if defined(__linux__)
        releaseRunLoop();
#endif
        editor.destroy();
        if (frame != nullptr)
            reinterpret_cast<Steinberg_FUnknown*>(frame)->lpVtbl->release(frame);
        owner->releaseImpl();
    }
 
#if defined(__linux__)
 
    // --- host run loop: GTK breathes only when pumped from here ---------------------
 
    void acquireRunLoop() noexcept
    {
        if (frame == nullptr || runLoop != nullptr) return;
        void* loop = nullptr;
        if (reinterpret_cast<Steinberg_FUnknown*>(frame)->lpVtbl->queryInterface(
                frame, Steinberg_Linux_IRunLoop_iid, &loop) == Steinberg_kResultOk)
            runLoop = static_cast<Steinberg_Linux_IRunLoop*>(loop);
    }
 
    void startTimer() noexcept
    {
        acquireRunLoop();
        if (runLoop != nullptr && !timerRegistered && editor.created())
            timerRegistered = runLoop->lpVtbl->registerTimer(runLoop,
                reinterpret_cast<Steinberg_Linux_ITimerHandler*>(lensPtr(2)),
                33) == Steinberg_kResultOk;
    }
 
    void stopTimer() noexcept
    {
        if (runLoop != nullptr && timerRegistered)
            runLoop->lpVtbl->unregisterTimer(runLoop,
                reinterpret_cast<Steinberg_Linux_ITimerHandler*>(lensPtr(2)));
        timerRegistered = false;
    }
 
    void releaseRunLoop() noexcept
    {
        stopTimer();
        if (runLoop != nullptr)
        {
            reinterpret_cast<Steinberg_FUnknown*>(runLoop)->lpVtbl->release(runLoop);
            runLoop = nullptr;
        }
    }
 
    static void SMTG_STDMETHODCALLTYPE sOnTimer(void* self_)
    {
        View* view = fromLens(self_, 2);
        view->editor.pump();
        view->owner->deliverPendingRestart();   // the frame's run loop ticks too
    }
 
#endif // __linux__
 
    static View* fromLens(void* iface, int lens) noexcept
    {
        return reinterpret_cast<View*>(static_cast<char*>(iface)
                                       - static_cast<ptrdiff_t>(lens) * sizeof(void*));
    }
 
    void* lensPtr(int lens) noexcept
    {
        return reinterpret_cast<char*>(this) + static_cast<ptrdiff_t>(lens) * sizeof(void*);
    }
 
    static const char* platformType() noexcept
    {
#if defined(_WIN32)
        return Steinberg_kPlatformTypeHWND;
#elif defined(__APPLE__)
        return Steinberg_kPlatformTypeNSView;
#else
        return Steinberg_kPlatformTypeX11EmbedWindowID;
#endif
    }
 
    // --- editor -> host/DSP bridge ------------------------------------------------
 
    static void cbSetParam(void* context, int index, double plain) noexcept
    {
        auto* view = static_cast<View*>(context);
        const Param& spec = P::parameters[static_cast<size_t>(index)];
        const double normalized = toNormalized(spec, plain);
        view->owner->applyNormalized(index, normalized);
        if (auto* handler = view->owner->handler.load(std::memory_order_relaxed))
        {
            const Steinberg_Vst_ParamID id = hash32(spec.id);
            if (view->editActive[static_cast<size_t>(index)])
                handler->lpVtbl->performEdit(handler, id, normalized);
            else
            {
                // Edits outside an explicit gesture still need one for host undo.
                handler->lpVtbl->beginEdit(handler, id);
                handler->lpVtbl->performEdit(handler, id, normalized);
                handler->lpVtbl->endEdit(handler, id);
            }
        }
    }
 
    static void cbBeginEdit(void* context, int index) noexcept
    {
        auto* view = static_cast<View*>(context);
        view->editActive[static_cast<size_t>(index)] = true;
        if (auto* handler = view->owner->handler.load(std::memory_order_relaxed))
            handler->lpVtbl->beginEdit(handler,
                hash32(P::parameters[static_cast<size_t>(index)].id));
    }
 
    static void cbEndEdit(void* context, int index) noexcept
    {
        auto* view = static_cast<View*>(context);
        view->editActive[static_cast<size_t>(index)] = false;
        if (auto* handler = view->owner->handler.load(std::memory_order_relaxed))
            handler->lpVtbl->endEdit(handler,
                hash32(P::parameters[static_cast<size_t>(index)].id));
    }
 
    // --- FUnknown -------------------------------------------------------------------
 
    Steinberg_tresult query(const Steinberg_TUID iid, void** obj) noexcept
    {
        if (obj == nullptr) return Steinberg_kInvalidArgument;
        *obj = nullptr;
        if (tuidEqual(iid, Steinberg_FUnknown_iid)
            || tuidEqual(iid, Steinberg_IPlugView_iid))
            *obj = lensPtr(0);
        else if (tuidEqual(iid, Steinberg_IPlugViewContentScaleSupport_iid))
            *obj = lensPtr(1);
#if defined(__linux__)
        else if (tuidEqual(iid, Steinberg_Linux_ITimerHandler_iid))
            *obj = lensPtr(2);
#endif
        if (*obj == nullptr) return Steinberg_kNoInterface;
        refs.fetch_add(1, std::memory_order_relaxed);
        return Steinberg_kResultOk;
    }
 
    template <int Lens>
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sQuery(void* self_,
                                                           const Steinberg_TUID iid,
                                                           void** obj)
    { return fromLens(self_, Lens)->query(iid, obj); }
 
    template <int Lens>
    static Steinberg_uint32 SMTG_STDMETHODCALLTYPE sAddRef(void* self_)
    { return fromLens(self_, Lens)->refs.fetch_add(1, std::memory_order_relaxed) + 1; }
 
    template <int Lens>
    static Steinberg_uint32 SMTG_STDMETHODCALLTYPE sRelease(void* self_)
    {
        auto* view = fromLens(self_, Lens);
        const Steinberg_uint32 left = view->refs.fetch_sub(1, std::memory_order_acq_rel) - 1;
        if (left == 0) delete view;
        return left;
    }
 
    // --- IPlugView --------------------------------------------------------------------
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sIsPlatformTypeSupported(void*,
        Steinberg_FIDString type)
    {
        return (webview_ui::Editor<P>::available() && type != nullptr
                && std::strcmp(type, platformType()) == 0)
             ? Steinberg_kResultTrue : Steinberg_kResultFalse;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sAttached(void* self_, void* parent,
                                                              Steinberg_FIDString type)
    {
        auto* view = fromLens(self_, 0);
        webview_ui::debugLog("vst3 attached(parent=%p type=%s) negotiated=%dx%d scale=%.2f",
                             parent, type != nullptr ? type : "?",
                             view->width, view->height, view->scale);
        if (sIsPlatformTypeSupported(self_, type) != Steinberg_kResultTrue
            || parent == nullptr)
            return Steinberg_kResultFalse;
        const webview_ui::HostCallbacks callbacks {
            view, &cbSetParam, &cbBeginEdit, &cbEndEdit
        };
        if (!view->editor.create(parent, view->owner->shadow, callbacks))
            return Steinberg_kResultFalse;
        // Fill the box the host ACTUALLY built - hosts differ in whether
        // getSize/setContentScaleFactor/attached arrive in spec order, so the
        // parent's real client size wins over the negotiated one.
        int parentW = 0, parentH = 0;
        if (view->editor.queryParentSize(parentW, parentH))
        {
            view->width  = parentW;
            view->height = parentH;
        }
        view->editor.setBounds(view->width, view->height);
        view->editor.setVisible(true);
#if defined(__linux__)
        // GTK breathes only when pumped from the host's run loop; without a
        // usable IRunLoop the page would freeze, so fall back to generic UI.
        view->startTimer();
        if (!view->timerRegistered)
        {
            webview_ui::debugLog("vst3 attached: no usable IRunLoop -> no editor");
            view->editor.destroy();
            return Steinberg_kResultFalse;
        }
#endif
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sRemoved(void* self_)
    {
        auto* view = fromLens(self_, 0);
#if defined(__linux__)
        view->stopTimer();
#endif
        view->editor.destroy();
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sOnWheel(void*, float)
    { return Steinberg_kResultFalse; }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sOnKeyDown(void*, Steinberg_char16,
                                                               Steinberg_int16, Steinberg_int16)
    { return Steinberg_kResultFalse; }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sOnKeyUp(void*, Steinberg_char16,
                                                             Steinberg_int16, Steinberg_int16)
    { return Steinberg_kResultFalse; }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetSize(void* self_,
                                                             Steinberg_ViewRect* size)
    {
        auto* view = fromLens(self_, 0);
        if (size == nullptr) return Steinberg_kInvalidArgument;
        size->left = 0;
        size->top = 0;
        size->right = view->width;
        size->bottom = view->height;
        webview_ui::debugLog("vst3 getSize -> %dx%d", view->width, view->height);
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sOnSize(void* self_,
                                                            Steinberg_ViewRect* newSize)
    {
        auto* view = fromLens(self_, 0);
        if (newSize == nullptr) return Steinberg_kInvalidArgument;
        const double proposedW = newSize->right - newSize->left;
        const double proposedH = newSize->bottom - newSize->top;
        double w = proposedW;
        double h = proposedH;
        // Enforce the resize policy HERE, not only in checkSizeConstraint:
        // some hosts drag-resize freely and only report the result. When the
        // host overshot, apply the constrained size and ask it to follow.
        if (!view->correctingSize)
            constrainEditorSize<P>(w, h, view->scale);
        webview_ui::debugLog("vst3 onSize %.0fx%.0f -> %.0fx%.0f%s",
                             proposedW, proposedH, w, h,
                             view->correctingSize ? " (correction round-trip)" : "");
        view->width  = toBoundedInt(w + 0.5, 1, static_cast<int>(kEditorMaxPixels));
        view->height = toBoundedInt(h + 0.5, 1, static_cast<int>(kEditorMaxPixels));
        view->editor.setBounds(view->width, view->height);
        if (!view->correctingSize && view->frame != nullptr
            && (view->width - proposedW > 1.0 || proposedW - view->width > 1.0
                || view->height - proposedH > 1.0 || proposedH - view->height > 1.0))
        {
            view->correctingSize = true;
            Steinberg_ViewRect corrected { 0, 0, view->width, view->height };
            view->frame->lpVtbl->resizeView(view->frame,
                reinterpret_cast<Steinberg_IPlugView*>(view->lensPtr(0)), &corrected);
            view->correctingSize = false;
        }
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sOnFocus(void*, Steinberg_TBool)
    { return Steinberg_kResultOk; }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sSetFrame(void* self_,
                                                              Steinberg_IPlugFrame* frame)
    {
        auto* view = fromLens(self_, 0);
#if defined(__linux__)
        view->releaseRunLoop();   // the run loop belongs to the old frame
#endif
        if (view->frame != nullptr)
            reinterpret_cast<Steinberg_FUnknown*>(view->frame)
                ->lpVtbl->release(view->frame);
        view->frame = frame;
        if (view->frame != nullptr)
            reinterpret_cast<Steinberg_FUnknown*>(view->frame)
                ->lpVtbl->addRef(view->frame);
#if defined(__linux__)
        if (view->editor.created())
            view->startTimer();   // frame arrived after attach (rare order)
#endif
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sCanResize(void*)
    {
        return editorResizeOf<P>() != EditorResize::Fixed ? Steinberg_kResultTrue
                                                          : Steinberg_kResultFalse;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sCheckSizeConstraint(void* self_,
        Steinberg_ViewRect* rect)
    {
        auto* view = fromLens(self_, 0);
        if (rect == nullptr) return Steinberg_kInvalidArgument;
        const double proposedW = rect->right - rect->left;
        const double proposedH = rect->bottom - rect->top;
        double w = proposedW;
        double h = proposedH;
        constrainEditorSize<P>(w, h, view->scale);
        rect->right  = rect->left
                     + toBoundedInt(w + 0.5, 1, static_cast<int>(kEditorMaxPixels));
        rect->bottom = rect->top
                     + toBoundedInt(h + 0.5, 1, static_cast<int>(kEditorMaxPixels));
        webview_ui::debugLog("vst3 checkSizeConstraint %.0fx%.0f -> %.0fx%.0f",
                             proposedW, proposedH, w, h);
        return Steinberg_kResultTrue;
    }
 
    inline static const Steinberg_IPlugViewVtbl kViewVtbl = {
        &sQuery<0>, &sAddRef<0>, &sRelease<0>,
        &sIsPlatformTypeSupported, &sAttached, &sRemoved,
        &sOnWheel, &sOnKeyDown, &sOnKeyUp,
        &sGetSize, &sOnSize, &sOnFocus,
        &sSetFrame, &sCanResize, &sCheckSizeConstraint
    };
 
    // --- IPlugViewContentScaleSupport ----------------------------------------------
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sSetContentScaleFactor(void* self_,
        Steinberg_IPlugViewContentScaleSupport_ScaleFactor factor)
    {
        auto* view = fromLens(self_, 1);
        if (!(factor > 0.0f)) return Steinberg_kInvalidArgument;   // NaN included
        const double previous = view->scale;
        view->scale = factor;
        webview_ui::debugLog("vst3 setContentScaleFactor %.2f (was %.2f)",
                             view->scale, previous);
        // Rescale the negotiated physical size (the page itself never zooms:
        // the web engine applies the window DPI to CSS pixels on its own).
        view->width  = toBoundedInt(view->width * (view->scale / previous) + 0.5,
                                    1, static_cast<int>(kEditorMaxPixels));
        view->height = toBoundedInt(view->height * (view->scale / previous) + 0.5,
                                    1, static_cast<int>(kEditorMaxPixels));
        if (view->editor.created() && view->frame != nullptr)
        {
            // Already on screen (e.g. dragged to another monitor): ask the
            // host to rebuild the window at the new physical size.
            Steinberg_ViewRect rect { 0, 0, view->width, view->height };
            view->frame->lpVtbl->resizeView(view->frame,
                reinterpret_cast<Steinberg_IPlugView*>(view->lensPtr(0)), &rect);
        }
        return Steinberg_kResultOk;
    }
 
    inline static const Steinberg_IPlugViewContentScaleSupportVtbl kScaleVtbl = {
        &sQuery<1>, &sAddRef<1>, &sRelease<1>,
        &sSetContentScaleFactor
    };
 
#if defined(__linux__)
    // Defined after the FUnknown thunks: a static member INITIALIZER has no
    // complete-class context, so every name it uses must be declared above.
    inline static const Steinberg_Linux_ITimerHandlerVtbl kTimerVtbl = {
        &sQuery<2>, &sAddRef<2>, &sRelease<2>, &sOnTimer
    };
#endif
};
 
#endif // DSPARK_PLUGIN_WEBVIEW
 
template <typename P>
Steinberg_IPlugView* SMTG_STDMETHODCALLTYPE Plugin<P>::sCreateView(void* self_,
                                                                   Steinberg_FIDString name)
{
    (void) self_;
    (void) name;
#if defined(DSPARK_PLUGIN_WEBVIEW)
    if constexpr (HasEditor<P>)
    {
        if (webview_ui::Editor<P>::available() && name != nullptr
            && std::strcmp(name, "editor") == 0)
        {
            auto* view = new (std::nothrow) View<P>(fromLens(self_, 2));
            if (view != nullptr)
                return reinterpret_cast<Steinberg_IPlugView*>(view->lensPtr(0));
        }
    }
#endif
    return nullptr;   // no editor: the host shows its generic parameter UI
}
 
// -- factory --------------------------------------------------------------------
 
template <typename P>
struct Factory
{
    const Steinberg_IPluginFactory3Vtbl* vtbl;
 
    Factory() noexcept { vtbl = &kVtbl; }
 
    static std::array<uint8_t, 16> classUid() noexcept
    {
        return makeUid(P::descriptor.productId, 0x56535433ull);   // 'VST3'
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sQuery(void* self_,
        const Steinberg_TUID iid, void** obj)
    {
        if (obj == nullptr) return Steinberg_kInvalidArgument;
        if (tuidEqual(iid, Steinberg_FUnknown_iid)
            || tuidEqual(iid, Steinberg_IPluginFactory_iid)
            || tuidEqual(iid, Steinberg_IPluginFactory2_iid)
            || tuidEqual(iid, Steinberg_IPluginFactory3_iid))
        {
            *obj = self_;
            return Steinberg_kResultOk;
        }
        *obj = nullptr;
        return Steinberg_kNoInterface;
    }
 
    static Steinberg_uint32 SMTG_STDMETHODCALLTYPE sAddRef(void*)  { return 100; }
    static Steinberg_uint32 SMTG_STDMETHODCALLTYPE sRelease(void*) { return 100; }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetFactoryInfo(void*,
        Steinberg_PFactoryInfo* info)
    {
        if (info == nullptr) return Steinberg_kInvalidArgument;
        std::memset(info, 0, sizeof(*info));
        copyAscii(P::descriptor.vendor, info->vendor, sizeof(info->vendor));
        copyAscii(P::descriptor.url, info->url, sizeof(info->url));
        copyAscii(P::descriptor.email, info->email, sizeof(info->email));
        info->flags = Steinberg_PFactoryInfo_FactoryFlags_kUnicode;
        return Steinberg_kResultOk;
    }
 
    static Steinberg_int32 SMTG_STDMETHODCALLTYPE sCountClasses(void*) { return 1; }
 
    static void fillClassCommon(Steinberg_TUID cid) noexcept
    {
        const auto uid = classUid();
        std::memcpy(cid, uid.data(), 16);
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetClassInfo(void*,
        Steinberg_int32 index, Steinberg_PClassInfo* info)
    {
        if (index != 0 || info == nullptr) return Steinberg_kInvalidArgument;
        std::memset(info, 0, sizeof(*info));
        fillClassCommon(info->cid);
        info->cardinality = 0x7FFFFFFF;   // kManyInstances
        copyAscii("Audio Module Class", info->category, sizeof(info->category));
        copyAscii(P::descriptor.name, info->name, sizeof(info->name));
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetClassInfo2(void*,
        Steinberg_int32 index, Steinberg_PClassInfo2* info)
    {
        if (index != 0 || info == nullptr) return Steinberg_kInvalidArgument;
        std::memset(info, 0, sizeof(*info));
        fillClassCommon(info->cid);
        info->cardinality = 0x7FFFFFFF;
        copyAscii("Audio Module Class", info->category, sizeof(info->category));
        copyAscii(P::descriptor.name, info->name, sizeof(info->name));
        info->classFlags = 0;
        copyAscii(P::descriptor.category == Category::Instrument ? "Instrument" : "Fx",
                  info->subCategories, sizeof(info->subCategories));
        copyAscii(P::descriptor.vendor, info->vendor, sizeof(info->vendor));
        copyAscii(P::descriptor.version, info->version, sizeof(info->version));
        copyAscii("VST 3.7.9", info->sdkVersion, sizeof(info->sdkVersion));
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sGetClassInfoUnicode(void*,
        Steinberg_int32 index, Steinberg_PClassInfoW* info)
    {
        if (index != 0 || info == nullptr) return Steinberg_kInvalidArgument;
        std::memset(info, 0, sizeof(*info));
        fillClassCommon(info->cid);
        info->cardinality = 0x7FFFFFFF;
        copyAscii("Audio Module Class", info->category, sizeof(info->category));
        asciiToString128(P::descriptor.name, info->name);
        info->classFlags = 0;
        copyAscii(P::descriptor.category == Category::Instrument ? "Instrument" : "Fx",
                  info->subCategories, sizeof(info->subCategories));
        asciiToString128(P::descriptor.vendor, info->vendor);
        asciiToString128(P::descriptor.version, info->version);
        asciiToString128("VST 3.7.9", info->sdkVersion);
        return Steinberg_kResultOk;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sCreateInstance(void*,
        Steinberg_FIDString cid, Steinberg_FIDString iid, void** obj)
    {
        if (cid == nullptr || iid == nullptr || obj == nullptr)
            return Steinberg_kInvalidArgument;
        *obj = nullptr;
        const auto uid = classUid();
        if (std::memcmp(cid, uid.data(), 16) != 0)
            return Steinberg_kNoInterface;
 
        auto* plugin = new (std::nothrow) Plugin<P>();
        if (plugin == nullptr) return Steinberg_kResultFalse;
 
        Steinberg_TUID requested;
        std::memcpy(requested, iid, sizeof(requested));
        const Steinberg_tresult r = plugin->query(requested, obj);
        plugin->releaseImpl();   // drop the construction reference
        return r == Steinberg_kResultOk ? Steinberg_kResultOk : Steinberg_kNoInterface;
    }
 
    static Steinberg_tresult SMTG_STDMETHODCALLTYPE sSetHostContext(void*, Steinberg_FUnknown*)
    { return Steinberg_kResultOk; }
 
    inline static const Steinberg_IPluginFactory3Vtbl kVtbl = {
        &sQuery, &sAddRef, &sRelease,
        &sGetFactoryInfo, &sCountClasses, &sGetClassInfo, &sCreateInstance,
        &sGetClassInfo2,
        &sGetClassInfoUnicode, &sSetHostContext
    };
};
 
} // namespace dspark::plugin::vst3
 
// -- module entry ----------------------------------------------------------------
 
#if defined(_WIN32)
#define DSPARK_VST3_EXPORT __declspec(dllexport)
#else
#define DSPARK_VST3_EXPORT __attribute__((visibility("default")))
#endif
 
#define DSPARK_VST3_PLUGIN(PluginClass)                                            \
    static dspark::plugin::vst3::Factory<PluginClass> gDsparkVst3Factory;          \
    extern "C" {                                                                   \
    DSPARK_VST3_EXPORT Steinberg_IPluginFactory* SMTG_STDMETHODCALLTYPE            \
    GetPluginFactory()                                                             \
    {                                                                              \
        return reinterpret_cast<Steinberg_IPluginFactory*>(&gDsparkVst3Factory);   \
    }                                                                              \
    DSPARK_VST3_EXPORT bool InitDll() { return true; }                             \
    DSPARK_VST3_EXPORT bool ExitDll() { return true; }                             \
    DSPARK_VST3_EXPORT bool ModuleEntry(void*) { return true; }                    \
    DSPARK_VST3_EXPORT bool ModuleExit() { return true; }                          \
    DSPARK_VST3_EXPORT bool bundleEntry(void*) { return true; }                    \
    DSPARK_VST3_EXPORT bool bundleExit() { return true; }                          \
    }