@libraz/libcantus 0.9.4 → 0.9.5

package/dist/{chunk-NVE34YGZ.cjs → chunk-WTAN4ACG.cjs}

@@ -1,6 +1,6 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
 
-var _chunkZEJR4TKLcjs = require('./chunk-ZEJR4TKL.cjs');
+var _chunk357ZDPVUcjs = require('./chunk-357ZDPVU.cjs');
 
 
 
@@ -14,7 +14,7 @@ var _chunkZEJR4TKLcjs = require('./chunk-ZEJR4TKL.cjs');
 
 
 
-var _chunkCAN76NCUcjs = require('./chunk-CAN76NCU.cjs');
+var _chunkKQN2ZYNDcjs = require('./chunk-KQN2ZYND.cjs');
 
 
 
@@ -28,8 +28,8 @@ var _chunkCAN76NCUcjs = require('./chunk-CAN76NCU.cjs');
 
 
 
-var _chunkLW53AHQUcjs = require('./chunk-LW53AHQU.cjs');
 
+var _chunkOL3IHHSJcjs = require('./chunk-OL3IHHSJ.cjs');
 
 
 
@@ -41,8 +41,8 @@ var _chunkLW53AHQUcjs = require('./chunk-LW53AHQU.cjs');
 
 
 
-var _chunkFNDWXRRIcjs = require('./chunk-FNDWXRRI.cjs');
 
+var _chunkBSLTLGM3cjs = require('./chunk-BSLTLGM3.cjs');
 
 
 
@@ -57,7 +57,9 @@ var _chunkFNDWXRRIcjs = require('./chunk-FNDWXRRI.cjs');
 
 
 
-var _chunk7MGZ7D62cjs = require('./chunk-7MGZ7D62.cjs');
+
+
+var _chunkPI3UXRWKcjs = require('./chunk-PI3UXRWK.cjs');
 
 // src/model/interval.ts
 var INVERSION_SUM = 9;
