note-mapper 1.0.0

package/index.js

@@ -0,0 +1,57 @@
+/**
+ * index.js
+ * Main entry point for note-mapper.
+ * Re-exports everything from all modules so consumers
+ * only need one import.
+ *
+ * @example
+ * import { SCALES, createMapper, ACTIONS_5 } from "note-mapper"
+ */
+
+// scales
+export {
+  SCALES,
+  KEYS,
+  MAJOR,
+  NATURAL_MINOR,
+  PENTATONIC_MINOR,
+  PENTATONIC_MAJOR,
+  BLUES,
+  DORIAN,
+  PHRYGIAN,
+  LYDIAN,
+  MIXOLYDIAN,
+  LOCRIAN,
+  HARMONIC_MINOR,
+  MELODIC_MINOR,
+  PHRYGIAN_DOMINANT,
+  WHOLE_TONE,
+  DIMINISHED,
+} from "./scales.js"
+
+// degrees
+export {
+  getDegree,
+  getDegreeWithTolerance,
+  degreeToNote,
+  isInScale,
+  pitchClass,
+} from "./degrees.js"
+
+// intervals
+export {
+  INTERVALS,
+  getInterval,
+  getIntervalInfo,
+  detectInterval,
+  isInterval,
+} from "./intervals.js"
+
+// mapper
+export {
+  createMapper,
+  ACTIONS_5,
+  ACTIONS_6,
+  ACTIONS_7,
+  ACTIONS_INTERVAL,
+} from "./mapper.js"

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "note-mapper",
+  "version": "1.0.0",
+  "description": "Map guitar notes from note-listener to scale degrees, intervals and game actions",
+  "main": "index.js",
+  "exports": {
+        ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": ["guitar", "music", "pitch", "scale", "interval", "game-controller"],
+  "author": "Donald Edwin",
+  "license": "MIT",
+  "type": "module",
+  "peerDependencies": {
+    "note-listener": "*"
+  }
+}

package/src/degrees.js

@@ -0,0 +1,147 @@
+/**
+ * degrees.js
+ * Resolves a note from note-listener into a scale degree.
+ * A degree is just the position of the note in the scale — 0 is the root.
+ */
+
+// ─── Enharmonic equivalents ──────────────────────────────────────────────────
+// Some notes have two names (C# = Db, F# = Gb etc).
+// This map normalizes them so lookups always work regardless of which
+// name the scale uses vs which name note-listener detected.
+
+const ENHARMONIC = {
+  "Db": "C#",
+  "D#": "Eb",
+  "Gb": "F#",
+  "G#": "Ab",
+  "A#": "Bb",
+  // and the reverse
+  "C#": "Db",
+  "Eb": "D#",
+  "F#": "Gb",
+  "Ab": "G#",
+  "Bb": "A#",
+}
+
+// ─── Utilities ───────────────────────────────────────────────────────────────
+
+/**
+ * Strips the octave number from a note string.
+ * "A2" → "A",  "C#3" → "C#",  "Bb4" → "Bb"
+ */
+export function pitchClass(note) {
+  return note.replace(/\d/g, "")
+}
+
+/**
+ * Looks up a pitch class in a scale, trying both its name
+ * and its enharmonic equivalent.
+ * Returns the index (degree) or -1 if not found.
+ */
+function findInScale(pc, scale) {
+  const direct = scale.indexOf(pc)
+  if (direct !== -1) return direct
+
+  const alt = ENHARMONIC[pc]
+  if (alt) return scale.indexOf(alt)
+
+  return -1
+}
+
+// ─── Main exports ────────────────────────────────────────────────────────────
+
+/**
+ * Returns the scale degree (0-based) of a note within a scale.
+ * Returns null if the note is not in the scale.
+ *
+ * @param {string}   note   - note string from note-listener e.g. "A2"
+ * @param {string[]} scale  - scale array from scales.js e.g. ["A","C","D","E","G"]
+ * @returns {number|null}
+ *
+ * @example
+ * getDegree("A2", ["A","C","D","E","G"]) // → 0  (root)
+ * getDegree("E3", ["A","C","D","E","G"]) // → 3
+ * getDegree("F#2",["A","C","D","E","G"]) // → null (not in scale)
+ */
+export function getDegree(note, scale) {
+  const pc = pitchClass(note)
+  const degree = findInScale(pc, scale)
+  return degree === -1 ? null : degree
+}
+
+/**
+ * Same as getDegree but with cents tolerance.
+ * Useful when the player is slightly out of tune —
+ * accepts the note if it's within centsTolerance cents of a scale degree.
+ *
+ * @param {string}   note            - note string from note-listener e.g. "A2"
+ * @param {number}   freq            - frequency in Hz from note-listener
+ * @param {string[]} scale           - scale array from scales.js
+ * @param {number}   centsTolerance  - how many cents off to still accept (default 40)
+ * @returns {number|null}
+ */
+export function getDegreeWithTolerance(note, freq, scale, centsTolerance = 40) {
+  // first try exact match
+  const exact = getDegree(note, scale)
+  if (exact !== null) return exact
+
+  // if no exact match, check if freq is close enough to any scale degree
+  for (let i = 0; i < scale.length; i++) {
+    const targetFreq = noteNameToFreq(scale[i])
+    if (!targetFreq) continue
+
+    // check across multiple octaves (2 through 6)
+    for (let octave = 2; octave <= 6; octave++) {
+      const octaveFreq = targetFreq * Math.pow(2, octave - 4)
+      const cents = Math.abs(1200 * Math.log2(freq / octaveFreq))
+      if (cents <= centsTolerance) return i
+    }
+  }
+
+  return null
+}
+
+/**
+ * Converts a pitch class name to its frequency in octave 4.
+ * Used internally by getDegreeWithTolerance.
+ */
+function noteNameToFreq(pc) {
+  const A4 = 440
+  const NOTE_NAMES = ["C","C#","D","D#","E","F","F#","G","G#","A","A#","B"]
+
+  // normalize enharmonics to sharps for lookup
+  const normalized = ENHARMONIC[pc] && NOTE_NAMES.includes(ENHARMONIC[pc])
+    ? ENHARMONIC[pc]
+    : pc
+
+  const semitone = NOTE_NAMES.indexOf(normalized)
+  if (semitone === -1) return null
+
+  // semitones from A4 (midi 69) → freq
+  const midi = semitone + 60 // C4 = midi 60
+  return A4 * Math.pow(2, (midi - 69) / 12)
+}
+
+/**
+ * Returns the note name for a given degree in a scale.
+ * The reverse of getDegree — useful for displaying what note to play next.
+ *
+ * @param {number}   degree - 0-based degree index
+ * @param {string[]} scale  - scale array from scales.js
+ * @returns {string|null}
+ *
+ * @example
+ * degreeToNote(0, ["A","C","D","E","G"]) // → "A"
+ * degreeToNote(3, ["A","C","D","E","G"]) // → "E"
+ */
+export function degreeToNote(degree, scale) {
+  return scale[degree] ?? null
+}
+
+/**
+ * Returns true if a note is in the scale, false if not.
+ * Useful for filtering out notes that don't belong before mapping to actions.
+ */
+export function isInScale(note, scale) {
+  return getDegree(note, scale) !== null
+}

