@libraz/libcantus 0.9.0 → 0.9.1

package/src/bass/index.ts

@@ -18,29 +18,57 @@ import { createRng } from '../random/index.js';
 import { nearestScaleTone } from '../scale/index.js';
 import type { KeyScale, NoteEvent } from '../types.js';
 
-/** A chord sounding over a half-open beat span `[startBeat, endBeat)`. */
+/**
+ * A chord sounding over a half-open beat span `[startBeat, endBeat)`.
+ *
+ * @category Composition
+ */
 export type BassSegment = {
   startBeat: number;
   endBeat: number;
   chord: Chord;
 };
 
-/** The bass-line idiom to generate. */
+/**
+ * The bass-line idiom to generate.
+ *
+ * @category Composition
+ */
 export type BassStyle = 'root' | 'rootFifth' | 'pop' | 'walking' | 'arpeggio';
 
-/** Options controlling {@link generateBassLine}. */
+/**
+ * Options controlling {@link generateBassLine}.
+ *
+ * @category Composition
+ */
 export type BassLineOptions = {
   /** Chord placement to follow; need not be pre-sorted. */
   segments: BassSegment[];
   /** Key/scale context, used for diatonic approach tones in `walking`. */
   key: KeyScale;
-  /** Time signature; used for metric accents. Default 4/4. */
+  /**
+   * Time signature; used for metric accents.
+   *
+   * @defaultValue `{ numerator: 4, denominator: 4 }`
+   */
   ts?: TimeSignature;
-  /** Bass-line idiom. Default `'root'`. */
+  /**
+   * Bass-line idiom.
+   *
+   * @defaultValue `'root'`
+   */
   style?: BassStyle;
-  /** Target register as a base MIDI octave; roots land around `octave*12+12`. Default 2. */
+  /**
+   * Target register as a base MIDI octave; roots land around `octave*12+12`.
+   *
+   * @defaultValue 2
+   */
   octave?: number;
-  /** Seed for the deterministic PRNG. Default 0. */
+  /**
+   * Seed for the deterministic PRNG.
+   *
+   * @defaultValue 0
+   */
   seed?: number;
 };
 
@@ -98,10 +126,18 @@ function chordTonePcs(chord: Chord): number[] {
   return pcs;
 }
 
-/** The chord's perfect-fifth pitch class, falling back to the root when absent. */
+/**
+ * The chord's fifth pitch class.
+ *
+ * Uses the perfect fifth when present, otherwise the chord's actual altered
+ * fifth (diminished = 6, augmented = 8 semitones above the root), so dim/aug/
+ * m7b5 chords sound their real fifth rather than a repeated root. Falls back to
+ * the root only when the chord has no fifth degree at all.
+ */
 function fifthPcOf(chord: Chord): number {
-  const hasFifth = chord.intervals.some((i) => pitchClass(i) === 7);
-  return hasFifth ? pitchClass(chord.rootPc + 7) : pitchClass(chord.rootPc);
+  const fifths = new Set(chord.intervals.map((i) => pitchClass(i)));
+  const chosen = fifths.has(7) ? 7 : fifths.has(6) ? 6 : fifths.has(8) ? 8 : undefined;
+  return chosen === undefined ? pitchClass(chord.rootPc) : pitchClass(chord.rootPc + chosen);
 }
 
 /** The sounding bass pitch class of a chord: its slash bass, else its root. */
