Guitar-Fretboard-Trainer/README.md

# Guitar Fretboard Trainer

![No build step](https://img.shields.io/badge/build-none-brightgreen?style=flat-square)
![Vanilla JS](https://img.shields.io/badge/vanilla-JS-f7df1e?style=flat-square&logo=javascript&logoColor=000)
![ES Modules](https://img.shields.io/badge/ES-modules-blue?style=flat-square)
![PWA ready](https://img.shields.io/badge/PWA-ready-5A0FC8?style=flat-square&logo=pwa)
![License MIT](https://img.shields.io/badge/license-MIT-lightgrey?style=flat-square)

A browser app to drill guitar fretboard note recognition. No framework, no build step — just plain HTML, CSS, and ES modules.

## Usage

Serve with any HTTP server and open in a browser (ES modules require a server — `file://` won't work):

```bash
python3 -m http.server 8080
# or
npx serve .
```

Then open http://localhost:8080.

## Quiz Modes

### Mode 1 — Name the Note
A position (string + fret) is highlighted on the fretboard. Choose the correct note from 9 buttons — by clicking, pressing `1`–`9`, or typing the note name on your keyboard.

### Mode 2 — Find All Occurrences
A target note and a 4–5 fret range are shown. Click every position in the range where that note appears, then hit **Submit**. Green = correct, red = wrong selection, faded green = missed.

## Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `Space` / `Enter` | Next question (or submit in mode 2) |
| `1`–`9` | Select answer button by position (mode 1) |
| `A`–`G` | Type a note name directly (mode 1) |
| `A` then `#` | Sharp — e.g. `A#` |
| `A` then `b` | Flat — e.g. `Ab` (resolved to `G#` internally) |
| `Tab` | Cycle between modes |

## Settings

- **6-string / 7-string** — standard tuning
- **Sharps only** — show only sharp names (no `D#/Eb` dual labels)
- **Natural notes only** — restrict to C D E F G A B

## Stats

A lifetime stats screen tracks accuracy per mode, accuracy per note, total questions answered, and best streak. Stats persist in `localStorage`.

## Project Structure

```
guitar-trainer/
├── index.html          # Markup only
├── site.webmanifest    # PWA manifest
├── css/
│   └── style.css       # All styles, CSS custom properties for theming
└── js/
    ├── music.js        # Music theory: notes, tunings, display helpers
    ├── fretboard.js    # SVG fretboard builder
    ├── quiz.js         # Question generation and answer evaluation
    └── app.js          # State, rendering, DOM wiring, keyboard shortcuts
```