@libraz/libcantus 0.9.3 → 0.9.5

package/dist/{chunk-C5XYKUVG.js → chunk-7EONYVI5.js}

@@ -1,32 +1,34 @@
-import {
-  formatNote,
-  midiToNote,
-  noteToPitchClass,
-  parseNote
-} from "./chunk-DYWFNC4A.js";
 import {
   NAMED_SCALES,
   chordPitchClasses,
   chordToneRole,
   createsHiddenParallelPerfect,
   createsParallelPerfect,
-  createsVoiceCrossing,
   createsVoiceOverlap,
-  exceedsSpacing,
   makeChord,
+  namedScaleMask,
+  requireScaleMask,
   scaleTonesInDegreeOrder
-} from "./chunk-MIWO425M.js";
+} from "./chunk-KBTTEX7Q.js";
 import {
+  InvalidInputError,
+  NoSolutionError,
   assertFiniteNumber,
+  assertFiniteSemitones,
   assertGenerationBudget,
   assertInteger,
-  assertPositiveInt
-} from "./chunk-FBQK3ZQN.js";
+  assertPositiveInt,
+  diatonicLetterOf,
+  formatNote,
+  midiToNote,
+  naturalPitchClassOf,
+  noteToPitchClass,
+  parseNote,
+  pitchClassOf,
+  transposeNote
+} from "./chunk-R2VVFAIN.js";
 
 // src/theory/chordscale/index.ts