@@ -166,9 +202,10 @@ function buildPop(ctx: BuildContext, seg: BassSegment): void {
       emitted = true;
     } else if (ctx.rng.prob(PICKUP_PROB)) {
       if (ctx.rng.prob(0.5)) {
-        // Octave pickup: the root an octave below the band anchor.
+        // Octave pickup: the root dropped toward the bottom of the register,
+        // clamped so it never falls below the declared band.
         const base = placePc(rootPc, ctx.prevMidi, ctx.low);
-        emit(ctx, pos, rootPc, base - 12);
+        emit(ctx, pos, rootPc, Math.max(ctx.low, base - 12));
       } else {
         ctx.prevMidi = emit(ctx, pos, fifthPcOf(seg.chord));
       }
@@ -231,6 +268,18 @@ function buildWalking(ctx: BuildContext, seg: BassSegment, next: BassSegment | u
  *
  * @param opts Segments, key, and generation options.
  * @returns Bass notes sorted by onset, non-overlapping.
+ *
+ * @example
+ * ```ts
+ * import { generateBassLine, makeChord, majorKey } from '@libraz/libcantus';
+ * const segments = [
+ *   { startBeat: 0, endBeat: 4, chord: makeChord(0, 'maj') },
+ *   { startBeat: 4, endBeat: 8, chord: makeChord(7, 'maj') },
+ * ];
+ * const notes = generateBassLine({ segments, key: majorKey(0), style: 'walking' });
+ * ```
+ *
+ * @category Composition
  */
 export function generateBassLine(opts: BassLineOptions): NoteEvent[] {
   const segments = [...opts.segments].sort((a, b) => a.startBeat - b.startBeat);

package/src/chord/index.ts

@@ -1,7 +1,11 @@
 import { scaleTonesInDegreeOrder } from '../scale/index.js';
 import type { KeyScale } from '../types.js';
 
-/** Chord quality identifiers understood by the chord builder. */
+/**
+ * Chord quality identifiers understood by the chord builder.
+ *
+ * @category Chords
+ */
 export type ChordQuality =
   | 'maj'
   | 'min'
@@ -34,12 +38,36 @@ export type ChordQuality =
   | '13'
   | '5';
 
-/** A chord expressed as a root pitch class plus semitone offsets. */
+/**
+ * A bare spelled pitch used as an enharmonic hint: a diatonic letter
+ * (0..6 = C..B) plus a chromatic alteration (-2 double-flat .. +2 double-sharp).
+ * Mirrors the letter/alter half of the pitch module's `Note` without an octave.
+ *
+ * @category Chords
+ */
+export type PitchSpelling = {
+  letter: number;
+  alter: number;
+};
+
+/**
+ * A chord expressed as a root pitch class plus semitone offsets.
+ *
+ * `rootSpelling`/`bassSpelling` are optional enharmonic hints recorded by
+ * parsers (e.g. `parseChordSymbol('Bb7')`) so formatters can reproduce the
+ * original spelling instead of defaulting to sharps. Consumers may ignore
+ * them; a hint is only trusted when its pitch class still matches the
+ * corresponding `rootPc`/`bassPc`.
+ *
+ * @category Chords
+ */
 export type Chord = {
   rootPc: number;
   quality: ChordQuality;
   intervals: number[];
   bassPc?: number;
+  rootSpelling?: PitchSpelling;
+  bassSpelling?: PitchSpelling;
 };
 
 /** Semitone offsets from the root for each supported chord quality. */
@@ -81,7 +109,11 @@ function pitchClass(value: number): number {
   return ((Math.trunc(value) % 12) + 12) % 12;
 }
 
-/** All chord qualities the builder understands, longest templates last. */
+/**
+ * All chord qualities the builder understands, longest templates last.
+ *
+ * @category Chords
+ */
 export function chordQualities(): ChordQuality[] {
   return Object.keys(QUALITY_INTERVALS) as ChordQuality[];
 }
@@ -97,6 +129,8 @@ export function chordQualities(): ChordQuality[] {
  * @param ext Chord quality to apply.
  * @param key Key context supplying the diatonic root.
  * @returns The constructed chord.
+ *
+ * @category Chords
  */
 export function chordFromDegree(degree: number, ext: ChordQuality, key: KeyScale): Chord {
   const tones = scaleTonesInDegreeOrder(key);
@@ -113,6 +147,15 @@ export function chordFromDegree(degree: number, ext: ChordQuality, key: KeyScale
  * @param quality Chord quality supplying the interval template.
  * @param bassPc Optional slash-chord bass pitch class.
  * @returns The constructed chord.
+ *
+ * @example
+ * ```ts
+ * import { makeChord } from '@libraz/libcantus';
+ * const cmaj7 = makeChord(0, 'maj7');
+ * // { rootPc: 0, quality: 'maj7', intervals: [0, 4, 7, 11] }
+ * ```
+ *
+ * @category Chords
  */
 export function makeChord(rootPc: number, quality: ChordQuality, bassPc?: number): Chord {
   const chord: Chord = {
@@ -131,6 +174,14 @@ export function makeChord(rootPc: number, quality: ChordQuality, bassPc?: number
  *
  * @param chord The chord to enumerate.
  * @returns The chord's pitch classes, sorted ascending in [0, 11].
+ *
+ * @example
+ * ```ts
+ * import { makeChord, chordPitchClasses } from '@libraz/libcantus';
+ * chordPitchClasses(makeChord(0, 'maj7')); // [0, 4, 7, 11]
+ * ```
+ *
+ * @category Chords
  */
 export function chordPitchClasses(chord: Chord): number[] {
   const set = new Set<number>();
@@ -156,6 +207,8 @@ function chordToneOffsets(chord: Chord): Set<number> {
  * @param pitch MIDI pitch or bare pitch class.
  * @param chord The chord providing the root reference.
  * @returns The chord-tone role, or null if the pitch has no basic role.
+ *
+ * @category Chords
  */
 export function chordToneRole(
   pitch: number,
@@ -275,6 +328,14 @@ function stackThirds(degree: number, key: KeyScale, size: 3 | 4): Chord {
  * @param degree 0-based scale degree of the chord root.
  * @param key Key/scale context.
  * @returns The diatonic triad.
+ *
+ * @example
+ * ```ts
+ * import { majorKey, diatonicTriad } from '@libraz/libcantus';
+ * const tonic = diatonicTriad(0, majorKey(0)); // C major triad (degree 0 of C major)
+ * ```
+ *
+ * @category Chords
  */
 export function diatonicTriad(degree: number, key: KeyScale): Chord {
   return stackThirds(degree, key, 3);
@@ -286,6 +347,8 @@ export function diatonicTriad(degree: number, key: KeyScale): Chord {
  * @param degree 0-based scale degree of the chord root.
  * @param key Key/scale context.
  * @returns The diatonic seventh chord.
+ *
+ * @category Chords
  */
 export function diatonicSeventh(degree: number, key: KeyScale): Chord {
   return stackThirds(degree, key, 4);

package/src/chordscale/index.ts

@@ -29,6 +29,8 @@ function maskHasPitchClass(mask: number, scaleRootPc: number, pc: number): boole
  * @param scaleMask The scale's 12-bit mode mask.
  * @param scaleRootPc The pitch class the mask is rooted on.
  * @returns True if the scale is a superset of the chord.
+ *
+ * @category Scales
  */
 export function scaleMatchesChord(
   chordPcs: number[],
@@ -43,37 +45,67 @@ export function scaleMatchesChord(
   return true;
 }
 
-/** A named scale rooted on a pitch class that fits over a chord. */
+/**
+ * A named scale rooted on a pitch class that fits over a chord.
+ *
+ * @category Scales
+ */
 export type ChordScaleMatch = {
   name: string;
   rootPc: number;
 };
 
+/**
+ * Scale names whose mask duplicates another {@link NAMED_SCALES} entry
+ * (major/ionian, naturalMinor/aeolian). Chord-scale analysis conventionally
+ * speaks in mode names, so these aliases are skipped and only the modal name
+ * is reported.
+ */
+const ALIASED_SCALE_NAMES = new Set(['major', 'naturalMinor']);
+
+/** Number of tones in a heptatonic (seven-note) scale. */
+const HEPTATONIC_SIZE = 7;
+
 /**
  * List the scales that fit over a chord, best fit first.
  *
  * Only the chord root is considered as the scale root, matching the
  * conventional chord-scale relationship. Every entry of {@link NAMED_SCALES}
- * whose pitch-class set is a superset of the chord's is returned, ranked by
- * fewest extra scale tones beyond the chord, then by scale size (heptatonic
- * before larger scales), then by scale name. The chromatic scale is only
- * returned as a fallback when no other scale contains the chord.
+ * whose pitch-class set is a superset of the chord's is returned once per
+ * distinct pitch-class set (aliased masks such as major/ionian report only the
+ * modal name), ranked by fewest extra scale tones beyond the chord, then by
+ * scale size (heptatonic before larger scales), then by scale name. For bare
+ * triads and smaller chords, heptatonic scales rank before pentatonics and
+ * other sizes: a pentatonic adds no modal color over a triad, so the seven-note
+ * modes are the more useful answer. The chromatic scale is only returned as a
+ * fallback when no other scale contains the chord.
  *
  * @param chord The chord to fit scales over.
  * @returns The matching scales rooted on the chord root, best fit first.
+ *
+ * @example
+ * ```ts
+ * import { makeChord, chordScales } from '@libraz/libcantus';
+ * const scales = chordScales(makeChord(0, 'maj7'));
+ * // scales for Cmaj7, best fit first; each is { name, rootPc: 0 }
+ * ```
+ *
+ * @category Scales
  */
 export function chordScales(chord: Chord): ChordScaleMatch[] {
   const chordPcs = chordPitchClasses(chord);
   const rootPc = pitchClass(chord.rootPc);
   const ranked: { name: string; extra: number; size: number }[] = [];
+  const seenMasks = new Set<number>();
   for (const name of Object.keys(NAMED_SCALES)) {
-    if (name === 'chromatic') {
+    if (name === 'chromatic' || ALIASED_SCALE_NAMES.has(name)) {
       continue;
     }
     const mask = NAMED_SCALES[name];
-    if (mask === undefined) {
+    if (mask === undefined || seenMasks.has(mask)) {
       continue;
     }
+    seenMasks.add(mask);
     if (scaleMatchesChord(chordPcs, mask, rootPc)) {
       const size = popcount12(mask);
       ranked.push({ name, extra: size - chordPcs.length, size });
@@ -87,7 +119,11 @@ export function chordScales(chord: Chord): ChordScaleMatch[] {
     }
     return [];
   }
+  const preferHeptatonic = chordPcs.length <= 3;
   ranked.sort((a, b) => {
+    if (preferHeptatonic && (a.size === HEPTATONIC_SIZE) !== (b.size === HEPTATONIC_SIZE)) {
+      return a.size === HEPTATONIC_SIZE ? -1 : 1;
+    }
     if (a.extra !== b.extra) {
       return a.extra - b.extra;
     }
@@ -109,6 +145,8 @@ export function chordScales(chord: Chord): ChordScaleMatch[] {
  * @param chord The chord providing the chord tones.
  * @param scaleName A key of {@link NAMED_SCALES}.
  * @returns The avoid-note pitch classes, sorted ascending in [0, 11].
+ *
+ * @category Scales
  */
 export function avoidNotes(chord: Chord, scaleName: string): number[] {
   const mask = NAMED_SCALES[scaleName];
@@ -144,6 +182,14 @@ export function avoidNotes(chord: Chord, scaleName: string): number[] {
  * @param chord The chord providing the chord tones.
  * @param scaleName A key of {@link NAMED_SCALES}.
  * @returns The available-tension pitch classes, sorted ascending in [0, 11].
+ *
+ * @example
+ * ```ts
+ * import { makeChord, availableTensions } from '@libraz/libcantus';
+ * availableTensions(makeChord(0, 'maj7'), 'ionian'); // [2, 9] — color tones over Cmaj7
+ * ```
+ *
+ * @category Scales
  */
 export function availableTensions(chord: Chord, scaleName: string): number[] {
   const mask = NAMED_SCALES[scaleName];
@@ -167,7 +213,11 @@ export function availableTensions(chord: Chord, scaleName: string): number[] {
   return tensions.sort((a, b) => a - b);
 }
 
-/** A scale fit over a chord together with its avoid notes and tensions. */
+/**
+ * A scale fit over a chord together with its avoid notes and tensions.
+ *
+ * @category Scales
+ */
 export type ChordScaleReportEntry = {
   name: string;
   rootPc: number;
@@ -184,6 +234,8 @@ export type ChordScaleReportEntry = {
  * @param chord The chord to analyze.
  * @param limit Optional maximum number of scales to report; all by default.
  * @returns One entry per reported scale, best fit first.
+ *
+ * @category Scales
  */
 export function chordScaleReport(chord: Chord, limit?: number): ChordScaleReportEntry[] {
   const matches = chordScales(chord);
@@ -196,7 +248,11 @@ export function chordScaleReport(chord: Chord, limit?: number): ChordScaleReport
   }));
 }
 
-/** A chord paired with the scale chosen for it by {@link scalesForChanges}. */
+/**
+ * A chord paired with the scale chosen for it by {@link scalesForChanges}.
+ *
+ * @category Scales
+ */
 export type ScaleChoice = {
   chord: Chord;
   scale: ChordScaleMatch;
@@ -251,6 +307,8 @@ function symmetricDifferenceSize(a: Set<number>, b: Set<number>): number {
  *
  * @param chords The chord sequence to choose scales for.
  * @returns One scale choice per chord, in input order.
+ *
+ * @category Scales
  */
 export function scalesForChanges(chords: Chord[]): ScaleChoice[] {
   if (chords.length === 0) {

package/src/countermelody/index.ts

@@ -1,10 +1,6 @@
 import type { Chord } from '../chord/index.js';
 import { chordToneRole } from '../chord/index.js';
-import {
-  createsParallelOctave,
-  createsParallelPerfect,
-  isForbiddenMelodicLeap,
-} from '../counterpoint/index.js';
+import { createsParallelPerfect, isForbiddenMelodicLeap } from '../counterpoint/index.js';
 import type { TimeSignature } from '../meter/index.js';
 import { isStrongBeat } from '../meter/index.js';
 import type { Rng } from '../random/index.js';
@@ -14,7 +10,11 @@ import { enumerateSafePitches } from '../safety/index.js';
 import { nearestScaleTone } from '../scale/index.js';
 import type { KeyScale, NoteEvent } from '../types.js';
 
-/** Options controlling {@link generateCounterMelody}. */
+/**
+ * Options controlling {@link generateCounterMelody}.
+ *
+ * @category Voicing & Counterpoint
+ */
 export type CounterMelodyOptions = {
   /** The lead line to write against, in ascending onset order. */
   melody: NoteEvent[];
@@ -22,22 +22,40 @@ export type CounterMelodyOptions = {
   chordAt: (beat: number) => Chord | null;
   /** Key/scale context for scale-tone decisions. */
   key: KeyScale;
-  /** Meter used for strong-beat decisions (default 4/4). */
+  /**
+   * Meter used for strong-beat decisions.
+   *
+   * @defaultValue 4/4
+   */
   ts?: TimeSignature;
-  /** Which side of the melody the counter line occupies (default `'below'`). */
+  /**
+   * Which side of the melody the counter line occupies.
+   *
+   * @defaultValue 'below'
+   */
   register?: 'above' | 'below';
   /**
-   * Onset strategy: `'complement'` (default) moves where the melody holds or
-   * rests and reinforces some strong beats; `'follow'` mirrors melody onsets.
+   * Onset strategy: `'complement'` moves where the melody holds or rests and
+   * reinforces some strong beats; `'follow'` mirrors melody onsets.
+   *
+   * @defaultValue 'complement'
    */
   rhythm?: 'complement' | 'follow';
-  /** Safety profile applied to candidate pitches (default `'pop'`). */
+  /**
+   * Safety profile applied to candidate pitches.
+   *
+   * @defaultValue 'pop'
+   */
   profile?: 'strict' | 'pop';
   /** Lowest MIDI pitch the counter line may use (default derived from `register`). */
   pitchLow?: number;
   /** Highest MIDI pitch the counter line may use (default derived from `register`). */
   pitchHigh?: number;
-  /** PRNG seed; the same seed always yields the same line (default 0). */
+  /**
+   * PRNG seed; the same seed always yields the same line.
+   *
+   * @defaultValue 0
+   */
   seed?: number;
 };
 
@@ -244,6 +262,17 @@ function fallbackPitch(
  *
  * @param opts The lead line, chord context callback, key, and generation knobs.
  * @returns The counter line as note events sorted by onset; `[]` for an empty melody.
+ * @example
+ * ```ts
+ * import { generateCounterMelody, majorKey, parseChordSymbol } from '@libraz/libcantus';
+ * const melody = [{ pitch: 72, startBeat: 0, durationBeat: 2 }];
+ * const counter = generateCounterMelody({
+ *   melody,
+ *   chordAt: () => parseChordSymbol('C'),
+ *   key: majorKey(0),
+ * }); // note events below the melody, in onset order
+ * ```
+ * @category Voicing & Counterpoint
  */
 export function generateCounterMelody(opts: CounterMelodyOptions): NoteEvent[] {
   const melody = [...opts.melody].sort((a, b) => a.startBeat - b.startBeat);
@@ -309,8 +338,9 @@ export function generateCounterMelody(opts: CounterMelodyOptions): NoteEvent[] {
         if (
           prevPitch !== undefined &&
           melPrev !== undefined &&
-          (createsParallelPerfect(prevPitch, candidate, melPrev, melPitch) ||
-            createsParallelOctave(prevPitch, candidate, melPrev, melPitch))
+          // Parallel octaves are the perfect-class-zero case of this predicate,
+          // so a single check covers both parallel fifths and octaves.
+          createsParallelPerfect(prevPitch, candidate, melPrev, melPitch)
         ) {
           continue;
         }

package/src/counterpoint/index.ts

@@ -12,6 +12,7 @@ function pitchClass(pitch: number): number {
  * @param upperPitch Pitch of the nominally higher voice.
  * @param lowerPitch Pitch of the nominally lower voice.
  * @returns True when the upper voice sits below the lower voice.
+ * @category Voicing & Counterpoint
  */
 export function createsVoiceCrossing(upperPitch: number, lowerPitch: number): boolean {
   return upperPitch < lowerPitch;
@@ -24,6 +25,7 @@ export function createsVoiceCrossing(upperPitch: number, lowerPitch: number): bo
  * @param b Second pitch.
  * @param twoVoice When true, the perfect fourth counts as dissonant.
  * @returns True when the vertical interval is dissonant.
+ * @category Voicing & Counterpoint
  */
 export function createsVerticalDissonance(a: number, b: number, twoVoice: boolean): boolean {
   return !isConsonantInterval(a - b, twoVoice);
@@ -39,6 +41,7 @@ export function createsVerticalDissonance(a: number, b: number, twoVoice: boolea
  * @param prev Starting pitch.
  * @param cur Ending pitch.
  * @returns True when the leap is forbidden in strict counterpoint.
+ * @category Voicing & Counterpoint
  */
 export function isForbiddenMelodicLeap(prev: number, cur: number): boolean {
   const semis = Math.abs(cur - prev);
@@ -78,6 +81,8 @@ function bothVoicesMove(aMove: number, bMove: number): boolean {
  * A fifth expanding to a twelfth counts (same perfect class); a fifth moving to
  * an octave does not (different perfect kinds — the direct/hidden case owned by
  * {@link createsHiddenParallelPerfect}).
+ *
+ * @category Voicing & Counterpoint
  */
 export function createsParallelPerfect(
   aPrev: number,
@@ -96,6 +101,15 @@ export function createsParallelPerfect(
 /**
  * Whether two voices move in consecutive parallel octaves (or unisons) by
  * similar motion.
+ *
+ * This is a strict subset of {@link createsParallelPerfect}: a similar-motion
+ * octave-to-octave is the perfect-class-zero case that predicate already flags
+ * (and it additionally catches the contrary-motion anti-parallel). Callers that
+ * tally parallel violations should therefore use {@link createsParallelPerfect}
+ * alone to avoid double counting; this predicate remains for callers wanting a
+ * dedicated similar-motion octave test.
+ *
+ * @category Voicing & Counterpoint
  */
 export function createsParallelOctave(
   aPrev: number,
@@ -112,6 +126,8 @@ export function createsParallelOctave(
 /**
  * Whether two voices move in consecutive parallel unisons — both landing on the
  * same pitch, having shared a pitch on the previous move.
+ *
+ * @category Voicing & Counterpoint
  */
 export function createsParallelUnison(
   aPrev: number,
@@ -132,6 +148,8 @@ export function createsParallelUnison(
  * The traditional step exception is applied: the approach is allowed when the
  * upper of the two voices moves by step, so only leaps into the perfect
  * interval are flagged.
+ *
+ * @category Voicing & Counterpoint
  */
 export function createsHiddenParallelPerfect(
   aPrev: number,
@@ -168,6 +186,7 @@ export function createsHiddenParallelPerfect(
  * @param upperCur Current pitch of the upper voice.
  * @param lowerPrev Previous pitch of the lower voice.
  * @param lowerCur Current pitch of the lower voice.
+ * @category Voicing & Counterpoint
  */
 export function createsVoiceOverlap(
   upperPrev: number,
@@ -186,6 +205,7 @@ export function createsVoiceOverlap(
  * @param upperPitch Pitch of the higher voice.
  * @param lowerPitch Pitch of the lower voice.
  * @param maxSemitones Maximum allowed spacing in semitones (default an octave).
+ * @category Voicing & Counterpoint
  */
 export function exceedsSpacing(upperPitch: number, lowerPitch: number, maxSemitones = 12): boolean {
   return Math.abs(upperPitch - lowerPitch) > maxSemitones;
@@ -198,6 +218,7 @@ export function exceedsSpacing(upperPitch: number, lowerPitch: number, maxSemito
  * @param cur The following pitch.
  * @param key Key context supplying the tonic.
  * @returns True when `prev` is the leading tone and `cur` is the tonic a step above.
+ * @category Voicing & Counterpoint
  */
 export function isLeadingToneResolution(prev: number, cur: number, key: KeyScale): boolean {
   const tonic = pitchClass(key.rootPc);