@libraz/libcantus 1.0.1 → 1.2.0

package/dist/{chunk-INHVXP6Z.js → chunk-RFIBF2RR.js}

@@ -1,33 +1,43 @@
 import {
   InvalidInputError,
+  MAX_NAME_ACCIDENTALS,
+  assertArray,
   assertDegree,
   assertFiniteNumber,
   assertFiniteSemitones,
+  assertFlag,
   assertGenerationBudget,
   assertInteger,
   assertMidiPitch,
   assertOneOf,
+  assertOptions,
+  assertPitchClass,
+  assertRecord,
   clampToMidi,
+  describeRejected,
   diatonicLetterOf,
   formatNote,
   isConsonantInterval,
+  maxNoteNameLength,
   midiToNote,
   naturalPitchClassOf,
   noteToMidi,
   noteToPitchClass,
   parseFailure,
-  parseKeyName,
   parseNote,
   pitchClassOf,
   spelledInterval,
   toNoteData,
+  transposeByInterval,
   transposeNote,
+  tryParseKeyName,
   tryParseNote,
   unwrapParse
-} from "./chunk-VTI6FOLB.js";
+} from "./chunk-AGOVW7U6.js";
 
 // src/theory/scale/masks.ts
 function maskFromOffsets(offsets) {
+  assertArray(offsets, "offsets");
   let mask = 1;
   for (const [index, offset] of offsets.entries()) {
     assertInteger(offset, `offsets[${index}]`);
@@ -51,6 +61,12 @@ var WHOLE_TONE_MASK = maskFromOffsets([0, 2, 4, 6, 8, 10]);
 var OCTATONIC_HALF_WHOLE_MASK = maskFromOffsets([0, 1, 3, 4, 6, 7, 9, 10]);
 var OCTATONIC_WHOLE_HALF_MASK = maskFromOffsets([0, 2, 3, 5, 6, 8, 9, 11]);
 var CHROMATIC_MASK = 4095;
+function assertModeMask(modeMask12, name = "modeMask12") {
+  return assertInteger(modeMask12, name, 1, CHROMATIC_MASK);
+}
+function maskOf(scale, name = "key") {
+  return assertModeMask(assertRecord(scale, name).modeMask12, `${name}.modeMask12`);
+}
 var LYDIAN_DOMINANT_MASK = maskFromOffsets([0, 2, 4, 6, 7, 9, 10]);
 var MIXOLYDIAN_B13_MASK = maskFromOffsets([0, 2, 4, 5, 7, 8, 10]);
 var LOCRIAN_NATURAL2_MASK = maskFromOffsets([0, 2, 3, 5, 6, 8, 10]);
@@ -156,6 +172,9 @@ var SCALE_ALIASES = Object.freeze({
   poorvi: "purvi"
 });
 function resolveScaleName(name) {
+  if (typeof name !== "string") {
+    throw new InvalidInputError(`scale name must be a string; received ${describeRejected(name)}`);
+  }
   if (Object.hasOwn(NAMED_SCALES, name)) {
     return name;
   }
@@ -178,21 +197,119 @@ function requireScaleMask(name, label = "scale") {
   }
   return mask;
 }
+var VARIANT_MASKS = {
+  major: MAJOR_MASK,
+  natural: NATURAL_MINOR_MASK,
+  harmonic: HARMONIC_MINOR_MASK,
+  melodic: MELODIC_MINOR_MASK
+};
+function isMinorMask(modeMask12) {
+  return (modeMask12 >> 3 & 1) === 1 && (modeMask12 >> 4 & 1) === 0;
+}
+function variantOfMask(modeMask12) {
+  assertModeMask(modeMask12);
+  for (const [variant, mask] of Object.entries(VARIANT_MASKS)) {
+    if (mask === modeMask12) {
+      return variant;
+    }
+  }
+  return "modal";
+}
+var KEY_VARIANTS = [
+  ...Object.keys(VARIANT_MASKS),
+  "modal"
+];
+function assertKeyVariant(variant, modeMask12) {
+  assertOneOf(variant, KEY_VARIANTS, "variant");
+  assertModeMask(modeMask12);
+  const named = VARIANT_MASKS[variant];
+  const matches = named === void 0 ? !Object.values(VARIANT_MASKS).includes(modeMask12) : named === modeMask12;
+  if (!matches) {
+    throw new InvalidInputError(
+      `variant ${variant} does not match the scale mask ${modeMask12}; pass the scale that variant names, or omit the variant`
+    );
+  }
+}
 
-// src/theory/scale/key.ts
-function majorKey(rootPc) {
+// src/theory/scale/scales.ts
+function majorScale(rootPc) {
   return { rootPc: pitchClassOf(rootPc), modeMask12: MAJOR_MASK };
 }
-function minorKey(rootPc) {
+function minorScale(rootPc) {
   return { rootPc: pitchClassOf(rootPc), modeMask12: NATURAL_MINOR_MASK };
 }
-function scaleByName(name, rootPc) {
+function namedScale(name, rootPc) {
   return { rootPc: pitchClassOf(rootPc), modeMask12: requireScaleMask(name) };
 }
 
+// src/theory/scale/name.ts
+function scaleWordKey(text) {
+  return text.replace(/[^a-z0-9]/gi, "").toLowerCase();
+}
+var BUILT_IN_SCALE_NAMES = [
+  ...Object.keys(NAMED_SCALES),
+  ...Object.keys(WORLD_SCALES),
+  ...Object.keys(SCALE_ALIASES)
+];
+var SCALE_BY_WORD = new Map(
+  BUILT_IN_SCALE_NAMES.map((name) => [scaleWordKey(name), name])
+);
+function scaleNameOfMask(mask) {
+  for (const name of Object.keys(NAMED_SCALES)) {
+    if (NAMED_SCALES[name] === mask) {
+      return name;
+    }
+  }
+  for (const name of Object.keys(WORLD_SCALES)) {
+    if (WORLD_SCALES[name] === mask) {
+      return name;
+    }
+  }
+  return void 0;
+}
+function bareTonic(note) {
+  return { letter: note.letter, alter: note.alter };
+}
+function tryNamedScaleKey(text) {
+  const trimmed = text.trim();
+  const separator = trimmed.search(/\s/);
+  if (separator < 0) {
+    return null;
+  }
+  const name = SCALE_BY_WORD.get(scaleWordKey(trimmed.slice(separator)));
+  if (name === void 0) {
+    return null;
+  }
+  const tonic = tryParseNote(trimmed.slice(0, separator));
+  if (!tonic.ok) {
+    return null;
+  }
+  const scale = namedScale(name, noteToPitchClass(tonic.value));
+  return { scale, tonic: bareTonic(tonic.value), variant: variantOfMask(scale.modeMask12) };
+}
+function tryResolveKeyName(text, opts) {
+  const asked = assertOptions(opts, "opts");
+  if (typeof text === "string" && (asked.system === void 0 || asked.system === "english")) {
+    const named = tryNamedScaleKey(text);
+    if (named !== null) {
+      return { ok: true, value: named };
+    }
+  }
+  const parsed = tryParseKeyName(text, asked);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  const tonic = bareTonic(parsed.value.tonic);
+  const rootPc = noteToPitchClass(tonic);
+  return parsed.value.mode === "major" ? { ok: true, value: { scale: majorScale(rootPc), tonic, variant: "major" } } : { ok: true, value: { scale: minorScale(rootPc), tonic, variant: "natural" } };
+}
+function resolveKeyName(text, opts) {
+  return unwrapParse(tryResolveKeyName(text, opts));
+}
+
 // src/theory/scale/coerce.ts
 function normalizedKeyScale(scale) {
-  assertInteger(scale.modeMask12, "key.modeMask12", 1, CHROMATIC_MASK);
+  assertModeMask(scale.modeMask12, "key.modeMask12");
   if ((scale.modeMask12 & 1) === 0) {
     throw new InvalidInputError(
       `key.modeMask12 must include its root; received ${scale.modeMask12}`
@@ -203,12 +320,10 @@ function normalizedKeyScale(scale) {
 }
 function toKeyScale(value) {
   if (typeof value === "string") {
-    const name = parseKeyName(value);
-    const rootPc = noteToPitchClass(name.tonic);
-    return name.mode === "major" ? majorKey(rootPc) : minorKey(rootPc);
+    return resolveKeyName(value).scale;
   }
   if (typeof value === "object" && value !== null) {
-    const data = "toJSON" in value && typeof value.toJSON === "function" ? value.toJSON().scale : value;
+    const data = "toJSON" in value && typeof value.toJSON === "function" ? value.toJSON().scale : "scale" in value ? value.scale : value;
     if (typeof data === "object" && data !== null) {
       return normalizedKeyScale(data);
     }
@@ -224,10 +339,11 @@ function inScale(pitch, scale) {
   return (scale.modeMask12 >> scaleOffset(pitch, scale) & 1) === 1;
 }
 function isScaleTone(pitch, key) {
-  return inScale(pitch, key);
+  return inScale(pitch, toKeyScale(key));
 }
 function nearestScaleTone(pitch, key) {
   const scale = toKeyScale(key);
+  assertFiniteNumber(pitch, "pitch");
   const base = clampToMidi(Math.round(pitch), "pitch");
   for (let distance = 0; distance < 12; distance += 1) {
     const lower = base - distance;
@@ -251,6 +367,10 @@ function scaleOffsets(key) {
   return offsets;
 }
 function scaleLadderPosition(pitch, key) {
+  return ladderPosition(pitch, toKeyScale(key));
+}
+function ladderPosition(pitch, key) {
+  assertFiniteNumber(pitch, "pitch");
   const offsets = scaleOffsets(key);
   const size = offsets.length;
   if (size === 0) {
@@ -268,6 +388,10 @@ function scaleLadderPosition(pitch, key) {
   return { rung: octave * size + degree, offset: within - (offsets[degree] ?? 0) };
 }
 function scaleLadderPitch(rung, key) {
+  return ladderPitch(rung, toKeyScale(key));
+}
+function ladderPitch(rung, key) {
+  assertFiniteNumber(rung, "rung");
   const offsets = scaleOffsets(key);
   const size = offsets.length;
   if (size === 0) {
@@ -278,12 +402,13 @@ function scaleLadderPitch(rung, key) {
   return pitchClassOf(key.rootPc) + octave * 12 + (offsets[degree] ?? 0);
 }
 function shiftByScaleDegrees(pitch, degrees, key) {
-  const steps = Math.trunc(degrees);
+  const scale = toKeyScale(key);
+  const steps = Math.trunc(assertFiniteNumber(degrees, "degrees"));
   if (steps === 0) {
     return pitch;
   }
-  const { rung, offset } = scaleLadderPosition(pitch, key);
-  return scaleLadderPitch(rung + steps, key) + offset;
+  const { rung, offset } = ladderPosition(pitch, scale);
+  return ladderPitch(rung + steps, scale) + offset;
 }
 function pitchToScaleDegree(pitch, key) {
   const scale = toKeyScale(key);
@@ -300,18 +425,10 @@ function pitchToScaleDegree(pitch, key) {
   return degree;
 }
 function diatonicPitchClasses(key) {
-  const scale = key;
-  const root = pitchClassOf(scale.rootPc);
-  const pcs = [];
-  for (let n = 0; n < 12; n += 1) {
-    if ((scale.modeMask12 >> n & 1) === 1) {
-      pcs.push((root + n) % 12);
-    }
-  }
-  return pcs.sort((a, b) => a - b);
+  return scaleTonesInDegreeOrder(key).sort((a, b) => a - b);
 }
 function scaleTonesInDegreeOrder(key) {
-  const scale = key;
+  const scale = toKeyScale(key);
   const root = pitchClassOf(scale.rootPc);
   const pcs = [];
   for (let n = 0; n < 12; n += 1) {
@@ -348,22 +465,20 @@ var DIATONIC_MODE_OFFSETS = /* @__PURE__ */ new Map([
   [rotateMask(MAJOR_MASK, 11), -5]
   // locrian
 ]);
-function hasMinorThird(modeMask12) {
-  return (modeMask12 >> 3 & 1) === 1 && (modeMask12 >> 4 & 1) === 0;
-}
 function modeOffset(key) {
   const diatonic = DIATONIC_MODE_OFFSETS.get(key.modeMask12);
   if (diatonic !== void 0) {
     return diatonic;
   }
-  return hasMinorThird(key.modeMask12) ? MINOR_MODE_OFFSET : 0;
+  return isMinorMask(key.modeMask12) ? MINOR_MODE_OFFSET : 0;
 }
 function isSignatureKey(key) {
-  return DIATONIC_MODE_OFFSETS.has(key.modeMask12) || key.modeMask12 === HARMONIC_MINOR_MASK || key.modeMask12 === MELODIC_MINOR_MASK;
+  const mask = maskOf(key);
+  return DIATONIC_MODE_OFFSETS.has(mask) || mask === HARMONIC_MINOR_MASK || mask === MELODIC_MINOR_MASK;
 }
 function keySignatureFifths(tonic, key) {
   const note = toNoteData(tonic);
-  const scale = key;
+  const scale = toKeyScale(key);
   const letter = diatonicLetterOf(note.letter);
   assertInteger(note.alter, "tonic.alter");
   assertInteger(scale.modeMask12, "key.modeMask12", 1, 4095);
@@ -376,33 +491,28 @@ function keyFromFifths(fifths, mode = "major") {
   const letter = FIFTHS_LETTERS[(index % 7 + 7) % 7] ?? 0;
   const alter = Math.floor(index / 7);
   const rootPc = pitchClassOf(naturalPitchClassOf(letter) + alter);
+  const scale = which === "minor" ? minorScale(rootPc) : majorScale(rootPc);
   return {
     tonic: { letter, alter },
-    key: which === "minor" ? minorKey(rootPc) : majorKey(rootPc)
+    scale,
+    variant: variantOfMask(scale.modeMask12)
   };
 }
 
 // src/theory/scale/relations.ts
 var ENHARMONIC_FIFTHS = 12;
 var MAX_CONVENTIONAL_FIFTHS = 7;
-var DOUBLE_ACCIDENTAL = 2;
 var MINOR_TONIC_FIFTHS = 3;
 var FLATTEST_TONIC_FIFTHS = -MAX_CONVENTIONAL_FIFTHS;
 var SHARPEST_TONIC_FIFTHS = MAX_CONVENTIONAL_FIFTHS + MINOR_TONIC_FIFTHS;
-function isMinorMode(modeMask12) {
-  return (modeMask12 >> 3 & 1) === 1 && (modeMask12 >> 4 & 1) === 0;
-}
-function assertModeMask(key, name = "key") {
-  return assertInteger(key.modeMask12, `${name}.modeMask12`, 1, CHROMATIC_MASK);
-}
 function modeOf(key) {
-  return isMinorMode(assertModeMask(key)) ? "minor" : "major";
+  return isMinorMask(maskOf(key)) ? "minor" : "major";
 }
 function oppositeMode(mode) {
   return mode === "major" ? "minor" : "major";
 }
 function soundsLike(a, b) {
-  return pitchClassOf(a.rootPc) === pitchClassOf(b.rootPc) && isMinorMode(a.modeMask12) === isMinorMode(b.modeMask12);
+  return pitchClassOf(a.rootPc) === pitchClassOf(b.rootPc) && isMinorMask(a.modeMask12) === isMinorMask(b.modeMask12);
 }
 function spelledLike(a, b) {
   return diatonicLetterOf(a.letter) === diatonicLetterOf(b.letter) && a.alter === b.alter;
@@ -413,7 +523,7 @@ function tonicCost(tonic, key) {
   for (const note of spellScale(tonic, key)) {
     const alter = Math.abs(note.alter);
     accidentals += alter;
-    if (alter >= DOUBLE_ACCIDENTAL) {
+    if (alter >= MAX_NAME_ACCIDENTALS) {
       doubles += 1;
     }
   }
@@ -429,7 +539,7 @@ function spellsBetter(a, b, signatureKey) {
   return false;
 }
 function spelledKeyOf(key) {
-  const scale = key;
+  const scale = assertRecord(key, "key");
   const rootPc = pitchClassOf(scale.rootPc);
   const signatureKey = isSignatureKey(scale);
   let tonic = keyFromFifths(0).tonic;
@@ -445,33 +555,35 @@ function spelledKeyOf(key) {
       best = cost;
     }
   }
-  return { tonic, key };
+  return { tonic, scale: key, variant: variantOfMask(key.modeMask12) };
 }
 function relativeKeyOf(tonic, key) {
-  const scale = toKeyScale(key);
-  return keyFromFifths(keySignatureFifths(tonic, scale), oppositeMode(modeOf(scale)));
+  const mode = modeOf(toKeyScale(key));
+  return keyFromFifths(tonicFifths(toNoteData(tonic), mode), oppositeMode(mode));
 }
 function parallelKeyOf(tonic, key) {
   const note = toNoteData(tonic);
   const mode = oppositeMode(modeOf(toKeyScale(key)));
   const rootPc = noteToPitchClass(note);
+  const scale = mode === "minor" ? minorScale(rootPc) : majorScale(rootPc);
   return {
     tonic: { letter: diatonicLetterOf(note.letter), alter: note.alter },
-    key: mode === "minor" ? minorKey(rootPc) : majorKey(rootPc)
+    scale,
+    variant: variantOfMask(scale.modeMask12)
   };
 }
 function tonicPosition(tonic) {
-  return keySignatureFifths(tonic, majorKey(noteToPitchClass(tonic)));
+  return keySignatureFifths(tonic, majorScale(noteToPitchClass(tonic)));
 }
 function tonicFifths(tonic, mode) {
   return tonicPosition(tonic) - (mode === "minor" ? MINOR_TONIC_FIFTHS : 0);
 }
 function isWrittenTonic(tonic, key) {
   const position = tonicPosition(tonic);
-  if (position < FLATTEST_TONIC_FIFTHS || position > SHARPEST_TONIC_FIFTHS) {
-    return false;
+  if (isSignatureKey(key)) {
+    return Math.abs(position) <= MAX_FIFTHS && Math.abs(keySignatureFifths(tonic, key)) <= MAX_CONVENTIONAL_FIFTHS;
   }
-  return isSignatureKey(key) ? Math.abs(keySignatureFifths(tonic, key)) <= MAX_CONVENTIONAL_FIFTHS : tonicCost(tonic, key).doubles === 0;
+  return position >= FLATTEST_TONIC_FIFTHS && position <= SHARPEST_TONIC_FIFTHS && tonicCost(tonic, { rootPc: noteToPitchClass(tonic), modeMask12: key.modeMask12 }).doubles === 0;
 }
 function dominantKeyOf(tonic, key) {
   const mode = modeOf(toKeyScale(key));
@@ -484,34 +596,35 @@ function subdominantKeyOf(tonic, key) {
 function enharmonicKeyOf(tonic, key) {
   const note = toNoteData(tonic);
   const scale = toKeyScale(key);
-  assertModeMask(scale);
+  maskOf(scale);
   for (const position of [
     tonicPosition(note) - ENHARMONIC_FIFTHS,
     tonicPosition(note) + ENHARMONIC_FIFTHS
   ]) {
-    if (position < FLATTEST_TONIC_FIFTHS || position > SHARPEST_TONIC_FIFTHS) {
+    if (Math.abs(position) > MAX_FIFTHS) {
       continue;
     }
-    const spelled = keyFromFifths(position).tonic;
-    if (!isWrittenTonic(spelled, scale)) {
+    const spelled2 = keyFromFifths(position).tonic;
+    if (!isWrittenTonic(spelled2, scale)) {
       continue;
     }
     return {
-      tonic: spelled,
+      tonic: spelled2,
       // The mask is the caller's; only the root is re-read, so a tonic that did
       // not spell the mask's own root still comes back consistent.
-      key: { rootPc: noteToPitchClass(spelled), modeMask12: scale.modeMask12 }
+      scale: { rootPc: noteToPitchClass(spelled2), modeMask12: scale.modeMask12 },
+      variant: variantOfMask(scale.modeMask12)
     };
   }
   return null;
 }
 function relativeOfDominantKeyOf(tonic, key) {
   const dominant = dominantKeyOf(tonic, key);
-  return relativeKeyOf(dominant.tonic, dominant.key);
+  return relativeKeyOf(dominant.tonic, dominant.scale);
 }
 function relativeOfSubdominantKeyOf(tonic, key) {
   const subdominant = subdominantKeyOf(tonic, key);
-  return relativeKeyOf(subdominant.tonic, subdominant.key);
+  return relativeKeyOf(subdominant.tonic, subdominant.scale);
 }
 var CLOSELY_RELATED = [
   { relation: "relative", of: relativeKeyOf },
@@ -527,19 +640,68 @@ function relatedKeysOf(tonic, key) {
   return CLOSELY_RELATED.map(({ relation, of }) => ({ ...of(note, scale), relation }));
 }
 function keyRelationBetween(a, b) {
-  assertModeMask(a.key, "a.key");
-  assertModeMask(b.key, "b.key");
-  if (soundsLike(a.key, b.key)) {
-    return spelledLike(a.tonic, b.tonic) ? "same" : "enharmonic";
+  const from = assertRecord(a, "a");
+  const to = assertRecord(b, "b");
+  maskOf(from.scale, "a.scale");
+  maskOf(to.scale, "b.scale");
+  if (soundsLike(from.scale, to.scale)) {
+    return spelledLike(from.tonic, to.tonic) ? "same" : "enharmonic";
   }
   for (const { relation, of } of CLOSELY_RELATED) {
-    if (soundsLike(of(a.tonic, a.key).key, b.key)) {
+    if (soundsLike(of(from.tonic, from.scale).scale, to.scale)) {
       return relation;
     }
   }
   return null;
 }
 
+// src/theory/scale/identity.ts
+function carriesIdentity(value) {
+  return typeof value === "object" && value !== null;
+}
+function carriedTonic(tonic, scale) {
+  if (noteToPitchClass(tonic) !== scale.rootPc) {
+    throw new InvalidInputError(
+      `tonic ${formatNote(tonic)} does not match the scale root pitch class ${scale.rootPc}; pass a tonic that spells the scale root, or omit it to have one chosen`
+    );
+  }
+  return { letter: tonic.letter, alter: tonic.alter };
+}
+function carriedVariant(variant, scale) {
+  assertKeyVariant(variant, scale.modeMask12);
+  return variant;
+}
+function resolveKey(value) {
+  if (typeof value === "string") {
+    return resolveKeyName(value);
+  }
+  const scale = toKeyScale(value);
+  const carried = carriesIdentity(value) && "toJSON" in value && typeof value.toJSON === "function" ? value.toJSON() : value;
+  const tonic = carriesIdentity(carried) && carried.tonic !== void 0 ? carriedTonic(carried.tonic, scale) : spelledKeyOf(scale).tonic;
+  const variant = carriesIdentity(carried) && carried.variant !== void 0 ? carriedVariant(carried.variant, scale) : variantOfMask(scale.modeMask12);
+  return { scale, tonic, variant };
+}
+function scaleOf(key) {
+  const scale = assertRecord(key, "key").scale;
+  maskOf(scale, "key.scale");
+  return scale;
+}
+
+// src/theory/scale/key.ts
+function spelled(scale) {
+  const { tonic, variant } = spelledKeyOf(scale);
+  return { ...scale, tonic, variant };
+}
+function majorKey(rootPc) {
+  return spelled(majorScale(rootPc));
+}
+function minorKey(rootPc) {
+  return spelled(minorScale(rootPc));
+}
+function scaleByName(name, rootPc) {
+  return spelled(namedScale(name, rootPc));
+}
+
 // src/theory/scale/system.ts
 var SCALE_SYSTEMS = Object.freeze({
   major: "common-practice",
@@ -607,7 +769,7 @@ function scaleSystemOf(scale) {
     }
     return SCALE_SYSTEMS[canonical];
   }
-  return SYSTEM_BY_MASK.get(scale.modeMask12);
+  return SYSTEM_BY_MASK.get(maskOf(scale, "scale"));
 }
 function supportsFunctionalHarmony(scale) {
   return scaleSystemOf(scale) !== "non-functional";
@@ -653,6 +815,7 @@ var BASE_TONES = {
 var SEVENTH_SEMITONES = { maj7: 11, min7: 10, dim7: 9 };
 var DEGREE_SEMITONES = { 6: 9, 9: 14, 11: 17, 13: 21 };
 var PERFECT_FIFTH = 7;
+var FIFTH_KEY = "5";
 var OMITTABLE_DEGREES = [1, 3, 5];
 var BASE_QUALITY = {
   maj: "maj",
@@ -676,114 +839,149 @@ function parts(base, spec = {}) {
   }
   return built;
 }
-var QUALITY_SPECS = {
-  maj: parts("maj"),
-  min: parts("min"),
-  dim: parts("dim"),
-  aug: parts("aug"),
-  majb5: parts("maj", { alt: [[5, -1]] }),
-  maj7: parts("maj", { seventh: "maj7" }),
-  min7: parts("min", { seventh: "min7" }),
-  dom7: parts("maj", { seventh: "min7" }),
-  dim7: parts("dim", { seventh: "dim7" }),
-  m7b5: parts("dim", { seventh: "min7" }),
-  minMaj7: parts("min", { seventh: "maj7" }),
-  minMaj9: parts("min", { seventh: "maj7", alt: [[9, 0]] }),
-  minMaj11: parts("min", {
-    seventh: "maj7",
-    alt: [
-      [9, 0],
-      [11, 0]
-    ]
-  }),
-  minMaj13: parts("min", {
-    seventh: "maj7",
-    alt: [
-      [9, 0],
-      [13, 0]
-    ]
-  }),
-  aug7: parts("aug", { seventh: "min7" }),
-  augMaj7: parts("aug", { seventh: "maj7" }),
-  "6": parts("maj", { add: [6] }),
-  min6: parts("min", { add: [6] }),
-  "6/9": parts("maj", { add: [6, 9] }),
-  sus2: parts("sus2"),
-  sus4: parts("sus4"),
-  add9: parts("maj", { add: [9] }),
-  add11: parts("maj", { add: [11] }),
-  maj9: parts("maj", { seventh: "maj7", alt: [[9, 0]] }),
-  min9: parts("min", { seventh: "min7", alt: [[9, 0]] }),
-  dom9: parts("maj", { seventh: "min7", alt: [[9, 0]] }),
-  "7b9": parts("maj", { seventh: "min7", alt: [[9, -1]] }),
-  "7#9": parts("maj", { seventh: "min7", alt: [[9, 1]] }),
-  "7#11": parts("maj", { seventh: "min7", alt: [[11, 1]] }),
-  "7b13": parts("maj", { seventh: "min7", alt: [[13, -1]] }),
+var QUALITY_SPECS = [
+  ["maj", parts("maj")],
+  ["min", parts("min")],
+  ["dim", parts("dim")],
+  ["aug", parts("aug")],
+  ["majb5", parts("maj", { alt: [[5, -1]] })],
+  ["maj7", parts("maj", { seventh: "maj7" })],
+  ["min7", parts("min", { seventh: "min7" })],
+  ["dom7", parts("maj", { seventh: "min7" })],
+  ["dim7", parts("dim", { seventh: "dim7" })],
+  ["m7b5", parts("dim", { seventh: "min7" })],
+  ["minMaj7", parts("min", { seventh: "maj7" })],
+  ["minMaj9", parts("min", { seventh: "maj7", alt: [[9, 0]] })],
+  [
+    "minMaj11",
+    parts("min", {
+      seventh: "maj7",
+      alt: [
+        [9, 0],
+        [11, 0]
+      ]
+    })
+  ],
+  [
+    "minMaj13",
+    parts("min", {
+      seventh: "maj7",
+      alt: [
+        [9, 0],
+        [13, 0]
+      ]
+    })
+  ],
+  ["aug7", parts("aug", { seventh: "min7" })],
+  ["augMaj7", parts("aug", { seventh: "maj7" })],
+  ["6", parts("maj", { add: [6] })],
+  ["min6", parts("min", { add: [6] })],
+  ["6/9", parts("maj", { add: [6, 9] })],
+  ["sus2", parts("sus2")],
+  ["sus4", parts("sus4")],
+  ["add9", parts("maj", { add: [9] })],
+  ["add11", parts("maj", { add: [11] })],
+  ["maj9", parts("maj", { seventh: "maj7", alt: [[9, 0]] })],
+  ["min9", parts("min", { seventh: "min7", alt: [[9, 0]] })],
+  ["dom9", parts("maj", { seventh: "min7", alt: [[9, 0]] })],
+  ["7b9", parts("maj", { seventh: "min7", alt: [[9, -1]] })],
+  ["7#9", parts("maj", { seventh: "min7", alt: [[9, 1]] })],
+  ["7#11", parts("maj", { seventh: "min7", alt: [[11, 1]] })],
+  ["7b13", parts("maj", { seventh: "min7", alt: [[13, -1]] })],
   // The eleventh chord as a chart voices it: the third gives way to the
   // eleventh a semitone above it rather than sounding against it.
-  "11": parts("maj", {
-    seventh: "min7",
-    alt: [
-      [9, 0],
-      [11, 0]
-    ],
-    omit: [3]
-  }),
-  "13": parts("maj", {
-    seventh: "min7",
-    alt: [
-      [9, 0],
-      [13, 0]
-    ]
-  }),
-  "5": parts("power"),
-  "7sus4": parts("sus4", { seventh: "min7" }),
-  "7b5": parts("maj", { seventh: "min7", alt: [[5, -1]] }),
+  [
+    "11",
+    parts("maj", {
+      seventh: "min7",
+      alt: [
+        [9, 0],
+        [11, 0]
+      ],
+      omit: [3]
+    })
+  ],
+  [
+    "13",
+    parts("maj", {
+      seventh: "min7",
+      alt: [
+        [9, 0],
+        [13, 0]
+      ]
+    })
+  ],
+  ["5", parts("power")],
+  ["7sus4", parts("sus4", { seventh: "min7" })],
+  ["7b5", parts("maj", { seventh: "min7", alt: [[5, -1]] })],
   // The altered dominant as it is voiced from a lead sheet: a dominant seventh
   // with a raised fifth and a raised ninth. The full seven-note altered stack
   // has no seven-letter spelling, so it is not what this symbol denotes.
-  "7alt": parts("aug", { seventh: "min7", alt: [[9, 1]] }),
-  "13b9": parts("maj", {
-    seventh: "min7",
-    alt: [
-      [9, -1],
-      [13, 0]
-    ]
-  }),
-  maj13: parts("maj", {
-    seventh: "maj7",
-    alt: [
-      [9, 0],
-      [13, 0]
-    ]
-  }),
-  "maj7#11": parts("maj", { seventh: "maj7", alt: [[11, 1]] }),
-  min11: parts("min", {
-    seventh: "min7",
-    alt: [
-      [9, 0],
-      [11, 0]
-    ]
-  }),
-  min13: parts("min", {
-    seventh: "min7",
-    alt: [
-      [9, 0],
-      [13, 0]
-    ]
-  }),
-  minAdd9: parts("min", { add: [9] }),
-  "min6/9": parts("min", { add: [6, 9] })
-};
+  ["7alt", parts("aug", { seventh: "min7", alt: [[9, 1]] })],
+  [
+    "13b9",
+    parts("maj", {
+      seventh: "min7",
+      alt: [
+        [9, -1],
+        [13, 0]
+      ]
+    })
+  ],
+  [
+    "maj13",
+    parts("maj", {
+      seventh: "maj7",
+      alt: [
+        [9, 0],
+        [13, 0]
+      ]
+    })
+  ],
+  ["maj7#11", parts("maj", { seventh: "maj7", alt: [[11, 1]] })],
+  [
+    "min11",
+    parts("min", {
+      seventh: "min7",
+      alt: [
+        [9, 0],
+        [11, 0]
+      ]
+    })
+  ],
+  [
+    "min13",
+    parts("min", {
+      seventh: "min7",
+      alt: [
+        [9, 0],
+        [13, 0]
+      ]
+    })
+  ],
+  ["minAdd9", parts("min", { add: [9] })],
+  ["min6/9", parts("min", { add: [6, 9] })]
+];
+var QUALITY_ORDER = QUALITY_SPECS.map(([quality]) => quality);
+var SPEC_BY_QUALITY = new Map(QUALITY_SPECS);
 function normalizeChordSpec(spec) {
   let base = spec.base;
   const alterations = /* @__PURE__ */ new Map();
   for (const alteration of spec.alterations ?? []) {
-    alterations.set(alteration.degree, alteration.alter);
+    const { degree, alter } = alteration;
+    if (degree === 5) {
+      const current = alterations.get(FIFTH_KEY);
+      if (current !== void 0 && current.alter <= alter) {
+        continue;
+      }
+      alterations.set(FIFTH_KEY, { degree, alter });
+      continue;
+    }
+    alterations.set(`${degree}:${alter}`, { degree, alter });
   }
   const additions = new Set(spec.additions ?? []);
   const omissions = new Set(spec.omissions ?? []);
-  const fifth = alterations.get(5);
+  const fifth = alterations.get(FIFTH_KEY)?.alter;
   if (fifth !== void 0) {
     if (base === "aug") {
       base = "maj";
@@ -791,19 +989,19 @@ function normalizeChordSpec(spec) {
       base = "min";
     }
     if (fifth === 0) {
-      alterations.delete(5);
+      alterations.delete(FIFTH_KEY);
     } else if (base === "maj" && fifth === 1) {
       base = "aug";
-      alterations.delete(5);
+      alterations.delete(FIFTH_KEY);
     } else if (base === "min" && fifth === -1) {
       base = "dim";
-      alterations.delete(5);
+      alterations.delete(FIFTH_KEY);
     }
   }
   if (spec.seventh === void 0) {
-    for (const [degree, alter] of [...alterations]) {
+    for (const [key, { degree, alter }] of [...alterations]) {
       if (degree !== 5 && alter === 0) {
-        alterations.delete(degree);
+        alterations.delete(key);
         additions.add(degree);
       }
     }
@@ -811,7 +1009,7 @@ function normalizeChordSpec(spec) {
   const normalized = {
     rootPc: spec.rootPc,
     base,
-    alterations: [...alterations].sort((a, b) => a[0] - b[0]).map(([degree, alter]) => ({ degree, alter })),
+    alterations: [...alterations.values()].sort((a, b) => a.degree - b.degree || a.alter - b.alter),
     additions: [...additions].sort((a, b) => a - b),
     omissions: [...omissions].sort((a, b) => a - b)
   };
@@ -851,10 +1049,7 @@ function chordSpecIntervals(spec) {
   return specIntervals(assertChordSpec(spec));
 }
 var QUALITY_INTERVALS = Object.fromEntries(
-  Object.keys(QUALITY_SPECS).map((quality) => [
-    quality,
-    specIntervals(normalizeChordSpec(QUALITY_SPECS[quality]))
-  ])
+  QUALITY_SPECS.map(([quality, spec]) => [quality, specIntervals(normalizeChordSpec(spec))])
 );
 function specKey(spec) {
   const normalized = normalizeChordSpec(spec);
@@ -867,16 +1062,14 @@ function specKey(spec) {
   ].join("|");
 }
 var QUALITY_BY_KEY = new Map(
-  Object.keys(QUALITY_SPECS).map((quality) => [
-    specKey(QUALITY_SPECS[quality]),
-    quality
-  ])
+  QUALITY_SPECS.map(([quality, spec]) => [specKey(spec), quality])
 );
 function chordSpecForQuality(quality, rootPc, bassPc) {
-  if (!Object.hasOwn(QUALITY_SPECS, quality)) {
+  const named = SPEC_BY_QUALITY.get(quality);
+  if (named === void 0) {
     throw new InvalidInputError(`Unknown chord quality: ${String(quality)}`);
   }
-  const spec = normalizeChordSpec(QUALITY_SPECS[quality]);
+  const spec = normalizeChordSpec(named);
   spec.rootPc = rootPc;
   if (bassPc !== void 0) {
     spec.bassPc = bassPc;
@@ -892,10 +1085,10 @@ function chordSpecQuality(spec) {
   if (exact !== void 0) {
     return exact;
   }
-  const offsets = new Set(specIntervals(checked));
+  const offsets = new Set(specIntervals({ ...checked, omissions: [] }));
   let nearest;
   let size = 0;
-  for (const quality of Object.keys(QUALITY_INTERVALS)) {
+  for (const quality of QUALITY_ORDER) {
     const template = QUALITY_INTERVALS[quality];
     if (template.length > size && template.every((offset) => offsets.has(offset))) {
       nearest = quality;
@@ -982,7 +1175,7 @@ function chordSpecFromIntervals(intervals) {
 function assertPart(value, allowed, name) {
   if (!allowed.includes(value)) {
     throw new InvalidInputError(
-      `${name} must be one of ${allowed.join(", ")}; received ${JSON.stringify(value)}`
+      `${name} must be one of ${allowed.join(", ")}; received ${describeRejected(value)}`
     );
   }
   return value;
@@ -1034,13 +1227,23 @@ function assertChordSpec(spec) {
 // src/theory/chord/index.ts
 var MAX_CHORD_INTERVAL = 127;
 function chordQualities() {
-  return Object.keys(QUALITY_INTERVALS);
+  return [...QUALITY_ORDER];
+}
+function assertChordQuality(quality) {
+  if (!Object.hasOwn(QUALITY_INTERVALS, quality)) {
+    throw new InvalidInputError(`Unknown chord quality: ${String(quality)}`);
+  }
+  return quality;
+}
+function assertChord(chord, name = "chord") {
+  const read = assertRecord(chord, name);
+  assertFiniteNumber(read.rootPc, `${name}.rootPc`);
+  assertChordQuality(read.quality);
+  return read;
 }
 function chordFromDegree(degree, ext, key) {
   assertDegree(degree, "chord degree");
-  if (!Object.hasOwn(QUALITY_INTERVALS, ext)) {
-    throw new InvalidInputError(`Unknown chord quality: ${String(ext)}`);
-  }
+  assertChordQuality(ext);
   const scale = toKeyScale(key);
   const tones = scaleTonesInDegreeOrder(scale);
   const length = tones.length;
@@ -1053,9 +1256,7 @@ function makeChord(rootPc, quality, bassPc) {
   if (bassPc !== void 0) {
     assertFiniteNumber(bassPc, "chord bassPc");
   }
-  if (!Object.hasOwn(QUALITY_INTERVALS, quality)) {
-    throw new InvalidInputError(`Unknown chord quality: ${String(quality)}`);
-  }
+  assertChordQuality(quality);
   const chord = {
     rootPc: pitchClassOf(rootPc),
     quality,
@@ -1079,6 +1280,7 @@ function chordFromSpec(spec) {
   return chord;
 }
 function chordSpecOf(chord) {
+  assertRecord(chord, "chord");
   assertFiniteNumber(chord.rootPc, "chord rootPc");
   const rootPc = pitchClassOf(chord.rootPc);
   const bassPc = chord.bassPc === void 0 ? void 0 : pitchClassOf(chord.bassPc);
@@ -1119,6 +1321,7 @@ function hasCustomIntervals(chord) {
   return !matchesQualityIntervals(chord.quality, chord.intervals);
 }
 function chordFromSpan(span) {
+  assertRecord(span, "chord span");
   const chord = makeChord(span.rootPc, span.quality, span.bassPc);
   if (span.intervals !== void 0) {
     chord.intervals = copySpanIntervals(span.intervals);
@@ -1127,9 +1330,7 @@ function chordFromSpan(span) {
 }
 function spanFromChord(chord, startBeat) {
   assertFiniteNumber(startBeat, "chord span startBeat");
-  if (!Object.hasOwn(QUALITY_INTERVALS, chord.quality)) {
-    throw new InvalidInputError(`Unknown chord quality: ${String(chord.quality)}`);
-  }
+  assertChord(chord);
   const span = { rootPc: chord.rootPc, quality: chord.quality, startBeat };
   if (chord.bassPc !== void 0) {
     span.bassPc = chord.bassPc;
@@ -1140,6 +1341,7 @@ function spanFromChord(chord, startBeat) {
   return span;
 }
 function transposeChord(chord, semitones) {
+  assertChord(chord);
   assertFiniteNumber(semitones, "semitones");
   const steps = Math.round(semitones);
   const moved = {
@@ -1171,59 +1373,145 @@ function chordToneSpellings(chord) {
   }
   return usable;
 }
-function chordPitchClasses(chord, opts = {}) {
-  const set = /* @__PURE__ */ new Set();
+function chordToneLetterOffsets(chord) {
+  const hints = chordToneSpellings(chord);
+  const rootHint = hints?.[chord.intervals.findIndex((interval) => pitchClassOf(interval) === 0)];
+  if (hints === void 0 || rootHint === void 0) {
+    return void 0;
+  }
+  return hints.map((hint) => diatonicLetterOf(hint.letter - rootHint.letter));
+}
+var ROLE_BY_LETTER_OFFSET = {
+  0: "root",
+  2: "third",
+  4: "fifth",
+  5: "sixth",
+  6: "seventh"
+};
+function spelledToneRole(pitch, chord) {
+  const offsets = chordToneLetterOffsets(chord);
+  if (offsets === void 0) {
+    return void 0;
+  }
+  const index = chord.intervals.findIndex(
+    (interval) => pitchClassOf(chord.rootPc + interval) === pitchClassOf(pitch)
+  );
+  const offset = offsets[index];
+  return offset === void 0 ? void 0 : ROLE_BY_LETTER_OFFSET[offset] ?? null;
+}
+function chordPcMask(chord, opts = {}) {
+  assertRecord(chord, "chord");
+  assertArray(chord.intervals, "chord intervals");
+  let mask = 0;
   for (const interval of chord.intervals) {
-    set.add(pitchClassOf(chord.rootPc + interval));
+    mask |= 1 << pitchClassOf(chord.rootPc + interval);
   }
   if (opts.includeBass !== false && chord.bassPc !== void 0) {
-    set.add(pitchClassOf(chord.bassPc));
+    mask |= 1 << pitchClassOf(chord.bassPc);
+  }
+  return mask;
+}
+function hasPitchClass(mask, pc) {
+  return (mask >> pc & 1) === 1;
+}
+function chordIntervalMask(chord) {
+  let mask = 0;
+  for (const interval of chord.intervals) {
+    mask |= 1 << (interval % 12 + 12) % 12;
+  }
+  return mask;
+}
+function chordPitchClasses(chord, opts = {}) {
+  const mask = chordPcMask(assertChord(chord), assertOptions(opts, "opts"));
+  const pcs = [];
+  for (let pc = 0; pc < 12; pc += 1) {
+    if (hasPitchClass(mask, pc)) {
+      pcs.push(pc);
+    }
   }
-  return [...set].sort((a, b) => a - b);
+  return pcs;
 }
 function intervalAboveRoot(pitch, chord) {
-  return ((pitchClassOf(pitch) - pitchClassOf(chord.rootPc)) % 12 + 12) % 12;
+  return ((pitchClassOf(pitch) - pitchClassOf(assertChord(chord).rootPc)) % 12 + 12) % 12;
 }
 function isChordMember(pitch, chord) {
-  return chord === null ? false : chordPitchClasses(chord).includes(pitchClassOf(pitch));
-}
-function chordToneOffsets(chord) {
-  return new Set(chord.intervals.map((i) => (i % 12 + 12) % 12));
+  return chord === null ? false : hasPitchClass(chordPcMask(chord), pitchClassOf(pitch));
 }
 function chordToneRole(pitch, chord) {
+  assertRecord(chord, "chord");
+  const spelled2 = spelledToneRole(pitch, chord);
+  if (spelled2 !== void 0) {
+    return spelled2;
+  }
   const interval = (pitchClassOf(pitch) - pitchClassOf(chord.rootPc) + 12) % 12;
-  const tones = chordToneOffsets(chord);
+  const tones = chordIntervalMask(chord);
+  const sounds = (ic) => hasPitchClass(tones, ic);
   if (interval === 0) {
-    return "root";
+    return sounds(0) ? "root" : null;
   }
   if (interval === 3 || interval === 4) {
-    return tones.has(interval) && (interval !== 3 || !tones.has(4)) ? "third" : null;
+    return sounds(interval) && (interval !== 3 || !sounds(4)) ? "third" : null;
   }
   if (interval === 7) {
-    return tones.has(7) ? "fifth" : null;
+    return sounds(7) ? "fifth" : null;
   }
   if (interval === 6) {
-    return tones.has(6) && !tones.has(7) ? "fifth" : null;
+    return sounds(6) && !sounds(7) ? "fifth" : null;
   }
   if (interval === 8) {
-    return tones.has(8) && !tones.has(7) ? "fifth" : null;
+    return sounds(8) && !sounds(7) ? "fifth" : null;
   }
   if (interval === 9) {
-    const hasHigherSeventh = tones.has(10) || tones.has(11);
-    const isDiminishedSeventh = tones.has(3) && tones.has(6) && !hasHigherSeventh;
-    if (tones.has(9) && isDiminishedSeventh) {
+    const hasHigherSeventh = sounds(10) || sounds(11);
+    const isDiminishedSeventh = sounds(3) && sounds(6) && !hasHigherSeventh;
+    if (sounds(9) && isDiminishedSeventh) {
       return "seventh";
     }
-    if (tones.has(9) && !hasHigherSeventh) {
+    if (sounds(9) && !hasHigherSeventh) {
       return "sixth";
     }
     return null;
   }
   if (interval === 10 || interval === 11) {
-    return tones.has(interval) ? "seventh" : null;
+    return sounds(interval) ? "seventh" : null;
   }
   return null;
 }
+var DEGREE_BY_ROLE = {
+  root: 1,
+  third: 3,
+  fifth: 5,
+  sixth: 6,
+  seventh: 7
+};
+var TENSION_DEGREE = [1, 2, 2, 2, 3, 4, 4, 5, 6, 6, 7, 7];
+function degreeOfInterval(interval, chord) {
+  const role = chordToneRole(pitchClassOf(chord.rootPc + interval), chord);
+  if (role !== null) {
+    return DEGREE_BY_ROLE[role];
+  }
+  return TENSION_DEGREE[(interval % 12 + 12) % 12];
+}
+function thirdSlotOf(chord) {
+  const tones = chordIntervalMask(chord);
+  if (hasPitchClass(tones, 4)) {
+    return { kind: "third", interval: 4 };
+  }
+  if (hasPitchClass(tones, 3)) {
+    return { kind: "third", interval: 3 };
+  }
+  const spec = chordSpecOf(chord);
+  if (spec.base === "sus2") {
+    return hasPitchClass(tones, 2) ? { kind: "suspension", interval: 2 } : { kind: "none" };
+  }
+  if (spec.base === "sus4" || spec.omissions.includes(3)) {
+    return hasPitchClass(tones, 5) ? { kind: "suspension", interval: 5 } : { kind: "none" };
+  }
+  return { kind: "none" };
+}
+function displacedThirds(chord) {
+  return thirdSlotOf(chord).kind === "suspension" ? [pitchClassOf(chord.rootPc + 3), pitchClassOf(chord.rootPc + 4)] : [];
+}
 function classifyTriad(thirdIc, fifthIc) {
   if (thirdIc === 4 && fifthIc === 8) {
     return "aug";
@@ -1396,16 +1684,32 @@ function capChromaticAccidentals(preferred, alternative) {
   return alternative !== void 0 && Math.abs(preferred.alter) - Math.abs(alternative.alter) >= 2 ? alternative : preferred;
 }
 var DIATONIC_LETTER_COUNT = 7;
+var MAX_JOINT_TONE_COUNT = DIATONIC_LETTER_COUNT + 1;
+var MAJOR_SEMITONES = [0, 2, 4, 5, 7, 9, 11];
+var IMPERFECT_DEGREES = /* @__PURE__ */ new Set([1, 2, 5, 6]);
+var DIATONIC_MODE_OFFSETS2 = MAJOR_SEMITONES.map(
+  (tonic, mode) => MAJOR_SEMITONES.map((_, degree) => pitchClassOf((MAJOR_SEMITONES[(mode + degree) % 7] ?? 0) - tonic))
+);
+function degreeStrain(tonic, note) {
+  const letterOffset = diatonicLetterOf(note.letter - tonic.letter);
+  const offset = pitchClassOf(notePitchClass(note) - notePitchClass(tonic));
+  let deviation = pitchClassOf(offset - (MAJOR_SEMITONES[letterOffset] ?? 0));
+  if (deviation > 6) {
+    deviation -= 12;
+  }
+  const strain = IMPERFECT_DEGREES.has(letterOffset) && deviation < 0 ? Math.abs(deviation + 1) : Math.abs(deviation);
+  return Math.min(strain, 2);
+}
 function isHeptatonic(key) {
   return scaleTonesInDegreeOrder(key).length === DIATONIC_LETTER_COUNT;
 }
-function hasMinorThird2(key) {
+function hasMinorThird(key) {
   const tones = scaleTonesInDegreeOrder(key);
   const root = pitchClassOf(key.rootPc);
   return tones.includes(pitchClassOf(root + 3)) && !tones.includes(pitchClassOf(root + 4));
 }
 function leansFlat(tonic, key) {
-  return tonic.alter < 0 || hasMinorThird2(key);
+  return tonic.alter < 0 || hasMinorThird(key);
 }
 function gappedCandidates(tonic, offset, pc, preferFlat) {
   const flat = letterFor(tonic, CHROMATIC_SPELLING_FLAT[offset], pc);
@@ -1417,22 +1721,64 @@ function gappedCandidates(tonic, offset, pc, preferFlat) {
   const alternative = preferred === flat ? sharp : flat;
   return alternative === void 0 || alternative.letter === preferred.letter ? [preferred] : [preferred, alternative];
 }
-function assignDistinctLetters(candidates, reserved) {
+function spellByParentMode(tonic, pcs, preferFlat) {
+  const tonicPc = notePitchClass(tonic);
+  let best;
+  let bestAlter = 0;
+  let bestSigned = 0;
+  for (const offsets of DIATONIC_MODE_OFFSETS2) {
+    const notes = [];
+    let alter = 0;
+    let signed = 0;
+    for (const pc of pcs) {
+      const degree = offsets.indexOf(pitchClassOf(pc - tonicPc));
+      const note = letterFor(tonic, degree < 0 ? void 0 : degree, pc);
+      if (note === void 0) {
+        break;
+      }
+      notes.push(note);
+      alter += Math.abs(note.alter);
+      signed += note.alter;
+    }
+    if (notes.length !== pcs.length) {
+      continue;
+    }
+    const evenlyLight = alter === bestAlter && (preferFlat ? signed < bestSigned : signed > bestSigned);
+    const lighter = alter < bestAlter || evenlyLight;
+    if (best === void 0 || lighter) {
+      best = notes;
+      bestAlter = alter;
+      bestSigned = signed;
+    }
+  }
+  return best;
+}
+function assignDistinctLetters(candidates, tonic, duplicates) {
+  const reserved = 1 << diatonicLetterOf(tonic.letter);
   let best;
+  let bestStrain = 0;
   let bestAlter = 0;
   let bestDeviations = 0;
   for (let choice = 0; choice < 1 << candidates.length; choice += 1) {
     const picked = [];
     let letters = reserved;
+    let spare = duplicates;
+    let strain = 0;
     let alter = 0;
     let deviations = 0;
     for (const [index, options] of candidates.entries()) {
       const preferred = options[0];
       const note = options[choice >> index & 1] ?? preferred;
-      if (note === void 0 || (letters & 1 << note.letter) !== 0) {
+      if (note === void 0) {
+        break;
+      }
+      const taken = (letters & 1 << note.letter) !== 0;
+      if (taken && (spare === 0 || (reserved & 1 << note.letter) !== 0)) {
         break;
       }
+      spare -= taken ? 1 : 0;
       letters |= 1 << note.letter;
+      strain += degreeStrain(tonic, note);
       alter += Math.abs(note.alter);
       deviations += note === preferred ? 0 : 1;
       picked.push(note);
@@ -1440,8 +1786,10 @@ function assignDistinctLetters(candidates, reserved) {
     if (picked.length !== candidates.length) {
       continue;
     }
-    if (best === void 0 || alter < bestAlter || alter === bestAlter && deviations < bestDeviations) {
+    const better = duplicates > 0 && strain !== bestStrain ? strain < bestStrain : alter !== bestAlter ? alter < bestAlter : deviations < bestDeviations;
+    if (best === void 0 || better) {
       best = picked;
+      bestStrain = strain;
       bestAlter = alter;
       bestDeviations = deviations;
     }
@@ -1449,18 +1797,33 @@ function assignDistinctLetters(candidates, reserved) {
   return best;
 }
 function spellGappedScale(tonic, key) {
+  const cacheKey = `${diatonicLetterOf(tonic.letter)}:${tonic.alter}:${key.rootPc}:${key.modeMask12}`;
+  const cached = JOINT_SPELLINGS.get(cacheKey);
+  if (cached !== void 0) {
+    return cached.spellings;
+  }
+  const answer = readGappedScale(tonic, key);
+  if (JOINT_SPELLINGS.size >= MAX_REMEMBERED_SCALES) {
+    JOINT_SPELLINGS.clear();
+  }
+  JOINT_SPELLINGS.set(cacheKey, { spellings: answer });
+  return answer;
+}
+var MAX_REMEMBERED_SCALES = 512;
+var JOINT_SPELLINGS = /* @__PURE__ */ new Map();
+function readGappedScale(tonic, key) {
   const tones = scaleTonesInDegreeOrder(key);
-  if (tones.length > DIATONIC_LETTER_COUNT) {
+  if (tones.length > MAX_JOINT_TONE_COUNT) {
     return void 0;
   }
   const tonicPc = pitchClassOf(naturalPitchClassOf(tonic.letter) + tonic.alter);
   const tonicNote = { letter: diatonicLetterOf(tonic.letter), alter: tonic.alter };
   const preferFlat = leansFlat(tonic, key);
   const rest = tones.filter((pc) => pitchClassOf(pc - tonicPc) !== 0);
-  const chosen = assignDistinctLetters(
-    rest.map((pc) => gappedCandidates(tonic, pitchClassOf(pc - tonicPc), pc, preferFlat)),
-    1 << tonicNote.letter
-  );
+  const candidates = rest.map((pc) => gappedCandidates(tonic, pitchClassOf(pc - tonicPc), pc, preferFlat));
+  const chosen = spellByParentMode(tonicNote, rest, preferFlat) ?? // A scale that can hold a letter per tone does; only one that cannot writes
+  // a letter twice, and then where the doubling falls is what is chosen.
+  assignDistinctLetters(candidates, tonicNote, 0) ?? assignDistinctLetters(candidates, tonicNote, 1);
   if (chosen === void 0) {
     return void 0;
   }
@@ -1498,7 +1861,7 @@ function spellByKey(pc, tonic, key) {
     if (isScaleTone(pc, key)) {
       const assigned = spellGappedScale(tonic, key)?.get(pitchClassOf(pc));
       if (assigned !== void 0) {
-        return assigned;
+        return { letter: assigned.letter, alter: assigned.alter };
       }
     }
     const [preferred] = gappedCandidates(tonic, offset, pc, leansFlat(tonic, key));
@@ -1523,13 +1886,39 @@ var CHORD_TONE_LETTER_STEPS = {
   11: 6
   // major seventh
 };
+var LETTER_STEP_BY_ROLE = {
+  root: 0,
+  third: 2,
+  fifth: 4,
+  sixth: 5,
+  seventh: 6
+};
 var MAX_CONTEXT_ALTER = 2;
-function chordToneSpelling(pc, chordRoot, tonic, key) {
+function chordToneLetterStep(pc, rootPc, chord) {
+  if (chord !== void 0) {
+    const offsets = chordToneLetterOffsets(chord);
+    const index = chord.intervals.findIndex(
+      (interval) => pitchClassOf(chord.rootPc + interval) === pitchClassOf(pc)
+    );
+    const offset = offsets?.[index];
+    if (offset !== void 0) {
+      return offset;
+    }
+    const role = chordToneRole(pc, chord);
+    if (role !== null) {
+      return LETTER_STEP_BY_ROLE[role];
+    }
+  }
+  return CHORD_TONE_LETTER_STEPS[pitchClassOf(pc - rootPc)];
+}
+function spellChordTone(pc, context, tonic, key) {
+  const { chord } = context;
+  const chordRoot = chord?.rootPc ?? context.chordRoot;
   if (chordRoot === void 0) {
     return void 0;
   }
-  const root = spellByKey(pitchClassOf(chordRoot), tonic, key);
-  return letterFor(root, CHORD_TONE_LETTER_STEPS[pitchClassOf(pc - chordRoot)], pc);
+  const root = chord === void 0 ? spellByKey(pitchClassOf(chordRoot), tonic, key) : chordRootSpelling(chord, tonic, key);
+  return letterFor(root, chordToneLetterStep(pc, chordRoot, chord), pc);
 }
 function neighbourSpelling(neighbour, gap, letterStep, pc, tonic, key) {
   if (neighbour === void 0 || pitchClassOf(neighbour - pc) !== pitchClassOf(gap)) {
@@ -1542,10 +1931,10 @@ function refineByContext(pc, tonic, key, context, keySpelling) {
   if (pitchClassOf(pc) === tonicPc || isScaleTone(pc, key)) {
     return keySpelling;
   }
-  const { chordRoot, previous, next } = context;
+  const { previous, next } = context;
   const candidates = [
-    // The sounding chord names the pitch by its interval above the root.
-    chordToneSpelling(pc, chordRoot, tonic, key),
+    // The sounding chord names the pitch by the degree it writes it as.
+    spellChordTone(pc, context, tonic, key),
     // A semitone below what follows: the pitch is its leading tone, a letter down.
     neighbourSpelling(next, 1, -1, pc, tonic, key),
     // A semitone above what preceded: the pitch is that note inflected upward,
@@ -1569,6 +1958,7 @@ function spellPitchClass(pc, tonic, key, context) {
   const note = toNoteData(tonic);
   const scale = toKeyScale(key);
   assertTonicOf(note, scale, "spellPitchClass");
+  assertOptions(context, "context");
   return spelledPitchClass(pc, note, scale, context);
 }
 function spelledPitchClass(pc, tonic, key, context) {
@@ -1577,15 +1967,18 @@ function spelledPitchClass(pc, tonic, key, context) {
 }
 function spellScale(tonic, key) {
   const note = toNoteData(tonic);
-  const scale = key;
+  const scale = toKeyScale(key);
   assertTonicOf(note, scale, "spellScale");
   return scaleTonesInDegreeOrder(scale).map((pc) => spelledPitchClass(pc, note, scale));
 }
 function spellPitchClasses(pcs, tonic, key) {
+  const classes = assertArray(pcs, "pcs");
   const note = toNoteData(tonic);
   const scale = toKeyScale(key);
   assertTonicOf(note, scale, "spellPitchClasses");
-  return pcs.map((pc) => spelledPitchClass(pc, note, scale));
+  return classes.map(
+    (pc, index) => spelledPitchClass(assertPitchClass(pc, `pcs[${index}]`), note, scale)
+  );
 }
 function chordLetterOffset(interval, chord) {
   switch (interval) {
@@ -1599,11 +1992,11 @@ function chordLetterOffset(interval, chord) {
       return 1;
     case 3:
     case 4:
-    case 16:
       return 2;
     case 15:
       return chord.intervals.some((i) => i === 3 || i === 4) ? 1 : 2;
     case 5:
+    case 16:
     case 17:
     case 18:
       return 3;
@@ -1616,10 +2009,10 @@ function chordLetterOffset(interval, chord) {
       return chord.quality === "dim7" ? 6 : 5;
     case 20:
     case 21:
+    case 22:
       return 5;
     case 10:
     case 11:
-    case 22:
     case 23:
       return 6;
     default: {
@@ -1630,22 +2023,14 @@ function chordLetterOffset(interval, chord) {
     }
   }
 }
-function hintedLetterOffsets(chord) {
-  const hints = chordToneSpellings(chord);
-  const rootHint = hints?.[chord.intervals.findIndex((interval) => pitchClassOf(interval) === 0)];
-  if (hints === void 0 || rootHint === void 0) {
-    return void 0;
-  }
-  return hints.map((hint) => diatonicLetterOf(hint.letter - rootHint.letter));
-}
 function spellChordFromRoot(chord, root) {
-  return chordTonesFromRoot(chord, toNoteData(root));
+  return chordTonesFromRoot(assertChord(chord), toNoteData(root));
 }
 function chordTonesFromRoot(chord, root) {
   if (pitchClassOf(naturalPitchClassOf(root.letter) + root.alter) !== pitchClassOf(chord.rootPc)) {
     throw new InvalidInputError("chord root spelling must match chord.rootPc");
   }
-  const hinted = hintedLetterOffsets(chord);
+  const hinted = chordToneLetterOffsets(chord);
   return chord.intervals.map((interval, index) => {
     const letter = diatonicLetterOf(root.letter + (hinted?.[index] ?? chordLetterOffset(interval, chord)));
     const pc = pitchClassOf(chord.rootPc + interval);
@@ -1653,6 +2038,7 @@ function chordTonesFromRoot(chord, root) {
   });
 }
 function spellChord(chord, tonic, key) {
+  assertChord(chord);
   const note = toNoteData(tonic);
   const scale = toKeyScale(key);
   assertTonicOf(note, scale, "spellChord");
@@ -1669,16 +2055,26 @@ function spellPitch(pitch, tonic, key, context) {
   const note = toNoteData(tonic);
   const scale = toKeyScale(key);
   assertTonicOf(note, scale, "spellPitch");
-  const rounded = Math.round(pitch);
-  const spelled = spelledPitchClass(pitchClassOf(rounded), note, scale, context);
-  const octave = (rounded - naturalPitchClassOf(spelled.letter) - spelled.alter) / 12 - 1;
-  return { letter: spelled.letter, alter: spelled.alter, octave };
+  assertOptions(context, "context");
+  const rounded = Math.round(assertFiniteNumber(pitch, "pitch"));
+  const spelled2 = spelledPitchClass(pitchClassOf(rounded), note, scale, context);
+  const octave = (rounded - naturalPitchClassOf(spelled2.letter) - spelled2.alter) / 12 - 1;
+  return { letter: spelled2.letter, alter: spelled2.alter, octave };
 }
 function noteNames(notes) {
+  assertArray(notes, "notes");
   return notes.map((note) => formatNote(toNoteData(note)));
 }
 
 // src/theory/counterpoint/internal.ts
+function assertQualityLabel(quality) {
+  if (typeof quality !== "string" || !/^(P|M|m|A+|d+)$/.test(quality)) {
+    throw new InvalidInputError(
+      `interval.quality must be an interval quality; received ${describeRejected(quality)}`
+    );
+  }
+  return quality;
+}
 function pitchOf(value) {
   return typeof value === "number" ? value : noteToMidi(value);
 }
@@ -1686,8 +2082,10 @@ function simpleIntervalNumber(numberValue) {
   return (Math.abs(numberValue) - 1) % 7 + 1;
 }
 function classifySpelledInterval(interval, twoVoice = true) {
-  const simple = simpleIntervalNumber(interval.number);
-  const quality = interval.quality;
+  assertFlag(twoVoice, "twoVoice");
+  const read = assertRecord(interval, "interval");
+  const simple = simpleIntervalNumber(assertDegree(read.number, "interval.number"));
+  const quality = assertQualityLabel(read.quality);
   if (quality === "P") {
     if (simple === 1 || simple === 5) {
       return 0 /* PerfectConsonance */;
@@ -1738,23 +2136,26 @@ function motionBetween(from, to) {
   return before === after ? "parallel" : "similar";
 }
 function voiceIndependence(lead, counter, opts) {
-  if (lead.length !== counter.length) {
+  assertOptions(opts, "opts");
+  const upper = assertArray(lead, "lead");
+  const lower = assertArray(counter, "counter");
+  if (upper.length !== lower.length) {
     throw new InvalidInputError(
-      `voiceIndependence needs the two lines aligned slot for slot; received ${lead.length} and ${counter.length}`
+      `voiceIndependence needs the two lines aligned slot for slot; received ${upper.length} and ${lower.length}`
     );
   }
   for (const [name, flags] of [
     ["leadAttacks", opts?.leadAttacks],
     ["counterAttacks", opts?.counterAttacks]
   ]) {
-    if (flags !== void 0 && flags.length !== lead.length) {
+    if (flags !== void 0 && flags.length !== upper.length) {
       throw new InvalidInputError(
-        `voiceIndependence needs ${name} aligned slot for slot with the lines; received ${flags.length} and ${lead.length}`
+        `voiceIndependence needs ${name} aligned slot for slot with the lines; received ${flags.length} and ${upper.length}`
       );
     }
   }
-  const slots = lead.map((leadNote, index) => {
-    const counterNote = counter[index] ?? null;
+  const slots = upper.map((leadNote, index) => {
+    const counterNote = lower[index] ?? null;
     return {
       lead: leadNote,
       counter: counterNote,
@@ -1840,6 +2241,7 @@ function voiceIndependence(lead, counter, opts) {
 }
 
 // src/theory/counterpoint/index.ts
+var HIDDEN_PARALLEL_READINGS = Object.freeze(["fourPart", "twoVoice"]);
 function createsVoiceCrossing(upper, lower) {
   return pitchOf(upper) < pitchOf(lower);
 }
@@ -1917,7 +2319,8 @@ function createsParallelUnison(aPrev, aCur, bPrev, bCur) {
   }
   return a1 === b1 && a0 === b0;
 }
-function createsHiddenParallelPerfect(aPrev, aCur, bPrev, bCur) {
+function createsHiddenParallelPerfect(aPrev, aCur, bPrev, bCur, strictness = "fourPart") {
+  assertOneOf(strictness, HIDDEN_PARALLEL_READINGS, "strictness");
   const a0 = pitchOf(aPrev);
   const a1 = pitchOf(aCur);
   const b0 = pitchOf(bPrev);
@@ -1933,7 +2336,7 @@ function createsHiddenParallelPerfect(aPrev, aCur, bPrev, bCur) {
     return false;
   }
   const upperMove = a1 >= b1 ? aMove : bMove;
-  if (Math.abs(upperMove) <= 2) {
+  if (strictness === "fourPart" && Math.abs(upperMove) <= 2) {
     return false;
   }
   return true;
@@ -1948,7 +2351,12 @@ function createsBattuta(aPrev, aCur, bPrev, bCur) {
   if (!bothVoicesMove(aMove, bMove) || similarMotion(aMove, bMove)) {
     return false;
   }
-  if (simpleClass(a1 - b1) !== 0) {
+  const nowClass = simpleClass(a1 - b1);
+  if (nowClass !== 0) {
+    return false;
+  }
+  const prevClass = simpleClass(a0 - b0);
+  if (prevClass === nowClass) {
     return false;
   }
   const upperMove = a1 >= b1 ? aMove : bMove;
@@ -1962,12 +2370,13 @@ function createsVoiceOverlap(upperPrev, upperCur, lowerPrev, lowerCur) {
   return u1 < l0 || l1 > u0;
 }
 function exceedsSpacing(upper, lower, maxSemitones = 12) {
+  assertFiniteNumber(maxSemitones, "maxSemitones");
   return Math.abs(pitchOf(upper) - pitchOf(lower)) > maxSemitones;
 }
 function isLeadingToneResolution(prev, cur, key) {
   const prevPitch = pitchOf(prev);
   const curPitch = pitchOf(cur);
-  const tonic = pitchClassOf(key.rootPc);
+  const tonic = pitchClassOf(toKeyScale(key).rootPc);
   const leading = (tonic + 11) % 12;
   if (pitchClassOf(prevPitch) !== leading || pitchClassOf(curPitch) !== tonic) {
     return false;
@@ -2009,7 +2418,18 @@ var PROFILE_WEIGHTS = Object.freeze({
 var SAFETY_PROFILES = Object.keys(PROFILE_WEIGHTS);
 function profileWeights(profile, overrides) {
   const base = PROFILE_WEIGHTS[assertOneOf(profile, SAFETY_PROFILES, "safety profile")];
-  return { ...base, ...overrides };
+  if (overrides === void 0) {
+    return { ...base };
+  }
+  assertRecord(overrides, "overrides");
+  const weights = { ...base };
+  for (const [field, value] of Object.entries(overrides)) {
+    if (value === void 0) {
+      continue;
+    }
+    weights[field] = assertFiniteNumber(value, `weight ${field}`);
+  }
+  return weights;
 }
 var NoteSafety = /* @__PURE__ */ ((NoteSafety2) => {
   NoteSafety2[NoteSafety2["Safe"] = 0] = "Safe";
@@ -2017,6 +2437,7 @@ var NoteSafety = /* @__PURE__ */ ((NoteSafety2) => {
   NoteSafety2[NoteSafety2["Dissonant"] = 2] = "Dissonant";
   return NoteSafety2;
 })(NoteSafety || {});
+Object.freeze(NoteSafety);
 var ReasonFlag = /* @__PURE__ */ ((ReasonFlag2) => {
   ReasonFlag2[ReasonFlag2["ChordTone"] = 1] = "ChordTone";
   ReasonFlag2[ReasonFlag2["Tension"] = 2] = "Tension";
@@ -2037,6 +2458,7 @@ var ReasonFlag = /* @__PURE__ */ ((ReasonFlag2) => {
   ReasonFlag2[ReasonFlag2["MelodicTritone"] = 65536] = "MelodicTritone";
   return ReasonFlag2;
 })(ReasonFlag || {});
+Object.freeze(ReasonFlag);
 var SUGGESTION_WINDOW = 12;
 var MAX_SUGGESTIONS = 3;
 var REASON_SEVERITY = [
@@ -2092,9 +2514,11 @@ function stepResolution(pitch, chord) {
 function evaluateSafety(q, opts = {}) {
   assertSafetyContext(q);
   assertMidiPitch(q.candidatePitch, "candidatePitch");
-  return evaluateInternal(q, opts.suggestions ?? true);
+  const options = assertOptions(opts, "opts");
+  return evaluateInternal(q, options.suggestions ?? true, options.partners ?? false);
 }
 function assertSafetyContext(q) {
+  assertRecord(q, "safety query");
   assertOneOf(q.profile, SAFETY_PROFILES, "safety profile");
   if (q.prevPitch !== void 0) assertMidiPitch(q.prevPitch, "prevPitch");
   if (q.vocalLow !== void 0) assertMidiPitch(q.vocalLow, "vocalLow");
@@ -2115,7 +2539,7 @@ function assertSafetyContext(q) {
     }
   }
 }
-function evaluateInternal(q, collectSuggestions) {
+function evaluateInternal(q, collectSuggestions, collectPartners) {
   let reasons = 0;
   let level = 0 /* Safe */;
   let resolveTo;
@@ -2186,41 +2610,58 @@ function evaluateInternal(q, collectSuggestions) {
       reasons |= 512 /* MajorSeventh */;
     }
   }
+  let bass = pitch;
+  let top = pitch;
+  for (const ov of q.otherVoices) {
+    bass = Math.min(bass, ov.pitch);
+    top = Math.max(top, ov.pitch);
+  }
+  const pairReasons = collectPartners ? new Array(q.otherVoices.length).fill(0) : void 0;
+  const flagPair = (index, flag) => {
+    reasons |= flag;
+    if (pairReasons !== void 0) {
+      pairReasons[index] = (pairReasons[index] ?? 0) | flag;
+    }
+  };
   if (q.strongBeat) {
-    const twoVoice = q.otherVoices.length === 1;
     const prev = q.prevPitch;
-    for (const ov of q.otherVoices) {
-      if (!createsVerticalDissonance(pitch, ov.pitch, twoVoice)) {
+    for (const [index, ov] of q.otherVoices.entries()) {
+      const againstBass = pitch === bass || ov.pitch === bass;
+      if (!createsVerticalDissonance(pitch, ov.pitch, againstBass)) {
         continue;
       }
       if (chord && isStructuralChordDissonance(pitch, ov.pitch, chord)) {
         continue;
       }
-      reasons |= 1024 /* VerticalDissonance */;
+      if (chord && q.profile === "pop" && pitchClassOf(Math.abs(pitch - ov.pitch)) === 5 && isChordMember(pitch, chord) && isChordMember(ov.pitch, chord)) {
+        continue;
+      }
+      flagPair(index, 1024 /* VerticalDissonance */);
       raise(2 /* Dissonant */);
-      if (prev !== void 0 && pitch === prev && ov.prevPitch !== void 0 && !createsVerticalDissonance(prev, ov.prevPitch, twoVoice)) {
-        reasons |= 16384 /* Suspension */;
+      if (prev !== void 0 && pitch === prev && ov.prevPitch !== void 0 && !createsVerticalDissonance(prev, ov.prevPitch, againstBass)) {
+        flagPair(index, 16384 /* Suspension */);
       }
     }
   }
   if (q.prevPitch !== void 0) {
     const prev = q.prevPitch;
-    for (const ov of q.otherVoices) {
+    for (const [index, ov] of q.otherVoices.entries()) {
       if (ov.prevPitch === void 0) {
         continue;
       }
       if (createsParallelPerfect(prev, pitch, ov.prevPitch, ov.pitch)) {
-        reasons |= 2048 /* ParallelPerfect */;
+        flagPair(index, 2048 /* ParallelPerfect */);
         raise(parallelSeverity);
       }
-      if (createsHiddenParallelPerfect(prev, pitch, ov.prevPitch, ov.pitch)) {
-        reasons |= 4096 /* HiddenParallel */;
+      const outerPair = pitch === top && ov.pitch === bass || pitch === bass && ov.pitch === top;
+      if (outerPair && createsHiddenParallelPerfect(prev, pitch, ov.prevPitch, ov.pitch)) {
+        flagPair(index, 4096 /* HiddenParallel */);
         raise(parallelSeverity);
       }
       const crossedNow = pitch - ov.pitch;
       const crossedPrev = prev - ov.prevPitch;
       if (crossedNow !== 0 && crossedPrev !== 0 && crossedNow > 0 !== crossedPrev > 0) {
-        reasons |= 8192 /* VoiceCrossing */;
+        flagPair(index, 8192 /* VoiceCrossing */);
         raise(parallelSeverity);
       }
     }
@@ -2236,6 +2677,17 @@ function evaluateInternal(q, collectSuggestions) {
       result.suggestions = suggestions;
     }
   }
+  if (pairReasons !== void 0) {
+    const partners = [];
+    pairReasons.forEach((pair, index) => {
+      if (pair !== 0) {
+        partners.push({ index, reasons: pair });
+      }
+    });
+    if (partners.length > 0) {
+      result.partners = partners;
+    }
+  }
   return result;
 }
 function findSafeNearby(q, candidate) {
@@ -2245,7 +2697,7 @@ function findSafeNearby(q, candidate) {
       if (p < 0 || p > 127) {
         continue;
       }
-      if (evaluateInternal({ ...q, candidatePitch: p }, false).safety === 0 /* Safe */) {
+      if (evaluateInternal({ ...q, candidatePitch: p }, false, false).safety === 0 /* Safe */) {
         out.push(p);
         if (out.length >= MAX_SUGGESTIONS) {
           return out;
@@ -2269,7 +2721,7 @@ var REASON_TEXT = [
   [2048 /* ParallelPerfect */, "Parallel perfect interval with another voice"],
   [4096 /* HiddenParallel */, "Hidden perfect interval by similar motion"],
   [8192 /* VoiceCrossing */, "Crosses another voice"],
-  [128 /* LargeLeap */, "Leap wider than the profile allows"],
+  [128 /* LargeLeap */, "Forbidden melodic leap \u2014 a seventh or wider than an octave"],
   [32768 /* NeedsResolution */, "Dissonance awaiting a stepwise resolution"],
   [2 /* Tension */, "Chord tension"],
   [8 /* ScaleTone */, "Scale tone, not in the chord"],
@@ -2314,7 +2766,7 @@ function enumerateSafePitches(q, pitchLow, pitchHigh) {
   const low = Math.max(pitchLow, q.vocalLow ?? pitchLow);
   const high = Math.min(pitchHigh, q.vocalHigh ?? pitchHigh);
   for (let pitch = high; pitch >= low; pitch -= 1) {
-    const result = evaluateInternal({ ...q, candidatePitch: pitch }, false);
+    const result = evaluateInternal({ ...q, candidatePitch: pitch }, false, false);
     if (result.safety === 2 /* Dissonant */) {
       continue;
     }
@@ -2327,7 +2779,7 @@ function enumerateSafePitches(q, pitchLow, pitchHigh) {
   return [...chordTones, ...others];
 }
 
-// src/theory/symbol/index.ts
+// src/theory/symbol/grammar.ts
 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 DEFAULT_SYSTEM = "english";
@@ -2430,51 +2882,6 @@ var QUALITY_MAP = {
   h: "m7b5",
   h7: "m7b5"
 };
-var CANONICAL_SUFFIX = {
-  maj: "",
-  min: "m",
-  dim: "dim",
-  aug: "aug",
-  maj7: "maj7",
-  min7: "m7",
-  dom7: "7",
-  dim7: "dim7",
-  m7b5: "m7b5",
-  minMaj7: "mMaj7",
-  minMaj9: "mMaj9",
-  minMaj11: "mMaj11",
-  minMaj13: "mMaj13",
-  aug7: "aug7",
-  augMaj7: "augMaj7",
-  majb5: "maj(b5)",
-  "6": "6",
-  min6: "m6",
-  "6/9": "6/9",
-  sus2: "sus2",
-  sus4: "sus4",
-  add9: "add9",
-  add11: "add11",
-  maj9: "maj9",
-  min9: "m9",
-  dom9: "9",
-  "7b9": "7b9",
-  "7#9": "7#9",
-  "7#11": "7#11",
-  "7b13": "7b13",
-  "11": "11",
-  "13": "13",
-  "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 knownQuality(suffix) {
   return Object.hasOwn(QUALITY_MAP, suffix) ? QUALITY_MAP[suffix] : void 0;
 }
@@ -2486,6 +2893,7 @@ var BASE_TOKENS = [
   ["dim", "dim"],
   ["aug", "aug"],
   ["maj", "major"],
+  ["Maj", "major"],
   ["m", "min"],
   ["-", "min"],
   ["o", "dim"],
@@ -2495,6 +2903,10 @@ var BASE_TOKENS = [
   ["\u0394", "major"],
   ["^", "major"]
 ];
+var COMPOUND_TOKENS = [
+  ["\xF8", { base: "dim", seventh: "min7" }],
+  ["h", { base: "dim", seventh: "min7" }]
+];
 var MAJOR_MARKERS = [
   ["maj", "word"],
   ["Maj", "word"],
@@ -2513,6 +2925,27 @@ var ADDED_DEGREES = {
 };
 var ALTERABLE = { "5": 5, "9": 9, "11": 11, "13": 13 };
 var OMITTABLE = { "1": 1, "3": 3, "5": 5 };
+function alterationKey(degree, alter) {
+  return `${degree}:${alter}`;
+}
+function writeAlteration(draft, degree, alter) {
+  if (draft.implied.delete(degree)) {
+    draft.alterations.delete(alterationKey(degree, 0));
+  }
+  draft.alterations.set(alterationKey(degree, alter), { degree, alter });
+}
+function implyAlteration(draft, degree) {
+  draft.implied.add(degree);
+  draft.alterations.set(alterationKey(degree, 0), { degree, alter: 0 });
+}
+function altersDegree(draft, degree) {
+  for (const alteration of draft.alterations.values()) {
+    if (alteration.degree === degree) {
+      return true;
+    }
+  }
+  return false;
+}
 function matchToken(text, at, table) {
   let found;
   for (const [token, value] of table) {
@@ -2536,15 +2969,18 @@ function stackTo(draft, top) {
     draft.additions.add(6);
     return;
   }
-  draft.seventh = draft.major ? "maj7" : draft.base === "dim" ? "dim7" : "min7";
+  draft.seventh = draft.major ? "maj7" : draft.seventhOverBase ?? (draft.base === "dim" ? "dim7" : "min7");
   if (top >= 9) {
-    draft.alterations.set(9, 0);
+    implyAlteration(draft, 9);
   }
   if (top === 11) {
-    draft.alterations.set(11, 0);
+    implyAlteration(draft, 11);
+    if (!draft.major && draft.base === "maj") {
+      draft.omissions.add(3);
+    }
   }
   if (top === 13) {
-    draft.alterations.set(13, 0);
+    implyAlteration(draft, 13);
   }
 }
 function applyFigure(draft, text, at) {
@@ -2560,7 +2996,7 @@ function applyFigure(draft, text, at) {
   if (text.startsWith("alt", at)) {
     draft.base = "aug";
     draft.seventh = "min7";
-    draft.alterations.set(9, 1);
+    writeAlteration(draft, 9, 1);
     return at + 3;
   }
   if (text.startsWith("add", at)) {
@@ -2592,13 +3028,37 @@ function applyFigure(draft, text, at) {
   if (degree === void 0) {
     return void 0;
   }
-  draft.alterations.set(degree.value, accidental?.value ?? 0);
+  if (degree.value === 5 && (accidental === void 0 || writesFifth(draft))) {
+    return void 0;
+  }
+  writeAlteration(draft, degree.value, accidental?.value ?? 0);
   return degree.next;
 }
+function writesFifth(draft) {
+  return draft.base === "dim" || draft.base === "aug" || altersDegree(draft, 5);
+}
 function matchNumberToken(text, at, table) {
   const entries = Object.entries(table).map(([token, value]) => [token, value]);
   return matchToken(text, at, entries);
 }
+function openings(core) {
+  const found = [];
+  for (const [token, value] of COMPOUND_TOKENS) {
+    if (core.startsWith(token)) {
+      found.push({ length: token.length, base: value.base, seventh: value.seventh });
+    }
+  }
+  for (const [token, value] of BASE_TOKENS) {
+    if (!core.startsWith(token)) {
+      continue;
+    }
+    found.push(
+      value === "major" ? { length: token.length, major: true, glyph: token === "\u0394" || token === "^" } : { length: token.length, base: value }
+    );
+  }
+  found.sort((a, b) => b.length - a.length);
+  return [...found, void 0];
+}
 function structuralSpec(text) {
   let core = "";
   const groups = [];
@@ -2626,24 +3086,37 @@ function structuralSpec(text) {
   if (inside) {
     return void 0;
   }
+  for (const opening of openings(core)) {
+    const spec = readCore(core, groups, opening);
+    if (spec !== void 0) {
+      return spec;
+    }
+  }
+  return void 0;
+}
+function readCore(core, groups, opening) {
   const draft = {
     base: "maj",
     alterations: /* @__PURE__ */ new Map(),
     additions: /* @__PURE__ */ new Set(),
     omissions: /* @__PURE__ */ new Set(),
+    implied: /* @__PURE__ */ new Set(),
     major: false
   };
   let at = 0;
-  const opening = matchToken(core, at, BASE_TOKENS);
   let markerGlyph = false;
   let markerAfterBase = false;
   if (opening !== void 0) {
-    at = opening.next;
-    if (opening.value === "major") {
+    at = opening.length;
+    if (opening.major === true) {
       draft.major = true;
-      markerGlyph = core.startsWith("\u0394") || core.startsWith("^");
-    } else {
-      draft.base = opening.value;
+      markerGlyph = opening.glyph === true;
+    } else if (opening.base !== void 0) {
+      draft.base = opening.base;
+      if (opening.seventh !== void 0) {
+        draft.seventh = opening.seventh;
+        draft.seventhOverBase = opening.seventh;
+      }
     }
   }
   if (!draft.major) {
@@ -2688,7 +3161,7 @@ function structuralSpec(text) {
     rootPc: 0,
     base: draft.base,
     ...draft.seventh === void 0 ? {} : { seventh: draft.seventh },
-    alterations: [...draft.alterations].map(([degree, alter]) => ({ degree, alter })),
+    alterations: [...draft.alterations.values()],
     additions: [...draft.additions],
     omissions: [...draft.omissions]
   };
@@ -2715,7 +3188,8 @@ function rootSplits(text, system) {
   }
   assertNamingSystem(system);
   const splits = [];
-  for (let end = text.length; end > 0; end -= 1) {
+  const longest = Math.min(text.length, maxNoteNameLength(system));
+  for (let end = longest; end > 0; end -= 1) {
     const root = bareNote(text.slice(0, end), system);
     if (root !== void 0) {
       splits.push({ root, rest: text.slice(end) });
@@ -2753,82 +3227,53 @@ function chordAfterRoot(root, rest, system) {
   const spec = suffixSpec(rest);
   return spec === void 0 ? void 0 : makeSpelledChord(root, spec);
 }
-function parseChordSymbol(text, opts) {
-  return unwrapParse(tryParseChordSymbol(text, opts));
-}
-function tryParseChordSymbol(text, opts) {
-  try {
-    if (typeof text !== "string") {
-      throw new InvalidInputError(`chord symbol must be a string; received ${typeof text}`);
-    }
-    const system = opts?.system ?? DEFAULT_SYSTEM;
-    const trimmed = text.trim().replaceAll("\u266F", "#").replaceAll("\u266D", "b").replaceAll("\u{1D12A}", "x").replaceAll("\u{1D12B}", "bb").replaceAll("\u2206", "\u0394");
-    const splits = rootSplits(trimmed, system);
-    if (splits.length === 0) {
-      throw new InvalidInputError(`Invalid chord symbol: ${text}`);
-    }
-    for (const { root, rest } of splits) {
-      const chord = chordAfterRoot(root, rest, system);
-      if (chord !== void 0) {
-        return { ok: true, value: chord };
-      }
-    }
-    throw new InvalidInputError(`Unrecognized chord quality: ${text}`);
-  } catch (error) {
-    return parseFailure(error);
-  }
-}
-function normalizedChord(data) {
-  if (!Array.isArray(data.intervals)) {
-    throw new InvalidInputError("chord.intervals must be an array of semitone offsets");
-  }
-  const copy = {
-    rootPc: pitchClassOf(assertFiniteNumber(data.rootPc, "chord.rootPc")),
-    quality: data.quality,
-    // Each offset is checked rather than copied blind: a chord holding a NaN
-    // interval voices, spells and formats as a chord that looks real, and the
-    // failure surfaces wherever the number is finally used.
-    intervals: data.intervals.map(
-      (interval, index) => assertFiniteNumber(interval, `chord.intervals[${index}]`)
-    )
-  };
-  if (data.bassPc !== void 0) {
-    copy.bassPc = pitchClassOf(assertFiniteNumber(data.bassPc, "chord.bassPc"));
-  }
-  if (data.rootSpelling !== void 0) {
-    copy.rootSpelling = data.rootSpelling;
-  }
-  if (data.bassSpelling !== void 0) {
-    copy.bassSpelling = data.bassSpelling;
-  }
-  if (data.toneSpellings !== void 0) {
-    copy.toneSpellings = data.toneSpellings;
-  }
-  return copy;
-}
-function toChordData(value) {
-  if (typeof value === "string") {
-    return parseChordSymbol(value);
-  }
-  if (typeof value === "object" && value !== null) {
-    const data = "toJSON" in value && typeof value.toJSON === "function" ? value.toJSON() : value;
-    return normalizedChord(data);
-  }
-  throw new InvalidInputError(
-    `chord must be a chord symbol or chord data; received ${typeof value}`
-  );
-}
-function symbolName(note, system) {
-  const name = formatNote(note, { system });
-  return system === "german" ? `${name.slice(0, 1).toUpperCase()}${name.slice(1)}` : name;
-}
-function pitchClassName(pc, hint, system, flats, inheritFlats) {
-  if (flats === void 0 && hint !== void 0 && noteToPitchClass(hint) === pc) {
-    return symbolName(hint, system);
-  }
-  const note = midiToNote(60 + pc, flats ?? inheritFlats ? "flat" : "sharp");
-  return symbolName({ letter: note.letter, alter: note.alter }, system);
-}
+
+// src/theory/symbol/suffix.ts
+var CANONICAL_SUFFIX = {
+  maj: "",
+  min: "m",
+  dim: "dim",
+  aug: "aug",
+  maj7: "maj7",
+  min7: "m7",
+  dom7: "7",
+  dim7: "dim7",
+  m7b5: "m7b5",
+  minMaj7: "mMaj7",
+  minMaj9: "mMaj9",
+  minMaj11: "mMaj11",
+  minMaj13: "mMaj13",
+  aug7: "aug7",
+  augMaj7: "augMaj7",
+  majb5: "maj(b5)",
+  "6": "6",
+  min6: "m6",
+  "6/9": "6/9",
+  sus2: "sus2",
+  sus4: "sus4",
+  add9: "add9",
+  add11: "add11",
+  maj9: "maj9",
+  min9: "m9",
+  dom9: "9",
+  "7b9": "7b9",
+  "7#9": "7#9",
+  "7#11": "7#11",
+  "7b13": "7b13",
+  "11": "11",
+  "13": "13",
+  "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"
+};
 var CORE_CANDIDATES = chordQualities().map((quality) => [quality, chordSpecForQuality(quality, 0)]).filter(([, spec]) => spec.alterations.every(({ degree, alter }) => degree === 5 || alter === 0));
 function carriesAlteration(spec, part) {
   return spec.alterations.some(
@@ -2900,42 +3345,338 @@ function specSuffix(spec) {
   const figures = figureText(spec, coreSpec);
   return figures.length === 0 ? text : `${text}(${figures.join(",")})`;
 }
+
+// src/theory/symbol/spelling.ts
+function bareSpelling(note) {
+  return { letter: note.letter, alter: note.alter };
+}
+function plainSpelling(pc, asFlat) {
+  return bareSpelling(midiToNote(60 + pc, asFlat ? "flat" : "sharp"));
+}
+function symbolName(note, system) {
+  const name = formatNote(note, { system });
+  return system === "german" ? `${name.slice(0, 1).toUpperCase()}${name.slice(1)}` : name;
+}
+function isWrittenSpelling(spelling) {
+  const written = midiToNote(
+    60 + noteToPitchClass(spelling),
+    spelling.alter < 0 ? "flat" : "sharp"
+  );
+  return written.letter === spelling.letter && written.alter === spelling.alter;
+}
+function pitchClassName(pc, hint, system, flats, inheritFlats) {
+  if (flats === void 0 && hint !== void 0 && noteToPitchClass(hint) === pc) {
+    return symbolName(hint, system);
+  }
+  return symbolName(plainSpelling(pc, flats ?? inheritFlats ?? false), system);
+}
+function onAccidentalSide(spelling, flats) {
+  return flats === void 0 || spelling.alter === 0 || spelling.alter < 0 === flats;
+}
+function bySameStep(spelling, from, to) {
+  return bareSpelling(transposeByInterval(spelling, spelledInterval(from, to)));
+}
+function spellingAbove(root, letters, pc) {
+  const letter = ((root.letter + letters) % 7 + 7) % 7;
+  const natural = noteToPitchClass({ letter, alter: 0 });
+  return { letter, alter: ((pc - natural) % 12 + 18) % 12 - 6 };
+}
+function carriedBass(spelling, from, to, asFlat, isOwnSpelling) {
+  const carried = bySameStep(spelling, from, to);
+  return isOwnSpelling(carried) || isWrittenSpelling(carried) ? carried : plainSpelling(noteToPitchClass(carried), asFlat);
+}
+function hintFor(hint, pc) {
+  return hint !== void 0 && noteToPitchClass(hint) === pc ? hint : void 0;
+}
+function rootSpellingFor(pc, hint, flats) {
+  return hint !== void 0 && onAccidentalSide(hint, flats) ? hint : plainSpelling(pc, flats ?? false);
+}
+
+// src/theory/symbol/index.ts
+function parseChordSymbol(text, opts) {
+  return unwrapParse(tryParseChordSymbol(text, opts));
+}
+function tryParseChordSymbol(text, opts) {
+  const asked = assertOptions(opts, "opts");
+  try {
+    if (typeof text !== "string") {
+      throw new InvalidInputError(`chord symbol must be a string; received ${typeof text}`);
+    }
+    const system = asked.system ?? DEFAULT_SYSTEM;
+    const trimmed = text.trim().replaceAll("\u266F", "#").replaceAll("\u266D", "b").replaceAll("\u{1D12A}", "x").replaceAll("\u{1D12B}", "bb").replaceAll("\u2206", "\u0394");
+    const splits = rootSplits(trimmed, system);
+    if (splits.length === 0) {
+      throw new InvalidInputError(`Invalid chord symbol: ${describeRejected(text)}`);
+    }
+    for (const { root, rest } of splits) {
+      const chord = chordAfterRoot(root, rest, system);
+      if (chord !== void 0) {
+        return { ok: true, value: chord };
+      }
+    }
+    throw new InvalidInputError(`Unrecognized chord quality: ${describeRejected(text)}`);
+  } catch (error) {
+    return parseFailure(error);
+  }
+}
 function formatChordSymbol(chord, opts) {
   const data = toChordData(chord);
   if (!Object.hasOwn(CANONICAL_SUFFIX, data.quality)) {
     throw new InvalidInputError(`Unknown chord quality: ${String(data.quality)}`);
   }
-  const system = opts?.system ?? DEFAULT_SYSTEM;
+  const asked = assertOptions(opts, "opts");
+  const system = asked.system ?? DEFAULT_SYSTEM;
+  const flats = asked.flats;
   const rootPc = pitchClassOf(data.rootPc);
-  const rootHint = data.rootSpelling;
-  const rootName = pitchClassName(rootPc, rootHint, system, opts?.flats);
+  const rootHint = hintFor(data.rootSpelling, rootPc);
+  const rootSpelling = rootSpellingFor(rootPc, rootHint, flats);
   const suffix = specSuffix(chordSpecOf(data));
-  let symbol = `${rootName}${suffix}`;
+  let symbol = `${symbolName(rootSpelling, system)}${suffix}`;
   if (data.bassPc !== void 0 && pitchClassOf(data.bassPc) !== rootPc) {
-    const inheritFlats = rootHint !== void 0 && noteToPitchClass(rootHint) === rootPc ? rootHint.alter < 0 : void 0;
     const bassPc = pitchClassOf(data.bassPc);
-    symbol += `/${pitchClassName(bassPc, data.bassSpelling, system, opts?.flats, inheritFlats)}`;
+    const bassHint = hintFor(data.bassSpelling, bassPc);
+    const tonePcs = new Set(chordPitchClasses(data, { includeBass: false }));
+    const ownSpelling = tonePcs.has(bassPc) ? spellingAbove(
+      rootSpelling,
+      (degreeOfInterval(pitchClassOf(bassPc - rootPc), data) ?? 1) - 1,
+      bassPc
+    ) : void 0;
+    const bassName = rootHint !== void 0 && bassHint !== void 0 ? symbolName(
+      carriedBass(
+        bassHint,
+        rootHint,
+        rootSpelling,
+        flats ?? rootSpelling.alter < 0,
+        (spelling) => ownSpelling !== void 0 && spelling.letter === ownSpelling.letter && spelling.alter === ownSpelling.alter
+      ),
+      system
+    ) : pitchClassName(bassPc, bassHint, system, flats, rootSpelling.alter < 0);
+    symbol += `/${bassName}`;
   }
   return symbol;
 }
+function transposeChordSpellings(spellings, semitones, flats) {
+  const byLetter = (spelling) => spelling === void 0 ? void 0 : bareSpelling(transposeNote(spelling, semitones));
+  const movedRoot = byLetter(spellings.rootSpelling);
+  const movedBass = byLetter(spellings.bassSpelling);
+  const side = [movedRoot, spellings.rootSpelling, movedBass, spellings.bassSpelling].find(
+    (spelling) => spelling !== void 0 && spelling.alter !== 0
+  );
+  const preferFlats = flats ?? (side !== void 0 && side.alter < 0);
+  const octaveOnly = pitchClassOf(semitones) === 0;
+  const plainName = (spelling, asFlat) => plainSpelling(noteToPitchClass(spelling), asFlat);
+  const writable = (spelling) => octaveOnly || isWrittenSpelling(spelling) ? spelling : plainName(spelling, preferFlats);
+  const root = spellings.rootSpelling;
+  const bass = spellings.bassSpelling;
+  const carriesBass = (candidate) => {
+    if (root === void 0 || bass === void 0 || octaveOnly || !isWrittenSpelling(bass)) {
+      return true;
+    }
+    const carried = bySameStep(bass, root, candidate);
+    return isWrittenSpelling(carried) && onAccidentalSide(carried, flats);
+  };
+  const moved = {};
+  if (movedRoot !== void 0) {
+    const asked = flats !== void 0 && !octaveOnly && !isWrittenSpelling(movedRoot);
+    const candidates = [
+      ...octaveOnly || isWrittenSpelling(movedRoot) ? [movedRoot] : [],
+      plainName(movedRoot, preferFlats),
+      ...asked ? [movedRoot] : [],
+      plainName(movedRoot, !preferFlats)
+    ];
+    moved.rootSpelling = candidates.find(carriesBass) ?? plainName(movedRoot, preferFlats);
+  }
+  const step = root !== void 0 && moved.rootSpelling !== void 0 ? spelledInterval(root, moved.rootSpelling) : void 0;
+  const byStep = (spelling) => bareSpelling(
+    step === void 0 ? transposeNote(spelling, semitones) : transposeByInterval(spelling, step)
+  );
+  if (bass !== void 0) {
+    moved.bassSpelling = writable(byStep(bass));
+  }
+  if (spellings.toneSpellings !== void 0) {
+    moved.toneSpellings = spellings.toneSpellings.map(byStep);
+  }
+  return moved;
+}
 function transposeChordSymbol(text, semitones, opts) {
   assertFiniteSemitones(semitones);
   const chord = parseChordSymbol(text, opts);
   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 = pitchClassOf(chord.bassPc + semitones);
   }
-  if (chord.bassSpelling !== void 0) {
-    const hint = transposeNote(chord.bassSpelling, semitones);
-    transposed.bassSpelling = { letter: hint.letter, alter: hint.alter };
+  const spellings = transposeChordSpellings(chord, semitones, opts?.flats);
+  if (spellings.rootSpelling !== void 0) {
+    transposed.rootSpelling = spellings.rootSpelling;
+  }
+  if (spellings.bassSpelling !== void 0) {
+    transposed.bassSpelling = spellings.bassSpelling;
+  }
+  if (spellings.toneSpellings !== void 0) {
+    transposed.toneSpellings = spellings.toneSpellings;
   }
   return formatChordSymbol(transposed, opts);
 }
 
+// src/theory/symbol/coerce.ts
+function normalizedChord(data) {
+  if (!Array.isArray(data.intervals)) {
+    throw new InvalidInputError("chord.intervals must be an array of semitone offsets");
+  }
+  const copy = {
+    rootPc: pitchClassOf(assertFiniteNumber(data.rootPc, "chord.rootPc")),
+    quality: data.quality,
+    // Each offset is checked rather than copied blind: a chord holding a NaN
+    // interval voices, spells and formats as a chord that looks real, and the
+    // failure surfaces wherever the number is finally used.
+    intervals: data.intervals.map(
+      (interval, index) => assertFiniteNumber(interval, `chord.intervals[${index}]`)
+    )
+  };
+  if (data.bassPc !== void 0) {
+    copy.bassPc = pitchClassOf(assertFiniteNumber(data.bassPc, "chord.bassPc"));
+  }
+  if (data.rootSpelling !== void 0) {
+    copy.rootSpelling = data.rootSpelling;
+  }
+  if (data.bassSpelling !== void 0) {
+    copy.bassSpelling = data.bassSpelling;
+  }
+  if (data.toneSpellings !== void 0) {
+    copy.toneSpellings = data.toneSpellings;
+  }
+  return copy;
+}
+function toChordData(value) {
+  if (typeof value === "string") {
+    return parseChordSymbol(value);
+  }
+  if (typeof value === "object" && value !== null) {
+    const data = "toJSON" in value && typeof value.toJSON === "function" ? value.toJSON() : value;
+    return normalizedChord(data);
+  }
+  throw new InvalidInputError(
+    `chord must be a chord symbol or chord data; received ${typeof value}`
+  );
+}
+
+// src/theory/tendency/index.ts
+function hasInterval(chord, semitones) {
+  return chord.intervals.some((interval) => pitchClassOf(interval) === semitones);
+}
+function isDiatonicChord(chord, key) {
+  return chordPitchClasses(chord).every((pc) => isScaleTone(pc, key));
+}
+function hasMajorThird(chord) {
+  return hasInterval(chord, 4);
+}
+function soundsDominantSeventh(chord) {
+  return hasMajorThird(chord) && hasInterval(chord, 10);
+}
+function soundsMajorTriad(chord) {
+  return hasMajorThird(chord) && !hasInterval(chord, 10) && !hasInterval(chord, 11);
+}
+function hasDominantSonority(chord) {
+  return soundsMajorTriad(chord) || soundsDominantSeventh(chord);
+}
+function isDominantChordOf(chord, key) {
+  if (pitchClassOf(chord.rootPc - key.rootPc) !== 7) {
+    return false;
+  }
+  if (hasMajorThird(chord)) {
+    return true;
+  }
+  const suspended = !hasInterval(chord, 3) && (hasInterval(chord, 5) || hasInterval(chord, 2));
+  return suspended && hasInterval(chord, 10);
+}
+function isNeapolitanChordOf(chord, key) {
+  return pitchClassOf(chord.rootPc - key.rootPc) === 1 && soundsMajorTriad(chord) && !isDiatonicChord(chord, key);
+}
+var DOMINANT_DEGREE = 5;
+function heptatonicFrameOf(key) {
+  return scaleTonesInDegreeOrder(key).length === 7 ? key : majorKey(pitchClassOf(key.rootPc));
+}
+function degreeTriad(tones, index) {
+  const root = tones[index] ?? 0;
+  return {
+    third: pitchClassOf((tones[(index + 2) % tones.length] ?? 0) - root),
+    fifth: pitchClassOf((tones[(index + 4) % tones.length] ?? 0) - root)
+  };
+}
+function tonicizableDegrees(key) {
+  const tones = scaleTonesInDegreeOrder(heptatonicFrameOf(key));
+  const minor = isMinorMask(key.modeMask12);
+  const out = [];
+  for (let index = 0; index < tones.length; index += 1) {
+    const rootPc = tones[index];
+    if (rootPc === void 0) {
+      continue;
+    }
+    const triad = degreeTriad(tones, index);
+    if (triad.fifth !== 7) {
+      continue;
+    }
+    const dominantDegree = minor && index + 1 === DOMINANT_DEGREE;
+    out.push({ degreeNumber: index + 1, rootPc, lower: triad.third === 3 && !dominantDegree });
+  }
+  return out;
+}
+function appliedDominantTarget(rootPc, key) {
+  const target = pitchClassOf(rootPc);
+  return tonicizableDegrees(key).find(
+    (degree) => degree.degreeNumber !== 1 && degree.rootPc === target
+  ) ?? null;
+}
+function leadingTonePcOf(key) {
+  return pitchClassOf(key.rootPc - 1);
+}
+var LEADING_TONE_QUALITIES = /* @__PURE__ */ new Set(["dim", "dim7", "m7b5"]);
+function soundsDiminishedTriad(chord) {
+  return hasInterval(chord, 3) && hasInterval(chord, 6) && !hasInterval(chord, 7);
+}
+function isLeadingToneChordOf(chord, key) {
+  return pitchClassOf(chord.rootPc) === leadingTonePcOf(key) && soundsDiminishedTriad(chord);
+}
+function isFunctioningLeadingTone(chord, key) {
+  const role = chordToneRole(leadingTonePcOf(key), chord);
+  if (role === "third") {
+    return pitchClassOf(chord.rootPc) === pitchClassOf(key.rootPc + 7);
+  }
+  if (role === "root") {
+    return soundsDiminishedTriad(chord);
+  }
+  return false;
+}
+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 fifthPcOf(chord) {
+  for (const interval of chord.intervals) {
+    const pc = pitchClassOf(chord.rootPc + interval);
+    if (chordToneRole(pc, chord) === "fifth") {
+      return pc;
+    }
+  }
+  return void 0;
+}
+function isDescendingStep(interval) {
+  return interval.number === 2 && (interval.semitones === -1 || interval.semitones === -2);
+}
+var THIRD_SEMITONES = [3, 4];
+function isFrustratedLeadingTone(fromPitch, toPitch, nextChord) {
+  if (!THIRD_SEMITONES.includes(fromPitch - toPitch)) {
+    return false;
+  }
+  const fifthPc = fifthPcOf(nextChord);
+  return fifthPc !== void 0 && pitchClassOf(toPitch) === fifthPc;
+}
+
 export {
   maskFromOffsets,
   MAJOR_MASK,
@@ -2954,6 +3695,7 @@ export {
   OCTATONIC_HALF_WHOLE_MASK,
   OCTATONIC_WHOLE_HALF_MASK,
   CHROMATIC_MASK,
+  assertModeMask,
   LYDIAN_DOMINANT_MASK,
   MIXOLYDIAN_B13_MASK,
   LOCRIAN_NATURAL2_MASK,
@@ -2972,9 +3714,11 @@ export {
   resolveScaleName,
   namedScaleMask,
   requireScaleMask,
-  majorKey,
-  minorKey,
-  scaleByName,
+  isMinorMask,
+  variantOfMask,
+  assertKeyVariant,
+  scaleNameOfMask,
+  tryResolveKeyName,
   toKeyScale,
   isScaleTone,
   nearestScaleTone,
@@ -2998,17 +3742,25 @@ export {
   spelledKeyOf,
   relativeKeyOf,
   parallelKeyOf,
+  isWrittenTonic,
   dominantKeyOf,
   subdominantKeyOf,
   enharmonicKeyOf,
   relatedKeysOf,
   keyRelationBetween,
+  resolveKey,
+  scaleOf,
+  majorKey,
+  minorKey,
+  scaleByName,
   SCALE_SYSTEMS,
   scaleSystemOf,
   supportsFunctionalHarmony,
   chordSpecIntervals,
   chordSpecQuality,
   chordQualities,
+  assertChordQuality,
+  assertChord,
   chordFromDegree,
   makeChord,
   chordFromSpec,
@@ -3021,6 +3773,9 @@ export {
   intervalAboveRoot,
   isChordMember,
   chordToneRole,
+  degreeOfInterval,
+  thirdSlotOf,
+  displacedThirds,
   diatonicTriad,
   diatonicSeventh,
   simpleIntervalNumber,
@@ -3044,10 +3799,28 @@ export {
   ReasonFlag,
   evaluateSafety,
   enumerateSafePitches,
+  toChordData,
   parseChordSymbol,
   tryParseChordSymbol,
-  toChordData,
   formatChordSymbol,
-  transposeChordSymbol
+  transposeChordSpellings,
+  transposeChordSymbol,
+  isDiatonicChord,
+  hasMajorThird,
+  soundsDominantSeventh,
+  hasDominantSonority,
+  isDominantChordOf,
+  isNeapolitanChordOf,
+  heptatonicFrameOf,
+  tonicizableDegrees,
+  appliedDominantTarget,
+  leadingTonePcOf,
+  LEADING_TONE_QUALITIES,
+  isLeadingToneChordOf,
+  isFunctioningLeadingTone,
+  seventhPcOf,
+  fifthPcOf,
+  isDescendingStep,
+  isFrustratedLeadingTone
 };
-//# sourceMappingURL=chunk-INHVXP6Z.js.map
+//# sourceMappingURL=chunk-RFIBF2RR.js.map