@libraz/libcantus 0.9.3 → 0.9.4

package/dist/{chunk-C5XYKUVG.js → chunk-RK35RIN7.js}

@@ -1,32 +1,32 @@
-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-D2FAJBYL.js";
 import {
+  InvalidInputError,
+  NoSolutionError,
   assertFiniteNumber,
   assertGenerationBudget,
   assertInteger,
-  assertPositiveInt
-} from "./chunk-FBQK3ZQN.js";
+  assertPositiveInt,
+  diatonicLetterOf,
+  formatNote,
+  midiToNote,
+  naturalPitchClassOf,
+  noteToPitchClass,
+  parseNote,
+  pitchClassOf
+} from "./chunk-XEBG3G53.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 +35,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,16 +48,31 @@ 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"
+];
+function conventionalRank(name) {
+  const index = SCALE_PREFERENCE.indexOf(name);
+  return index < 0 ? SCALE_PREFERENCE.length : index;
+}
 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;
     }
@@ -84,16 +99,18 @@ function chordScales(chord) {
     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)) {
     return [];
@@ -104,18 +121,15 @@ function avoidNotes(chord, scaleName) {
     if (!maskHasPitchClass(mask, rootPc, pc) || chordSet.has(pc)) {
       continue;
     }
-    if (chordSet.has(pitchClass(pc - 1))) {
+    if (chordSet.has(pitchClassOf(pc - 1))) {
       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)) {
     return [];
@@ -143,14 +157,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;
@@ -228,64 +242,117 @@ 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 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);
+    const degreeOffset = CHROMATIC_SPELLING[offset];
+    if (degreeOffset !== void 0) {
+      const letter = diatonicLetterOf(tonic.letter + degreeOffset);
       return { letter, alter: alterFor(letter, pc) };
     }
-  }
-  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 +373,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,7 +398,7 @@ 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;
     }
@@ -338,14 +406,26 @@ function chordLetterOffset(interval, chord) {
 }
 function spellChordFromRoot(chord, root) {
   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);
@@ -411,7 +491,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: "",
@@ -443,10 +552,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(
@@ -464,7 +583,7 @@ function parseChordSymbol(text) {
   const trimmed = text.trim();
   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 +592,48 @@ 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) {
   const chord = parseChordSymbol(text);
-  const transposed = { ...chord, rootPc: pitchClass2(chord.rootPc + semitones) };
+  const transposed = { ...chord, rootPc: pitchClassOf(chord.rootPc + semitones) };
   if (chord.bassPc !== void 0) {
-    transposed.bassPc = pitchClass2(chord.bassPc + semitones);
+    transposed.bassPc = pitchClassOf(chord.bassPc + semitones);
   }
   return formatChordSymbol(transposed, opts);
 }
@@ -514,15 +642,16 @@ 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 LEADING_TONE_DOUBLING_PENALTY = 200;
+var RESOLUTION_PENALTY = 40;
 var MAX_CANDIDATES = 4e3;
-function pitchClass3(value) {
-  return (Math.trunc(value) % 12 + 12) % 12;
-}
+var MAX_SEARCH_NODES = MAX_CANDIDATES * 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);
     }
   }
@@ -535,65 +664,107 @@ function pitchesForPc(pc, range) {
 }
 function enumerateVoicings(chord, ranges, maxSpacing) {
   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 build = (voice) => {
-    if (results.length >= MAX_CANDIDATES) {
+    nodes += 1;
+    if (results.length >= MAX_CANDIDATES || nodes > MAX_SEARCH_NODES) {
       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 (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 +778,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 +815,57 @@ 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) };
-  });
-  const maxSpacing = opts?.maxSpacing ?? DEFAULT_MAX_SPACING;
+  }) : resolveRanges(opts);
+  const maxSpacing = resolveMaxSpacing(opts);
   const candidates = enumerateVoicings(chord, ranges, maxSpacing);
   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(current, candidate) + VIOLATION_PENALTY * violationCount(current, candidate);
     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 +892,22 @@ 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");
+  if (maxSpacing < 0) {
+    throw new InvalidInputError("maxSpacing must be non-negative");
+  }
+  return maxSpacing;
+}
+function voiceChord(chord, opts) {
+  const ranges = resolveRanges(opts);
+  const maxSpacing = resolveMaxSpacing(opts);
   const candidates = enumerateVoicings(chord, ranges, maxSpacing);
   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 +922,63 @@ 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 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));
     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 +997,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 +1019,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 +1044,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 +1054,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 +1068,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 +1079,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 +1102,7 @@ export {
   spellPitchClasses,
   spellChordFromRoot,
   spellChord,
+  spellPitch,
   noteNames,
   parseChordSymbol,
   formatChordSymbol,
@@ -901,4 +1114,4 @@ export {
   nextVoicing,
   voiceChordStyled
 };
-//# sourceMappingURL=chunk-C5XYKUVG.js.map
+//# sourceMappingURL=chunk-RK35RIN7.js.map