package/src/intervals.js

@@ -0,0 +1,138 @@
+/**
+ * intervals.js
+ * Detects and names the interval between two simultaneously detected notes.
+ * Works with the notes array from note-listener's onNotes callback.
+ */
+
+// ─── Interval definitions ────────────────────────────────────────────────────
+
+export const INTERVALS = {
+  0:  { name: "Unison",        short: "P1",  character: "same note"            },
+  1:  { name: "Minor 2nd",     short: "m2",  character: "tense, dissonant"     },
+  2:  { name: "Major 2nd",     short: "M2",  character: "stepwise, mild"       },
+  3:  { name: "Minor 3rd",     short: "m3",  character: "minor, sad"           },
+  4:  { name: "Major 3rd",     short: "M3",  character: "major, bright"        },
+  5:  { name: "Perfect 4th",   short: "P4",  character: "open, suspended"      },
+  6:  { name: "Tritone",       short: "TT",  character: "maximum tension"      },
+  7:  { name: "Perfect 5th",   short: "P5",  character: "power chord, strong"  },
+  8:  { name: "Minor 6th",     short: "m6",  character: "melancholic"          },
+  9:  { name: "Major 6th",     short: "M6",  character: "warm, resolved"       },
+  10: { name: "Minor 7th",     short: "m7",  character: "bluesy, unresolved"   },
+  11: { name: "Major 7th",     short: "M7",  character: "jazzy, tense"         },
+  12: { name: "Octave",        short: "P8",  character: "same note reinforced" },
+}
+
+// ─── Utilities ───────────────────────────────────────────────────────────────
+
+/**
+ * Converts a frequency to a MIDI note number (not rounded — keeps decimals).
+ * Used for interval calculation so we work in semitone space.
+ */
+function freqToMidi(freq) {
+  return 12 * Math.log2(freq / 440) + 69
+}
+
+// ─── Main exports ────────────────────────────────────────────────────────────
+
+/**
+ * Returns the interval in semitones between two frequencies.
+ * Always returns a positive number between 0 and 12 (octave-reduced).
+ *
+ * @param {number} freqA
+ * @param {number} freqB
+ * @returns {number} semitones 0–12
+ *
+ * @example
+ * getInterval(440, 660) // → 7  (perfect 5th, A4 to E5)
+ * getInterval(440, 880) // → 12 (octave)
+ */
+export function getInterval(freqA, freqB) {
+  const semitones = Math.abs(freqToMidi(freqA) - freqToMidi(freqB))
+  return Math.round(semitones) % 12 || 12
+  // the || 12 means: if mod 12 gives 0 (an octave), return 12 not 0
+  // so unison (same note) = 0, octave = 12, everything else 1–11
+}
+
+/**
+ * Returns the full interval info object for two frequencies.
+ *
+ * @param {number} freqA
+ * @param {number} freqB
+ * @returns {{ semitones, name, short, character }}
+ *
+ * @example
+ * getIntervalInfo(440, 660)
+ * // → { semitones: 7, name: "Perfect 5th", short: "P5", character: "power chord, strong" }
+ */
+export function getIntervalInfo(freqA, freqB) {
+  const semitones = getInterval(freqA, freqB)
+  return { semitones, ...INTERVALS[semitones] }
+}
+
+/**
+ * Detects an interval from the notes array given by note-listener's onNotes.
+ * Only looks at notes with isOnset: true so held notes don't re-trigger.
+ *
+ * Uses a timing window — notes don't have to arrive in the exact same frame,
+ * just within windowMs milliseconds of each other.
+ *
+ * @param {Array}  notes     - the notes array from onNotes
+ * @param {Array}  history   - a mutable array you maintain across calls (pass [] initially)
+ * @param {number} windowMs  - how long to wait for a second note (default 150ms)
+ * @returns {{ semitones, name, short, character, notes } | null}
+ *
+ * @example
+ * const history = []
+ *
+ * onNotes(notes) {
+ *   const interval = detectInterval(notes, history)
+ *   if (interval) console.log(interval.name) // "Perfect 5th"
+ * }
+ */
+export function detectInterval(notes, history, windowMs = 150) {
+  const now = Date.now()
+
+  // add any new onsets to the history buffer
+  for (const n of notes) {
+    if (n.isOnset) {
+      history.push({ freq: n.freq, note: n.note, time: now })
+    }
+  }
+
+  // remove entries older than the window
+  while (history.length && now - history[0].time > windowMs) {
+    history.shift()
+  }
+
+  // if we have at least two notes in the window, we have an interval
+  if (history.length >= 2) {
+    const a = history[0]
+    const b = history[1]
+    const info = getIntervalInfo(a.freq, b.freq)
+
+    // clear history so we don't keep re-firing the same interval
+    history.length = 0
+
+    return {
+      ...info,
+      notes: [a.note, b.note],
+    }
+  }
+
+  return null
+}
+
+/**
+ * Checks if a detected interval matches a named interval.
+ * Useful for if/else game logic without dealing with semitone numbers.
+ *
+ * @param {number} semitones  - from getInterval()
+ * @param {string} name       - interval short name e.g. "P5", "m3", "TT"
+ * @returns {boolean}
+ *
+ * @example
+ * if (isInterval(semitones, "P5")) triggerAction("power_attack")
+ */
+export function isInterval(semitones, name) {
+  return INTERVALS[semitones]?.short === name
+}

