@libraz/libcantus 0.9.1 → 0.9.2

package/src/{functional/index.ts → analyze/functional/roman.ts}

@@ -1,37 +1,16 @@
 /**
- * Functional harmony: Roman-numeral parsing and formatting, harmonic function
- * (tonic / subdominant / dominant), and cadence detection.
+ * Roman-numeral parsing and formatting.
  *
- * Roots are pitch classes measured against the key tonic, so borrowed and
- * chromatic chords are handled by their semitone offset rather than requiring a
- * spelled key signature.
+ * The {@link ROMAN_STYLE} table is the single source of truth for both
+ * directions, so {@link chordToRoman} and {@link romanToChord} stay mutual
+ * inverses by construction.
  */
 
-import type { Chord, ChordQuality } from '../chord/index.js';
-import { chordPitchClasses, makeChord } from '../chord/index.js';
-import {
-  HARMONIC_MINOR_MASK,
-  isScaleTone,
-  MAJOR_MASK,
-  majorKey,
-  NATURAL_MINOR_MASK,
-  scaleTonesInDegreeOrder,
-} from '../scale/index.js';
-import type { KeyScale } from '../types.js';
-
-/**
- * The three broad harmonic functions of tonal music.
- *
- * @category Functional Harmony
- */
-export type HarmonicFunction = 'tonic' | 'subdominant' | 'dominant';
-
-/**
- * A recognized cadence type, or null when a chord pair forms none.
- *
- * @category Functional Harmony
- */
-export type Cadence = 'authentic' | 'plagal' | 'half' | 'deceptive' | null;
+import type { KeyScale } from '../../core/types.js';
+import type { Chord, ChordQuality } from '../../theory/chord/index.js';
+import { makeChord } from '../../theory/chord/index.js';
+import { majorKey, scaleTonesInDegreeOrder } from '../../theory/scale/index.js';
+import { degreeRootPc, mod12 } from './internal.js';
 
 /** Roman numeral glyphs indexed by degree number - 1. */
 const ROMAN = ['I', 'II', 'III', 'IV', 'V', 'VI', 'VII'] as const;
@@ -63,46 +42,6 @@ const OFFSET_SPELLING: readonly [number, string][] = [
   [7, ''],
 ];
 
