feat(fretboard): add guitar/mandolin aliases, alternate tunings, open chords, commonChords

- guitar()/violao() and mandolin()/bandolim() as English/PT-BR alias pairs
- dropD(), openG(), dadgad() factory methods with PROGMEM tuning tables
- setString(string, midiNote) for single-string retuning
- commonChords(scale, output, max) — best fingering per diatonic degree
- isOpenFingering(fg) and openFingerings(chord, output, max) — first-position shapes
- 32 new tests added (409 total, 0 failures)

Author: sauloverissimo

README.md

@@ -43,7 +43,7 @@ Tiers auto-select based on platform, or override with `#define GINGODUINO_TIER N
 - Harmonic field analysis with T/S/D functions and roles (+ deduce from notes/chords)
 - Harmonic tree (directed graph, major/minor, classical + jazz traditions)
 - Progression analysis: identify, deduce (ranked), predict (next branch)
-- Fretboard engine: violao, cavaquinho, bandolim, ukulele with fingering scoring
+- Fretboard engine: guitar/violao, cavaquinho, mandolin/bandolim, ukulele; alternate tunings (Drop D, Open G, DADGAD); common chords, open-position fingerings
 - Musical events (note, chord, rest) and sequences with tempo/time signature
 - Real-time harmonic monitor with chord/field detection and per-note context
 - MIDI 1.0 parser (running status, SysEx) and stateless dispatcher
@@ -52,7 +52,7 @@ Tiers auto-select based on platform, or override with `#define GINGODUINO_TIER N
 - Chord comparison: 17 dimensions including Neo-Riemannian transforms and Forte vectors
 - Fixed-size arrays, no dynamic allocation, PROGMEM support
 - Compatible with Arduino IDE, PlatformIO, and ESP-IDF
-- 384 native tests passing
+- 409 native tests passing
 
 ### Installation
 
@@ -200,23 +200,45 @@ field.signature();                     // 0
 
 #### GingoFretboard
 ```cpp
-GingoFretboard guitar = GingoFretboard::violao();   // 6 strings, 19 frets
-// Also: ::cavaquinho(), ::bandolim(), ::ukulele()
+// Standard instruments
+GingoFretboard guitar = GingoFretboard::guitar();   // 6 strings, E A D G B E
+GingoFretboard viol   = GingoFretboard::violao();   // same tuning, Portuguese alias
+// Also: ::cavaquinho(), ::mandolin(), ::bandolim(), ::ukulele()
 
-guitar.noteAt(0, 5);                  // GingoNote("A") — string 0, fret 5
-guitar.midiAt(0, 0);                  // 40 (E2)
+// Alternate tunings
+GingoFretboard dd = GingoFretboard::dropD();   // D A D G B E
+GingoFretboard og = GingoFretboard::openG();   // D G D G B D
+GingoFretboard dg = GingoFretboard::dadgad();  // D A D G A D
+
+// Retune a single string
+guitar.setString(0, 38);   // lower string 0 to D2 (drop D by hand)
+
+// Note / MIDI lookup
+guitar.noteAt(0, 5);        // GingoNote("A") — string 0, fret 5
+guitar.midiAt(0, 0);        // 40 (E2)
 
 GingoFretPos positions[48];
 guitar.positions(GingoNote("E"), positions, 48);
 guitar.scalePositions(scale, positions, 48, 0, 4);
 
+// Fingerings
 GingoFingering fg;
-guitar.fingering(GingoChord("CM"), 0, fg); // best fingering at position 0
+guitar.fingering(GingoChord("CM"), 0, fg);       // fingering at position 0
 
 GingoFingering fgs[5];
-guitar.fingerings(GingoChord("CM"), fgs, 5); // up to 5 fingerings
+guitar.fingerings(GingoChord("CM"), fgs, 5);     // up to 5 fingerings, sorted by score
+
+// Open-position shapes only (open string + frets 1-4)
+GingoFingering opens[5];
+guitar.openFingerings(GingoChord("GM"), opens, 5);
+guitar.isOpenFingering(opens[0]);                // true
+
+// Common chords for a scale (best fingering per degree)
+GingoFingering ccs[7];
+guitar.commonChords(GingoScale("G", SCALE_MAJOR), ccs, 7);
+// ccs[]: GM, Am, Bm, CM, DM, Em, F#dim — sorted by field degree
 
-GingoFretboard capo2 = guitar.capo(2);      // transposed fretboard
+GingoFretboard capo2 = guitar.capo(2);           // transposed fretboard
 ```
 
 #### GingoEvent & GingoSequence (Tier 3)