@@ -77,10 +79,12 @@ var Interval = class _Interval {
   #number;
   #quality;
   #semitones;
-  constructor(numberValue, quality, semitones) {
+  #descending;
+  constructor(numberValue, quality, semitones, descending = semitones < 0) {
     this.#number = numberValue;
     this.#quality = quality;
     this.#semitones = semitones;
+    this.#descending = descending;
   }
   /**
    * The spelled interval between two notes.
@@ -104,9 +108,9 @@ var Interval = class _Interval {
    *   `P5` spanning 8 semitones is not a value any other method can produce.
    */
   static of(numberValue, quality, semitones) {
-    const expected = _chunk7MGZ7D62cjs.intervalSemitones.call(void 0, numberValue, quality);
+    const expected = _chunkPI3UXRWKcjs.intervalSemitones.call(void 0, numberValue, quality);
     if (Math.abs(semitones) !== expected) {
-      throw new (0, _chunk7MGZ7D62cjs.InvalidInputError)(
+      throw new (0, _chunkPI3UXRWKcjs.InvalidInputError)(
         `${quality}${numberValue} spans ${expected} semitones; received ${semitones}`
       );
     }
@@ -119,7 +123,12 @@ var Interval = class _Interval {
    * @returns The wrapped interval.
    */
   static fromData(data) {
-    return new _Interval(data.number, data.quality, data.semitones);
+    return new _Interval(
+      data.number,
+      data.quality,
+      data.semitones,
+      _nullishCoalesce(data.descending, () => ( data.semitones < 0))
+    );
   }
   /**
    * Rebuild an interval from its {@link Interval.toJSON} output.
@@ -138,7 +147,7 @@ var Interval = class _Interval {
    * @throws If the name is not a quality label followed by a diatonic number.
    */
   static parse(name) {
-    return _Interval.fromData(_chunk7MGZ7D62cjs.parseInterval.call(void 0, name));
+    return _Interval.fromData(_chunkPI3UXRWKcjs.parseInterval.call(void 0, name));
   }
   /** Diatonic size: 1 = unison, 2 = second, ... 8 = octave, and beyond. */
   get number() {
@@ -166,10 +175,10 @@ var Interval = class _Interval {
    * @returns The inverted interval, e.g. `M3` becomes `m6`.
    */
   invert() {
-    const simple = (this.#number - 1) % 7 + 1;
+    const simple = this.#number === 8 ? 8 : (this.#number - 1) % 7 + 1;
     const numberValue = INVERSION_SUM - simple;
     const quality = invertQuality(this.#quality);
-    return _Interval.of(numberValue, quality, _chunk7MGZ7D62cjs.intervalSemitones.call(void 0, numberValue, quality));
+    return _Interval.of(numberValue, quality, _chunkPI3UXRWKcjs.intervalSemitones.call(void 0, numberValue, quality));
   }
   /**
    * Whether the interval is consonant.
@@ -179,7 +188,7 @@ var Interval = class _Interval {
    * @returns True if the interval is consonant in that context.
    */
   isConsonant(twoVoice = true) {
-    return _chunk7MGZ7D62cjs.isConsonantInterval.call(void 0, this.#semitones, twoVoice);
+    return _chunkPI3UXRWKcjs.isConsonantInterval.call(void 0, this.#semitones, twoVoice);
   }
   /**
    * Whether another interval is spelled identically.
@@ -191,7 +200,7 @@ var Interval = class _Interval {
    * @returns True when number, quality, and span all match.
    */
   equals(other) {
-    return this.#number === other.number && this.#quality === other.quality && this.#semitones === other.semitones;
+    return this.#number === other.number && this.#quality === other.quality && this.#semitones === other.semitones && this.#descending === other.#descending;
   }
   /**
    * The plain interval data, for JSON serialization.
@@ -202,7 +211,17 @@ var Interval = class _Interval {
    * @returns The diatonic number, quality, and semitone span.
    */
   toJSON() {
-    return { number: this.#number, quality: this.#quality, semitones: this.#semitones };
+    return this.#descending ? {
+      number: this.#number,
+      quality: this.#quality,
+      semitones: this.#semitones,
+      descending: true
+    } : this.#semitones < 0 ? {
+      number: this.#number,
+      quality: this.#quality,
+      semitones: this.#semitones,
+      descending: false
+    } : { number: this.#number, quality: this.#quality, semitones: this.#semitones };
   }
   /**
    * The interval's name, so a template literal or a log line reads as the
@@ -218,7 +237,7 @@ var Interval = class _Interval {
 // src/model/note.ts
 function copyNote(data) {
   if (!Number.isInteger(data.letter) || data.letter < 0 || data.letter > 6) {
-    throw new (0, _chunk7MGZ7D62cjs.InvalidInputError)(
+    throw new (0, _chunkPI3UXRWKcjs.InvalidInputError)(
       `note letter must be an integer in [0, 6]; received ${data.letter}`
     );
   }
@@ -226,6 +245,7 @@ function copyNote(data) {
   if (data.octave !== void 0) {
     copy.octave = data.octave;
   }
+  _chunkPI3UXRWKcjs.noteToPitchClass.call(void 0, copy);
   return copy;
 }
 var Note = class _Note {
@@ -247,7 +267,7 @@ var Note = class _Note {
    * @throws If the text is not a valid note.
    */
   static of(name) {
-    return new _Note(_chunk7MGZ7D62cjs.parseNote.call(void 0, name));
+    return new _Note(_chunkPI3UXRWKcjs.parseNote.call(void 0, name));
   }
   /**
    * Name a MIDI number (middle C = C4 = 60) as a note.
@@ -257,7 +277,7 @@ var Note = class _Note {
    * @returns The spelled note, with octave.
    */
   static fromMidi(midi, spelling = "sharp") {
-    return new _Note(_chunk7MGZ7D62cjs.midiToNote.call(void 0, midi, spelling));
+    return new _Note(_chunkPI3UXRWKcjs.midiToNote.call(void 0, midi, spelling));
   }
   /**
    * Wrap an existing plain note object.
@@ -271,11 +291,11 @@ var Note = class _Note {
   }
   /** The note rendered as scientific pitch notation, e.g. `'G4'` or `'Bb'`. */
   get name() {
-    return _chunk7MGZ7D62cjs.formatNote.call(void 0, this.#data);
+    return _chunkPI3UXRWKcjs.formatNote.call(void 0, this.#data);
   }
   /** The pitch class (0..11), ignoring octave. */
   get pitchClass() {
-    return _chunk7MGZ7D62cjs.noteToPitchClass.call(void 0, this.#data);
+    return _chunkPI3UXRWKcjs.noteToPitchClass.call(void 0, this.#data);
   }
   /**
    * The MIDI number (middle C = C4 = 60).
@@ -284,9 +304,9 @@ var Note = class _Note {
    */
   get midi() {
     if (this.#data.octave === void 0) {
-      throw new (0, _chunk7MGZ7D62cjs.InvalidInputError)(`note ${this.name} has no octave, so it has no MIDI number`);
+      throw new (0, _chunkPI3UXRWKcjs.InvalidInputError)(`note ${this.name} has no octave, so it has no MIDI number`);
     }
-    return _chunk7MGZ7D62cjs.noteToMidi.call(void 0, this.#data);
+    return _chunkPI3UXRWKcjs.noteToMidi.call(void 0, this.#data);
   }
   /** The diatonic letter number: 0..6 for C..B. */
   get letter() {
@@ -328,7 +348,7 @@ var Note = class _Note {
     if (semitones === 0 && _optionalChain([opts, 'optionalAccess', _ => _.spelling]) === void 0) {
       return new _Note(this.#data);
     }
-    return new _Note(_chunk7MGZ7D62cjs.transposeNote.call(void 0, this.#data, semitones, opts));
+    return new _Note(_chunkPI3UXRWKcjs.transposeNote.call(void 0, this.#data, semitones, opts));
   }
   /**
    * The spelled interval from this note to another.
@@ -337,7 +357,7 @@ var Note = class _Note {
    * @returns The interval, which {@link Interval.toJSON} unwraps to plain data.
    */
   intervalTo(other) {
-    return Interval.fromData(_chunk7MGZ7D62cjs.spelledInterval.call(void 0, this.#data, other.data));
+    return Interval.fromData(_chunkPI3UXRWKcjs.spelledInterval.call(void 0, this.#data, other.data));
   }
   /**
    * Transpose by a spelled interval, keeping the spelling the interval names.
@@ -355,7 +375,7 @@ var Note = class _Note {
    * ```
    */
   transposeBy(interval) {
-    return new _Note(_chunk7MGZ7D62cjs.transposeByInterval.call(void 0, this.#data, interval.toJSON()));
+    return new _Note(_chunkPI3UXRWKcjs.transposeByInterval.call(void 0, this.#data, interval.toJSON()));
   }
   /**
    * Rebuild a note from its {@link Note.toJSON} output.
@@ -400,13 +420,13 @@ var Note = class _Note {
 
 // src/model/shared.ts
 function spellPitchClassBare(pc, spelling) {
-  const spelled = _chunk7MGZ7D62cjs.midiToNote.call(void 0, 60 + _chunk7MGZ7D62cjs.pitchClassOf.call(void 0, pc), spelling);
+  const spelled = _chunkPI3UXRWKcjs.midiToNote.call(void 0, 60 + _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, pc), spelling);
   return { letter: spelled.letter, alter: spelled.alter };
 }
 
 // src/model/key.ts
 function accidentalLoad(tonic, scale) {
-  return _chunkLW53AHQUcjs.spellScale.call(void 0, tonic, scale).reduce((sum, note) => sum + Math.abs(note.alter), 0);
+  return _chunkOL3IHHSJcjs.spellScale.call(void 0, tonic, scale).reduce((sum, note) => sum + Math.abs(note.alter), 0);
 }
 function bestTonicForScale(rootPc, scale) {
   const sharp = spellPitchClassBare(rootPc, "sharp");
@@ -419,21 +439,38 @@ function bestTonicForScale(rootPc, scale) {
 var Key = class _Key {
   #scale;
   #tonic;
+  #variant;
   /**
    * Wrap a key/scale and its spelled tonic.
    *
    * @param scale The key/scale; its root is normalized to a pitch class.
    * @param tonic The spelled tonic anchoring letter-name spelling.
+   * @param variant Optional detected scale form retained for display.
    */
-  constructor(scale, tonic) {
-    const rootPc = _chunk7MGZ7D62cjs.pitchClassOf.call(void 0, scale.rootPc);
+  constructor(scale, tonic, variant) {
+    _chunkPI3UXRWKcjs.assertInteger.call(void 0, scale.rootPc, "scale.rootPc");
+    _chunkPI3UXRWKcjs.assertInteger.call(void 0, scale.modeMask12, "scale.modeMask12", 1, 4095);
+    if ((scale.modeMask12 & 1) === 0) {
+      throw new (0, _chunkPI3UXRWKcjs.InvalidInputError)("scale.modeMask12 must include the tonic (bit 0)");
+    }
+    const rootPc = _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, scale.rootPc);
     if (tonic.pitchClass !== rootPc) {
-      throw new (0, _chunk7MGZ7D62cjs.InvalidInputError)(
+      throw new (0, _chunkPI3UXRWKcjs.InvalidInputError)(
         `tonic ${tonic.name} does not match the scale root pitch class ${rootPc}; pass a tonic that spells the scale root, or omit it to have one chosen`
       );
     }
     this.#scale = { rootPc, modeMask12: scale.modeMask12 };
     this.#tonic = tonic;
+    this.#variant = variant;
+  }
+  /** Preserve detection metadata while replacing its plain key with this API's Key. */
+  static #fromMatch(match) {
+    const key = new _Key(
+      match.key,
+      bestTonicForScale(_chunkPI3UXRWKcjs.pitchClassOf.call(void 0, match.key.rootPc), match.key),
+      match.variant
+    );
+    return { ...match, key };
   }
   /**
    * A major key.
@@ -446,9 +483,9 @@ var Key = class _Key {
   static major(root) {
     if (typeof root === "string") {
       const tonic = Note.of(root);
-      return new _Key(_chunkFNDWXRRIcjs.majorKey.call(void 0, tonic.pitchClass), tonic);
+      return new _Key(_chunkBSLTLGM3cjs.majorKey.call(void 0, tonic.pitchClass), tonic);
     }
-    const scale = _chunkFNDWXRRIcjs.majorKey.call(void 0, root);
+    const scale = _chunkBSLTLGM3cjs.majorKey.call(void 0, root);
     return new _Key(scale, bestTonicForScale(root, scale));
   }
   /**
@@ -462,9 +499,9 @@ var Key = class _Key {
   static minor(root) {
     if (typeof root === "string") {
       const tonic = Note.of(root);
-      return new _Key(_chunkFNDWXRRIcjs.minorKey.call(void 0, tonic.pitchClass), tonic);
+      return new _Key(_chunkBSLTLGM3cjs.minorKey.call(void 0, tonic.pitchClass), tonic);
     }
-    const scale = _chunkFNDWXRRIcjs.minorKey.call(void 0, root);
+    const scale = _chunkBSLTLGM3cjs.minorKey.call(void 0, root);
     return new _Key(scale, bestTonicForScale(root, scale));
   }
   /**
@@ -480,10 +517,10 @@ var Key = class _Key {
   static named(name, root) {
     if (typeof root === "string") {
       const tonic = Note.of(root);
-      return new _Key(_chunkFNDWXRRIcjs.scaleByName.call(void 0, name, tonic.pitchClass), tonic);
+      return new _Key(_chunkBSLTLGM3cjs.scaleByName.call(void 0, name, tonic.pitchClass), tonic);
     }
-    const scale = _chunkFNDWXRRIcjs.scaleByName.call(void 0, name, _chunk7MGZ7D62cjs.pitchClassOf.call(void 0, root));
-    return new _Key(scale, bestTonicForScale(_chunk7MGZ7D62cjs.pitchClassOf.call(void 0, root), scale));
+    const scale = _chunkBSLTLGM3cjs.scaleByName.call(void 0, name, _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, root));
+    return new _Key(scale, bestTonicForScale(_chunkPI3UXRWKcjs.pitchClassOf.call(void 0, root), scale));
   }
   /**
    * Wrap an existing `KeyScale`, synthesizing a spelled tonic when none is
@@ -500,7 +537,7 @@ var Key = class _Key {
    * @throws If the given tonic is not the scale's root pitch class.
    */
   static of(scale, tonic) {
-    return new _Key(scale, _nullishCoalesce(tonic, () => ( bestTonicForScale(_chunk7MGZ7D62cjs.pitchClassOf.call(void 0, scale.rootPc), scale))));
+    return new _Key(scale, _nullishCoalesce(tonic, () => ( bestTonicForScale(_chunkPI3UXRWKcjs.pitchClassOf.call(void 0, scale.rootPc), scale))));
   }
   /**
    * Rebuild a key from its {@link Key.toJSON} output.
@@ -521,7 +558,17 @@ var Key = class _Key {
    * @returns Ranked keys (may be empty).
    */
   static detect(pitches, opts) {
-    return _chunkCAN76NCUcjs.detectKey.call(void 0, pitches, opts).map((match) => _Key.of(match.key));
+    return _Key.detectMatches(pitches, opts).map((match) => match.key);
+  }
+  /**
+   * Identify keys while retaining each candidate's score, fit, and scale form.
+   *
+   * @param pitches MIDI pitches or bare pitch classes.
+   * @param opts How to weigh the input; see {@link DetectKeyOptions}.
+   * @returns Ranked key matches (may be empty).
+   */
+  static detectMatches(pitches, opts) {
+    return _chunkKQN2ZYNDcjs.detectKey.call(void 0, pitches, opts).map((match) => _Key.#fromMatch(match));
   }
   /**
    * The single best key interpretation of a pitch set.
@@ -536,8 +583,8 @@ var Key = class _Key {
    * ```
    */
   static detectBest(pitches, opts) {
-    const best = _chunkCAN76NCUcjs.detectKeyBest.call(void 0, pitches, opts);
-    return best === null ? null : _Key.of(best.key);
+    const best = _chunkKQN2ZYNDcjs.detectKeyBest.call(void 0, pitches, opts);
+    return best === null ? null : _Key.#fromMatch(best).key;
   }
   /**
    * Whether another key has the same tonic pitch class and mode.
@@ -566,7 +613,11 @@ var Key = class _Key {
   }
   /** Whether the scale has a minor third and no major third. */
   get isMinor() {
-    return _chunkCAN76NCUcjs.isMinorKey.call(void 0, this.#scale);
+    return _chunkKQN2ZYNDcjs.isMinorKey.call(void 0, this.#scale);
+  }
+  /** The detected scale form, when this key came from key detection. */
+  get variant() {
+    return this.#variant;
   }
   /**
    * The scale's pitch classes in ascending scale-degree order (degree 0 first).
@@ -574,7 +625,7 @@ var Key = class _Key {
    * @returns One pitch class per scale degree.
    */
   pitchClasses() {
-    return _chunkFNDWXRRIcjs.scaleTonesInDegreeOrder.call(void 0, this.#scale);
+    return _chunkBSLTLGM3cjs.scaleTonesInDegreeOrder.call(void 0, this.#scale);
   }
   /**
    * Transpose the key by a number of semitones.
@@ -592,9 +643,13 @@ var Key = class _Key {
    * ```
    */
   transpose(semitones) {
-    _chunk7MGZ7D62cjs.assertFiniteNumber.call(void 0, semitones, "semitones");
-    const rootPc = _chunk7MGZ7D62cjs.pitchClassOf.call(void 0, this.#scale.rootPc + Math.round(semitones));
-    return _Key.of({ rootPc, modeMask12: this.#scale.modeMask12 });
+    _chunkPI3UXRWKcjs.assertFiniteNumber.call(void 0, semitones, "semitones");
+    const rootPc = _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, this.#scale.rootPc + Math.round(semitones));
+    return new _Key(
+      { rootPc, modeMask12: this.#scale.modeMask12 },
+      this.#tonic.transpose(semitones),
+      this.#variant
+    );
   }
   /**
    * The spelled scale, one note per degree (e.g. C D E F G A B for C major).
@@ -602,7 +657,7 @@ var Key = class _Key {
    * @returns Spelled octave-less notes in scale-degree order.
    */
   notes() {
-    return _chunkLW53AHQUcjs.spellScale.call(void 0, this.#tonic.data, this.#scale).map((note) => new Note(note));
+    return _chunkOL3IHHSJcjs.spellScale.call(void 0, this.#tonic.data, this.#scale).map((note) => new Note(note));
   }
   /**
    * Alias of {@link Key.notes}.
@@ -636,7 +691,7 @@ var Key = class _Key {
    *   an explicit `quality` for those.
    */
   chord(degree, quality) {
-    const data = quality === void 0 ? _chunkFNDWXRRIcjs.diatonicTriad.call(void 0, degree, this.#scale) : _chunkFNDWXRRIcjs.chordFromDegree.call(void 0, degree, quality, this.#scale);
+    const data = quality === void 0 ? _chunkBSLTLGM3cjs.diatonicTriad.call(void 0, degree, this.#scale) : _chunkBSLTLGM3cjs.chordFromDegree.call(void 0, degree, quality, this.#scale);
     return new Chord(data, this);
   }
   /**
@@ -648,7 +703,7 @@ var Key = class _Key {
    *   degrees. Use {@link Key.chord} with an explicit quality instead.
    */
   diatonicTriad(degree) {
-    return new Chord(_chunkFNDWXRRIcjs.diatonicTriad.call(void 0, degree, this.#scale), this);
+    return new Chord(_chunkBSLTLGM3cjs.diatonicTriad.call(void 0, degree, this.#scale), this);
   }
   /**
    * The diatonic seventh chord on a scale degree, carrying this key as context.
@@ -659,7 +714,7 @@ var Key = class _Key {
    *   degrees. Use {@link Key.chord} with an explicit quality instead.
    */
   diatonicSeventh(degree) {
-    return new Chord(_chunkFNDWXRRIcjs.diatonicSeventh.call(void 0, degree, this.#scale), this);
+    return new Chord(_chunkBSLTLGM3cjs.diatonicSeventh.call(void 0, degree, this.#scale), this);
   }
   /**
    * Build the chord denoted by a Roman numeral in this key (including applied
@@ -670,7 +725,7 @@ var Key = class _Key {
    * @throws If the numeral is not valid.
    */
   roman(text) {
-    return new Chord(_chunkCAN76NCUcjs.romanToChord.call(void 0, text, this.#scale), this);
+    return new Chord(_chunkKQN2ZYNDcjs.romanToChord.call(void 0, text, this.#scale), this);
   }
   /**
    * Whether a pitch belongs to the scale.
@@ -679,7 +734,7 @@ var Key = class _Key {
    * @returns True if the pitch class is a scale tone.
    */
   contains(x) {
-    return _chunkFNDWXRRIcjs.isScaleTone.call(void 0, typeof x === "number" ? x : x.pitchClass, this.#scale);
+    return _chunkBSLTLGM3cjs.isScaleTone.call(void 0, typeof x === "number" ? x : x.pitchClass, this.#scale);
   }
   /**
    * The plain key data, for JSON serialization.
@@ -696,12 +751,14 @@ var Key = class _Key {
   }
   /**
    * The key's tonic and mode, so a template literal or a log line reads as the
-   * key. Only the major/minor distinction is named, since a mask does not carry
-   * a scale name.
+   * key. Detected harmonic and melodic minor keys retain their scale form.
    *
    * @returns The name, e.g. `'C major'` or `'A minor'`.
    */
   toString() {
+    if (this.#variant === "harmonic" || this.#variant === "melodic") {
+      return `${this.#tonic.name} ${this.#variant} minor`;
+    }
     return `${this.#tonic.name} ${this.isMinor ? "minor" : "major"}`;
   }
 };
@@ -717,9 +774,13 @@ var Progression = class _Progression {
    * @param key Optional key context for analysis methods.
    */
   constructor(chords, key) {
-    this.#chords = Object.freeze([...chords]);
+    this.#chords = Object.freeze(_Progression.#attachKey(chords, key));
     this.#key = key;
   }
+  /** Attach a progression key to chord members that do not already carry one. */
+  static #attachKey(chords, key) {
+    return key === void 0 ? [...chords] : chords.map((chord) => chord.key === void 0 ? chord.withKey(key) : chord);
+  }
   /**
    * Build a progression from the {@link ChordSpan} records the generators
    * return, keeping their order.
@@ -740,11 +801,10 @@ var Progression = class _Progression {
    * ```
    */
   static fromSpans(spans, key) {
-    const chords = spans.map((span) => {
-      const chord = Chord.from(_chunkFNDWXRRIcjs.makeChord.call(void 0, span.rootPc, span.quality, span.bassPc));
-      return key === void 0 ? chord : chord.withKey(key);
-    });
-    return key === void 0 ? new _Progression(chords) : new _Progression(chords, key);
+    const chords = spans.map(
+      (span) => Chord.from(_chunkBSLTLGM3cjs.makeChord.call(void 0, span.rootPc, span.quality, span.bassPc))
+    );
+    return new _Progression(chords, key);
   }
   /**
    * Rebuild a progression from its {@link Progression.toJSON} output.
@@ -831,21 +891,23 @@ var Progression = class _Progression {
    * @throws If any chord admits no voicing within the given ranges.
    */
   voice(opts) {
-    return _chunkLW53AHQUcjs.voiceProgression.call(void 0, 
+    const key = _nullishCoalesce(_optionalChain([opts, 'optionalAccess', _2 => _2.key]), () => ( _optionalChain([this, 'access', _3 => _3.#key, 'optionalAccess', _4 => _4.scale])));
+    return _chunkOL3IHHSJcjs.voiceProgression.call(void 0, 
       this.#chords.map((chord) => chord.data),
-      opts
+      key === void 0 ? opts : { ...opts, key }
     );
   }
   /**
    * The Roman numeral of each chord in a key.
    *
    * @param key Key to analyze in; falls back to the carried context.
+   * @param opts Applied-numeral rendering options.
    * @returns One numeral per chord.
    * @throws If no key is given and none is carried.
    */
-  roman(key) {
+  roman(key, opts) {
     const resolved = this.#resolveKey(key);
-    return this.#chords.map((chord) => chord.roman(resolved));
+    return this.#chords.map((chord) => chord.roman(resolved, opts));
   }
   /**
    * The harmonic function of each chord in a key.
@@ -865,17 +927,26 @@ var Progression = class _Progression {
    * progression has fewer than two chords.
    *
    * @param key Key to analyze in; falls back to the carried context.
+   * @param opts Applied-numeral rendering options.
    * @returns Per-chord analyses and the closing cadence.
    * @throws If no key is given and none is carried.
    */
-  analyze(key) {
+  analyze(key, opts) {
     const resolved = this.#resolveKey(key);
-    const chords = this.#chords.map((chord) => chord.analyze(resolved));
+    const chords = this.#chords.map((chord) => chord.analyze(resolved, opts));
     const from = this.#chords[this.#chords.length - 2];
     const to = this.#chords[this.#chords.length - 1];
-    const cadence = from !== void 0 && to !== void 0 ? _chunkCAN76NCUcjs.detectCadence.call(void 0, from.data, to.data, resolved.scale) : null;
+    const cadence = from !== void 0 && to !== void 0 ? _chunkKQN2ZYNDcjs.detectCadence.call(void 0, from.data, to.data, resolved.scale) : null;
     return { chords, cadence };
   }
+  /**
+   * Choose one compatible scale for every chord, favoring smooth changes.
+   *
+   * @returns One scale choice per chord in this progression.
+   */
+  scales() {
+    return _chunkOL3IHHSJcjs.scalesForChanges.call(void 0, this.#chords.map((chord) => chord.data));
+  }
   /**
    * The plain progression data, for JSON serialization.
    *
@@ -900,12 +971,12 @@ var Progression = class _Progression {
    * ```
    */
   transpose(semitones) {
-    const key = _optionalChain([this, 'access', _2 => _2.#key, 'optionalAccess', _3 => _3.transpose, 'call', _4 => _4(semitones)]);
+    const key = _optionalChain([this, 'access', _5 => _5.#key, 'optionalAccess', _6 => _6.transpose, 'call', _7 => _7(semitones)]);
     const chords = this.#chords.map((chord) => {
       const moved = chord.transpose(semitones);
       return key !== void 0 && moved.key === void 0 ? moved.withKey(key) : moved;
     });
-    return key === void 0 ? new _Progression(chords) : new _Progression(chords, key);
+    return new _Progression(chords, key);
   }
   /**
    * The chord symbols separated by spaces, so a template literal or a log line
@@ -916,17 +987,25 @@ var Progression = class _Progression {
   toString() {
     return this.#chords.map((chord) => chord.symbol()).join(" ");
   }
+  /**
+   * The plain progression data, for JSON serialization.
+   *
+   * Private class fields do not serialize, so this preserves both the chord
+   * data and any carried key in `JSON.stringify(progression)`.
+   *
+   * @returns The chord data sequence and the carried key, if any.
+   */
   toJSON() {
     return {
-      chords: this.#chords.map((chord) => chord.data),
-      key: _optionalChain([this, 'access', _5 => _5.#key, 'optionalAccess', _6 => _6.toJSON, 'call', _7 => _7()])
+      chords: this.#chords.map((chord) => chord.toJSON()),
+      key: _optionalChain([this, 'access', _8 => _8.#key, 'optionalAccess', _9 => _9.toJSON, 'call', _10 => _10()])
     };
   }
   /** Resolve the key for an analysis method: explicit first, then carried. */
   #resolveKey(key) {
     const resolved = _nullishCoalesce(key, () => ( this.#key));
     if (resolved === void 0) {
-      throw new (0, _chunk7MGZ7D62cjs.InvalidInputError)(
+      throw new (0, _chunkPI3UXRWKcjs.InvalidInputError)(
         "progression has no key context; pass a Key or attach one with withKey()"
       );
     }
@@ -936,7 +1015,14 @@ var Progression = class _Progression {
 
 // src/model/chord.ts
 function hintMatches(hint, pc) {
-  return hint !== void 0 && pc !== void 0 && _chunk7MGZ7D62cjs.pitchClassOf.call(void 0, _chunk7MGZ7D62cjs.noteToPitchClass.call(void 0, hint)) === _chunk7MGZ7D62cjs.pitchClassOf.call(void 0, pc);
+  return hint !== void 0 && pc !== void 0 && _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, _chunkPI3UXRWKcjs.noteToPitchClass.call(void 0, hint)) === _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, pc);
+}
+function transposeHint(hint, semitones) {
+  if (hint === void 0) {
+    return void 0;
+  }
+  const moved = _chunkPI3UXRWKcjs.transposeNote.call(void 0, hint, semitones);
+  return { letter: moved.letter, alter: moved.alter };
 }
 function copyChord(data) {
   const copy = {
@@ -962,8 +1048,8 @@ function deriveBassSpelling(chord, key) {
   }
   const root = chord.rootSpelling;
   if (root !== void 0) {
-    const index = chord.intervals.findIndex((i) => _chunk7MGZ7D62cjs.pitchClassOf.call(void 0, chord.rootPc + i) === bassPc);
-    const tone = index >= 0 ? _chunkLW53AHQUcjs.spellChordFromRoot.call(void 0, chord, root)[index] : void 0;
+    const index = chord.intervals.findIndex((i) => _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, chord.rootPc + i) === bassPc);
+    const tone = index >= 0 ? _chunkOL3IHHSJcjs.spellChordFromRoot.call(void 0, chord, root)[index] : void 0;
     if (tone !== void 0) {
       return { letter: tone.letter, alter: tone.alter };
     }
@@ -971,7 +1057,7 @@ function deriveBassSpelling(chord, key) {
   if (key === void 0) {
     return void 0;
   }
-  const spelled = _chunkLW53AHQUcjs.spellPitchClass.call(void 0, bassPc, key.tonic.data, key.scale);
+  const spelled = _chunkOL3IHHSJcjs.spellPitchClass.call(void 0, bassPc, key.tonic.data, key.scale);
   return { letter: spelled.letter, alter: spelled.alter };
 }
 var Chord = class _Chord {
@@ -996,10 +1082,13 @@ var Chord = class _Chord {
    * first key's letters forever. A spelling the caller supplied always wins.
    */
   get #data() {
+    return this.#dataWithKey(this.#key);
+  }
+  /** Build a read view whose missing spellings are derived from `key`. */
+  #dataWithKey(key) {
     const out = copyChord(this.#given);
-    const key = this.#key;
     if (out.rootSpelling === void 0 && key !== void 0) {
-      out.rootSpelling = _chunkLW53AHQUcjs.spellPitchClass.call(void 0, out.rootPc, key.tonic.data, key.scale);
+      out.rootSpelling = _chunkOL3IHHSJcjs.spellPitchClass.call(void 0, out.rootPc, key.tonic.data, key.scale);
     }
     if (out.bassSpelling === void 0) {
       const bass = deriveBassSpelling(out, key);
@@ -1022,7 +1111,7 @@ var Chord = class _Chord {
     const bassNote = typeof bass === "string" ? Note.of(bass) : void 0;
     const bassPc = bassNote !== void 0 ? bassNote.pitchClass : bass;
     const rootNote = typeof root === "string" ? Note.of(root) : void 0;
-    const data = _chunkFNDWXRRIcjs.makeChord.call(void 0, 
+    const data = _chunkBSLTLGM3cjs.makeChord.call(void 0, 
       rootNote !== void 0 ? rootNote.pitchClass : root,
       quality,
       bassPc
@@ -1074,7 +1163,7 @@ var Chord = class _Chord {
    * @throws If the root or quality is not recognized.
    */
   static parse(symbol) {
-    return new _Chord(_chunkLW53AHQUcjs.parseChordSymbol.call(void 0, symbol));
+    return new _Chord(_chunkOL3IHHSJcjs.parseChordSymbol.call(void 0, symbol));
   }
   /**
    * Identify the chords matching a set of pitches, best interpretation first.
@@ -1084,8 +1173,8 @@ var Chord = class _Chord {
    * @returns Ranked chord interpretations (may be empty).
    */
   static detect(pitches, opts) {
-    return _chunkCAN76NCUcjs.detectChord.call(void 0, pitches, opts).map(
-      (match) => new _Chord(_chunkFNDWXRRIcjs.makeChord.call(void 0, match.rootPc, match.quality, match.bassPc))
+    return _chunkKQN2ZYNDcjs.detectChord.call(void 0, pitches, opts).map(
+      (match) => new _Chord(_chunkBSLTLGM3cjs.makeChord.call(void 0, match.rootPc, match.quality, match.bassPc))
     );
   }
   /**
@@ -1107,8 +1196,8 @@ var Chord = class _Chord {
    * ```
    */
   static detectMatches(pitches, opts) {
-    return _chunkCAN76NCUcjs.detectChord.call(void 0, pitches, opts).map((match) => ({
-      chord: new _Chord(_chunkFNDWXRRIcjs.makeChord.call(void 0, match.rootPc, match.quality, match.bassPc)),
+    return _chunkKQN2ZYNDcjs.detectChord.call(void 0, pitches, opts).map((match) => ({
+      chord: new _Chord(_chunkBSLTLGM3cjs.makeChord.call(void 0, match.rootPc, match.quality, match.bassPc)),
       match
     }));
   }
@@ -1120,7 +1209,7 @@ var Chord = class _Chord {
    * @returns The top-ranked chord, or null when nothing matches.
    */
   static detectBest(pitches, opts) {
-    const best = _chunkCAN76NCUcjs.detectChordBest.call(void 0, pitches, opts);
+    const best = _chunkKQN2ZYNDcjs.detectChordBest.call(void 0, pitches, opts);
     return best === null ? null : new _Chord(best);
   }
   /** The root pitch class (0..11). */
@@ -1171,17 +1260,18 @@ var Chord = class _Chord {
    * @returns Pitch classes ascending in [0, 11].
    */
   pitchClasses() {
-    return _chunkFNDWXRRIcjs.chordPitchClasses.call(void 0, this.#data);
+    return _chunkBSLTLGM3cjs.chordPitchClasses.call(void 0, this.#data);
   }
   /**
    * The chord's Roman numeral in a key.
    *
    * @param key Key to analyze in; falls back to the carried context.
+   * @param opts Applied-numeral rendering options.
    * @returns The Roman numeral string.
    * @throws If no key is given and none is carried.
    */
-  roman(key) {
-    return _chunkCAN76NCUcjs.chordToRoman.call(void 0, this.#data, this.#resolveKey(key).scale);
+  roman(key, opts) {
+    return _chunkKQN2ZYNDcjs.chordToRoman.call(void 0, this.#data, this.#resolveKey(key).scale, opts);
   }
   /**
    * The chord's harmonic function (tonic / subdominant / dominant) in a key.
@@ -1191,17 +1281,18 @@ var Chord = class _Chord {
    * @throws If no key is given and none is carried.
    */
   function(key) {
-    return _chunkCAN76NCUcjs.functionOf.call(void 0, this.#data, this.#resolveKey(key).scale);
+    return _chunkKQN2ZYNDcjs.functionOf.call(void 0, this.#data, this.#resolveKey(key).scale);
   }
   /**
    * Full functional analysis: function, borrowing, and Roman numeral.
    *
    * @param key Key to analyze in; falls back to the carried context.
+   * @param opts Applied-numeral rendering options.
    * @returns The chord analysis.
    * @throws If no key is given and none is carried.
    */
-  analyze(key) {
-    return _chunkCAN76NCUcjs.analyzeChord.call(void 0, this.#data, this.#resolveKey(key).scale);
+  analyze(key, opts) {
+    return _chunkKQN2ZYNDcjs.analyzeChord.call(void 0, this.#data, this.#resolveKey(key).scale, opts);
   }
   /**
    * Whether the chord is borrowed from the parallel mode (modal interchange).
@@ -1211,7 +1302,7 @@ var Chord = class _Chord {
    * @throws If no key is given and none is carried.
    */
   isBorrowed(key) {
-    return _chunkCAN76NCUcjs.isBorrowedChord.call(void 0, this.#data, this.#resolveKey(key).scale);
+    return _chunkKQN2ZYNDcjs.isBorrowedChord.call(void 0, this.#data, this.#resolveKey(key).scale);
   }
   /**
    * The origin of a non-diatonic chord (parallel mode or Neapolitan), or null.
@@ -1221,7 +1312,7 @@ var Chord = class _Chord {
    * @throws If no key is given and none is carried.
    */
   borrowedSource(key) {
-    return _chunkCAN76NCUcjs.borrowedSource.call(void 0, this.#data, this.#resolveKey(key).scale);
+    return _chunkKQN2ZYNDcjs.borrowedSource.call(void 0, this.#data, this.#resolveKey(key).scale);
   }
   /**
    * The chord rendered as a lead-sheet symbol (e.g. `'Cmaj7'`, `'F#m7'`, `'C/G'`).
@@ -1230,7 +1321,7 @@ var Chord = class _Chord {
    * @returns The chord symbol.
    */
   symbol(opts) {
-    return _chunkLW53AHQUcjs.formatChordSymbol.call(void 0, this.#data, opts);
+    return _chunkOL3IHHSJcjs.formatChordSymbol.call(void 0, this.#data, opts);
   }
   /**
    * Realize the chord as one MIDI pitch per voice, ascending.
@@ -1243,8 +1334,8 @@ var Chord = class _Chord {
    * @throws If no voicing fits the given ranges.
    */
   voice(opts) {
-    const key = _nullishCoalesce(_optionalChain([opts, 'optionalAccess', _8 => _8.key]), () => ( _optionalChain([this, 'access', _9 => _9.#key, 'optionalAccess', _10 => _10.scale])));
-    return _chunkLW53AHQUcjs.voiceChord.call(void 0, this.#data, key === void 0 ? opts : { ...opts, key });
+    const key = _nullishCoalesce(_optionalChain([opts, 'optionalAccess', _11 => _11.key]), () => ( _optionalChain([this, 'access', _12 => _12.#key, 'optionalAccess', _13 => _13.scale])));
+    return _chunkOL3IHHSJcjs.voiceChord.call(void 0, this.#data, key === void 0 ? opts : { ...opts, key });
   }
   /**
    * Realize the chord as a single styled voicing (`close`, `drop2`, `drop3`,
@@ -1254,7 +1345,7 @@ var Chord = class _Chord {
    * @returns MIDI pitches, ascending.
    */
   styledVoicing(opts) {
-    return _chunkLW53AHQUcjs.voiceChordStyled.call(void 0, this.#data, opts);
+    return _chunkOL3IHHSJcjs.voiceChordStyled.call(void 0, this.#data, opts);
   }
   /**
    * The negative-harmony mirror of the chord about the key's tonic–dominant
@@ -1267,7 +1358,7 @@ var Chord = class _Chord {
    */
   negativeHarmony(key) {
     const resolved = this.#resolveKey(key);
-    return new _Chord(_chunkZEJR4TKLcjs.negativeHarmonyMirror.call(void 0, this.#data, resolved.scale), _nullishCoalesce(key, () => ( this.#key)));
+    return new _Chord(_chunk357ZDPVUcjs.negativeHarmonyMirror.call(void 0, this.#data, resolved.scale), _nullishCoalesce(key, () => ( this.#key)));
   }
   /**
    * The n-th inversion: a copy whose bass is the chord tone `n` steps above the
@@ -1286,14 +1377,14 @@ var Chord = class _Chord {
     const intervals = data.intervals;
     const length = intervals.length;
     if (length === 0) {
-      throw new (0, _chunk7MGZ7D62cjs.InvalidInputError)("cannot invert a chord with no intervals");
+      throw new (0, _chunkPI3UXRWKcjs.InvalidInputError)("cannot invert a chord with no intervals");
     }
     const index = (n % length + length) % length;
     delete data.bassSpelling;
     if (index === 0) {
       delete data.bassPc;
     } else {
-      data.bassPc = _chunk7MGZ7D62cjs.pitchClassOf.call(void 0, data.rootPc + (_nullishCoalesce(intervals[index], () => ( 0))));
+      data.bassPc = _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, data.rootPc + (_nullishCoalesce(intervals[index], () => ( 0))));
     }
     return new _Chord(data, this.#key);
   }
@@ -1314,8 +1405,16 @@ var Chord = class _Chord {
    * ```
    */
   transpose(semitones) {
-    const moved = _chunkFNDWXRRIcjs.transposeChord.call(void 0, this.#given, semitones);
-    return new _Chord(moved, _optionalChain([this, 'access', _11 => _11.#key, 'optionalAccess', _12 => _12.transpose, 'call', _13 => _13(semitones)]));
+    const moved = _chunkBSLTLGM3cjs.transposeChord.call(void 0, this.#given, semitones);
+    const rootSpelling = transposeHint(this.#given.rootSpelling, semitones);
+    const bassSpelling = transposeHint(this.#given.bassSpelling, semitones);
+    if (rootSpelling !== void 0) {
+      moved.rootSpelling = rootSpelling;
+    }
+    if (bassSpelling !== void 0) {
+      moved.bassSpelling = bassSpelling;
+    }
+    return new _Chord(moved, _optionalChain([this, 'access', _14 => _14.#key, 'optionalAccess', _15 => _15.transpose, 'call', _16 => _16(semitones)]));
   }
   /**
    * The named scales that fit over this chord, best fit first, rooted on the
@@ -1324,7 +1423,7 @@ var Chord = class _Chord {
    * @returns The matching scales.
    */
   scales() {
-    return _chunkLW53AHQUcjs.chordScales.call(void 0, this.#data);
+    return _chunkOL3IHHSJcjs.chordScales.call(void 0, this.#data);
   }
   /**
    * The available tensions (usable non-chord, non-avoid scale tones) of a
@@ -1335,7 +1434,7 @@ var Chord = class _Chord {
    * @throws If `scaleName` is not a built-in scale.
    */
   tensions(scaleName) {
-    return _chunkLW53AHQUcjs.availableTensions.call(void 0, this.#data, scaleName);
+    return _chunkOL3IHHSJcjs.availableTensions.call(void 0, this.#data, scaleName);
   }
   /**
    * The avoid notes (scale tones a semitone above a chord tone) of a scale
@@ -1346,7 +1445,7 @@ var Chord = class _Chord {
    * @throws If `scaleName` is not a built-in scale.
    */
   avoidNotes(scaleName) {
-    return _chunkLW53AHQUcjs.avoidNotes.call(void 0, this.#data, scaleName);
+    return _chunkOL3IHHSJcjs.avoidNotes.call(void 0, this.#data, scaleName);
   }
   /**
    * Spell the chord tones with letter names, root first, in the key's spelling.
@@ -1368,23 +1467,23 @@ var Chord = class _Chord {
    *   spelling of its own.
    */
   spell(key) {
-    const data = this.#data;
     const resolved = _nullishCoalesce(key, () => ( this.#key));
+    const data = this.#dataWithKey(resolved);
     let tones;
     if (resolved === void 0) {
       const root = data.rootSpelling;
       if (root === void 0) {
-        throw new (0, _chunk7MGZ7D62cjs.InvalidInputError)(
+        throw new (0, _chunkPI3UXRWKcjs.InvalidInputError)(
           "chord has no key context and no root spelling; pass a Key, attach one with withKey(), or build the chord from a symbol"
         );
       }
-      tones = _chunkLW53AHQUcjs.spellChordFromRoot.call(void 0, data, root);
+      tones = _chunkOL3IHHSJcjs.spellChordFromRoot.call(void 0, data, root);
     } else {
-      tones = _chunkLW53AHQUcjs.spellChord.call(void 0, data, resolved.tonic.data, resolved.scale);
+      tones = _chunkOL3IHHSJcjs.spellChord.call(void 0, data, resolved.tonic.data, resolved.scale);
     }
     const bassPc = data.bassPc;
     const bass = data.bassSpelling;
-    if (bassPc !== void 0 && bass !== void 0 && !tones.some((tone) => _chunk7MGZ7D62cjs.pitchClassOf.call(void 0, _chunk7MGZ7D62cjs.noteToPitchClass.call(void 0, tone)) === _chunk7MGZ7D62cjs.pitchClassOf.call(void 0, bassPc))) {
+    if (bassPc !== void 0 && bass !== void 0 && !tones.some((tone) => _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, _chunkPI3UXRWKcjs.noteToPitchClass.call(void 0, tone)) === _chunkPI3UXRWKcjs.pitchClassOf.call(void 0, bassPc))) {
       tones = [...tones, { letter: bass.letter, alter: bass.alter }];
     }
     return tones.map((note) => new Note(note));
@@ -1417,7 +1516,7 @@ var Chord = class _Chord {
    * @returns A copy of the underlying plain chord object.
    */
   toJSON() {
-    return this.data;
+    return copyChord(this.#given);
   }
   /**
    * The chord symbol, so a template literal or a log line reads as the chord.
@@ -1431,7 +1530,7 @@ var Chord = class _Chord {
   #resolveKey(key) {
     const resolved = _nullishCoalesce(key, () => ( this.#key));
     if (resolved === void 0) {
-      throw new (0, _chunk7MGZ7D62cjs.InvalidInputError)(
+      throw new (0, _chunkPI3UXRWKcjs.InvalidInputError)(
         "chord has no key context; pass a Key or attach one with withKey()"
       );
     }
@@ -1446,4 +1545,4 @@ var Chord = class _Chord {
 
 
 exports.Interval = Interval; exports.Note = Note; exports.Key = Key; exports.Progression = Progression; exports.Chord = Chord;
-//# sourceMappingURL=chunk-NVE34YGZ.cjs.map
+//# sourceMappingURL=chunk-WTAN4ACG.cjs.map