-/** Harmonic function of each semitone offset above the tonic (major context). */
-const FUNCTION_BY_OFFSET: readonly HarmonicFunction[] = [
-  'tonic', // 0  I
-  'subdominant', // 1  bII (Neapolitan)
-  'subdominant', // 2  ii
-  'tonic', // 3  bIII
-  'tonic', // 4  iii
-  'subdominant', // 5  IV
-  'dominant', // 6  #IV / bV
-  'dominant', // 7  V
-  'subdominant', // 8  bVI
-  'tonic', // 9  vi
-  'subdominant', // 10 bVII
-  'dominant', // 11 vii
-];
-
-function mod12(n: number): number {
-  return ((n % 12) + 12) % 12;
-}
-
-/**
- * Whether a key's scale has a minor third and no major third (a minor key).
- *
- * @category Functional Harmony
- */
-export function isMinorKey(key: KeyScale): boolean {
-  const hasMinorThird = (key.modeMask12 >> 3) & 1;
-  const hasMajorThird = (key.modeMask12 >> 4) & 1;
-  return Boolean(hasMinorThird) && !hasMajorThird;
-}
-
-/** Diatonic pitch class of a 1-based scale degree in a key. */
-function degreeRootPc(degreeNumber: number, key: KeyScale): number {
-  const tones = scaleTonesInDegreeOrder(key);
-  if (tones.length === 0) {
-    return mod12(key.rootPc);
-  }
-  return tones[(degreeNumber - 1) % tones.length] ?? mod12(key.rootPc);
-}
-
 /** Choose a seventh-chord quality from a triad label and the numeral case. */
 function seventhQuality(base: 'maj' | 'min' | 'dim' | 'aug', halfDim: boolean): ChordQuality {
   if (halfDim) {
@@ -452,260 +391,3 @@ export function chordToRoman(chord: Chord, key: KeyScale): string {
   }
   return `${accidental}${cased}${suffix}`;
 }
-
-/**
- * The harmonic function of a chord in a key, from its root's offset above the
- * tonic. The mapping follows common-practice major-key function and is a useful
- * approximation in minor and for borrowed chords.
- *
- * @param chord The chord.
- * @param key The prevailing key.
- * @returns The harmonic function.
- * @category Functional Harmony
- */
-export function functionOf(chord: Chord, key: KeyScale): HarmonicFunction {
-  return FUNCTION_BY_OFFSET[mod12(chord.rootPc - key.rootPc)] ?? 'tonic';
-}
-
-/**
- * The origin of a recognized non-diatonic chord, or null when none applies.
- *
- * @category Functional Harmony
- */
-export type BorrowedSource = 'parallel-minor' | 'parallel-major' | 'neapolitan' | null;
-
-/**
- * The result of {@link analyzeChord}: function, borrowing, and Roman numeral.
- *
- * @category Functional Harmony
- */
-export type ChordAnalysis = {
-  function: HarmonicFunction;
-  borrowed: boolean;
-  source: BorrowedSource;
-  roman: string;
-};
-
-/**
- * Whether every pitch class of a chord belongs to the key's scale.
- *
- * The test is strict against the key's own mode mask: in a natural-minor key
- * the harmonic-minor dominant (major V) is *not* diatonic, since the raised
- * leading tone lies outside the mask. Borrowing predicates treat that case as
- * an in-key alteration separately (see {@link isBorrowedChord}).
- *
- * @param chord The chord to test.
- * @param key The prevailing key.
- * @returns True if all chord pitch classes are scale tones.
- * @category Functional Harmony
- */
-export function isDiatonic(chord: Chord, key: KeyScale): boolean {
-  return chordPitchClasses(chord).every((pc) => isScaleTone(pc, key));
-}
-
-/**
- * The parallel key: same tonic, opposite mode.
- *
- * A key with a minor third (natural/harmonic/melodic minor, dorian, phrygian)
- * maps to the parallel major; any other key maps to the parallel natural minor.
- *
- * @param key The key to mirror.
- * @returns The parallel major or natural-minor key on the same tonic.
- * @category Functional Harmony
- */
-export function parallelKey(key: KeyScale): KeyScale {
-  return {
-    rootPc: mod12(key.rootPc),
-    modeMask12: isMinorKey(key) ? MAJOR_MASK : NATURAL_MINOR_MASK,
-  };
-}
-
-/**
- * In a minor key, whether a non-diatonic chord is explained by the harmonic
- * minor scale on the same tonic (major V, V7, the raised-leading-tone viio).
- * Such chords are in-key chromatic alterations, not modal interchange.
- */
-function isHarmonicMinorAlteration(chord: Chord, key: KeyScale): boolean {
-  return (
-    isMinorKey(key) &&
-    isDiatonic(chord, { rootPc: mod12(key.rootPc), modeMask12: HARMONIC_MINOR_MASK })
-  );
-}
-
-/** Whether a chord is the Neapolitan: a major triad on the flat second degree. */
-function isNeapolitan(chord: Chord, key: KeyScale): boolean {
-  return mod12(chord.rootPc - key.rootPc) === 1 && chord.quality === 'maj';
-}
-
-/**
- * Whether a chord is borrowed from the parallel mode (modal interchange).
- *
- * True when the chord is not diatonic to `key` but is diatonic to its
- * {@link parallelKey} — e.g. iv, bVI, or bVII in a major key, or the Picardy
- * tonic and major IV in a minor key. Two non-diatonic families are excluded:
- * chords diatonic to neither mode (they are chromatic, not borrowed), and, in
- * a minor key, chords explained by the harmonic minor scale (the major
- * dominant and raised-leading-tone chords), which are in-key alterations
- * rather than interchange even though they happen to fit the parallel major.
- *
- * @param chord The chord to test.
- * @param key The prevailing key.
- * @returns True if the chord is borrowed from the parallel mode.
- * @category Functional Harmony
- */
-export function isBorrowedChord(chord: Chord, key: KeyScale): boolean {
-  if (isDiatonic(chord, key)) {
-    return false;
-  }
-  if (isHarmonicMinorAlteration(chord, key)) {
-    return false;
-  }
-  return isDiatonic(chord, parallelKey(key));
-}
-
-/**
- * Identify where a non-diatonic chord comes from.
- *
- * The Neapolitan (major triad on b2) is recognized first, since it sits
- * outside both parallel modes; parallel-mode borrowing follows the
- * {@link isBorrowedChord} rules. Diatonic chords, harmonic-minor alterations,
- * and unrecognized chromatic chords all yield null.
- *
- * @param chord The chord to classify.
- * @param key The prevailing key.
- * @returns The borrowing source, or null.
- * @category Functional Harmony
- */
-export function borrowedSource(chord: Chord, key: KeyScale): BorrowedSource {
-  if (isDiatonic(chord, key)) {
-    return null;
-  }
-  if (isNeapolitan(chord, key)) {
-    return 'neapolitan';
-  }
-  if (isBorrowedChord(chord, key)) {
-    return isMinorKey(key) ? 'parallel-major' : 'parallel-minor';
-  }
-  return null;
-}
-
-/** Diminished-family qualities: diminished triad, dim7, half-diminished. */
-function isDiminishedQuality(quality: ChordQuality): boolean {
-  return quality === 'dim' || quality === 'dim7' || quality === 'm7b5';
-}
-
-/** Whether the chord's interval template carries a major third above the root. */
-function hasMajorThird(chord: Chord): boolean {
-  return chord.intervals.some((interval) => mod12(interval) === 4);
-}
-
-/**
- * Quality-aware harmonic function, refining the offset table where chord
- * quality disambiguates: diminished chords on the leading tone or the raised
- * subdominant resolve by semitone and act as dominants; the Neapolitan and the
- * major-third chords on bVI/bVII borrowed from the parallel minor act as
- * subdominant (predominant) harmony. All other chords keep {@link functionOf}.
- */
-function qualityAwareFunction(chord: Chord, key: KeyScale): HarmonicFunction {
-  const offset = mod12(chord.rootPc - key.rootPc);
-  if (isDiminishedQuality(chord.quality) && (offset === 11 || offset === 6)) {
-    return 'dominant';
-  }
-  if (isNeapolitan(chord, key)) {
-    return 'subdominant';
-  }
-  if (!isMinorKey(key) && hasMajorThird(chord) && (offset === 8 || offset === 10)) {
-    return 'subdominant';
-  }
-  return functionOf(chord, key);
-}
-
-/**
- * Analyze a chord in a key: harmonic function, borrowing, and Roman numeral.
- *
- * The function is quality-aware (see the predicates behind it), the source
- * follows {@link borrowedSource}, and the numeral comes from
- * {@link chordToRoman}. `borrowed` is true whenever a source is identified —
- * including the Neapolitan, which the stricter parallel-mode predicate
- * {@link isBorrowedChord} does not count.
- *
- * @param chord The chord to analyze.
- * @param key The prevailing key.
- * @returns The chord analysis.
- * @example
- * ```ts
- * import { analyzeChord, makeChord, majorKey } from '@libraz/libcantus';
- * analyzeChord(makeChord(7, 'dom7'), majorKey(0));
- * // { function: 'dominant', borrowed: false, source: null, roman: 'V7' }
- * ```
- * @category Functional Harmony
- */
-export function analyzeChord(chord: Chord, key: KeyScale): ChordAnalysis {
-  const source = borrowedSource(chord, key);
-  return {
-    function: qualityAwareFunction(chord, key),
-    borrowed: source !== null,
-    source,
-    roman: chordToRoman(chord, key),
-  };
-}
-
-/**
- * Classify the cadence formed by moving from one chord to the next.
- *
- * - authentic: V (dominant a fifth above the tonic) to I
- * - plagal: IV (a fourth above the tonic) to I
- * - deceptive: V to the submediant (diatonic vi or borrowed bVI in major, VI in
- *   minor)
- * - half: any chord other than the dominant itself to V
- *
- * A static V-to-V repeat with no root motion is not a cadence and yields null.
- *
- * @param from The penultimate chord.
- * @param to The final chord.
- * @param key The prevailing key.
- * @returns The cadence type, or null.
- * @example
- * ```ts
- * import { detectCadence, makeChord, majorKey } from '@libraz/libcantus';
- * detectCadence(makeChord(7, 'maj'), makeChord(0, 'maj'), majorKey(0)); // => 'authentic'
- * ```
- * @category Functional Harmony
- */
-export function detectCadence(from: Chord, to: Chord, key: KeyScale): Cadence {
-  const tonic = mod12(key.rootPc);
-  const fromOffset = mod12(from.rootPc - tonic);
-  const toOffset = mod12(to.rootPc - tonic);
-  // Deceptive targets: the diatonic submediant (vi at offset 9 in major, VI at
-  // offset 8 in minor) plus, in a major key, the borrowed flat-submediant bVI
-  // at offset 8.
-  const deceptiveTargets = isMinorKey(key) ? [8] : [8, 9];
-  if (fromOffset === 7 && toOffset === 0) {
-    return 'authentic';
-  }
-  if (fromOffset === 5 && toOffset === 0) {
-    return 'plagal';
-  }
-  if (fromOffset === 7 && deceptiveTargets.includes(toOffset)) {
-    return 'deceptive';
-  }
-  // A move to the dominant is a half cadence, but a no-root-motion V-to-V repeat
-  // is not a cadence at all.
-  if (toOffset === 7 && fromOffset !== 7) {
-    return 'half';
-  }
-  return null;
-}
-
-/**
- * The secondary dominant (V7) that tonicizes a scale degree.
- *
- * @param targetDegree 0-based scale degree to tonicize.
- * @param key The prevailing key.
- * @returns A dominant-seventh chord a fifth above the target's root.
- * @category Functional Harmony
- */
-export function secondaryDominant(targetDegree: number, key: KeyScale): Chord {
-  const targetRoot = degreeRootPc(targetDegree + 1, key);
-  return makeChord(mod12(targetRoot + 7), 'dom7');
-}

package/src/analyze/index.ts

@@ -0,0 +1,49 @@
+/**
+ * Public API of the analyze layer. Re-exports every analyze-layer module;
+ * also available from the package root.
+ */
+export type {
+  ArrangementAnalysis,
+  ArrangementOptions,
+  ArrangementTrack,
+  Conflict,
+  TensionPoint,
+  TrackAnalysis,
+  TrackRole,
+} from './arrange/index.js';
+export { analyzeArrangement, tensionCurve } from './arrange/index.js';
+export type { ChordMatch, KeyMatch } from './detect/index.js';
+export { detectChord, detectChordBest, detectKey } from './detect/index.js';
+export type {
+  BorrowedSource,
+  Cadence,
+  ChordAnalysis,
+  HarmonicFunction,
+} from './functional/index.js';
+export {
+  analyzeChord,
+  borrowedSource,
+  chordToRoman,
+  detectCadence,
+  functionOf,
+  isBorrowedChord,
+  isDiatonic,
+  isMinorKey,
+  parallelKey,
+  romanToChord,
+  secondaryDominant,
+} from './functional/index.js';
+export type {
+  CadenceHit,
+  ChordSegment,
+  ChordTimeline,
+  ChordTimelineOptions,
+  ChordTimelineResult,
+} from './timeline/index.js';
+export {
+  chordTimelineFromChords,
+  chordTimelineFromNotes,
+  detectCadences,
+} from './timeline/index.js';
+export type { AnalyzedNote, TheoryLabel, VoiceNote } from './voice/index.js';
+export { analyzeVoice } from './voice/index.js';

package/src/{timeline → analyze/timeline}/index.ts

@@ -1,14 +1,13 @@
-import type { Chord } from '../chord/index.js';
-import { chordPitchClasses, makeChord } from '../chord/index.js';
+import type { TimeSignature } from '../../core/meter/index.js';
+import { beatsPerBar, metricWeight, parseTimeSignature } from '../../core/meter/index.js';
+import type { KeyScale, NoteEvent } from '../../core/types.js';
+import type { Chord, ChordSpan } from '../../theory/chord/index.js';
+import { chordPitchClasses, makeChord } from '../../theory/chord/index.js';
+import { isScaleTone, majorKey } from '../../theory/scale/index.js';
 import type { ChordMatch } from '../detect/index.js';
 import { detectChord, detectChordBest, detectKey } from '../detect/index.js';
 import type { Cadence } from '../functional/index.js';
 import { detectCadence } from '../functional/index.js';
-import type { TimeSignature } from '../meter/index.js';
-import { beatsPerBar, metricWeight, parseTimeSignature } from '../meter/index.js';
-import type { GeneratedChord } from '../progression/index.js';
-import { isScaleTone, majorKey } from '../scale/index.js';
-import type { KeyScale, NoteEvent } from '../types.js';
 
 /**
  * A chord occupying a half-open beat span.
@@ -45,10 +44,7 @@ export type ChordTimeline = {
  * @returns A queryable chord timeline.
  * @category Arrangement & Analysis
  */
-export function chordTimelineFromChords(
-  chords: GeneratedChord[],
-  totalBeats: number,
-): ChordTimeline {
+export function chordTimelineFromChords(chords: ChordSpan[], totalBeats: number): ChordTimeline {
   const sorted = [...chords].sort((a, b) => a.startBeat - b.startBeat);
   const segments: ChordSegment[] = sorted
     .map((gc, i) => {

package/src/{analysis → analyze/voice}/index.ts

@@ -1,8 +1,11 @@
-import type { Chord } from '../chord/index.js';
-import { chordPitchClasses, chordToneRole } from '../chord/index.js';
-import { createsVerticalDissonance, isLeadingToneResolution } from '../counterpoint/index.js';
-import type { VoiceSnapshot } from '../safety/index.js';
-import type { KeyScale, NoteEvent } from '../types.js';
+import type { KeyScale, NoteEvent } from '../../core/types.js';
+import type { Chord } from '../../theory/chord/index.js';
+import { chordPitchClasses, chordToneRole } from '../../theory/chord/index.js';
+import {
+  createsVerticalDissonance,
+  isLeadingToneResolution,
+} from '../../theory/counterpoint/index.js';
+import type { VoiceSnapshot } from '../../theory/safety/index.js';
 
 /**
  * A theory annotation attached to a note.

package/src/core/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Public API of the core layer. Re-exports every core-layer module;
+ * also available from the package root.
+ */
+export {
+  classifyInterval,
+  IntervalQuality,
+  isConsonantInterval,
+  isPerfectInterval,
+} from './interval/index.js';
+export type { BarPosition, TimeSignature } from './meter/index.js';
+export {
+  barPositionToBeat,
+  beatsPerBar,
+  beatToBarPosition,
+  formatTimeSignature,
+  isCompound,
+  isStrongBeat,
+  metricWeight,
+  parseTimeSignature,
+  pulsesPerBar,
+  tuplet,
+} from './meter/index.js';
+export type { Note as NoteData, SpelledInterval } from './pitch/index.js';
+export {
+  formatNote,
+  midiToNote,
+  noteToMidi,
+  noteToPitchClass,
+  parseNote,
+  spelledInterval,
+} from './pitch/index.js';
+export type { Rng } from './random/index.js';
+export { createRng } from './random/index.js';
+export type { Tuning } from './tuning/index.js';
+export {
+  centsBetweenFreq,
+  centsOfSteps,
+  edo,
+  frequencyOf,
+  JUST_RATIOS,
+  justDeviationCents,
+  nearestStep,
+  ratioToCents,
+  TWELVE_TET,
+} from './tuning/index.js';
+export type { KeyScale, NoteEvent } from './types.js';

package/src/{bass → generate/bass}/index.ts

@@ -12,11 +12,11 @@
  * library-wide convention.
  */
 
-import type { Chord } from '../chord/index.js';
-import { isStrongBeat, type TimeSignature } from '../meter/index.js';
-import { createRng } from '../random/index.js';
-import { nearestScaleTone } from '../scale/index.js';
-import type { KeyScale, NoteEvent } from '../types.js';
+import { isStrongBeat, type TimeSignature } from '../../core/meter/index.js';
+import { createRng } from '../../core/random/index.js';
+import type { KeyScale, NoteEvent } from '../../core/types.js';
+import type { Chord } from '../../theory/chord/index.js';
+import { nearestScaleTone } from '../../theory/scale/index.js';
 
 /**
  * A chord sounding over a half-open beat span `[startBeat, endBeat)`.

package/src/{countermelody → generate/countermelody}/index.ts

@@ -1,14 +1,14 @@
-import type { Chord } from '../chord/index.js';
-import { chordToneRole } from '../chord/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';
-import { createRng } from '../random/index.js';
-import type { VoiceSnapshot } from '../safety/index.js';
-import { enumerateSafePitches } from '../safety/index.js';
-import { nearestScaleTone } from '../scale/index.js';
-import type { KeyScale, NoteEvent } from '../types.js';
+import type { TimeSignature } from '../../core/meter/index.js';
+import { isStrongBeat } from '../../core/meter/index.js';
+import type { Rng } from '../../core/random/index.js';
+import { createRng } from '../../core/random/index.js';
+import type { KeyScale, NoteEvent } from '../../core/types.js';
+import type { Chord } from '../../theory/chord/index.js';
+import { chordToneRole } from '../../theory/chord/index.js';
+import { createsParallelPerfect, isForbiddenMelodicLeap } from '../../theory/counterpoint/index.js';
+import type { VoiceSnapshot } from '../../theory/safety/index.js';
+import { enumerateSafePitches } from '../../theory/safety/index.js';
+import { nearestScaleTone } from '../../theory/scale/index.js';
 
 /**
  * Options controlling {@link generateCounterMelody}.

package/src/{drums → generate/drums}/index.ts

@@ -99,7 +99,7 @@ export type EuclideanKick = {
  *
  * @category Composition
  */
-export type DrumGenOptions = {
+export type DrumsOptions = {
   bars: number;
   bpm: number;
   style: GrooveStyle;
@@ -163,7 +163,7 @@ export type DrumGenOptions = {
  *
  * @category Composition
  */
-export function generateDrums(opts: DrumGenOptions): DrumHit[] {
+export function generateDrums(opts: DrumsOptions): DrumHit[] {
   const track = new HitList();
   const rng = createRng(opts.seed ?? 0);
   const mapping = mapStyle(opts.style);

package/src/{drums → generate/drums}/rng.ts

@@ -3,5 +3,5 @@
  * `DrumRng` is retained as the drum-facing name of the shared {@link Rng} type.
  */
 
-export type { Rng as DrumRng } from '../random/index.js';
-export { createRng } from '../random/index.js';
+export type { Rng as DrumRng } from '../../core/random/index.js';
+export { createRng } from '../../core/random/index.js';

package/src/{groove → generate/groove}/index.ts

@@ -13,9 +13,9 @@ import {
   formatTimeSignature,
   metricWeight,
   type TimeSignature,
-} from '../meter/index.js';
-import { createRng } from '../random/index.js';
-import type { NoteEvent } from '../types.js';
+} from '../../core/meter/index.js';
+import { createRng } from '../../core/random/index.js';
+import type { NoteEvent } from '../../core/types.js';
 
 /**
  * Options controlling {@link humanize}.

package/src/{harmonize → generate/harmonize}/index.ts

@@ -1,18 +1,18 @@
-import type { Chord, ChordQuality } from '../chord/index.js';
-import { chordPitchClasses, diatonicTriad, makeChord } from '../chord/index.js';
-import type { HarmonyRole } from '../harmony/index.js';
-import { roleOf } from '../harmony/index.js';
-import type { TimeSignature } from '../meter/index.js';
-import { isStrongBeat } from '../meter/index.js';
-import type { GeneratedChord } from '../progression/index.js';
+import type { TimeSignature } from '../../core/meter/index.js';
+import { isStrongBeat } from '../../core/meter/index.js';
+import type { KeyScale, NoteEvent } from '../../core/types.js';
+import type { Chord, ChordQuality } from '../../theory/chord/index.js';
+import { chordPitchClasses, diatonicTriad, makeChord } from '../../theory/chord/index.js';
+import type { HarmonyRole } from '../../theory/harmony/index.js';
+import { roleOf } from '../../theory/harmony/index.js';
 import {
   isScaleTone,
   majorKey,
   minorKey,
   NATURAL_MINOR_MASK,
   scaleTonesInDegreeOrder,
-} from '../scale/index.js';
-import type { KeyScale, NoteEvent } from '../types.js';
+} from '../../theory/scale/index.js';
+import type { ChordSpan } from '../progression/index.js';
 
 /**
  * A melody note supplied to the harmonizer: a {@link NoteEvent}.
@@ -48,7 +48,7 @@ export type HarmonizeOptions = {
 export type HarmonizeResult = {
   transposeSemitones: number;
   key: KeyScale;
-  chords: GeneratedChord[];
+  chords: ChordSpan[];
   melodyRoles: { noteIndex: number; role: HarmonyRole }[];
 };
 
@@ -356,7 +356,7 @@ function harmonizeOnce(
  *   reharmonize: 'diatonic',
  *   placement: { transposeSearch: false, octaveSearch: false },
  * });
- * result.chords; // one GeneratedChord per harmonic-rhythm segment
+ * result.chords; // one ChordSpan per harmonic-rhythm segment
  * ```
  * @category Reharmonization
  */
@@ -413,9 +413,9 @@ export function harmonizeMelody(opts: HarmonizeOptions): HarmonizeResult {
     }
   }
 
-  const chords: GeneratedChord[] = bestPath.map((ci, s) => {
+  const chords: ChordSpan[] = bestPath.map((ci, s) => {
     const cand = candAt(ci);
-    const chord: GeneratedChord = {
+    const chord: ChordSpan = {
       rootPc: cand.rootPc,
       quality: cand.quality,
       startBeat: segments[s]?.startBeat ?? s * hr,