package/src/mapper.js

@@ -0,0 +1,254 @@
+/**
+ * mapper.js
+ * Maps scale degrees and intervals to game actions.
+ * This is the final layer — it takes what degrees.js and intervals.js
+ * give you and turns them into something your game can act on.
+ */
+
+// ─── Default action maps ─────────────────────────────────────────────────────
+
+// 5 note pentatonic — good for simple games
+export const ACTIONS_5 = {
+  0: "jump",
+  1: "move_left",
+  2: "move_right",
+  3: "attack",
+  4: "shield",
+}
+
+// 6 note blues — adds one extra action
+export const ACTIONS_6 = {
+  0: "jump",
+  1: "move_left",
+  2: "move_right",
+  3: "attack",
+  4: "shield",
+  5: "special",
+}
+
+// 7 note diatonic — full action set
+export const ACTIONS_7 = {
+  0: "jump",
+  1: "move_left",
+  2: "move_right",
+  3: "attack",
+  4: "shield",
+  5: "special",
+  6: "ultimate",
+}
+
+// interval-based actions — two notes played together
+export const ACTIONS_INTERVAL = {
+  7:  "power_attack",   // perfect 5th — power chord
+  3:  "block",          // minor 3rd
+  4:  "dodge",          // major 3rd
+  12: "ultimate",       // octave
+  5:  "special",        // perfect 4th
+  6:  "taunt",          // tritone — maximum tension
+  10: "roll",           // minor 7th
+  9:  "heal",           // major 6th
+}
+
+// ─── Main exports ────────────────────────────────────────────────────────────
+
+/**
+ * Creates a mapper instance that connects note-listener output
+ * to game actions. This is the main thing you use in your app.
+ *
+ * @param {object} opts
+ * @param {string[]}      opts.scale           - scale array from scales.js
+ * @param {object}        [opts.degreeActions] - degree → action map (default ACTIONS_7)
+ * @param {object}        [opts.intervalActions] - semitones → action map (default ACTIONS_INTERVAL)
+ * @param {number}        [opts.centsTolerance] - how many cents off to still accept (default 40)
+ * @param {number}        [opts.intervalWindow] - ms window for interval detection (default 150)
+ * @param {function}      opts.onAction        - fires when any action is triggered
+ *
+ * @returns {{ process, setScale, setDegreeActions, setIntervalActions }}
+ *
+ * @example
+ * const mapper = createMapper({
+ *   scale: SCALES["natural_minor"]["A"],
+ *   onAction(action, meta) {
+ *     console.log(action) // "jump", "power_attack" etc
+ *     console.log(meta)   // { note, freq, degree, interval, isOnset }
+ *   }
+ * })
+ *
+ * // inside note-listener's onNotes:
+ * onNotes(notes) {
+ *   mapper.process(notes)
+ * }
+ */
+export function createMapper({
+  scale,
+  degreeActions  = ACTIONS_7,
+  intervalActions = ACTIONS_INTERVAL,
+  centsTolerance = 40,
+  intervalWindow = 150,
+  onAction,
+} = {}) {
+  let _scale          = scale
+  let _degreeActions  = degreeActions
+  let _intervalActions = intervalActions
+  let _intervalHistory = []
+
+  // ── onset gate ────────────────────────────────────────────────────────────
+  // tracks which notes are currently held so we only fire on the attack,
+  // not continuously while the note rings
+  const _heldNotes = new Set()
+
+  function processOnsets(notes) {
+    const onsets = []
+
+    for (const n of notes) {
+      if (n.isOnset && !_heldNotes.has(n.note)) {
+        _heldNotes.add(n.note)
+        onsets.push(n)
+      }
+      // if a note is no longer in the detected list, release it
+    }
+
+    // release notes that stopped sounding
+    const currentNotes = new Set(notes.map(n => n.note))
+    for (const held of _heldNotes) {
+      if (!currentNotes.has(held)) _heldNotes.delete(held)
+    }
+
+    return onsets
+  }
+
+  // ── interval detection ────────────────────────────────────────────────────
+  function processInterval(notes) {
+    const now = Date.now()
+
+    for (const n of notes) {
+      if (n.isOnset) {
+        _intervalHistory.push({ freq: n.freq, note: n.note, time: now })
+      }
+    }
+
+    // remove old entries outside the window
+    while (_intervalHistory.length && now - _intervalHistory[0].time > intervalWindow) {
+      _intervalHistory.shift()
+    }
+
+    if (_intervalHistory.length >= 2) {
+      const a = _intervalHistory[0]
+      const b = _intervalHistory[1]
+
+      const semitones = Math.round(
+        Math.abs(12 * Math.log2(a.freq / b.freq))
+      ) % 12 || 12
+
+      _intervalHistory.length = 0
+      return { semitones, notes: [a.note, b.note] }
+    }
+
+    return null
+  }
+
+  // ── degree detection ──────────────────────────────────────────────────────
+  function processDegree(note, freq) {
+    const pc = note.replace(/\d/g, "")
+
+    // try direct match first
+    let degree = _scale.indexOf(pc)
+
+    // try enharmonic equivalent
+    if (degree === -1) {
+      const ENHARMONIC = {
+        "Db":"C#","D#":"Eb","Gb":"F#","G#":"Ab","A#":"Bb",
+        "C#":"Db","Eb":"D#","F#":"Gb","Ab":"G#","Bb":"A#",
+      }
+      const alt = ENHARMONIC[pc]
+      if (alt) degree = _scale.indexOf(alt)
+    }
+
+    // try cents tolerance if still not found
+    if (degree === -1 && freq) {
+      for (let i = 0; i < _scale.length; i++) {
+        for (let octave = 2; octave <= 6; octave++) {
+          const midi  = (_scale.indexOf(_scale[i]) + 60)
+          const tFreq = 440 * Math.pow(2, (midi - 69) / 12) * Math.pow(2, octave - 4)
+          const cents = Math.abs(1200 * Math.log2(freq / tFreq))
+          if (cents <= centsTolerance) { degree = i; break }
+        }
+        if (degree !== -1) break
+      }
+    }
+
+    return degree === -1 ? null : degree
+  }
+
+  // ── main process function ─────────────────────────────────────────────────
+
+  /**
+   * Call this inside note-listener's onNotes with the notes array.
+   * It will fire onAction for every detected action.
+   *
+   * @param {Array} notes - the notes array from note-listener's onNotes
+   */
+  function process(notes) {
+    if (!notes?.length) return
+
+    // --- interval check (two notes together) ---
+    const interval = processInterval(notes)
+    if (interval) {
+      const action = _intervalActions[interval.semitones]
+      if (action && onAction) {
+        onAction(action, {
+          type: "interval",
+          interval: interval.semitones,
+          notes: interval.notes,
+        })
+      }
+    }
+
+    // --- single note degree check ---
+    const onsets = processOnsets(notes)
+    for (const n of onsets) {
+      const degree = processDegree(n.note, n.freq)
+      if (degree === null) continue
+
+      const action = _degreeActions[degree]
+      if (action && onAction) {
+        onAction(action, {
+          type:   "degree",
+          degree,
+          note:   n.note,
+          freq:   n.freq,
+          cents:  n.cents,
+          energy: n.energy,
+        })
+      }
+    }
+  }
+
+  // ── public API ────────────────────────────────────────────────────────────
+
+  return {
+    process,
+
+    /** swap the scale at runtime e.g. when player changes key */
+    setScale(newScale) {
+      _scale = newScale
+      _heldNotes.clear()
+      _intervalHistory.length = 0
+    },
+
+    /** swap the degree action map at runtime */
+    setDegreeActions(newActions) {
+      _degreeActions = newActions
+    },
+
+    /** swap the interval action map at runtime */
+    setIntervalActions(newActions) {
+      _intervalActions = newActions
+    },
+
+    /** returns which notes are currently being held */
+    getHeldNotes() {
+      return [..._heldNotes]
+    },
+  }
+}