@@ -478,7 +500,7 @@ Tiers auto-detectados por plataforma, ou force com `#define GINGODUINO_TIER N`.
 - Analise de campo harmonico com funcoes T/S/D e roles (+ deduce a partir de notas/acordes)
 - Arvore harmonica (grafo dirigido, major/minor, tradicoes classica + jazz)
 - Analise de progressao: identify, deduce (ranked), predict (proximo branch)
-- Engine de braco: violao, cavaquinho, bandolim, ukulele com scoring de digitacao
+- Engine de braco: guitar/violao, cavaquinho, mandolin/bandolim, ukulele; afinacoes alternativas (Drop D, Open G, DADGAD); acordes comuns, digitacoes em primeira posicao
 - Eventos musicais (nota, acorde, pausa) e sequencias com tempo/compasso
 - Monitor harmonico em tempo real com deteccao de acordes/campos e contexto por nota
 - Parser MIDI 1.0 (running status, SysEx) e dispatcher stateless
@@ -487,7 +509,7 @@ Tiers auto-detectados por plataforma, ou force com `#define GINGODUINO_TIER N`.
 - Comparacao de acordes: 17 dimensoes incluindo transformacoes Neo-Riemannian e vetores Forte
 - Arrays de tamanho fixo, sem alocacao dinamica, suporte PROGMEM
 - Compativel com Arduino IDE, PlatformIO e ESP-IDF
-- 384 testes nativos passando
+- 409 testes nativos passando
 
 ### Instalacao
 

extras/tests/test_native.cpp

@@ -792,6 +792,78 @@ void testFretboard() {
     GingoFretboard uke = GingoFretboard::ukulele();
     CHECK(uke.numStrings() == 4, "ukulele numStrings=4");
     CHECK(strcmp(uke.name(), "Ukulele") == 0, "ukulele name");
+
+    // English aliases
+    GingoFretboard eng = GingoFretboard::guitar();
+    CHECK(eng.numStrings() == 6, "guitar() numStrings=6");
+    CHECK(strcmp(eng.name(), "Guitar") == 0, "guitar() name=Guitar");
+    CHECK(eng.openMidi(0) == 40, "guitar() same tuning as violao");
+
+    GingoFretboard mand = GingoFretboard::mandolin();
+    CHECK(mand.numStrings() == 4, "mandolin() numStrings=4");
+    CHECK(strcmp(mand.name(), "Mandolin") == 0, "mandolin() name=Mandolin");
+    CHECK(mand.openMidi(0) == 55, "mandolin() open string 0 = G3 (55)");
+
+    // Alternate tunings
+    GingoFretboard dd = GingoFretboard::dropD();
+    CHECK(dd.numStrings() == 6, "dropD numStrings=6");
+    CHECK(dd.openMidi(0) == 38, "dropD string 0 = D2 (38)");
+    CHECK(dd.openMidi(1) == 45, "dropD string 1 = A2 (45)");
+    {
+        GingoNote dn = dd.noteAt(0, 0);
+        CHECK(strcmp(dn.name(), "D") == 0, "dropD string 0 open = D");
+    }
+
+    GingoFretboard og = GingoFretboard::openG();
+    CHECK(og.openMidi(0) == 38, "openG string 0 = D2 (38)");
+    CHECK(og.openMidi(1) == 43, "openG string 1 = G2 (43)");
+    {
+        GingoNote gn = og.noteAt(1, 0);
+        CHECK(strcmp(gn.name(), "G") == 0, "openG string 1 open = G");
+    }
+
+    GingoFretboard dg = GingoFretboard::dadgad();
+    CHECK(dg.openMidi(0) == 38, "dadgad string 0 = D2 (38)");
+    CHECK(dg.openMidi(4) == 57, "dadgad string 4 = A3 (57)");
+    {
+        GingoNote an = dg.noteAt(4, 0);
+        CHECK(strcmp(an.name(), "A") == 0, "dadgad string 4 open = A");
+    }
+
+    // setString (retune)
+    GingoFretboard custom = GingoFretboard::guitar();
+    custom.setString(0, 38);  // lower to D2 (drop D)
+    CHECK(custom.openMidi(0) == 38, "setString: string 0 retuned to 38");
+    {
+        GingoNote dn2 = custom.noteAt(0, 0);
+        CHECK(strcmp(dn2.name(), "D") == 0, "setString: string 0 = D after retune");
+    }
+    CHECK(custom.openMidi(1) == 45, "setString: other strings unchanged");
+
+    // commonChords
+    GingoScale gMaj("G", SCALE_MAJOR);
+    GingoFingering ccs[7];
+    uint8_t ncc = guitar.commonChords(gMaj, ccs, 7);
+    CHECK(ncc > 0, "commonChords(G major) returns results");
+    printf("         commonChords(G major): %d chords\n", ncc);
+    for (uint8_t i = 0; i < ncc; i++) {
+        printf("           [%d] %s score=%d\n", i, ccs[i].chordName.c_str(), ccs[i].score);
+    }
+
+    // openFingerings / isOpenFingering
+    GingoFingering opens[5];
+    uint8_t nopen = guitar.openFingerings(GingoChord("GM"), opens, 5);
+    CHECK(nopen > 0, "openFingerings(GM) found open shape(s)");
+    if (nopen > 0) {
+        CHECK(guitar.isOpenFingering(opens[0]), "first result of openFingerings is open");
+        printf("         openFingerings(GM): %d open shapes found\n", nopen);
+    }
+
+    // Bandolim alias
+    GingoFretboard bnd = GingoFretboard::bandolim();
+    CHECK(bnd.numStrings() == 4, "bandolim numStrings=4");
+    CHECK(strcmp(bnd.name(), "Bandolim") == 0, "bandolim name=Bandolim");
+    CHECK(bnd.openMidi(0) == mand.openMidi(0), "bandolim same tuning as mandolin");
 }
 
 // =====================================================================

