TrackMapEditor.h

// Super Timecode Converter
// Copyright (c) 2026 Fiverecords -- MIT License
// https://github.com/fiverecords/SuperTimecodeConverter

#pragma once
#include <JuceHeader.h>
#include "AppSettings.h"
#include "ProDJLinkInput.h"
#include "DbServerClient.h"
#include "CuePointEditor.h"
#include "CustomLookAndFeel.h"

//==============================================================================
// TrackMapEditor -- Table editor for the Track Map: artist|title[|duration]
// -> timecode offset, triggers and cue points.
//
// Shown in a window of its own by MainComponent.  Receives a TrackMap& --
// the global map (owned by AppSettings) or one engine's override set -- and
// a ProDJLinkInput* (for Learn).  Calls onChange() whenever the map is
// modified so the caller can persist settings and refresh engine lookups.
//==============================================================================
class TrackMapEditor : public juce::Component,
                       public juce::TableListBoxModel
{
public:
    //--------------------------------------------------------------------------
    // Construction
    //--------------------------------------------------------------------------
    TrackMapEditor(TrackMap& map, ProDJLinkInput* proDJLink = nullptr)
        : trackMap(map), proDJLinkInput(proDJLink)
    {
        setSize(780, 560);
        rebuildRows();

        // --- Table ---
        addAndMakeVisible(table);
        table.setModel(this);
        table.setColour(juce::ListBox::backgroundColourId, bgDarker);
        table.setColour(juce::ListBox::outlineColourId, borderCol);
        table.setOutlineThickness(1);
        table.setRowHeight(24);
        table.setHeaderHeight(22);
        table.getHeader().setStretchToFitActive(true);

        auto& hdr = table.getHeader();
        hdr.addColumn("#",         ColPlaylistPos, 36, 30, 50);  // playlist order
        hdr.addColumn("Artist",    ColArtist,  140, 80, 300);
        hdr.addColumn("Title",     ColTitle,   130, 80, 300);
        hdr.addColumn("Offset",    ColOffset,  100, 80, 130);
        hdr.addColumn("BPM",       ColBpm,      46, 40,  70, juce::TableHeaderComponent::notSortable);
        hdr.addColumn("Trig",      ColTrig,     40, 30,  60, juce::TableHeaderComponent::notSortable);
        hdr.addColumn("Cues",      ColCues,     40, 30,  60, juce::TableHeaderComponent::notSortable);
        hdr.addColumn("Notes",     ColNotes,   100, 60, 400, juce::TableHeaderComponent::notSortable);

        // Default: sort by playlist position (ascending)
        hdr.setSortColumnId(ColPlaylistPos, true);

        // --- Buttons ---
        auto addBtn = [this](juce::TextButton& btn, const juce::String& text)
        {
            addAndMakeVisible(btn);
            btn.setButtonText(text);
            btn.setColour(juce::TextButton::buttonColourId, bgPanel);
            btn.setColour(juce::TextButton::buttonOnColourId, bgPanel.brighter(0.1f));
            btn.setColour(juce::TextButton::textColourOffId, textBright);
        };

        addBtn(btnLearn,    "Learn");
        addBtn(btnAdd,      "Add");
        addBtn(btnDelete,   "Delete");
        addBtn(btnClearAll, "Clear All");
        addBtn(btnImport,   "Import");
        addBtn(btnExport,   "Export");

        btnLearn.setColour(juce::TextButton::buttonColourId, accentCyan.withAlpha(0.25f));
        btnLearn.setColour(juce::TextButton::textColourOffId, accentCyan.brighter(0.4f));
        btnLearn.setEnabled(true);  // onLearn handles missing sources gracefully

        // Player selector for Learn -- lets the user capture tracks from any CDJ player
        addAndMakeVisible(lblLearnLayer);
        lblLearnLayer.setText("Player:", juce::dontSendNotification);
        lblLearnLayer.setFont(juce::Font(juce::FontOptions(9.0f)));
        lblLearnLayer.setColour(juce::Label::textColourId, textMid);
        lblLearnLayer.setJustificationType(juce::Justification::centredRight);

        addAndMakeVisible(cmbLearnLayer);
        for (int i = 1; i <= ProDJLink::kMaxPlayers; ++i)
            cmbLearnLayer.addItem(juce::String("Player ") + juce::String(i), i);
        cmbLearnLayer.setSelectedId(1, juce::dontSendNotification);  // default Player 1
        cmbLearnLayer.setColour(juce::ComboBox::backgroundColourId, bgPanel);
        cmbLearnLayer.setColour(juce::ComboBox::textColourId, accentCyan.brighter(0.4f));
        cmbLearnLayer.setColour(juce::ComboBox::outlineColourId, borderCol);
        cmbLearnLayer.setEnabled(proDJLinkInput != nullptr);

        btnLearn.onClick  = [this] { onLearn(); };
        btnAdd.onClick    = [this] { onAdd(); };
        btnDelete.onClick = [this] { onDeleteSelected(); };
        btnClearAll.onClick = [this] { onClearAll(); };
        btnImport.onClick = [this] { onImport(); };
        btnExport.onClick = [this] { onExport(); };

        // --- Scope selector ---
        addAndMakeVisible(lblScope);
        lblScope.setText("Scope:", juce::dontSendNotification);
        lblScope.setFont(juce::Font(juce::FontOptions(9.0f)));
        lblScope.setColour(juce::Label::textColourId, textMid);
        lblScope.setJustificationType(juce::Justification::centredRight);

        addAndMakeVisible(cmbScope);
        cmbScope.addItem("Global (all engines)", 1);
        cmbScope.setSelectedId(1, juce::dontSendNotification);
        cmbScope.setColour(juce::ComboBox::backgroundColourId, bgPanel);
        cmbScope.setColour(juce::ComboBox::textColourId, textBright);
        cmbScope.setColour(juce::ComboBox::outlineColourId, borderCol);
        cmbScope.onChange = [this]
        {
            const int id = cmbScope.getSelectedId();
            const int chosen = (id <= 1) ? -1 : id - 2;
            if (chosen != scopeEngine && onScopeChange)
                onScopeChange(chosen);
        };

        addBtn(btnCopyGlobal, "Copy from global");
        btnCopyGlobal.setColour(juce::TextButton::buttonColourId, accentGreen.withAlpha(0.25f));
        btnCopyGlobal.setColour(juce::TextButton::textColourOffId, accentGreen.brighter(0.6f));
        btnCopyGlobal.setVisible(false);
        btnCopyGlobal.onClick = [this] { onCopyFromGlobal(); };

        // --- Edit form ---
        addAndMakeVisible(formPanel);
        formPanel.setVisible(false);

        auto addField = [this](juce::Label& lbl, juce::TextEditor& ed,
                               const juce::String& labelText, bool readOnly = false)
        {
            formPanel.addAndMakeVisible(lbl);
            lbl.setText(labelText, juce::dontSendNotification);
            lbl.setFont(juce::Font(juce::FontOptions(getMonoFontName(), 9.0f, juce::Font::plain)));
            lbl.setColour(juce::Label::textColourId, textDim);
            lbl.setJustificationType(juce::Justification::centredLeft);

            formPanel.addAndMakeVisible(ed);
            ed.setFont(juce::Font(juce::FontOptions(getMonoFontName(), 11.0f, juce::Font::plain)));
            ed.setColour(juce::TextEditor::backgroundColourId, bgDarker);
            ed.setColour(juce::TextEditor::textColourId, textBright);
            ed.setColour(juce::TextEditor::outlineColourId, borderCol);
            ed.setColour(juce::TextEditor::focusedOutlineColourId, accentCyan);
            ed.setReadOnly(readOnly);
        };

        addField(lblFormArtist,  edFormArtist,  "ARTIST:");
        addField(lblFormTitle,   edFormTitle,   "TITLE:");
        addField(lblFormOffset,  edFormOffset,  "OFFSET (HH:MM:SS:FF):");
        addField(lblFormNotes,   edFormNotes,   "NOTES:");

        // --- MIDI trigger fields (independent: Note, CC, PC can coexist) ---
        addField(lblFormMidiCh, edFormMidiCh, "MIDI CH:");
        edFormMidiCh.setInputRestrictions(2, "0123456789");

        addField(lblFormMidiNote, edFormMidiNote, "NOTE:");
        edFormMidiNote.setInputRestrictions(3, "-0123456789");
        edFormMidiNote.setTextToShowWhenEmpty("--", textDim);

        addField(lblFormMidiNoteVel, edFormMidiNoteVel, "VEL:");
        edFormMidiNoteVel.setInputRestrictions(3, "0123456789");

        addField(lblFormMidiCC, edFormMidiCC, "CC#:");
        edFormMidiCC.setInputRestrictions(3, "-0123456789");
        edFormMidiCC.setTextToShowWhenEmpty("--", textDim);

        addField(lblFormMidiCCVal, edFormMidiCCVal, "VAL:");
        edFormMidiCCVal.setInputRestrictions(3, "0123456789");

        // --- Trigger section header ---
        formPanel.addAndMakeVisible(lblTriggerSection);
        lblTriggerSection.setText("TRIGGERS ON TRACK LOAD", juce::dontSendNotification);
        lblTriggerSection.setFont(juce::Font(juce::FontOptions(getMonoFontName(), 10.0f, juce::Font::bold)));
        lblTriggerSection.setColour(juce::Label::textColourId, accentCyan);
        lblTriggerSection.setJustificationType(juce::Justification::centredLeft);

        // --- OSC trigger fields ---
        addField(lblFormOscAddr, edFormOscAddr, "OSC TRIGGER ADDRESS:");
        edFormOscAddr.setTextToShowWhenEmpty("/trigger/track", textDim);
        addField(lblFormOscArgs, edFormOscArgs, "OSC TRIGGER ARGS:");
        edFormOscArgs.setTextToShowWhenEmpty("i:1 s:\"text\"  |  {artist} {title}", textDim);

        // --- Art-Net DMX trigger fields ---
        addField(lblFormDmxCh, edFormDmxCh, "DMX CH:");
        edFormDmxCh.setInputRestrictions(3, "0123456789");
        edFormDmxCh.setTextToShowWhenEmpty("--", textDim);

        addField(lblFormDmxVal, edFormDmxVal, "DMX VAL:");
        edFormDmxVal.setInputRestrictions(3, "0123456789");

        // BPM multiplier combo
        formPanel.addAndMakeVisible(lblFormBpmMult);
        lblFormBpmMult.setText("BPM MULT:", juce::dontSendNotification);
        lblFormBpmMult.setFont(juce::Font(juce::FontOptions(getMonoFontName(), 9.0f, juce::Font::plain)));
        lblFormBpmMult.setColour(juce::Label::textColourId, textDim);
        lblFormBpmMult.setJustificationType(juce::Justification::centredLeft);

        formPanel.addAndMakeVisible(cmbFormBpmMult);
        cmbFormBpmMult.addItem("--  (off)",   1);   // bpmMultiplier = 0
        cmbFormBpmMult.addItem("x2  (double)",2);   // bpmMultiplier = 1
        cmbFormBpmMult.addItem("x4  (quad)",  3);   // bpmMultiplier = 2
        cmbFormBpmMult.addItem("/2  (half)",  4);   // bpmMultiplier = -1
        cmbFormBpmMult.addItem("/4  (quarter)",5);  // bpmMultiplier = -2
        cmbFormBpmMult.setSelectedId(1, juce::dontSendNotification);
        cmbFormBpmMult.setColour(juce::ComboBox::backgroundColourId, bgDarker);
        cmbFormBpmMult.setColour(juce::ComboBox::textColourId, textBright);
        cmbFormBpmMult.setColour(juce::ComboBox::outlineColourId, borderCol);

        auto addFormBtn = [this](juce::TextButton& btn, const juce::String& text)
        {
            formPanel.addAndMakeVisible(btn);
            btn.setButtonText(text);
            btn.setColour(juce::TextButton::buttonColourId, bgPanel);
            btn.setColour(juce::TextButton::textColourOffId, textBright);
        };

        addFormBtn(btnFormSave,   "Save");
        addFormBtn(btnFormCancel, "Cancel");
        addFormBtn(btnFormCues,   "Cue Editor");
        btnFormSave.setColour(juce::TextButton::buttonColourId, accentGreen.withAlpha(0.3f));
        btnFormCues.setColour(juce::TextButton::buttonColourId, juce::Colour(0xFF00CC88).withAlpha(0.25f));
        btnFormCues.setColour(juce::TextButton::textColourOffId, juce::Colour(0xFF00CC88));
        btnFormSave.onClick   = [this] { onFormSave(); };
        btnFormCancel.onClick = [this] { onFormCancel(); };

        // Enter/Return key saves the form (same as clicking Save)
        auto returnToSave = [this] { onFormSave(); };
        edFormArtist.onReturnKey  = returnToSave;
        edFormTitle.onReturnKey   = returnToSave;
        edFormOffset.onReturnKey  = returnToSave;
        edFormNotes.onReturnKey   = returnToSave;
        edFormMidiCh.onReturnKey  = returnToSave;
        edFormMidiNote.onReturnKey = returnToSave;
        edFormMidiNoteVel.onReturnKey = returnToSave;
        edFormMidiCC.onReturnKey  = returnToSave;
        edFormMidiCCVal.onReturnKey = returnToSave;
        edFormOscAddr.onReturnKey = returnToSave;
        edFormOscArgs.onReturnKey = returnToSave;
        edFormDmxCh.onReturnKey   = returnToSave;
        edFormDmxVal.onReturnKey  = returnToSave;
        btnFormCues.onClick   = [this]
        {
            if (!onOpenCueEditor) return;
            if (auto* entry = findEditedEntry())
                onOpenCueEditor(entry);
        };

        // --- Status bar ---
        addAndMakeVisible(lblStatus);
        lblStatus.setFont(juce::Font(juce::FontOptions(getMonoFontName(), 9.0f, juce::Font::plain)));
        lblStatus.setColour(juce::Label::textColourId, textMid);
        updateStatusText();
    }

    ~TrackMapEditor() override
    {
        if (importPreviewWindow != nullptr)
            delete importPreviewWindow.getComponent();
    }

    //--------------------------------------------------------------------------
    // Callback when TrackMap is modified (wire to save + refresh)
    //--------------------------------------------------------------------------
    std::function<void()> onChange;

    /// The user picked another scope in the selector: -1 = global, else the
    /// engine index.  The owner re-opens the editor on that map.
    std::function<void(int)> onScopeChange;

    /// Called when user clicks the Cues column to open the cue editor for a track.
    /// Receives a mutable pointer to the TrackMapEntry: valid until that
    /// entry is erased or the map cleared (see CuePointEditor's lifetime
    /// contract).
    std::function<void(TrackMapEntry*)> onOpenCueEditor;

    /// Callback to get active track info from the current engine.
    /// Used as fallback for Learn when ProDJLink is not the active input
    /// (e.g. StageLinQ mode).  Returns artist, title, durationSec.
    struct LearnTrackInfo { juce::String artist, title; int durationSec = 0; };
    std::function<LearnTrackInfo()> onLearnTrackInfo;

    //--------------------------------------------------------------------------
    // Scope and active track
    //--------------------------------------------------------------------------
    /// Configure the scope selector and, for an engine scope, the override
    /// behaviour.  `engineNames` are the choices after "Global"; `engine` is
    /// the current scope (-1 = global); `global` is the global map, used in
    /// override scope for context (offset, notes) and for "Copy from global".
    void setScope(int engine, const juce::StringArray& engineNames, const TrackMap* global)
    {
        scopeEngine = engine;
        globalMap   = global;

        cmbScope.clear(juce::dontSendNotification);
        cmbScope.addItem("Global (all engines)", 1);
        for (int i = 0; i < engineNames.size(); ++i)
            cmbScope.addItem(engineNames[i] + " overrides", 2 + i);
        cmbScope.setSelectedId(engine < 0 ? 1 : 2 + engine, juce::dontSendNotification);

        const bool ovr = isOverrideScope();
        btnCopyGlobal.setVisible(ovr);
        // A playlist import into an override set would create empty overrides
        // for every track, silencing the global triggers on this engine.
        btnImport.setEnabled(!ovr);
        btnImport.setAlpha(ovr ? 0.35f : 1.0f);
        lblFormOffset.setText(ovr ? "Offset (global)" : "Offset", juce::dontSendNotification);
        lblFormNotes.setText(ovr ? "Notes (global)" : "Notes", juce::dontSendNotification);
        resized();
        repaint();
    }

    int getScopeEngine() const { return scopeEngine; }

    /// The track playing on the current engine, highlighted in the table and
    /// named in the status line.  Artist and title only: every entry of that
    /// artist and title matches, whatever its duration (isActiveEntry).
    /// MainComponent's timer calls it on every tick; a change of track
    /// repaints the table and rewrites the status line (one pass over the
    /// map), which before waited for the next refresh().  Message thread.
    void setActiveTrack(const juce::String& artist, const juce::String& title)
    {
        auto newKey = TrackMapEntry::makeKey(artist, title);
        if (activeTrackKey != newKey) { activeTrackKey = newKey; table.repaint(); updateStatusText(); }
    }

    /// Set the Learn player combo to match the engine's current player.
    void setLearnPlayer(int player)
    {
        cmbLearnLayer.setSelectedId(juce::jlimit(1, ProDJLink::kMaxPlayers, player),
                                     juce::dontSendNotification);
    }

    /// Show or hide the Learn "Player:" combo.
    ///
    /// The player selector only applies to the ProDJLink source, where the
    /// user might want to learn the track loaded on any one of up to four
    /// CDJs.  StageLinQ exposes its current deck through the engine's
    /// active-track cache directly, and Winamp has no player concept at
    /// all (one Winamp = one playhead).  For both of those, the combo is
    /// hidden and `onLearn()` skips the ProDJLink-direct path in favour of
    /// the `onLearnTrackInfo` callback which reads from the current
    /// engine's cached track info.
    void setShowPlayerSelector(bool show)
    {
        lblLearnLayer.setVisible(show);
        cmbLearnLayer.setVisible(show);
        resized();
    }

    /// Phase 2: set metadata client for enriched Learn data
    void setDbServerClient(DbServerClient* client) { dbClient = client; }

    //--------------------------------------------------------------------------
    // Refresh after external changes
    //--------------------------------------------------------------------------
    void refresh()
    {
        rebuildRows();
        table.updateContent();
        table.repaint();
        updateStatusText();
    }

    //--------------------------------------------------------------------------
    // Component overrides
    //--------------------------------------------------------------------------
    void paint(juce::Graphics& g) override
    {
        g.fillAll(bgDark);

        // Draw form panel border when visible
        if (formPanel.isVisible())
        {
            g.setColour(borderCol.brighter(0.1f));
            g.drawRect(formPanel.getBounds().expanded(1), 1);
            g.setColour(bgDarker.brighter(0.03f));
            g.fillRect(formPanel.getBounds());
        }
    }

    void resized() override
    {
        auto area = getLocalBounds().reduced(8);

        // Button row
        auto btnRow = area.removeFromTop(28);
        int bw = 64;
        btnLearn.setBounds(btnRow.removeFromLeft(bw));   btnRow.removeFromLeft(4);
        if (lblLearnLayer.isVisible())
        {
            lblLearnLayer.setBounds(btnRow.removeFromLeft(38));
            cmbLearnLayer.setBounds(btnRow.removeFromLeft(100));  btnRow.removeFromLeft(8);
        }
        btnAdd.setBounds(btnRow.removeFromLeft(bw));      btnRow.removeFromLeft(4);
        btnDelete.setBounds(btnRow.removeFromLeft(bw));  btnRow.removeFromLeft(4);
        btnClearAll.setBounds(btnRow.removeFromLeft(bw));

        btnExport.setBounds(btnRow.removeFromRight(bw));  btnRow.removeFromRight(4);
        btnImport.setBounds(btnRow.removeFromRight(bw));  btnRow.removeFromRight(8);

        // Scope selector sits between the two button groups; "Copy from
        // global" only exists in override scope.
        if (btnCopyGlobal.isVisible())
        {
            btnCopyGlobal.setBounds(btnRow.removeFromRight(120));
            btnRow.removeFromRight(8);
        }
        cmbScope.setBounds(btnRow.removeFromRight(juce::jlimit(120, 200, btnRow.getWidth() - 44)));
        lblScope.setBounds(btnRow.removeFromRight(44));

        area.removeFromTop(6);

        // Status bar
        auto statusRow = area.removeFromBottom(18);
        lblStatus.setBounds(statusRow);

        // Edit form (fixed height at bottom, above status)
        if (formPanel.isVisible())
        {
            area.removeFromBottom(4);
            auto formArea = area.removeFromBottom(kFormHeight);
            formPanel.setBounds(formArea);
            layoutForm(formArea.withZeroOrigin());
            area.removeFromBottom(4);
        }

        // Table takes remaining space
        table.setBounds(area);
    }

    //==========================================================================
    // TableListBoxModel
    //==========================================================================
    int getNumRows() override { return (int)rows.size(); }

    void sortOrderChanged(int newSortColumnId, bool isForwards) override
    {
        activeSortColumn = newSortColumnId;
        sortForwards = isForwards;
        rebuildRows();
        table.updateContent();
        table.repaint();
    }

    void paintRowBackground(juce::Graphics& g, int rowNumber,
                            int /*w*/, int /*h*/, bool isSelected) override
    {
        if (rowNumber < 0 || rowNumber >= (int)rows.size()) return;

        bool isActive = isActiveEntry(*rows[(size_t)rowNumber]);

        if (isSelected)
            g.fillAll(accentCyan.withAlpha(0.15f));
        else if (isActive)
            g.fillAll(accentGreen.withAlpha(0.08f));
        else
            g.fillAll((rowNumber % 2 == 0) ? bgDarker : bgDarker.brighter(0.02f));
    }

    void paintCell(juce::Graphics& g, int rowNumber, int columnId,
                   int width, int height, bool /*isSelected*/) override
    {
        if (rowNumber < 0 || rowNumber >= (int)rows.size()) return;
        jassert(rowsGeneration == trackMap.getGeneration());  // stale pointers!
        const auto& entry = *rows[(size_t)rowNumber];

        bool isActive = isActiveEntry(entry);
        g.setColour(isActive ? accentGreen.brighter(0.3f) : textBright);
        g.setFont(juce::Font(juce::FontOptions(getMonoFontName(), 11.0f, juce::Font::plain)));

        juce::String text;
        switch (columnId)
        {
            case ColPlaylistPos:
                // Show playlist position (sortOrder) or "--" if not in a playlist
                if (entry.sortOrder > 0)
                    text = juce::String(entry.sortOrder);
                else
                {
                    text = "--";
                    g.setColour(textBright.withAlpha(0.4f));
                }
                break;
            case ColArtist:  text = entry.artist; break;
            case ColTitle:   text = entry.title; break;
            case ColOffset:  text = entry.timecodeOffset; break;
            case ColBpm:
            {
                // Show compact BPM multiplier indicator
                switch (entry.bpmMultiplier)
                {
                    case  1: text = "x2";  g.setColour(accentCyan.brighter(0.3f)); break;
                    case  2: text = "x4";  g.setColour(accentCyan.brighter(0.3f)); break;
                    case -1: text = "/2";  g.setColour(accentCyan.brighter(0.3f)); break;
                    case -2: text = "/4";  g.setColour(accentCyan.brighter(0.3f)); break;
                    default: text = "--";  break;
                }
                break;
            }
            case ColTrig:
            {
                // Show compact trigger indicators: M=MIDI, O=OSC, D=DMX
                juce::String t;
                if (entry.hasMidiTrigger())   t += "M";
                if (entry.hasOscTrigger())    t += "O";
                if (entry.hasArtnetTrigger()) t += "D";
                if (t.isNotEmpty())
                {
                    g.setColour(juce::Colour(0xFFFFAB00));  // amber accent
                    g.drawText(t, 4, 0, width - 8, height, juce::Justification::centredLeft, true);
                }
                return;
            }
            case ColCues:
            {
                int n = (int)entry.cuePoints.size();
                if (n > 0)
                {
                    g.setColour(juce::Colour(0xFF00CC88));  // green-teal accent
                    g.drawText(juce::String(n), 4, 0, width - 8, height,
                               juce::Justification::centredLeft, true);
                }
                else
                {
                    g.setColour(juce::Colour(0xFF555555));
                    g.drawText("+", 4, 0, width - 8, height,
                               juce::Justification::centredLeft, true);
                }
                return;
            }
            case ColNotes:   text = entry.notes; break;
        }

        // Playlist position column reads better centered
        auto justification = (columnId == ColPlaylistPos)
            ? juce::Justification::centred
            : juce::Justification::centredLeft;
        g.drawText(text, 4, 0, width - 8, height, justification, true);
    }

    void cellDoubleClicked(int rowNumber, int /*columnId*/,
                           const juce::MouseEvent&) override
    {
        if (rowNumber >= 0 && rowNumber < (int)rows.size())
            openFormForRow(rowNumber);
    }

    void cellClicked(int rowNumber, int columnId, const juce::MouseEvent&) override
    {
        if (columnId == ColCues && rowNumber >= 0 && rowNumber < (int)rows.size())
        {
            if (onOpenCueEditor)
            {
                // Get mutable pointer from the trackMap (rows[] are const pointers)
                auto* entry = trackMap.find(rows[(size_t)rowNumber]->artist,
                                             rows[(size_t)rowNumber]->title,
                                             rows[(size_t)rowNumber]->durationSec);
                if (entry)
                    onOpenCueEditor(entry);
            }
        }
    }

    void selectedRowsChanged(int lastRowSelected) override
    {
        (void)lastRowSelected;
        // Don't auto-open form on single click -- double-click opens it
    }

private:
    //--------------------------------------------------------------------------
    // Data
    //--------------------------------------------------------------------------
    TrackMap& trackMap;
    ProDJLinkInput* proDJLinkInput;
    DbServerClient* dbClient = nullptr;  // Phase 2: metadata cache for Learn

    // Scope (see setScope): -1 = the global map, >= 0 = that engine's
    // override layer.  In override scope `trackMap` IS the override set and
    // `globalMap` is the global map, read for context and for copying.
    int scopeEngine = -1;
    const TrackMap* globalMap = nullptr;
    bool isOverrideScope() const { return scopeEngine >= 0 && globalMap != nullptr; }

    std::vector<const TrackMapEntry*> rows;   // sorted snapshot (ptrs into trackMap) for display
    int  activeSortColumn = ColPlaylistPos;     // default: playlist order
    bool sortForwards     = true;
    uint64_t rowsGeneration = 0;               // generation at which rows were built
    std::string activeTrackKey;  // artist|title key of currently playing track (no duration)

    // The entry the form edits, by identity -- artist, title and duration,
    // the map's key -- not by row: rows are rebuilt by every refresh(), sort
    // and auto-fill while the form stays open, and a row index then names
    // another track.  SAVE used to preserve that track's cues, remove it and
    // give its cues and duration to the edited one (AUDIT SET-3).
    // editingExisting false = the form adds a new entry.
    bool         editingExisting = false;
    juce::String editingArtist, editingTitle;
    int          editingDurationSec = 0;

    int learnedDurationSec = 0;        // captured from CDJ during Learn (used for new entries)
    bool learnRetryInProgress = false; // a Learn click is awaiting late-arriving duration

    //--------------------------------------------------------------------------
    // Colours (matching MainComponent)
    //--------------------------------------------------------------------------
    juce::Colour bgDark       { 0xFF12141A };
    juce::Colour bgPanel      { 0xFF14161C };
    juce::Colour bgDarker     { 0xFF0D0E12 };
    juce::Colour borderCol    { 0xFF1E2028 };
    juce::Colour textDim      { 0xFF37474F };
    juce::Colour textMid      { 0xFF546E7A };
    juce::Colour textBright   { 0xFFCFD8DC };
    juce::Colour accentCyan   { 0xFF00838F };
    juce::Colour accentGreen  { 0xFF2E7D32 };

    //--------------------------------------------------------------------------
    // Column IDs
    //--------------------------------------------------------------------------
    enum { ColPlaylistPos = 1, ColArtist, ColTitle, ColOffset, ColBpm, ColTrig, ColCues, ColNotes };

    //--------------------------------------------------------------------------
    // UI components
    //--------------------------------------------------------------------------
    juce::TableListBox table { "TrackMapTable", this };

    juce::TextButton btnLearn, btnAdd, btnDelete, btnClearAll, btnImport, btnExport;
    juce::Label lblLearnLayer;
    juce::ComboBox cmbLearnLayer;

    // Scope selector (Global / Engine N overrides) and the override-only
    // "Copy from global" button.
    juce::Label    lblScope;
    juce::ComboBox cmbScope;
    juce::TextButton btnCopyGlobal;

    // Edit form
    juce::Component formPanel;
    static constexpr int kFormHeight = 256;   // track info + trigger section + buttons

    juce::Label      lblFormArtist, lblFormTitle, lblFormOffset, lblFormNotes;
    juce::TextEditor edFormArtist, edFormTitle, edFormOffset, edFormNotes;

    // MIDI trigger (Note, CC)
    juce::Label      lblFormMidiCh, lblFormMidiNote, lblFormMidiNoteVel;
    juce::Label      lblFormMidiCC, lblFormMidiCCVal;
    juce::TextEditor edFormMidiCh, edFormMidiNote, edFormMidiNoteVel;
    juce::TextEditor edFormMidiCC, edFormMidiCCVal;

    // Trigger section header
    juce::Label      lblTriggerSection;

    // OSC trigger
    juce::Label      lblFormOscAddr, lblFormOscArgs;
    juce::TextEditor edFormOscAddr, edFormOscArgs;

    // Art-Net DMX trigger
    juce::Label      lblFormDmxCh, lblFormDmxVal;
    juce::TextEditor edFormDmxCh, edFormDmxVal;

    // BPM multiplier (per-track)
    juce::Label    lblFormBpmMult;
    juce::ComboBox cmbFormBpmMult;

    juce::TextButton btnFormSave, btnFormCancel, btnFormCues;

    juce::Label lblStatus;

    //--------------------------------------------------------------------------
    // Helpers
    //--------------------------------------------------------------------------
    void rebuildRows()
    {
        // Default view (or any unknown column): playlist order ascending.
        // This also covers the case where JUCE reports no sort (columnId==0).
        if (activeSortColumn <= 0
            || (activeSortColumn == ColPlaylistPos && sortForwards))
        {
            rows = trackMap.getAllSortedPtrs();
            rowsGeneration = trackMap.getGeneration();
            return;
        }

        // Custom column sort: snapshot all entries then sort
        rows.clear();
        rows.reserve(trackMap.size());
        for (auto& [k, entry] : trackMap.getEntries())
            rows.push_back(&entry);

        auto cmpStr = [this](const juce::String& a, const juce::String& b) {
            int c = a.compareIgnoreCase(b);
            return sortForwards ? (c < 0) : (c > 0);
        };

        std::sort(rows.begin(), rows.end(),
            [&](const TrackMapEntry* a, const TrackMapEntry* b) {
                switch (activeSortColumn)
                {
                    case ColPlaylistPos:
                    {
                        // Tracks without a playlist position (sortOrder==0) always
                        // come LAST, regardless of sort direction. This keeps the
                        // "# == --" group at the bottom where the user expects it.
                        bool aHas = (a->sortOrder > 0);
                        bool bHas = (b->sortOrder > 0);
                        if (aHas != bHas) return aHas;  // the one with an order wins
                        if (aHas)  // both have sort orders
                            return sortForwards ? (a->sortOrder < b->sortOrder)
                                                : (a->sortOrder > b->sortOrder);
                        // Neither has a sort order -- tiebreak by artist/title
                        if (a->artist.compareIgnoreCase(b->artist) != 0)
                            return a->artist.compareIgnoreCase(b->artist) < 0;
                        return a->title.compareIgnoreCase(b->title) < 0;
                    }
                    case ColArtist:
                        if (a->artist.compareIgnoreCase(b->artist) != 0)
                            return cmpStr(a->artist, b->artist);
                        return cmpStr(a->title, b->title);  // tiebreak by title
                    case ColTitle:
                        return cmpStr(a->title, b->title);
                    case ColOffset:
                        return cmpStr(a->timecodeOffset, b->timecodeOffset);
                    default:
                        return false;
                }
            });
        rowsGeneration = trackMap.getGeneration();
    }

    /// The entry the form was opened on, looked up by key now; null when
    /// the form adds a new entry or the entry has gone from the map.
    TrackMapEntry* findEditedEntry()
    {
        return editingExisting ? trackMap.find(editingArtist, editingTitle, editingDurationSec) : nullptr;
    }

    /// True for the entry of the track playing now.  activeTrackKey has no
    /// duration (setActiveTrack gets artist and title), so the entry's key
    /// is compared without its duration too: an entry learned from a deck
    /// or imported from rekordbox carries one and never matched (AUDIT
    /// SET-11).
    bool isActiveEntry(const TrackMapEntry& entry) const
    {
        return !activeTrackKey.empty() && TrackMapEntry::makeKey(entry.artist, entry.title) == activeTrackKey;
    }

    void notifyChanged()
    {
        rebuildRows();
        table.updateContent();
        table.repaint();
        updateStatusText();
        if (onChange) onChange();
    }

    void updateStatusText()
    {
        juce::String s = "Tracks: " + juce::String(trackMap.size());
        if (!activeTrackKey.empty())
        {
            // Find the entry to show artist - title
            for (auto& [k, entry] : trackMap.getEntries())
            {
                if (isActiveEntry(entry))
                {
                    s += " | Active: " + entry.artist + " - " + entry.title + " (MAPPED)";
                    break;
                }
            }
            if (!s.contains("MAPPED"))
                s += " | Active track (UNMAPPED)";
        }
        lblStatus.setText(s, juce::dontSendNotification);
    }

    //--------------------------------------------------------------------------
    // Form layout
    //--------------------------------------------------------------------------
    void layoutForm(juce::Rectangle<int> area)
    {
        area = area.reduced(6, 4);
        const int labelH = 13;
        const int fieldH = 22;
        const int rowH   = labelH + fieldH;

        // Row 1: Artist, Title
        auto row1 = area.removeFromTop(rowH);
        {
            int halfW = (row1.getWidth() - 8) / 2;
            auto seg = row1.removeFromLeft(halfW);
            lblFormArtist.setBounds(seg.removeFromTop(labelH));
            edFormArtist.setBounds(seg);
            row1.removeFromLeft(8);

            lblFormTitle.setBounds(row1.removeFromTop(labelH));
            edFormTitle.setBounds(row1);
        }

        area.removeFromTop(4);

        // Row 2: Offset, Notes
        auto row2 = area.removeFromTop(rowH);
        {
            auto seg = row2.removeFromLeft(160);
            lblFormOffset.setBounds(seg.removeFromTop(labelH));
            edFormOffset.setBounds(seg);
            row2.removeFromLeft(8);

            lblFormNotes.setBounds(row2.removeFromTop(labelH));
            edFormNotes.setBounds(row2);
        }

        area.removeFromTop(6);

        // ---- Trigger section header ----
        lblTriggerSection.setBounds(area.removeFromTop(16));

        area.removeFromTop(4);

        // Row 4: MIDI Trigger: Ch, Note, Vel, CC#, CCVal
        auto row4 = area.removeFromTop(rowH);
        {
            auto seg = row4.removeFromLeft(52);
            lblFormMidiCh.setBounds(seg.removeFromTop(labelH));
            edFormMidiCh.setBounds(seg);
            row4.removeFromLeft(6);

            seg = row4.removeFromLeft(52);
            lblFormMidiNote.setBounds(seg.removeFromTop(labelH));
            edFormMidiNote.setBounds(seg);
            row4.removeFromLeft(6);

            seg = row4.removeFromLeft(52);
            lblFormMidiNoteVel.setBounds(seg.removeFromTop(labelH));
            edFormMidiNoteVel.setBounds(seg);
            row4.removeFromLeft(12);

            seg = row4.removeFromLeft(52);
            lblFormMidiCC.setBounds(seg.removeFromTop(labelH));
            edFormMidiCC.setBounds(seg);
            row4.removeFromLeft(6);

            seg = row4.removeFromLeft(52);
            lblFormMidiCCVal.setBounds(seg.removeFromTop(labelH));
            edFormMidiCCVal.setBounds(seg);
        }

        area.removeFromTop(4);

        // Row 5: OSC Trigger Address + Args
        auto row5 = area.removeFromTop(rowH);
        {
            int halfOsc = (row5.getWidth() - 8) / 2;

            auto seg = row5.removeFromLeft(halfOsc);
            lblFormOscAddr.setBounds(seg.removeFromTop(labelH));
            edFormOscAddr.setBounds(seg);
            row5.removeFromLeft(8);

            lblFormOscArgs.setBounds(row5.removeFromTop(labelH));
            edFormOscArgs.setBounds(row5);
        }

        area.removeFromTop(4);

        // Row 6: Art-Net DMX trigger + BPM Multiplier
        auto row6 = area.removeFromTop(rowH);
        {
            auto seg = row6.removeFromLeft(80);
            lblFormDmxCh.setBounds(seg.removeFromTop(labelH));
            edFormDmxCh.setBounds(seg);
            row6.removeFromLeft(8);

            seg = row6.removeFromLeft(80);
            lblFormDmxVal.setBounds(seg.removeFromTop(labelH));
            edFormDmxVal.setBounds(seg);
            row6.removeFromLeft(16);

            seg = row6.removeFromLeft(180);
            lblFormBpmMult.setBounds(seg.removeFromTop(labelH));
            cmbFormBpmMult.setBounds(seg);
        }

        area.removeFromTop(6);

        // Row 7: Cue Editor (left), Save / Cancel (right) -- anchored to bottom
        auto row7 = area.removeFromBottom(24);
        {
            btnFormCues.setBounds(row7.removeFromLeft(90));
            btnFormCancel.setBounds(row7.removeFromRight(64));
            row7.removeFromRight(4);
            btnFormSave.setBounds(row7.removeFromRight(64));
        }
    }

    //--------------------------------------------------------------------------
    // Form open / close
    //--------------------------------------------------------------------------
    /// Override scope: identity, offset and notes are the global entry's and
    /// are not editable here (the engine never reads them from an override).
    /// Shows the global values for context, read-only.  Global scope: leaves
    /// the fields editable.
    void applyScopeToForm(const juce::String& artist, const juce::String& title, int durationSec)
    {
        const bool ovr = isOverrideScope();
        edFormOffset.setReadOnly(ovr);
        edFormNotes.setReadOnly(ovr);
        edFormOffset.setAlpha(ovr ? 0.6f : 1.0f);
        edFormNotes.setAlpha(ovr ? 0.6f : 1.0f);
        if (!ovr) return;

        const TrackMapEntry* g = globalEntryFor(artist, title, durationSec);
        edFormOffset.setText(g ? g->timecodeOffset : juce::String("00:00:00:00"), false);
        edFormNotes.setText(g ? g->notes : juce::String("(no global entry)"), false);
    }

    /// Override scope only: start an override from a copy of a global entry.
    /// Offers the tracks that have a global entry and no override yet, the
    /// active track first.
    void onCopyFromGlobal()
    {
        if (!isOverrideScope()) return;

        std::vector<const TrackMapEntry*> candidates;
        for (auto* g : globalMap->getAllSortedPtrs())
            if (!trackMap.contains(g->artist, g->title, g->durationSec))
                candidates.push_back(g);

        if (candidates.empty())
        {
            lblStatus.setText("Every global track already has an override on this engine", juce::dontSendNotification);
            return;
        }

        juce::PopupMenu menu;
        int id = 1;
        for (auto* g : candidates)
        {
            const bool active = (TrackMapEntry::makeKey(g->artist, g->title) == activeTrackKey);
            juce::String label = (g->artist.isNotEmpty() ? g->artist + " - " : juce::String()) + g->title;
            if (active) label = "> " + label + "  (active)";
            menu.addItem(id++, label);
        }

        juce::Component::SafePointer<TrackMapEditor> safeThis(this);
        menu.showMenuAsync(juce::PopupMenu::Options().withTargetComponent(&btnCopyGlobal),
            [safeThis, candidates](int result)
            {
                if (safeThis == nullptr || result <= 0 || result > (int)candidates.size()) return;
                TrackMapEntry copy = *candidates[(size_t)result - 1];
                safeThis->trackMap.addOrUpdate(copy);
                safeThis->rebuildRows();
                safeThis->table.updateContent();
                safeThis->lblStatus.setText("Override added from global: " + copy.title, juce::dontSendNotification);
                if (safeThis->onChange) safeThis->onChange();
            });
    }

    /// Trigger, DMX and BPM-multiplier fields from an entry.
    void fillTriggerFields(const TrackMapEntry& entry)
    {
        // MIDI trigger (independent fields)
        edFormMidiCh.setText(juce::String(entry.midiChannel + 1), false);   // display 1-16
        edFormMidiNote.setText(entry.midiNoteNum >= 0 ? juce::String(entry.midiNoteNum) : "", false);
        edFormMidiNoteVel.setText(juce::String(entry.midiNoteVel), false);
        edFormMidiCC.setText(entry.midiCCNum >= 0 ? juce::String(entry.midiCCNum) : "", false);
        edFormMidiCCVal.setText(juce::String(entry.midiCCVal), false);

        // OSC trigger
        edFormOscAddr.setText(entry.oscAddress, false);
        edFormOscArgs.setText(entry.oscArgs, false);

        // Art-Net DMX trigger
        edFormDmxCh.setText(entry.artnetCh > 0 ? juce::String(entry.artnetCh) : "", false);
        edFormDmxVal.setText(juce::String(entry.artnetVal), false);

        // BPM multiplier
        {
            int comboId = 1; // default: off
            if      (entry.bpmMultiplier ==  1) comboId = 2;
            else if (entry.bpmMultiplier ==  2) comboId = 3;
            else if (entry.bpmMultiplier == -1) comboId = 4;
            else if (entry.bpmMultiplier == -2) comboId = 5;
            cmbFormBpmMult.setSelectedId(comboId, juce::dontSendNotification);
        }
    }

    /// Override scope: the global entry for an identity, by the same three
    /// key steps the engine uses.  Null in global scope or when none exists.
    const TrackMapEntry* globalEntryFor(const juce::String& artist, const juce::String& title, int durationSec) const
    {
        if (!isOverrideScope()) return nullptr;
        const TrackMapEntry* g = globalMap->find(artist, title, durationSec);
        if (!g && durationSec > 0) g = globalMap->find(artist, title, 0);
        if (!g) g = globalMap->findIgnoringDuration(artist, title);
        return g;