package/src/scales.js

@@ -0,0 +1,301 @@
+/**
+ * scales.js
+ * Complete scale definitions for all 12 keys.
+ * Each scale is an ordered array of pitch classes (no octave numbers).
+ * The order defines the degree — index 0 is always the root.
+ *
+ * Keys: C, C#, D, Eb, E, F, F#, G, Ab, A, Bb, B
+ */
+
+// ─── Pentatonic Minor (5 notes) ──────────────────────────────────────────────
+// Formula: 1 b3 4 5 b7
+
+export const PENTATONIC_MINOR = {
+  "C":  ["C",  "Eb", "F",  "G",  "Bb"],
+  "C#": ["C#", "E",  "F#", "G#", "B"],
+  "D":  ["D",  "F",  "G",  "A",  "C"],
+  "Eb": ["Eb", "Gb", "Ab", "Bb", "Db"],
+  "E":  ["E",  "G",  "A",  "B",  "D"],
+  "F":  ["F",  "Ab", "Bb", "C",  "Eb"],
+  "F#": ["F#", "A",  "B",  "C#", "E"],
+  "G":  ["G",  "Bb", "C",  "D",  "F"],
+  "Ab": ["Ab", "B",  "Db", "Eb", "Gb"],
+  "A":  ["A",  "C",  "D",  "E",  "G"],
+  "Bb": ["Bb", "Db", "Eb", "F",  "Ab"],
+  "B":  ["B",  "D",  "E",  "F#", "A"],
+}
+
+// ─── Pentatonic Major (5 notes) ──────────────────────────────────────────────
+// Formula: 1 2 3 5 6
+
+export const PENTATONIC_MAJOR = {
+  "C":  ["C",  "D",  "E",  "G",  "A"],
+  "C#": ["C#", "D#", "F",  "G#", "A#"],
+  "D":  ["D",  "E",  "F#", "A",  "B"],
+  "Eb": ["Eb", "F",  "G",  "Bb", "C"],
+  "E":  ["E",  "F#", "G#", "B",  "C#"],
+  "F":  ["F",  "G",  "A",  "C",  "D"],
+  "F#": ["F#", "G#", "A#", "C#", "D#"],
+  "G":  ["G",  "A",  "B",  "D",  "E"],
+  "Ab": ["Ab", "Bb", "C",  "Eb", "F"],
+  "A":  ["A",  "B",  "C#", "E",  "F#"],
+  "Bb": ["Bb", "C",  "D",  "F",  "G"],
+  "B":  ["B",  "C#", "D#", "F#", "G#"],
+}
+
+// ─── Blues (6 notes) ─────────────────────────────────────────────────────────
+// Formula: 1 b3 4 b5 5 b7
+
+export const BLUES = {
+  "C":  ["C",  "Eb", "F",  "Gb", "G",  "Bb"],
+  "C#": ["C#", "E",  "F#", "G",  "G#", "B"],
+  "D":  ["D",  "F",  "G",  "Ab", "A",  "C"],
+  "Eb": ["Eb", "Gb", "Ab", "A",  "Bb", "Db"],
+  "E":  ["E",  "G",  "A",  "Bb", "B",  "D"],
+  "F":  ["F",  "Ab", "Bb", "B",  "C",  "Eb"],
+  "F#": ["F#", "A",  "B",  "C",  "C#", "E"],
+  "G":  ["G",  "Bb", "C",  "Db", "D",  "F"],
+  "Ab": ["Ab", "B",  "Db", "D",  "Eb", "Gb"],
+  "A":  ["A",  "C",  "D",  "Eb", "E",  "G"],
+  "Bb": ["Bb", "Db", "Eb", "E",  "F",  "Ab"],
+  "B":  ["B",  "D",  "E",  "F",  "F#", "A"],
+}
+
+// ─── Major / Ionian (7 notes) ────────────────────────────────────────────────
+// Formula: 1 2 3 4 5 6 7
+
+export const MAJOR = {
+  "C":  ["C",  "D",  "E",  "F",  "G",  "A",  "B"],
+  "C#": ["C#", "D#", "F",  "F#", "G#", "A#", "C"],
+  "D":  ["D",  "E",  "F#", "G",  "A",  "B",  "C#"],
+  "Eb": ["Eb", "F",  "G",  "Ab", "Bb", "C",  "D"],
+  "E":  ["E",  "F#", "G#", "A",  "B",  "C#", "D#"],
+  "F":  ["F",  "G",  "A",  "Bb", "C",  "D",  "E"],
+  "F#": ["F#", "G#", "A#", "B",  "C#", "D#", "F"],
+  "G":  ["G",  "A",  "B",  "C",  "D",  "E",  "F#"],
+  "Ab": ["Ab", "Bb", "C",  "Db", "Eb", "F",  "G"],
+  "A":  ["A",  "B",  "C#", "D",  "E",  "F#", "G#"],
+  "Bb": ["Bb", "C",  "D",  "Eb", "F",  "G",  "A"],
+  "B":  ["B",  "C#", "D#", "E",  "F#", "G#", "A#"],
+}
+
+// ─── Natural Minor / Aeolian (7 notes) ───────────────────────────────────────
+// Formula: 1 2 b3 4 5 b6 b7
+
+export const NATURAL_MINOR = {
+  "C":  ["C",  "D",  "Eb", "F",  "G",  "Ab", "Bb"],
+  "C#": ["C#", "D#", "E",  "F#", "G#", "A",  "B"],
+  "D":  ["D",  "E",  "F",  "G",  "A",  "Bb", "C"],
+  "Eb": ["Eb", "F",  "Gb", "Ab", "Bb", "B",  "Db"],
+  "E":  ["E",  "F#", "G",  "A",  "B",  "C",  "D"],
+  "F":  ["F",  "G",  "Ab", "Bb", "C",  "Db", "Eb"],
+  "F#": ["F#", "G#", "A",  "B",  "C#", "D",  "E"],
+  "G":  ["G",  "A",  "Bb", "C",  "D",  "Eb", "F"],
+  "Ab": ["Ab", "Bb", "B",  "Db", "Eb", "E",  "Gb"],
+  "A":  ["A",  "B",  "C",  "D",  "E",  "F",  "G"],
+  "Bb": ["Bb", "C",  "Db", "Eb", "F",  "Gb", "Ab"],
+  "B":  ["B",  "C#", "D",  "E",  "F#", "G",  "A"],
+}
+
+// ─── Dorian (7 notes) ────────────────────────────────────────────────────────
+// Formula: 1 2 b3 4 5 6 b7
+
+export const DORIAN = {
+  "C":  ["C",  "D",  "Eb", "F",  "G",  "A",  "Bb"],
+  "C#": ["C#", "D#", "E",  "F#", "G#", "A#", "B"],
+  "D":  ["D",  "E",  "F",  "G",  "A",  "B",  "C"],
+  "Eb": ["Eb", "F",  "Gb", "Ab", "Bb", "C",  "Db"],
+  "E":  ["E",  "F#", "G",  "A",  "B",  "C#", "D"],
+  "F":  ["F",  "G",  "Ab", "Bb", "C",  "D",  "Eb"],
+  "F#": ["F#", "G#", "A",  "B",  "C#", "D#", "E"],
+  "G":  ["G",  "A",  "Bb", "C",  "D",  "E",  "F"],
+  "Ab": ["Ab", "Bb", "B",  "Db", "Eb", "F",  "Gb"],
+  "A":  ["A",  "B",  "C",  "D",  "E",  "F#", "G"],
+  "Bb": ["Bb", "C",  "Db", "Eb", "F",  "G",  "Ab"],
+  "B":  ["B",  "C#", "D",  "E",  "F#", "G#", "A"],
+}
+
+// ─── Phrygian (7 notes) ──────────────────────────────────────────────────────
+// Formula: 1 b2 b3 4 5 b6 b7
+
+export const PHRYGIAN = {
+  "C":  ["C",  "Db", "Eb", "F",  "G",  "Ab", "Bb"],
+  "C#": ["C#", "D",  "E",  "F#", "G#", "A",  "B"],
+  "D":  ["D",  "Eb", "F",  "G",  "A",  "Bb", "C"],
+  "Eb": ["Eb", "E",  "Gb", "Ab", "Bb", "B",  "Db"],
+  "E":  ["E",  "F",  "G",  "A",  "B",  "C",  "D"],
+  "F":  ["F",  "Gb", "Ab", "Bb", "C",  "Db", "Eb"],
+  "F#": ["F#", "G",  "A",  "B",  "C#", "D",  "E"],
+  "G":  ["G",  "Ab", "Bb", "C",  "D",  "Eb", "F"],
+  "Ab": ["Ab", "A",  "B",  "Db", "Eb", "E",  "Gb"],
+  "A":  ["A",  "Bb", "C",  "D",  "E",  "F",  "G"],
+  "Bb": ["Bb", "B",  "Db", "Eb", "F",  "Gb", "Ab"],
+  "B":  ["B",  "C",  "D",  "E",  "F#", "G",  "A"],
+}
+
+// ─── Lydian (7 notes) ────────────────────────────────────────────────────────
+// Formula: 1 2 3 #4 5 6 7
+
+export const LYDIAN = {
+  "C":  ["C",  "D",  "E",  "F#", "G",  "A",  "B"],
+  "C#": ["C#", "D#", "F",  "G",  "G#", "A#", "C"],
+  "D":  ["D",  "E",  "F#", "G#", "A",  "B",  "C#"],
+  "Eb": ["Eb", "F",  "G",  "A",  "Bb", "C",  "D"],
+  "E":  ["E",  "F#", "G#", "A#", "B",  "C#", "D#"],
+  "F":  ["F",  "G",  "A",  "B",  "C",  "D",  "E"],
+  "F#": ["F#", "G#", "A#", "C",  "C#", "D#", "F"],
+  "G":  ["G",  "A",  "B",  "C#", "D",  "E",  "F#"],
+  "Ab": ["Ab", "Bb", "C",  "D",  "Eb", "F",  "G"],
+  "A":  ["A",  "B",  "C#", "D#", "E",  "F#", "G#"],
+  "Bb": ["Bb", "C",  "D",  "E",  "F",  "G",  "A"],
+  "B":  ["B",  "C#", "D#", "F",  "F#", "G#", "A#"],
+}
+
+// ─── Mixolydian (7 notes) ────────────────────────────────────────────────────
+// Formula: 1 2 3 4 5 6 b7
+
+export const MIXOLYDIAN = {
+  "C":  ["C",  "D",  "E",  "F",  "G",  "A",  "Bb"],
+  "C#": ["C#", "D#", "F",  "F#", "G#", "A#", "B"],
+  "D":  ["D",  "E",  "F#", "G",  "A",  "B",  "C"],
+  "Eb": ["Eb", "F",  "G",  "Ab", "Bb", "C",  "Db"],
+  "E":  ["E",  "F#", "G#", "A",  "B",  "C#", "D"],
+  "F":  ["F",  "G",  "A",  "Bb", "C",  "D",  "Eb"],
+  "F#": ["F#", "G#", "A#", "B",  "C#", "D#", "E"],
+  "G":  ["G",  "A",  "B",  "C",  "D",  "E",  "F"],
+  "Ab": ["Ab", "Bb", "C",  "Db", "Eb", "F",  "Gb"],
+  "A":  ["A",  "B",  "C#", "D",  "E",  "F#", "G"],
+  "Bb": ["Bb", "C",  "D",  "Eb", "F",  "G",  "Ab"],
+  "B":  ["B",  "C#", "D#", "E",  "F#", "G#", "A"],
+}
+
+// ─── Locrian (7 notes) ───────────────────────────────────────────────────────
+// Formula: 1 b2 b3 4 b5 b6 b7
+
+export const LOCRIAN = {
+  "C":  ["C",  "Db", "Eb", "F",  "Gb", "Ab", "Bb"],
+  "C#": ["C#", "D",  "E",  "F#", "G",  "A",  "B"],
+  "D":  ["D",  "Eb", "F",  "G",  "Ab", "Bb", "C"],
+  "Eb": ["Eb", "E",  "Gb", "Ab", "A",  "B",  "Db"],
+  "E":  ["E",  "F",  "G",  "A",  "Bb", "C",  "D"],
+  "F":  ["F",  "Gb", "Ab", "Bb", "B",  "Db", "Eb"],
+  "F#": ["F#", "G",  "A",  "B",  "C",  "D",  "E"],
+  "G":  ["G",  "Ab", "Bb", "C",  "Db", "Eb", "F"],
+  "Ab": ["Ab", "A",  "B",  "Db", "D",  "E",  "Gb"],
+  "A":  ["A",  "Bb", "C",  "D",  "Eb", "F",  "G"],
+  "Bb": ["Bb", "B",  "Db", "Eb", "E",  "Gb", "Ab"],
+  "B":  ["B",  "C",  "D",  "E",  "F",  "G",  "A"],
+}
+
+// ─── Harmonic Minor (7 notes) ────────────────────────────────────────────────
+// Formula: 1 2 b3 4 5 b6 7
+
+export const HARMONIC_MINOR = {
+  "C":  ["C",  "D",  "Eb", "F",  "G",  "Ab", "B"],
+  "C#": ["C#", "D#", "E",  "F#", "G#", "A",  "C"],
+  "D":  ["D",  "E",  "F",  "G",  "A",  "Bb", "C#"],
+  "Eb": ["Eb", "F",  "Gb", "Ab", "Bb", "B",  "D"],
+  "E":  ["E",  "F#", "G",  "A",  "B",  "C",  "D#"],
+  "F":  ["F",  "G",  "Ab", "Bb", "C",  "Db", "E"],
+  "F#": ["F#", "G#", "A",  "B",  "C#", "D",  "F"],
+  "G":  ["G",  "A",  "Bb", "C",  "D",  "Eb", "F#"],
+  "Ab": ["Ab", "Bb", "B",  "Db", "Eb", "E",  "G"],
+  "A":  ["A",  "B",  "C",  "D",  "E",  "F",  "G#"],
+  "Bb": ["Bb", "C",  "Db", "Eb", "F",  "Gb", "A"],
+  "B":  ["B",  "C#", "D",  "E",  "F#", "G",  "A#"],
+}
+
+// ─── Melodic Minor (7 notes) ─────────────────────────────────────────────────
+// Formula: 1 2 b3 4 5 6 7
+
+export const MELODIC_MINOR = {
+  "C":  ["C",  "D",  "Eb", "F",  "G",  "A",  "B"],
+  "C#": ["C#", "D#", "E",  "F#", "G#", "A#", "C"],
+  "D":  ["D",  "E",  "F",  "G",  "A",  "B",  "C#"],
+  "Eb": ["Eb", "F",  "Gb", "Ab", "Bb", "C",  "D"],
+  "E":  ["E",  "F#", "G",  "A",  "B",  "C#", "D#"],
+  "F":  ["F",  "G",  "Ab", "Bb", "C",  "D",  "E"],
+  "F#": ["F#", "G#", "A",  "B",  "C#", "D#", "F"],
+  "G":  ["G",  "A",  "Bb", "C",  "D",  "E",  "F#"],
+  "Ab": ["Ab", "Bb", "B",  "Db", "Eb", "F",  "G"],
+  "A":  ["A",  "B",  "C",  "D",  "E",  "F#", "G#"],
+  "Bb": ["Bb", "C",  "Db", "Eb", "F",  "G",  "A"],
+  "B":  ["B",  "C#", "D",  "E",  "F#", "G#", "A#"],
+}
+
+// ─── Phrygian Dominant (7 notes) ─────────────────────────────────────────────
+// Formula: 1 b2 3 4 5 b6 b7  (Spanish/metal feel)
+
+export const PHRYGIAN_DOMINANT = {
+  "C":  ["C",  "Db", "E",  "F",  "G",  "Ab", "Bb"],
+  "C#": ["C#", "D",  "F",  "F#", "G#", "A",  "B"],
+  "D":  ["D",  "Eb", "F#", "G",  "A",  "Bb", "C"],
+  "Eb": ["Eb", "E",  "G",  "Ab", "Bb", "B",  "Db"],
+  "E":  ["E",  "F",  "G#", "A",  "B",  "C",  "D"],
+  "F":  ["F",  "Gb", "A",  "Bb", "C",  "Db", "Eb"],
+  "F#": ["F#", "G",  "A#", "B",  "C#", "D",  "E"],
+  "G":  ["G",  "Ab", "B",  "C",  "D",  "Eb", "F"],
+  "Ab": ["Ab", "A",  "C",  "Db", "Eb", "E",  "Gb"],
+  "A":  ["A",  "Bb", "C#", "D",  "E",  "F",  "G"],
+  "Bb": ["Bb", "B",  "D",  "Eb", "F",  "Gb", "Ab"],
+  "B":  ["B",  "C",  "D#", "E",  "F#", "G",  "A"],
+}
+
+// ─── Whole Tone (6 notes) ────────────────────────────────────────────────────
+// Formula: all whole steps — only 2 unique versions exist, rest are modes of same scale
+
+export const WHOLE_TONE = {
+  "C":  ["C",  "D",  "E",  "F#", "G#", "A#"],
+  "C#": ["C#", "D#", "F",  "G",  "A",  "B"],
+  "D":  ["D",  "E",  "F#", "G#", "A#", "C"],
+  "Eb": ["Eb", "F",  "G",  "A",  "B",  "C#"],
+  "E":  ["E",  "F#", "G#", "A#", "C",  "D"],
+  "F":  ["F",  "G",  "A",  "B",  "C#", "D#"],
+  "F#": ["F#", "G#", "A#", "C",  "D",  "E"],
+  "G":  ["G",  "A",  "B",  "C#", "D#", "F"],
+  "Ab": ["Ab", "Bb", "C",  "D",  "E",  "F#"],
+  "A":  ["A",  "B",  "C#", "D#", "F",  "G"],
+  "Bb": ["Bb", "C",  "D",  "E",  "F#", "G#"],
+  "B":  ["B",  "C#", "D#", "F",  "G",  "A"],
+}
+
+// ─── Diminished (8 notes) ────────────────────────────────────────────────────
+// Formula: alternating whole and half steps
+
+export const DIMINISHED = {
+  "C":  ["C",  "D",  "Eb", "F",  "Gb", "Ab", "A",  "B"],
+  "C#": ["C#", "D#", "E",  "F#", "G",  "A",  "Bb", "C"],
+  "D":  ["D",  "E",  "F",  "G",  "Ab", "Bb", "B",  "C#"],
+  "Eb": ["Eb", "F",  "Gb", "Ab", "A",  "B",  "C",  "D"],
+  "E":  ["E",  "F#", "G",  "A",  "Bb", "C",  "Db", "D#"],
+  "F":  ["F",  "G",  "Ab", "Bb", "B",  "Db", "D",  "E"],
+  "F#": ["F#", "G#", "A",  "B",  "C",  "D",  "Eb", "F"],
+  "G":  ["G",  "A",  "Bb", "C",  "Db", "Eb", "E",  "F#"],
+  "Ab": ["Ab", "Bb", "B",  "Db", "D",  "E",  "F",  "G"],
+  "A":  ["A",  "B",  "C",  "D",  "Eb", "F",  "F#", "G#"],
+  "Bb": ["Bb", "C",  "Db", "Eb", "E",  "F#", "G",  "A"],
+  "B":  ["B",  "C#", "D",  "E",  "F",  "G",  "Ab", "A#"],
+}
+
+// ─── Convenience lookup ───────────────────────────────────────────────────────
+
+export const SCALES = {
+  "major":              MAJOR,
+  "natural_minor":      NATURAL_MINOR,
+  "pentatonic_minor":   PENTATONIC_MINOR,
+  "pentatonic_major":   PENTATONIC_MAJOR,
+  "blues":              BLUES,
+  "dorian":             DORIAN,
+  "phrygian":           PHRYGIAN,
+  "lydian":             LYDIAN,
+  "mixolydian":         MIXOLYDIAN,
+  "locrian":            LOCRIAN,
+  "harmonic_minor":     HARMONIC_MINOR,
+  "melodic_minor":      MELODIC_MINOR,
+  "phrygian_dominant":  PHRYGIAN_DOMINANT,
+  "whole_tone":         WHOLE_TONE,
+  "diminished":         DIMINISHED,
+}
+
+// list of all valid root keys
+export const KEYS = ["C", "C#", "D", "Eb", "E", "F", "F#", "G", "Ab", "A", "Bb", "B"]