src/GingoFretboard.cpp

@@ -33,6 +33,14 @@ GingoFretboard::GingoFretboard(const char* name,
 // Factories
 // ---------------------------------------------------------------------------
 
+GingoFretboard GingoFretboard::guitar(uint8_t numFrets) {
+    return GingoFretboard("Guitar", data::TUNING_VIOLAO, 6, numFrets);
+}
+
+GingoFretboard GingoFretboard::mandolin(uint8_t numFrets) {
+    return GingoFretboard("Mandolin", data::TUNING_BANDOLIM, 4, numFrets);
+}
+
 GingoFretboard GingoFretboard::violao(uint8_t numFrets) {
     return GingoFretboard("Violao", data::TUNING_VIOLAO, 6, numFrets);
 }
@@ -49,6 +57,18 @@ GingoFretboard GingoFretboard::ukulele(uint8_t numFrets) {
     return GingoFretboard("Ukulele", data::TUNING_UKULELE, 4, numFrets);
 }
 
+GingoFretboard GingoFretboard::dropD(uint8_t numFrets) {
+    return GingoFretboard("DropD", data::TUNING_DROP_D, 6, numFrets);
+}
+
+GingoFretboard GingoFretboard::openG(uint8_t numFrets) {
+    return GingoFretboard("OpenG", data::TUNING_OPEN_G, 6, numFrets);
+}
+
+GingoFretboard GingoFretboard::dadgad(uint8_t numFrets) {
+    return GingoFretboard("DADGAD", data::TUNING_DADGAD, 6, numFrets);
+}
+
 // ---------------------------------------------------------------------------
 // Info
 // ---------------------------------------------------------------------------
@@ -308,6 +328,76 @@ bool GingoFretboard::identify(const uint8_t* stringFrets, uint8_t count,
     return GingoChord::identify(notes, noteCount, output, maxLen);
 }
 
+// ---------------------------------------------------------------------------
+// Retune
+// ---------------------------------------------------------------------------
+
+void GingoFretboard::setString(uint8_t string, uint8_t midiNote) {
+    if (string < numStrings_) {
+        openMidi_[string] = midiNote;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Common chords
+// ---------------------------------------------------------------------------
+
+uint8_t GingoFretboard::commonChords(const GingoScale& scale,
+                                     GingoFingering* output, uint8_t maxResults) const {
+    GingoField field(scale.tonic().name(), scale.parent());
+    GingoChord fieldChords[7];
+    uint8_t numChords = field.chords(fieldChords, 7);
+    uint8_t written = 0;
+
+    for (uint8_t i = 0; i < numChords && written < maxResults; i++) {
+        // Try the first few positions and keep the best-scoring fingering
+        GingoFingering best;
+        bool bestValid = false;
+        for (uint8_t pos = 0; pos < 4; pos++) {
+            GingoFingering fg;
+            if (fingering(fieldChords[i], pos, fg)) {
+                if (!bestValid || fg.score < best.score) {
+                    best = fg;
+                    bestValid = true;
+                }
+            }
+        }
+        if (bestValid) {
+            output[written++] = best;
+        }
+    }
+    return written;
+}
+
+// ---------------------------------------------------------------------------
+// Open fingerings
+// ---------------------------------------------------------------------------
+
+bool GingoFretboard::isOpenFingering(const GingoFingering& fg) const {
+    bool hasOpen = false;
+    for (uint8_t i = 0; i < fg.numStrings; i++) {
+        if (fg.strings[i].action == STRING_OPEN) {
+            hasOpen = true;
+        } else if (fg.strings[i].action == STRING_FRETTED && fg.strings[i].fret > 4) {
+            return false;
+        }
+    }
+    return hasOpen;
+}
+
+uint8_t GingoFretboard::openFingerings(const GingoChord& chord,
+                                       GingoFingering* output, uint8_t maxResults) const {
+    GingoFingering all[GINGODUINO_MAX_FINGERINGS + 4];
+    uint8_t count = fingerings(chord, all, GINGODUINO_MAX_FINGERINGS + 4);
+    uint8_t written = 0;
+    for (uint8_t i = 0; i < count && written < maxResults; i++) {
+        if (isOpenFingering(all[i])) {
+            output[written++] = all[i];
+        }
+    }
+    return written;
+}
+
 // ---------------------------------------------------------------------------
 // Capo
 // ---------------------------------------------------------------------------

src/GingoFretboard.h

@@ -14,6 +14,7 @@
 #include "GingoNote.h"
 #include "GingoChord.h"
 #include "GingoScale.h"
+#include "GingoField.h"
 
 namespace gingoduino {
 
@@ -77,18 +78,33 @@ class GingoFretboard {
                    uint8_t numStrings,
                    uint8_t numFrets = 19);
 
-    /// Factory: standard 6-string guitar (violao).
+    /// Factory: standard 6-string guitar (standard tuning).
+    static GingoFretboard guitar(uint8_t numFrets = 19);
+
+    /// Factory: mandolin (4 strings, G D A E).
+    static GingoFretboard mandolin(uint8_t numFrets = 17);
+
+    /// Factory: standard 6-string guitar — Portuguese alias for guitar().
     static GingoFretboard violao(uint8_t numFrets = 19);
 
     /// Factory: cavaquinho (4 strings).
     static GingoFretboard cavaquinho(uint8_t numFrets = 17);
 
-    /// Factory: bandolim / mandolin (4 strings).
+    /// Factory: bandolim — Portuguese alias for mandolin().
     static GingoFretboard bandolim(uint8_t numFrets = 17);
 
     /// Factory: ukulele (4 strings).
     static GingoFretboard ukulele(uint8_t numFrets = 17);
 
+    /// Factory: drop D tuning (D A D G B E).
+    static GingoFretboard dropD(uint8_t numFrets = 19);
+
+    /// Factory: open G tuning (D G D G B D).
+    static GingoFretboard openG(uint8_t numFrets = 19);
+
+    /// Factory: DADGAD tuning (D A D G A D).
+    static GingoFretboard dadgad(uint8_t numFrets = 19);
+
     /// Instrument name.
     const char* name() const { return name_.c_str(); }
 
@@ -140,6 +156,24 @@ class GingoFretboard {
     bool identify(const uint8_t* stringFrets, uint8_t count,
                   char* output, uint8_t maxLen) const;
 
+    /// Retune a single string to a new MIDI note.
+    void setString(uint8_t string, uint8_t midiNote);
+
+    /// Find the best fingering for each diatonic chord of the given scale.
+    /// Uses the scale's harmonic field (triads). Returns number of fingerings written.
+    /// Note: uses the parent scale type — modes return their parallel major/minor field.
+    uint8_t commonChords(const GingoScale& scale,
+                         GingoFingering* output, uint8_t maxResults) const;
+
+    /// Return true if this fingering uses at least one open string
+    /// and all fretted notes are within the first 4 frets.
+    bool isOpenFingering(const GingoFingering& fg) const;
+
+    /// Find open-position fingerings for a chord (open strings, frets 1-4).
+    /// Returns the number of fingerings written.
+    uint8_t openFingerings(const GingoChord& chord,
+                           GingoFingering* output, uint8_t maxResults) const;
+
     /// Create a new fretboard with a capo at the given fret.
     GingoFretboard capo(uint8_t fret) const;
 

src/gingoduino_progmem.h

@@ -540,6 +540,15 @@ static const uint8_t TUNING_BANDOLIM[4] PROGMEM = { 55, 62, 69, 76 };
 // Ukulele — G4 C4 E4 A4
 static const uint8_t TUNING_UKULELE[4] PROGMEM = { 67, 60, 64, 69 };
 
+// Drop D — D2 A2 D3 G3 B3 E4
+static const uint8_t TUNING_DROP_D[6] PROGMEM = { 38, 45, 50, 55, 59, 64 };
+
+// Open G — D2 G2 D3 G3 B3 D4
+static const uint8_t TUNING_OPEN_G[6] PROGMEM = { 38, 43, 50, 55, 59, 62 };
+
+// DADGAD — D2 A2 D3 G3 A3 D4
+static const uint8_t TUNING_DADGAD[6] PROGMEM = { 38, 45, 50, 55, 57, 62 };
+
 #endif // GINGODUINO_HAS_FRETBOARD
 
 // ===================================================================