-function pitchClass(value) {
-  return (Math.trunc(value) % 12 + 12) % 12;
-}
 function popcount12(mask) {
   let count = 0;
   for (let n = 0; n < 12; n += 1) {
@@ -35,7 +37,7 @@ function popcount12(mask) {
   return count;
 }
 function maskHasPitchClass(mask, scaleRootPc, pc) {
-  const offset = pitchClass(pc - scaleRootPc);
+  const offset = pitchClassOf(pc - scaleRootPc);
   return (mask >> offset & 1) === 1;
 }
 function scaleMatchesChord(chordPcs, scaleMask, scaleRootPc) {
@@ -48,21 +50,51 @@ function scaleMatchesChord(chordPcs, scaleMask, scaleRootPc) {
 }
 var ALIASED_SCALE_NAMES = /* @__PURE__ */ new Set(["major", "naturalMinor"]);
 var HEPTATONIC_SIZE = 7;
+var SCALE_PREFERENCE = [
+  "ionian",
+  "major",
+  "mixolydian",
+  "dorian",
+  "lydian",
+  "aeolian",
+  "naturalMinor",
+  "phrygian",
+  "locrian"
+];
+var IDIOMATIC_SCALES = {
+  aug: ["wholeTone"],
+  m7b5: ["locrian"]
+};
+function conventionalRank(name) {
+  const index = SCALE_PREFERENCE.indexOf(name);
+  return index < 0 ? SCALE_PREFERENCE.length : index;
+}
+function idiomaticRank(chord, name) {
+  const choices = IDIOMATIC_SCALES[chord.quality];
+  if (choices === void 0) {
+    return 0;
+  }
+  const index = choices.indexOf(name);
+  return index < 0 ? choices.length + 1 : index;
+}
+function isAlteredDominant(chord, scaleName) {
+  return chord.quality === "dom7" && scaleName === "altered";
+}
 function chordScales(chord) {
   const chordPcs = chordPitchClasses(chord);
-  const rootPc = pitchClass(chord.rootPc);
+  const rootPc = pitchClassOf(chord.rootPc);
   const ranked = [];
   const seenMasks = /* @__PURE__ */ new Set();
   for (const name of Object.keys(NAMED_SCALES)) {
     if (name === "chromatic" || ALIASED_SCALE_NAMES.has(name)) {
       continue;
     }
-    const mask = NAMED_SCALES[name];
+    const mask = namedScaleMask(name);
     if (mask === void 0 || seenMasks.has(mask)) {
       continue;
     }
     seenMasks.add(mask);
-    if (scaleMatchesChord(chordPcs, mask, rootPc)) {
+    if (scaleMatchesChord(chordPcs, mask, rootPc) || isAlteredDominant(chord, name)) {
       const size = popcount12(mask);
       ranked.push({ name, extra: size - chordPcs.length, size });
     }
@@ -75,27 +107,32 @@ function chordScales(chord) {
   }
   const preferHeptatonic = chordPcs.length <= 3;
   ranked.sort((a, b) => {
+    const idiomaticA = idiomaticRank(chord, a.name);
+    const idiomaticB = idiomaticRank(chord, b.name);
+    if (idiomaticA !== idiomaticB) {
+      return idiomaticA - idiomaticB;
+    }
     if (preferHeptatonic && a.size === HEPTATONIC_SIZE !== (b.size === HEPTATONIC_SIZE)) {
       return a.size === HEPTATONIC_SIZE ? -1 : 1;
     }
     if (a.extra !== b.extra) {
       return a.extra - b.extra;
     }
-    if (a.size !== b.size) {
-      return a.size - b.size;
+    const rankA = conventionalRank(a.name);
+    const rankB = conventionalRank(b.name);
+    if (rankA !== rankB) {
+      return rankA - rankB;
     }
     return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
   });
   return ranked.map((entry) => ({ name: entry.name, rootPc }));
 }
 function avoidNotes(chord, scaleName) {
-  const mask = NAMED_SCALES[scaleName];
-  if (mask === void 0) {
-    return [];
-  }
-  const rootPc = pitchClass(chord.rootPc);
+  const mask = requireScaleMask(scaleName);
+  const rootPc = pitchClassOf(chord.rootPc);
   const chordPcs = chordPitchClasses(chord);
-  if (!scaleMatchesChord(chordPcs, mask, rootPc)) {
+  const alteredDominant = isAlteredDominant(chord, scaleName);
+  if (!scaleMatchesChord(chordPcs, mask, rootPc) && !alteredDominant) {
     return [];
   }
   const chordSet = new Set(chordPcs);
@@ -104,24 +141,23 @@ function avoidNotes(chord, scaleName) {
     if (!maskHasPitchClass(mask, rootPc, pc) || chordSet.has(pc)) {
       continue;
     }
-    if (chordSet.has(pitchClass(pc - 1))) {
+    const suspendedThird = chord.quality === "sus4" || chord.quality === "7sus4" ? pc === pitchClassOf(rootPc + 4) : false;
+    if (!alteredDominant && (chordSet.has(pitchClassOf(pc - 1)) || suspendedThird)) {
       avoid.push(pc);
     }
   }
   return avoid.sort((a, b) => a - b);
 }
 function availableTensions(chord, scaleName) {
-  const mask = NAMED_SCALES[scaleName];
-  if (mask === void 0) {
-    return [];
-  }
-  const rootPc = pitchClass(chord.rootPc);
+  const mask = requireScaleMask(scaleName);
+  const rootPc = pitchClassOf(chord.rootPc);
   const chordPcs = chordPitchClasses(chord);
-  if (!scaleMatchesChord(chordPcs, mask, rootPc)) {
+  const alteredDominant = isAlteredDominant(chord, scaleName);
+  if (!scaleMatchesChord(chordPcs, mask, rootPc) && !alteredDominant) {
     return [];
   }
   const chordSet = new Set(chordPcs);
-  const avoidSet = new Set(avoidNotes(chord, scaleName));
+  const avoidSet = alteredDominant ? /* @__PURE__ */ new Set() : new Set(avoidNotes(chord, scaleName));
   const tensions = [];
   for (let pc = 0; pc < 12; pc += 1) {
     if (!maskHasPitchClass(mask, rootPc, pc) || chordSet.has(pc) || avoidSet.has(pc)) {
@@ -132,8 +168,11 @@ function availableTensions(chord, scaleName) {
   return tensions.sort((a, b) => a - b);
 }
 function chordScaleReport(chord, limit) {
+  if (limit !== void 0) {
+    assertPositiveInt(limit, "chord-scale report limit");
+  }
   const matches = chordScales(chord);
-  const chosen = limit === void 0 ? matches : matches.slice(0, Math.max(0, limit));
+  const chosen = limit === void 0 ? matches : matches.slice(0, limit);
   return chosen.map((match) => ({
     name: match.name,
     rootPc: match.rootPc,
@@ -143,14 +182,14 @@ function chordScaleReport(chord, limit) {
 }
 var RANK_PENALTY = 0.01;
 function scalePitchClassSet(name, rootPc) {
-  const mask = NAMED_SCALES[name];
+  const mask = namedScaleMask(name);
   const pcs = /* @__PURE__ */ new Set();
   if (mask === void 0) {
     return pcs;
   }
   for (let n = 0; n < 12; n += 1) {
     if ((mask >> n & 1) === 1) {
-      pcs.add(pitchClass(rootPc + n));
+      pcs.add(pitchClassOf(rootPc + n));
     }
   }
   return pcs;
@@ -170,6 +209,7 @@ function symmetricDifferenceSize(a, b) {
   return count;
 }
 function scalesForChanges(chords) {
+  assertGenerationBudget(chords.length, "chord-scale changes");
   if (chords.length === 0) {
     return [];
   }
@@ -228,64 +268,123 @@ function scalesForChanges(chords) {
 }
 
 // src/theory/spelling/index.ts
-var LETTER_SEMITONES = [0, 2, 4, 5, 7, 9, 11];
 var CHROMATIC_SPELLING = {
-  1: { degreeOffset: 1, alter: -1 },
+  1: 1,
   // b2
-  3: { degreeOffset: 2, alter: -1 },
+  2: 1,
+  // M2
+  3: 2,
   // b3
-  6: { degreeOffset: 3, alter: 1 },
+  4: 2,
+  // M3
+  5: 3,
+  // P4
+  6: 3,
   // #4
-  8: { degreeOffset: 5, alter: -1 },
+  7: 4,
+  // P5
+  8: 5,
   // b6
-  9: { degreeOffset: 5, alter: 1 },
+  9: 5,
   // #6 (raised sixth of a minor key)
-  10: { degreeOffset: 6, alter: -1 },
+  10: 6,
   // b7
-  11: { degreeOffset: 6, alter: 1 }
+  11: 6
   // #7 (raised leading tone of a minor key)
 };
-function mod12(n) {
-  return (n % 12 + 12) % 12;
-}
-function mod7(n) {
-  return (n % 7 + 7) % 7;
-}
-function naturalPc(letter) {
-  return LETTER_SEMITONES[mod7(letter)] ?? 0;
-}
+var CHROMATIC_SPELLING_FLAT = {
+  ...CHROMATIC_SPELLING,
+  6: 4
+  // b5
+};
+var CHROMATIC_SPELLING_SHARP = {
+  1: 0,
+  // #1
+  2: 1,
+  // M2
+  3: 1,
+  // #2
+  4: 2,
+  // M3
+  5: 3,
+  // P4
+  6: 3,
+  // #4
+  7: 4,
+  // P5
+  8: 4,
+  // #5
+  9: 5,
+  // M6
+  10: 5,
+  // #6
+  11: 6
+  // M7
+};
 function alterFor(letter, pc) {
-  let d = mod12(pc - naturalPc(letter));
+  let d = pitchClassOf(pc - naturalPitchClassOf(letter));
   if (d > 6) {
     d -= 12;
   }
   return d;
 }
+function letterFor(tonic, degreeOffset, pc) {
+  if (degreeOffset === void 0) {
+    return void 0;
+  }
+  const letter = diatonicLetterOf(tonic.letter + degreeOffset);
+  return { letter, alter: alterFor(letter, pc) };
+}
+function pickSpelling(flat, sharp, preferFlat) {
+  if (flat === void 0 || sharp === void 0) {
+    return flat ?? sharp;
+  }
+  if (Math.abs(flat.alter) !== Math.abs(sharp.alter)) {
+    return Math.abs(flat.alter) < Math.abs(sharp.alter) ? flat : sharp;
+  }
+  return preferFlat ? flat : sharp;
+}
+function capChromaticAccidentals(preferred, alternative) {
+  return alternative !== void 0 && Math.abs(preferred.alter) - Math.abs(alternative.alter) >= 2 ? alternative : preferred;
+}
 function isHeptatonic(key) {
   return scaleTonesInDegreeOrder(key).length === 7;
 }
-function spellPitchClass(pc, tonic, key) {
-  const tonicPc = mod12(naturalPc(tonic.letter) + tonic.alter);
-  const offset = mod12(pc - tonicPc);
+function hasMinorThird(key) {
   const tones = scaleTonesInDegreeOrder(key);
-  if (isHeptatonic(key)) {
-    const degree = tones.indexOf(mod12(pc));
+  const root = pitchClassOf(key.rootPc);
+  return tones.includes(pitchClassOf(root + 3)) && !tones.includes(pitchClassOf(root + 4));
+}
+function spellPitchClass(pc, tonic, key) {
+  const tonicPc = pitchClassOf(naturalPitchClassOf(tonic.letter) + tonic.alter);
+  const offset = pitchClassOf(pc - tonicPc);
+  if (offset === 0) {
+    return { letter: diatonicLetterOf(tonic.letter), alter: tonic.alter };
+  }
+  const heptatonic = isHeptatonic(key);
+  if (heptatonic) {
+    const degree = scaleTonesInDegreeOrder(key).indexOf(pitchClassOf(pc));
     if (degree >= 0) {
-      const letter = mod7(tonic.letter + degree);
+      const letter = diatonicLetterOf(tonic.letter + degree);
       return { letter, alter: alterFor(letter, pc) };
     }
-    const chromatic = CHROMATIC_SPELLING[offset];
-    if (chromatic) {
-      const letter = mod7(tonic.letter + chromatic.degreeOffset);
-      return { letter, alter: alterFor(letter, pc) };
+    const degreeOffset = CHROMATIC_SPELLING[offset];
+    const preferred = letterFor(tonic, degreeOffset, pc);
+    if (preferred !== void 0) {
+      const flat = letterFor(tonic, CHROMATIC_SPELLING_FLAT[offset], pc);
+      const sharp = letterFor(tonic, CHROMATIC_SPELLING_SHARP[offset], pc);
+      const alternative = flat?.letter === preferred.letter ? sharp : sharp?.letter === preferred.letter ? flat : void 0;
+      return capChromaticAccidentals(preferred, alternative);
     }
-  }
-  for (let letter = 0; letter < 7; letter += 1) {
-    if (naturalPc(letter) === mod12(pc)) {
-      return { letter, alter: 0 };
+  } else {
+    const flat = letterFor(tonic, CHROMATIC_SPELLING_FLAT[offset], pc);
+    const sharp = letterFor(tonic, CHROMATIC_SPELLING_SHARP[offset], pc);
+    const best = pickSpelling(flat, sharp, tonic.alter < 0 || hasMinorThird(key));
+    if (best !== void 0) {
+      return best;
     }
   }
-  const belowLetter = mod7([0, 0, 1, 1, 2, 3, 3, 4, 4, 5, 5, 6][mod12(pc)] ?? 0);
+  const belowLetter = diatonicLetterOf([0, 0, 1, 1, 2, 3, 3, 4, 4, 5, 5, 6][pitchClassOf(pc)] ?? 0);
   return { letter: belowLetter, alter: alterFor(belowLetter, pc) };
 }
 function spellScale(tonic, key) {
@@ -306,9 +405,10 @@ function chordLetterOffset(interval, chord) {
       return 1;
     case 3:
     case 4:
-    case 15:
     case 16:
       return 2;
+    case 15:
+      return chord.intervals.some((i) => i === 3 || i === 4) ? 1 : 2;
     case 5:
     case 17:
     case 18:
@@ -330,32 +430,48 @@ function chordLetterOffset(interval, chord) {
       return 6;
     default: {
       const octaves = Math.floor(Math.max(0, interval) / 12);
-      const simple = mod12(interval);
+      const simple = pitchClassOf(interval);
       const simpleOffset = [0, 1, 1, 2, 2, 3, 4, 4, 4, 5, 6, 6][simple] ?? 0;
       return octaves * 7 + simpleOffset;
     }
   }
 }
 function spellChordFromRoot(chord, root) {
+  if (pitchClassOf(naturalPitchClassOf(root.letter) + root.alter) !== pitchClassOf(chord.rootPc)) {
+    throw new InvalidInputError("chord root spelling must match chord.rootPc");
+  }
   return chord.intervals.map((interval) => {
-    const letter = mod7(root.letter + chordLetterOffset(interval, chord));
-    const pc = mod12(chord.rootPc + interval);
+    const letter = diatonicLetterOf(root.letter + chordLetterOffset(interval, chord));
+    const pc = pitchClassOf(chord.rootPc + interval);
     return { letter, alter: alterFor(letter, pc) };
   });
 }
 function spellChord(chord, tonic, key) {
-  const root = spellPitchClass(chord.rootPc, tonic, key);
-  return spellChordFromRoot(chord, root);
+  return spellChordFromRoot(chord, chordRootSpelling(chord, tonic, key));
+}
+function chordRootSpelling(chord, tonic, key) {
+  const hint = chord.rootSpelling;
+  if (hint !== void 0 && pitchClassOf(naturalPitchClassOf(hint.letter) + hint.alter) === pitchClassOf(chord.rootPc)) {
+    return { letter: diatonicLetterOf(hint.letter), alter: hint.alter };
+  }
+  return spellPitchClass(chord.rootPc, tonic, key);
+}
+function spellPitch(pitch, tonic, key) {
+  const rounded = Math.round(pitch);
+  const spelled = spellPitchClass(pitchClassOf(rounded), tonic, key);
+  const octave = (rounded - naturalPitchClassOf(spelled.letter) - spelled.alter) / 12 - 1;
+  return { letter: spelled.letter, alter: spelled.alter, octave };
 }
 function noteNames(notes) {
   return notes.map(formatNote);
 }
 
 // src/theory/symbol/index.ts
-var ROOT_RE = /^[A-Ga-g](?:#{1,2}|b{1,2})?/;
-var BASS_RE = /^[A-Ga-g](?:#{1,2}|b{1,2})?$/;
+var ROOT_RE = /^[A-Ga-g](?:#{1,2}|b{1,2}|x)?/;
+var BASS_RE = /^[A-Ga-g](?:#{1,2}|b{1,2}|x)?$/;
 var QUALITY_MAP = {
   "": "maj",
+  maj: "maj",
   m: "min",
   min: "min",
   "-": "min",
@@ -380,6 +496,15 @@ var QUALITY_MAP = {
   mMaj7: "minMaj7",
   mM7: "minMaj7",
   minMaj7: "minMaj7",
+  mMaj9: "minMaj9",
+  mM9: "minMaj9",
+  minMaj9: "minMaj9",
+  mMaj11: "minMaj11",
+  mM11: "minMaj11",
+  minMaj11: "minMaj11",
+  mMaj13: "minMaj13",
+  mM13: "minMaj13",
+  minMaj13: "minMaj13",
   aug7: "aug7",
   "+7": "aug7",
   "7#5": "aug7",
@@ -411,7 +536,36 @@ var QUALITY_MAP = {
   "7b13": "7b13",
   "11": "11",
   "13": "13",
-  "5": "5"
+  "5": "5",
+  "7sus4": "7sus4",
+  "7sus": "7sus4",
+  "9sus4": "11",
+  "9sus": "11",
+  "7b5": "7b5",
+  "7alt": "7alt",
+  alt: "7alt",
+  "13b9": "13b9",
+  maj13: "maj13",
+  M13: "maj13",
+  "maj7#11": "maj7#11",
+  "M7#11": "maj7#11",
+  m11: "min11",
+  min11: "min11",
+  m13: "min13",
+  min13: "min13",
+  madd9: "minAdd9",
+  "min(add9)": "minAdd9",
+  "m(add9)": "minAdd9",
+  "6add9": "6/9",
+  "m6/9": "min6/9",
+  m69: "min6/9",
+  "min6/9": "min6/9",
+  // ASCII stand-ins for the degree and half-diminished glyphs, which most
+  // lead sheets and chord-chart text files use instead of the typographic ones.
+  o: "dim",
+  o7: "dim7",
+  h: "m7b5",
+  h7: "m7b5"
 };
 var CANONICAL_SUFFIX = {
   maj: "",
@@ -424,6 +578,9 @@ var CANONICAL_SUFFIX = {
   dim7: "dim7",
   m7b5: "m7b5",
   minMaj7: "mMaj7",
+  minMaj9: "mMaj9",
+  minMaj11: "mMaj11",
+  minMaj13: "mMaj13",
   aug7: "aug7",
   augMaj7: "augMaj7",
   majb5: "maj(b5)",
@@ -443,10 +600,20 @@ var CANONICAL_SUFFIX = {
   "7b13": "7b13",
   "11": "11",
   "13": "13",
-  "5": "5"
+  "5": "5",
+  "7sus4": "7sus4",
+  "7b5": "7b5",
+  "7alt": "7alt",
+  "13b9": "13b9",
+  maj13: "maj13",
+  "maj7#11": "maj7#11",
+  min11: "m11",
+  min13: "m13",
+  minAdd9: "madd9",
+  "min6/9": "m6/9"
 };
-function pitchClass2(value) {
-  return (Math.trunc(value) % 12 + 12) % 12;
+function knownQuality(suffix) {
+  return Object.hasOwn(QUALITY_MAP, suffix) ? QUALITY_MAP[suffix] : void 0;
 }
 function makeSpelledChord(root, quality, bass) {
   const chord = makeChord(
@@ -461,10 +628,10 @@ function makeSpelledChord(root, quality, bass) {
   return chord;
 }
 function parseChordSymbol(text) {
-  const trimmed = text.trim();
+  const trimmed = text.trim().replaceAll("\u266F", "#").replaceAll("\u266D", "b").replaceAll("\u{1D12A}", "x").replaceAll("\u{1D12B}", "bb");
   const rootMatch = ROOT_RE.exec(trimmed);
   if (!rootMatch) {
-    throw new Error(`Invalid chord symbol: ${text}`);
+    throw new InvalidInputError(`Invalid chord symbol: ${text}`);
   }
   const rootToken = rootMatch[0];
   const rootNote = parseNote(rootToken);
@@ -473,39 +640,57 @@ function parseChordSymbol(text) {
   if (slashIndex !== -1) {
     const before = rest.slice(0, slashIndex);
     const after = rest.slice(slashIndex + 1);
-    const beforeQuality = QUALITY_MAP[before];
+    const beforeQuality = knownQuality(before);
     if (beforeQuality !== void 0 && BASS_RE.test(after)) {
       return makeSpelledChord(rootNote, beforeQuality, parseNote(after));
     }
   }
-  const quality = QUALITY_MAP[rest];
+  const quality = knownQuality(rest);
   if (quality === void 0) {
-    throw new Error(`Unrecognized chord quality: ${text}`);
+    throw new InvalidInputError(`Unrecognized chord quality: ${text}`);
   }
   return makeSpelledChord(rootNote, quality);
 }
-function pitchClassName(pc, hint, flats) {
+function pitchClassName(pc, hint, flats, inheritFlats) {
   if (flats === void 0 && hint !== void 0 && noteToPitchClass(hint) === pc) {
     return formatNote(hint);
   }
-  const note = midiToNote(60 + pc, flats ? "flat" : "sharp");
+  const note = midiToNote(60 + pc, flats ?? inheritFlats ? "flat" : "sharp");
   return formatNote({ letter: note.letter, alter: note.alter });
 }
 function formatChordSymbol(chord, opts) {
-  const rootPc = pitchClass2(chord.rootPc);
-  const rootName = pitchClassName(rootPc, chord.rootSpelling, opts?.flats);
+  assertFiniteNumber(chord.rootPc, "chord rootPc");
+  if (chord.bassPc !== void 0) {
+    assertFiniteNumber(chord.bassPc, "chord bassPc");
+  }
+  if (!Object.hasOwn(CANONICAL_SUFFIX, chord.quality)) {
+    throw new InvalidInputError(`Unknown chord quality: ${String(chord.quality)}`);
+  }
+  const rootPc = pitchClassOf(chord.rootPc);
+  const rootHint = chord.rootSpelling;
+  const rootName = pitchClassName(rootPc, rootHint, opts?.flats);
   const suffix = CANONICAL_SUFFIX[chord.quality];
   let symbol = `${rootName}${suffix}`;
-  if (chord.bassPc !== void 0 && pitchClass2(chord.bassPc) !== rootPc) {
-    symbol += `/${pitchClassName(pitchClass2(chord.bassPc), chord.bassSpelling, opts?.flats)}`;
+  if (chord.bassPc !== void 0 && pitchClassOf(chord.bassPc) !== rootPc) {
+    const inheritFlats = rootHint !== void 0 && noteToPitchClass(rootHint) === rootPc ? rootHint.alter < 0 : void 0;
+    symbol += `/${pitchClassName(pitchClassOf(chord.bassPc), chord.bassSpelling, opts?.flats, inheritFlats)}`;
   }
   return symbol;
 }
 function transposeChordSymbol(text, semitones, opts) {
+  assertFiniteSemitones(semitones);
   const chord = parseChordSymbol(text);
-  const transposed = { ...chord, rootPc: pitchClass2(chord.rootPc + semitones) };
+  const transposed = { ...chord, rootPc: pitchClassOf(chord.rootPc + semitones) };
+  if (chord.rootSpelling !== void 0) {
+    const hint = transposeNote(chord.rootSpelling, semitones);
+    transposed.rootSpelling = { letter: hint.letter, alter: hint.alter };
+  }
   if (chord.bassPc !== void 0) {
-    transposed.bassPc = pitchClass2(chord.bassPc + semitones);
+    transposed.bassPc = pitchClassOf(chord.bassPc + semitones);
+  }
+  if (chord.bassSpelling !== void 0) {
+    const hint = transposeNote(chord.bassSpelling, semitones);
+    transposed.bassSpelling = { letter: hint.letter, alter: hint.alter };
   }
   return formatChordSymbol(transposed, opts);
 }
@@ -514,15 +699,17 @@ function transposeChordSymbol(text, semitones, opts) {
 var DEFAULT_MAX_SPACING = 12;
 var VIOLATION_PENALTY = 1e3;
 var MISSING_TONE_PENALTY = 500;
+var MISSING_FIFTH_PENALTY = 20;
 var POOR_DOUBLING_PENALTY = 4;
-var MAX_CANDIDATES = 4e3;
-function pitchClass3(value) {
-  return (Math.trunc(value) % 12 + 12) % 12;
-}
+var UNISON_PENALTY = 100;
+var LEADING_TONE_DOUBLING_PENALTY = 200;
+var RESOLUTION_PENALTY = 200;
+var DEFAULT_MAX_CANDIDATES = 4e3;
+var SEARCH_NODES_PER_CANDIDATE = 16;
 function pitchesForPc(pc, range) {
   const result = [];
   for (let midi = Math.ceil(range.min); midi <= range.max; midi += 1) {
-    if (pitchClass3(midi) === pc) {
+    if (pitchClassOf(midi) === pc) {
       result.push(midi);
     }
   }
@@ -533,67 +720,115 @@ function pitchesForPc(pc, range) {
     return da === db ? a - b : da - db;
   });
 }
-function enumerateVoicings(chord, ranges, maxSpacing) {
+function enumerateVoicings(chord, ranges, maxSpacing, maxCandidates = DEFAULT_MAX_CANDIDATES) {
   const chordPcs = chordPitchClasses(chord);
-  const bassPc = pitchClass3(chord.bassPc ?? chord.rootPc);
+  const bassPc = pitchClassOf(chord.bassPc ?? chord.rootPc);
+  const byVoice = ranges.map(
+    (range, voice) => (voice === 0 ? [bassPc] : chordPcs).flatMap((pc) => pitchesForPc(pc, range))
+  );
+  for (let voice = 0; voice < byVoice.length; voice += 1) {
+    if ((byVoice[voice] ?? []).length === 0) {
+      throw new NoSolutionError("no voicing satisfies the given ranges");
+    }
+  }
   const results = [];
   const current = [];
+  let nodes = 0;
+  const maxSearchNodes = maxCandidates * SEARCH_NODES_PER_CANDIDATE;
   const build = (voice) => {
-    if (results.length >= MAX_CANDIDATES) {
+    nodes += 1;
+    if (results.length >= maxCandidates || nodes > maxSearchNodes) {
       return;
     }
     if (voice === ranges.length) {
       results.push([...current]);
       return;
     }
-    const range = ranges[voice];
-    if (range === void 0) {
-      return;
-    }
-    const pcs = voice === 0 ? [bassPc] : chordPcs;
     const prev = current[voice - 1];
-    for (const pc of pcs) {
-      for (const pitch of pitchesForPc(pc, range)) {
-        if (prev !== void 0) {
-          if (pitch < prev) {
-            continue;
-          }
-          const spacingLimit = voice === 1 ? maxSpacing + 12 : maxSpacing;
-          if (pitch - prev > spacingLimit) {
-            continue;
-          }
+    for (const pitch of byVoice[voice] ?? []) {
+      if (prev !== void 0) {
+        if (pitch < prev) {
+          continue;
+        }
+        const spacingLimit = voice === 1 ? maxSpacing + 12 : maxSpacing;
+        if (pitch - prev > spacingLimit) {
+          continue;
         }
-        current.push(pitch);
-        build(voice + 1);
-        current.pop();
       }
+      current.push(pitch);
+      build(voice + 1);
+      current.pop();
     }
   };
   build(0);
   return results;
 }
-function structuralPenalty(pitches, chord) {
+function structuralPenalty(pitches, chord, key) {
   const counts = /* @__PURE__ */ new Map();
   for (const pitch of pitches) {
-    const pc = pitchClass3(pitch);
+    const pc = pitchClassOf(pitch);
     counts.set(pc, (counts.get(pc) ?? 0) + 1);
   }
   let penalty = 0;
+  for (let index = 1; index < pitches.length; index += 1) {
+    if (pitches[index] === pitches[index - 1]) {
+      penalty += UNISON_PENALTY;
+    }
+  }
   for (const pc of chordPitchClasses(chord)) {
     if (!counts.has(pc)) {
-      penalty += MISSING_TONE_PENALTY;
+      penalty += chordToneRole(pc, chord) === "fifth" ? MISSING_FIFTH_PENALTY : MISSING_TONE_PENALTY;
     }
   }
-  const rootPc = pitchClass3(chord.rootPc);
-  const fifthPc = pitchClass3(chord.rootPc + 7);
+  const rootPc = pitchClassOf(chord.rootPc);
+  const leadingTonePc = key === void 0 ? void 0 : pitchClassOf(key.rootPc - 1);
   for (const [pc, count] of counts) {
-    if (count > 1 && pc !== rootPc && pc !== fifthPc) {
+    if (count <= 1) {
+      continue;
+    }
+    if (pc === leadingTonePc) {
+      penalty += (count - 1) * LEADING_TONE_DOUBLING_PENALTY;
+      continue;
+    }
+    if (pc !== rootPc && chordToneRole(pc, chord) !== "fifth") {
       penalty += (count - 1) * POOR_DOUBLING_PENALTY;
     }
   }
   return penalty;
 }
-function violationCount(prev, cur, maxSpacing) {
+function seventhPcOf(chord) {
+  for (const interval of chord.intervals) {
+    const pc = pitchClassOf(chord.rootPc + interval);
+    if (chordToneRole(pc, chord) === "seventh") {
+      return pc;
+    }
+  }
+  return void 0;
+}
+function resolutionViolations(prev, cur, prevChord, nextChord, key) {
+  const seventhPc = seventhPcOf(prevChord);
+  const leadingTonePc = key === void 0 ? void 0 : pitchClassOf(key.rootPc - 1);
+  const tonicPc = key === void 0 ? void 0 : pitchClassOf(key.rootPc);
+  const nextPcs = new Set(chordPitchClasses(nextChord));
+  let count = 0;
+  for (let voice = 0; voice < prev.length && voice < cur.length; voice += 1) {
+    const from = prev[voice];
+    const to = cur[voice];
+    if (from === void 0 || to === void 0) {
+      continue;
+    }
+    const fromPc = pitchClassOf(from);
+    const motion = to - from;
+    if (fromPc === seventhPc && !nextPcs.has(fromPc) && motion !== -1 && motion !== -2) {
+      count += 1;
+    }
+    if (fromPc === leadingTonePc && tonicPc !== void 0 && nextPcs.has(tonicPc) && !nextPcs.has(fromPc) && motion !== 1) {
+      count += 1;
+    }
+  }
+  return count;
+}
+function violationCount(prev, cur) {
   let count = 0;
   for (let lower = 0; lower < cur.length; lower += 1) {
     for (let upper = lower + 1; upper < cur.length; upper += 1) {
@@ -607,16 +842,10 @@ function violationCount(prev, cur, maxSpacing) {
       if (createsParallelPerfect(prevUpper, curUpper, prevLower, curLower)) {
         count += 1;
       }
-      if (createsVoiceCrossing(curUpper, curLower)) {
-        count += 1;
-      }
       if (upper === lower + 1) {
         if (createsVoiceOverlap(prevUpper, curUpper, prevLower, curLower)) {
           count += 1;
         }
-        if (lower > 0 && exceedsSpacing(curUpper, curLower, maxSpacing)) {
-          count += 1;
-        }
       }
     }
   }
@@ -650,48 +879,70 @@ function voiceLeadingCost(from, to) {
   return total;
 }
 function nextVoicing(current, chord, opts) {
-  const ranges = opts?.ranges !== void 0 || opts?.voices !== void 0 ? resolveRanges(opts) : current.map((pitch) => {
+  const derived = opts?.ranges === void 0 && opts?.voices === void 0;
+  if (derived) {
+    if (current.length === 0) {
+      throw new InvalidInputError("current must contain at least one pitch");
+    }
+    for (let index = 0; index < current.length; index += 1) {
+      assertFiniteNumber(current[index] ?? Number.NaN, `current[${index}]`);
+    }
+  }
+  const ranges = derived ? current.map((pitch) => {
     const centre = Math.min(127, Math.max(0, pitch));
     return { min: Math.max(0, centre - 12), max: Math.min(127, centre + 12) };
+  }) : resolveRanges(opts);
+  for (let index = 0; index < current.length; index += 1) {
+    assertFiniteNumber(current[index] ?? Number.NaN, `current[${index}]`);
+  }
+  if (current.length < ranges.length) {
+    throw new InvalidInputError(
+      `current has ${current.length} voices but the requested ranges require ${ranges.length}`
+    );
+  }
+  const source = current.length === ranges.length ? current : ranges.length === 1 ? [current[0] ?? Number.NaN] : ranges.map((_, index) => {
+    const sourceIndex = Math.round(index * (current.length - 1) / (ranges.length - 1));
+    return current[sourceIndex] ?? Number.NaN;
   });
-  const maxSpacing = opts?.maxSpacing ?? DEFAULT_MAX_SPACING;
-  const candidates = enumerateVoicings(chord, ranges, maxSpacing);
+  const maxSpacing = resolveMaxSpacing(opts);
+  const candidates = enumerateVoicings(chord, ranges, maxSpacing, resolveMaxCandidates(opts));
+  const previousChord = opts?.previousChord;
   let best;
   let bestScore = Number.POSITIVE_INFINITY;
   for (const candidate of candidates) {
-    const score = structuralPenalty(candidate, chord) + voiceLeadingCost(current, candidate) + VIOLATION_PENALTY * violationCount(current, candidate, maxSpacing);
+    const score = structuralPenalty(candidate, chord, opts?.key) + voiceLeadingCost(source, candidate) + VIOLATION_PENALTY * violationCount(source, candidate) + RESOLUTION_PENALTY * (previousChord === void 0 ? 0 : resolutionViolations(source, candidate, previousChord, chord, opts?.key));
     if (score < bestScore) {
       bestScore = score;
       best = candidate;
     }
   }
   if (best === void 0) {
-    throw new Error("no voicing satisfies the given ranges");
+    throw new NoSolutionError("no voicing satisfies the given ranges");
   }
   return best;
 }
 
 // src/theory/voicing/satb.ts
-var SATB_RANGES = [
-  { min: 40, max: 60 },
-  { min: 48, max: 67 },
-  { min: 55, max: 74 },
-  { min: 60, max: 79 }
-];
+var SATB_RANGES = Object.freeze([
+  Object.freeze({ min: 40, max: 60 }),
+  Object.freeze({ min: 48, max: 67 }),
+  Object.freeze({ min: 55, max: 74 }),
+  Object.freeze({ min: 60, max: 79 })
+]);
 var DERIVED_LOW = 40;
 var DERIVED_HIGH = 79;
 var DERIVED_SPAN = 19;
 function resolveRanges(opts) {
   if (opts?.ranges !== void 0) {
     if (opts.ranges.length === 0) {
-      throw new Error("ranges must contain at least one voice range");
+      throw new InvalidInputError("ranges must contain at least one voice range");
     }
     assertGenerationBudget(opts.ranges.length, "voice ranges", 128);
     return opts.ranges.map((range, index) => {
       assertFiniteNumber(range.min, `ranges[${index}].min`);
       assertFiniteNumber(range.max, `ranges[${index}].max`);
       if (range.min > range.max) {
-        throw new RangeError(`ranges[${index}].min must not exceed max`);
+        throw new InvalidInputError(`ranges[${index}].min must not exceed max`);
       }
       assertGenerationBudget(
         Math.floor(range.max) - Math.ceil(range.min) + 1,
@@ -718,16 +969,27 @@ function resolveRanges(opts) {
   }
   return ranges;
 }
-function voiceChord(chord, opts) {
-  const ranges = resolveRanges(opts);
+function resolveMaxSpacing(opts) {
   const maxSpacing = opts?.maxSpacing ?? DEFAULT_MAX_SPACING;
   assertFiniteNumber(maxSpacing, "maxSpacing");
-  if (maxSpacing < 0) throw new RangeError("maxSpacing must be non-negative");
-  const candidates = enumerateVoicings(chord, ranges, maxSpacing);
+  if (maxSpacing < 0) {
+    throw new InvalidInputError("maxSpacing must be non-negative");
+  }
+  return maxSpacing;
+}
+function resolveMaxCandidates(opts) {
+  if (opts?.maxCandidates === void 0) return void 0;
+  assertPositiveInt(opts.maxCandidates, "maxCandidates", 1e6);
+  return opts.maxCandidates;
+}
+function voiceChord(chord, opts) {
+  const ranges = resolveRanges(opts);
+  const maxSpacing = resolveMaxSpacing(opts);
+  const candidates = enumerateVoicings(chord, ranges, maxSpacing, resolveMaxCandidates(opts));
   let best;
   let bestScore = Number.POSITIVE_INFINITY;
   for (const candidate of candidates) {
-    let score = structuralPenalty(candidate, chord);
+    let score = structuralPenalty(candidate, chord, opts?.key);
     for (let i = 0; i < candidate.length; i += 1) {
       const pitch = candidate[i];
       const range = ranges[i];
@@ -742,39 +1004,68 @@ function voiceChord(chord, opts) {
     }
   }
   if (best === void 0) {
-    throw new Error("no voicing satisfies the given ranges");
+    throw new NoSolutionError(
+      `no voicing satisfies the given ranges for ${formatChordSymbol(chord)}`
+    );
   }
   return best;
 }
+function noSolutionAt(index, chord) {
+  return new NoSolutionError(
+    `no voicing satisfies the given ranges for ${formatChordSymbol(chord)} at index ${index}`,
+    { at: index }
+  );
+}
+function locate(index, chord, work) {
+  try {
+    return work();
+  } catch (error) {
+    if (error instanceof NoSolutionError) {
+      throw noSolutionAt(index, chord);
+    }
+    throw error;
+  }
+}
 function voiceProgression(chords, opts) {
-  assertGenerationBudget(chords.length * 4e3, "voiced progression search");
+  assertGenerationBudget(chords.length, "voiced progression chords", opts?.budget);
   const ranges = resolveRanges(opts);
-  const maxSpacing = opts?.maxSpacing ?? DEFAULT_MAX_SPACING;
-  assertFiniteNumber(maxSpacing, "maxSpacing");
-  if (maxSpacing < 0) throw new RangeError("maxSpacing must be non-negative");
+  const maxSpacing = resolveMaxSpacing(opts);
+  const maxCandidates = resolveMaxCandidates(opts);
   const result = [];
   let prev;
-  for (const chord of chords) {
+  let prevChord;
+  for (let index = 0; index < chords.length; index += 1) {
+    const chord = chords[index];
+    if (chord === void 0) {
+      continue;
+    }
     if (prev === void 0) {
-      prev = voiceChord(chord, opts);
+      prev = locate(index, chord, () => voiceChord(chord, opts));
+      prevChord = chord;
       result.push(prev);
       continue;
     }
-    const candidates = enumerateVoicings(chord, ranges, maxSpacing);
+    const candidates = locate(
+      index,
+      chord,
+      () => enumerateVoicings(chord, ranges, maxSpacing, maxCandidates)
+    );
     let best;
     let bestScore = Number.POSITIVE_INFINITY;
     for (const candidate of candidates) {
-      const score = structuralPenalty(candidate, chord) + voiceLeadingCost(prev, candidate) + VIOLATION_PENALTY * violationCount(prev, candidate, maxSpacing);
+      const unresolved = prevChord === void 0 ? 0 : resolutionViolations(prev, candidate, prevChord, chord, opts?.key);
+      const score = structuralPenalty(candidate, chord, opts?.key) + voiceLeadingCost(prev, candidate) + VIOLATION_PENALTY * violationCount(prev, candidate) + RESOLUTION_PENALTY * unresolved;
       if (score < bestScore) {
         bestScore = score;
         best = candidate;
       }
     }
     if (best === void 0) {
-      throw new Error("no voicing satisfies the given ranges");
+      throw noSolutionAt(index, chord);
     }
     result.push(best);
     prev = best;
+    prevChord = chord;
   }
   return result;
 }
@@ -793,7 +1084,7 @@ function dedupePcs(pcs) {
   return result;
 }
 function lowestPitchAtOrAbove(pc, floor) {
-  return floor + ((pc - pitchClass3(floor)) % 12 + 12) % 12;
+  return floor + ((pc - pitchClassOf(floor)) % 12 + 12) % 12;
 }
 function nearestPc(target, pcs) {
   let best = pcs[0] ?? target;
@@ -815,10 +1106,10 @@ function voiceChordStyled(chord, opts) {
     assertFiniteNumber(opts.topNote, "styled voicing topNote");
   }
   const base = 12 * (octave + 1);
-  const rootPc = pitchClass3(chord.rootPc);
-  const bassPc = pitchClass3(chord.bassPc ?? chord.rootPc);
+  const rootPc = pitchClassOf(chord.rootPc);
+  const bassPc = pitchClassOf(chord.bassPc ?? chord.rootPc);
   const omitRoot = style === "rootless" || opts?.rootless === true;
-  let order = dedupePcs(chord.intervals.map((interval) => pitchClass3(chord.rootPc + interval)));
+  let order = dedupePcs(chord.intervals.map((interval) => pitchClassOf(chord.rootPc + interval)));
   const bassIndex = order.indexOf(bassPc);
   if (bassIndex > 0) {
     order = [...order.slice(bassIndex), ...order.slice(0, bassIndex)];
@@ -840,7 +1131,7 @@ function voiceChordStyled(chord, opts) {
     return [];
   }
   if (opts?.topNote !== void 0) {
-    const target = order.includes(pitchClass3(opts.topNote)) ? pitchClass3(opts.topNote) : nearestPc(pitchClass3(opts.topNote), order);
+    const target = order.includes(pitchClassOf(opts.topNote)) ? pitchClassOf(opts.topNote) : nearestPc(pitchClassOf(opts.topNote), order);
     const targetIndex = order.indexOf(target);
     order = [...order.slice(targetIndex + 1), ...order.slice(0, targetIndex + 1)];
   }
@@ -850,7 +1141,7 @@ function voiceChordStyled(chord, opts) {
     if (prev === void 0) {
       prev = lowestPitchAtOrAbove(pc, base);
     } else {
-      let delta = ((pc - pitchClass3(prev)) % 12 + 12) % 12;
+      let delta = ((pc - pitchClassOf(prev)) % 12 + 12) % 12;
       if (delta === 0) {
         delta = 12;
       }
@@ -864,7 +1155,7 @@ function voiceChordStyled(chord, opts) {
     stack[stack.length - 3] = (stack[stack.length - 3] ?? 0) - 12;
   }
   if (chord.bassPc !== void 0) {
-    const bassIndexInStack = stack.findIndex((pitch) => pitchClass3(pitch) === bassPc);
+    const bassIndexInStack = stack.findIndex((pitch) => pitchClassOf(pitch) === bassPc);
     if (bassIndexInStack >= 0) {
       const otherLowest = Math.min(
         ...stack.filter((_pitch, index) => index !== bassIndexInStack),
@@ -875,7 +1166,15 @@ function voiceChordStyled(chord, opts) {
       }
     }
   }
-  return stack.sort((a, b) => a - b);
+  const voicing = stack.sort((a, b) => a - b);
+  const lowest = voicing[0] ?? 0;
+  const highest = voicing[voicing.length - 1] ?? 0;
+  if (lowest < 0 || highest > 127) {
+    throw new InvalidInputError(
+      `styled voicing at octave ${octave} spans MIDI ${lowest}..${highest}, outside 0..127`
+    );
+  }
+  return voicing;
 }
 
 export {
@@ -890,6 +1189,7 @@ export {
   spellPitchClasses,
   spellChordFromRoot,
   spellChord,
+  spellPitch,
   noteNames,
   parseChordSymbol,
   formatChordSymbol,
@@ -901,4 +1201,4 @@ export {
   nextVoicing,
   voiceChordStyled
 };
-//# sourceMappingURL=chunk-C5XYKUVG.js.map
+//# sourceMappingURL=chunk-7EONYVI5.js.map