@libraz/libcantus 0.9.3 → 0.9.5

package/dist/model/index.d.ts

@@ -1,9 +1,122 @@
-import { D as DetectChordOptions } from '../index-JnF4v9bx.js';
-import { H as HarmonicFunction, a as ChordAnalysis, C as Cadence, B as BorrowedSource } from '../function-DVH4Eusr.js';
-import { a as ChordQuality, C as Chord$1 } from '../index-Bt4tOUD9.js';
-import { d as VoicingOptions, c as StyledVoicingOptions, C as ChordScaleMatch } from '../styled-DZ7GjShb.js';
-import { N as Note$1, S as SpelledInterval } from '../index-CGMZNCx6.js';
-import { K as KeyScale } from '../types-MGP29r3t.js';
+import { b as KeyVariant, a as DetectKeyOptions, K as KeyMatch, D as DetectChordOptions, C as ChordMatch } from '../index-CAN7v-kw.js';
+import { b as ChordToRomanOptions, H as HarmonicFunction, a as ChordAnalysis, C as Cadence, B as BorrowedSource } from '../function-DTCt675z.js';
+import { I as IntervalQualityLabel, S as SpelledInterval, N as Note$1 } from '../index-tR9jTn26.js';
+import { K as KeyScale } from '../types-BN6_Q9Kl.js';
+import { a as ChordQuality, c as ChordSpan, C as Chord$1 } from '../index-COw1Ky9g.js';
+export { P as PitchSpelling } from '../index-COw1Ky9g.js';
+import { p as ScaleNameInput, r as VoicingOptions, n as ScaleChoice, q as StyledVoicingOptions, a as ChordScaleMatch } from '../styled-Bl0ZK28h.js';
+export { o as ScaleName, V as VoiceRange, s as VoicingStyle } from '../styled-Bl0ZK28h.js';
+
+/**
+ * An immutable spelled interval value: a diatonic number, a quality label, and
+ * a signed semitone span. A thin convenience wrapper over the pitch module's
+ * plain interval result.
+ *
+ * @category Class API
+ * @example
+ * ```ts
+ * import { Interval, Note } from '@libraz/libcantus';
+ * Interval.between(Note.of('C4'), Note.of('G4')).name; // 'P5'
+ * ```
+ */
+declare class Interval {
+    #private;
+    private constructor();
+    /**
+     * The spelled interval between two notes.
+     *
+     * @param a The first note.
+     * @param b The second note.
+     * @returns The interval from `a` to `b`.
+     */
+    static between(a: Note, b: Note): Interval;
+    /**
+     * Build an interval from explicit components.
+     *
+     * @param numberValue Diatonic size: 1 = unison, 2 = second, ... 8 = octave.
+     * @param quality Quality label: `'P'`, `'M'`, `'m'`, or repeated `'A'`/`'d'`.
+     * @param semitones Signed semitone span; its magnitude must be the span the
+     *   number and quality describe.
+     * @returns The interval.
+     * @throws If the three components do not describe the same interval — a
+     *   `P5` spanning 8 semitones is not a value any other method can produce.
+     */
+    static of(numberValue: number, quality: IntervalQualityLabel, semitones: number): Interval;
+    /**
+     * Wrap a plain spelled interval, as returned by the pitch module.
+     *
+     * @param data The plain interval.
+     * @returns The wrapped interval.
+     */
+    static fromData(data: SpelledInterval): Interval;
+    /**
+     * Rebuild an interval from its {@link Interval.toJSON} output.
+     *
+     * @param data The serialized interval.
+     * @returns The wrapped interval.
+     */
+    static fromJSON(data: SpelledInterval): Interval;
+    /**
+     * Parse an interval name such as `'P5'`, `'m3'`, or `'AA4'`.
+     *
+     * @param name The interval name.
+     * @returns The ascending interval of that name.
+     * @throws If the name is not a quality label followed by a diatonic number.
+     */
+    static parse(name: string): Interval;
+    /** Diatonic size: 1 = unison, 2 = second, ... 8 = octave, and beyond. */
+    get number(): number;
+    /** Quality label: `'P'`, `'M'`, `'m'`, or repeated `'A'`/`'d'`. */
+    get quality(): IntervalQualityLabel;
+    /** Signed semitone span. */
+    get semitones(): number;
+    /** A readable label composed of quality and number, e.g. `'P5'` or `'M3'`. */
+    get name(): string;
+    /**
+     * The interval's inversion: the complement that completes the octave.
+     *
+     * A compound interval is reduced to its simple form first, and the result is
+     * always ascending — an inversion answers "what is left of the octave",
+     * which has no direction of its own.
+     *
+     * @returns The inverted interval, e.g. `M3` becomes `m6`.
+     */
+    invert(): Interval;
+    /**
+     * Whether the interval is consonant.
+     *
+     * @param twoVoice When true, the perfect fourth counts as a dissonance,
+     *   matching two-voice counterpoint.
+     * @returns True if the interval is consonant in that context.
+     */
+    isConsonant(twoVoice?: boolean): boolean;
+    /**
+     * Whether another interval is spelled identically.
+     *
+     * Enharmonic equivalents are not equal: an augmented second and a minor
+     * third span the same distance but are different intervals.
+     *
+     * @param other The interval to compare with.
+     * @returns True when number, quality, and span all match.
+     */
+    equals(other: Interval): boolean;
+    /**
+     * The plain interval data, for JSON serialization.
+     *
+     * Private class fields do not serialize, so an explicit `toJSON` keeps
+     * `JSON.stringify(interval)` from collapsing to `{}`.
+     *
+     * @returns The diatonic number, quality, and semitone span.
+     */
+    toJSON(): SpelledInterval;
+    /**
+     * The interval's name, so a template literal or a log line reads as the
+     * interval.
+     *
+     * @returns The name, e.g. `'M3'`.
+     */
+    toString(): string;
+}
 
 /**
  * An immutable spelled note: a diatonic letter plus a chromatic alteration and
@@ -23,6 +136,7 @@ declare class Note {
      * Wrap a plain note object.
      *
      * @param data The spelled note; it is copied, never retained or mutated.
+     * @throws If `letter` is not an integer in 0..6.
      */
     constructor(data: Note$1);
     /**
@@ -46,6 +160,7 @@ declare class Note {
      *
      * @param data The plain note.
      * @returns The wrapped note.
+     * @throws If `letter` is not an integer in 0..6.
      */
     static fromData(data: Note$1): Note;
     /** The note rendered as scientific pitch notation, e.g. `'G4'` or `'Bb'`. */
@@ -67,24 +182,59 @@ declare class Note {
     /** A copy of the underlying plain note object. */
     get data(): Note$1;
     /**
-     * Transpose by a signed number of semitones.
+     * Transpose by a signed number of semitones, keeping the spelling.
      *
-     * When the note carries an octave the transposition happens in MIDI space and
-     * the result is spelled with a sharp preference. An octave-less note stays
+     * The letter moves by the diatonic distance of the conventional interval for
+     * that many semitones, so `Ab4` up a major second is `Bb4` rather than `A#4`
+     * and a flat key stays on the flat side. An octave-less note stays
      * octave-less: only its pitch class is moved. Transposing by zero is the
      * identity: the original spelling is preserved (no enharmonic respelling).
      *
      * @param semitones The signed semitone offset.
+     * @param opts `spelling` forces the result onto the sharp or flat side
+     *   instead of following this note's letter.
      * @returns The transposed note.
+     * @example
+     * ```ts
+     * import { Note } from '@libraz/libcantus';
+     * Note.of('Ab4').transpose(2).name; // 'Bb4'
+     * Note.of('Ab4').transpose(2, { spelling: 'sharp' }).name; // 'A#4'
+     * ```
      */
-    transpose(semitones: number): Note;
+    transpose(semitones: number, opts?: {
+        spelling?: 'sharp' | 'flat';
+    }): Note;
     /**
      * The spelled interval from this note to another.
      *
      * @param other The second note.
-     * @returns The diatonic number, quality, and semitone span.
+     * @returns The interval, which {@link Interval.toJSON} unwraps to plain data.
      */
-    intervalTo(other: Note): SpelledInterval;
+    intervalTo(other: Note): Interval;
+    /**
+     * Transpose by a spelled interval, keeping the spelling the interval names.
+     *
+     * Unlike {@link Note.transpose}, which picks a letter from the semitone
+     * count, the interval's diatonic number decides the letter: C up an
+     * augmented second is D#, not Eb.
+     *
+     * @param interval The interval to apply; a descending interval moves down.
+     * @returns The transposed note.
+     * @example
+     * ```ts
+     * import { Interval, Note } from '@libraz/libcantus';
+     * Note.of('C4').transposeBy(Interval.parse('A2')).name; // 'D#4'
+     * ```
+     */
+    transposeBy(interval: Interval): Note;
+    /**
+     * Rebuild a note from its {@link Note.toJSON} output.
+     *
+     * @param data The serialized note.
+     * @returns The wrapped note.
+     * @throws If `letter` is not an integer in 0..6.
+     */
+    static fromJSON(data: Note$1): Note;
     /**
      * Whether another note has the same letter, alteration, and octave.
      *
@@ -101,8 +251,18 @@ declare class Note {
      * @returns A copy of the underlying plain note object.
      */
     toJSON(): Note$1;
+    /**
+     * The note's name, so a template literal or a log line reads as the note.
+     *
+     * @returns The spelled name, e.g. `'Bb3'`.
+     */
+    toString(): string;
 }
 
+/** A detected key paired with the score and scale form that produced it. */
+type DetectedKeyMatch = Omit<KeyMatch, 'key'> & {
+    key: Key;
+};
 /**
  * An immutable key/scale: a `KeyScale` (root pitch class plus mode mask) paired
  * with a spelled tonic that anchors letter-name spelling. Acts as the factory
@@ -122,8 +282,9 @@ declare class Key {
      *
      * @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: KeyScale, tonic: Note);
+    constructor(scale: KeyScale, tonic: Note, variant?: KeyVariant);
     /**
      * A major key.
      *
@@ -146,20 +307,79 @@ declare class Key {
      * A key on a named scale (e.g. `'dorian'`, `'harmonicMinor'`).
      *
      * @param name The scale name, a key of the scale module's named-scale table.
-     * @param root Tonic as a note name or a pitch class.
+     * @param root Tonic as a note name or a pitch class; a numeric root is
+     *   spelled with whichever accidental side yields the fewest accidentals
+     *   across the scale, exactly as {@link Key.major} does.
      * @returns The key.
      * @throws If the name is not a known scale.
      */
-    static named(name: string, root: string | number): Key;
+    static named(name: ScaleNameInput, root: string | number): Key;
     /**
      * Wrap an existing `KeyScale`, synthesizing a spelled tonic when none is
-     * given (flat-preferred for minor-third scales, sharp-preferred otherwise).
+     * given.
+     *
+     * The synthesized tonic is chosen the same way as for a numeric root
+     * elsewhere: whichever accidental side spells the scale with the fewest
+     * accidentals. This is what keeps `Key.of(detectKey(...).scale)` from handing
+     * every downstream chord a double-sharp spelling.
      *
      * @param scale The key/scale to wrap.
-     * @param tonic Optional spelled tonic.
+     * @param tonic Optional spelled tonic; must spell the scale's root pitch class.
      * @returns The key.
+     * @throws If the given tonic is not the scale's root pitch class.
      */
     static of(scale: KeyScale, tonic?: Note): Key;
+    /**
+     * Rebuild a key from its {@link Key.toJSON} output.
+     *
+     * @param data The serialized key and tonic.
+     * @returns The key.
+     */
+    static fromJSON(data: {
+        scale: KeyScale;
+        tonic: Note$1;
+    }): Key;
+    /**
+     * Identify the keys a set of pitches fits, best interpretation first.
+     *
+     * The counterpart of {@link Chord.detect}.
+     *
+     * @param pitches MIDI pitches or bare pitch classes.
+     * @param opts How to weigh the input; see {@link DetectKeyOptions}.
+     * @returns Ranked keys (may be empty).
+     */
+    static detect(pitches: readonly number[], opts?: DetectKeyOptions): 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: readonly number[], opts?: DetectKeyOptions): DetectedKeyMatch[];
+    /**
+     * The single best key interpretation of a pitch set.
+     *
+     * @param pitches MIDI pitches or bare pitch classes.
+     * @param opts How to weigh the input; see {@link DetectKeyOptions}.
+     * @returns The top-ranked key, or null when nothing matches.
+     * @example
+     * ```ts
+     * import { Key } from '@libraz/libcantus';
+     * Key.detectBest([0, 2, 4, 5, 7, 9, 11])?.toString(); // 'C major'
+     * ```
+     */
+    static detectBest(pitches: readonly number[], opts?: DetectKeyOptions): Key | null;
+    /**
+     * Whether another key has the same tonic pitch class and mode.
+     *
+     * The spelled tonic is not compared: C# major and Db major are the same key
+     * written two ways.
+     *
+     * @param other The key to compare.
+     * @returns True when tonic and mode mask both match.
+     */
+    equals(other: Key): boolean;
     /** A copy of the underlying plain `KeyScale`. */
     get scale(): KeyScale;
     /** The spelled tonic. */
@@ -168,12 +388,30 @@ declare class Key {
     get rootPc(): number;
     /** Whether the scale has a minor third and no major third. */
     get isMinor(): boolean;
+    /** The detected scale form, when this key came from key detection. */
+    get variant(): KeyVariant | undefined;
     /**
      * The scale's pitch classes in ascending scale-degree order (degree 0 first).
      *
      * @returns One pitch class per scale degree.
      */
     pitchClasses(): number[];
+    /**
+     * Transpose the key by a number of semitones.
+     *
+     * The mode mask is unchanged, so the scale keeps its shape; only the tonic
+     * moves. The new tonic is spelled the way that key is conventionally written
+     * — D major, not C## major.
+     *
+     * @param semitones The signed semitone offset.
+     * @returns The transposed key.
+     * @example
+     * ```ts
+     * import { Key } from '@libraz/libcantus';
+     * Key.major('C').transpose(2).toString(); // 'D major'
+     * ```
+     */
+    transpose(semitones: number): Key;
     /**
      * The spelled scale, one note per degree (e.g. C D E F G A B for C major).
      *
@@ -202,6 +440,10 @@ declare class Key {
      * @param degree 0-based scale degree of the chord root.
      * @param quality Optional chord quality.
      * @returns The chord, with this key attached.
+     * @throws Without a `quality`, if this key's scale is not heptatonic —
+     *   stacking thirds needs seven degrees, so the pentatonic, blues,
+     *   whole-tone, octatonic and chromatic scales have no diatonic triad. Pass
+     *   an explicit `quality` for those.
      */
     chord(degree: number, quality?: ChordQuality): Chord;
     /**
@@ -209,6 +451,8 @@ declare class Key {
      *
      * @param degree 0-based scale degree of the chord root.
      * @returns The triad, with this key attached.
+     * @throws If this key's scale is not heptatonic; stacking thirds needs seven
+     *   degrees. Use {@link Key.chord} with an explicit quality instead.
      */
     diatonicTriad(degree: number): Chord;
     /**
@@ -216,6 +460,8 @@ declare class Key {
      *
      * @param degree 0-based scale degree of the chord root.
      * @returns The seventh chord, with this key attached.
+     * @throws If this key's scale is not heptatonic; stacking thirds needs seven
+     *   degrees. Use {@link Key.chord} with an explicit quality instead.
      */
     diatonicSeventh(degree: number): Chord;
     /**
@@ -248,6 +494,13 @@ declare class Key {
         scale: KeyScale;
         tonic: Note$1;
     };
+    /**
+     * The key's tonic and mode, so a template literal or a log line reads as the
+     * key. Detected harmonic and melodic minor keys retain their scale form.
+     *
+     * @returns The name, e.g. `'C major'` or `'A minor'`.
+     */
+    toString(): string;
 }
 
 /**
@@ -272,12 +525,69 @@ declare class Progression {
      * @param key Optional key context for analysis methods.
      */
     constructor(chords: readonly Chord[], key?: Key);
-    /** A copy of the chord sequence. */
+    /**
+     * Build a progression from the {@link ChordSpan} records the generators
+     * return, keeping their order.
+     *
+     * The spans' `startBeat`, `degree`, and `secondaryDominant` are analysis
+     * annotations that a chord sequence does not carry; only the harmony crosses
+     * over. Keep the spans themselves if the timing matters.
+     *
+     * @param spans The chord spans, in order.
+     * @param key Optional key context for the analysis methods.
+     * @returns The progression.
+     * @example
+     * ```ts
+     * import { generateProgression, Key, Progression } from '@libraz/libcantus';
+     * const key = Key.major('C');
+     * const spans = generateProgression({ key: key.scale, style: 'dance', bars: 4 });
+     * Progression.fromSpans(spans, key).roman();
+     * ```
+     */
+    static fromSpans(spans: readonly ChordSpan[], key?: Key): Progression;
+    /**
+     * Rebuild a progression from its {@link Progression.toJSON} output.
+     *
+     * @param data The serialized chords and key.
+     * @returns The progression.
+     */
+    static fromJSON(data: {
+        chords: Chord$1[];
+        key?: {
+            scale: KeyScale;
+            tonic: Note$1;
+        } | undefined;
+    }): Progression;
+    /**
+     * The chord sequence.
+     *
+     * The array is the progression's own and is frozen rather than copied, so
+     * reading it in a loop stays linear.
+     */
     get chords(): readonly Chord[];
     /** The carried key context, if any. */
     get key(): Key | undefined;
     /** The number of chords. */
     get length(): number;
+    /**
+     * The chord at an index.
+     *
+     * @param index 0-based position; a negative index counts from the end.
+     * @returns The chord, or undefined when the index is out of range.
+     */
+    at(index: number): Chord | undefined;
+    /** Iterate the chords in order, so a progression works with `for...of`. */
+    [Symbol.iterator](): IterableIterator<Chord>;
+    /**
+     * Whether another progression holds the same chords in the same order.
+     *
+     * The key context is not compared: it is an analysis lens, not part of the
+     * harmony. Chord equality follows {@link Chord.equals}.
+     *
+     * @param other The progression to compare.
+     * @returns True when the chord sequences match.
+     */
+    equals(other: Progression): boolean;
     /**
      * A copy of this progression with a chord appended.
      *
@@ -304,10 +614,11 @@ declare class Progression {
      * 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?: Key): string[];
+    roman(key?: Key, opts?: ChordToRomanOptions): string[];
     /**
      * The harmonic function of each chord in a key.
      *
@@ -323,13 +634,20 @@ declare 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?: Key): {
+    analyze(key?: Key, opts?: ChordToRomanOptions): {
         chords: ChordAnalysis[];
         cadence: Cadence;
     };
+    /**
+     * Choose one compatible scale for every chord, favoring smooth changes.
+     *
+     * @returns One scale choice per chord in this progression.
+     */
+    scales(): ScaleChoice[];
     /**
      * The plain progression data, for JSON serialization.
      *
@@ -339,6 +657,36 @@ declare class Progression {
      *
      * @returns The chord data sequence and the carried key, if any.
      */
+    /**
+     * Transpose every chord by a number of semitones.
+     *
+     * A carried key moves with the chords, so the progression keeps its degrees
+     * and functions in the new key.
+     *
+     * @param semitones The signed semitone offset.
+     * @returns The transposed progression.
+     * @example
+     * ```ts
+     * import { Chord, Progression } from '@libraz/libcantus';
+     * new Progression([Chord.parse('C'), Chord.parse('G')]).transpose(2).toString(); // 'D A'
+     * ```
+     */
+    transpose(semitones: number): Progression;
+    /**
+     * The chord symbols separated by spaces, so a template literal or a log line
+     * reads as the progression.
+     *
+     * @returns The symbols in order, e.g. `'C Am F G'`.
+     */
+    toString(): string;
+    /**
+     * 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(): {
         chords: Chord$1[];
         key: {
@@ -375,10 +723,11 @@ declare class Chord {
      *
      * @param root Root as a note name (e.g. `'Eb'`) or a pitch class.
      * @param quality The chord quality.
-     * @param bass Optional slash-chord bass pitch class.
+     * @param bass Optional slash-chord bass, as a note name (e.g. `'Bb'`) or a
+     *   pitch class. A named bass keeps its own spelling.
      * @returns The chord (without key context).
      */
-    static of(root: string | number, quality: ChordQuality, bass?: number): Chord;
+    static of(root: string | number, quality: ChordQuality, bass?: string | number): Chord;
     /**
      * Wrap an existing plain chord object.
      *
@@ -386,6 +735,24 @@ declare class Chord {
      * @returns The wrapped chord (without key context).
      */
     static from(data: Chord$1): Chord;
+    /**
+     * Alias of {@link Chord.from}, matching the `fromData` factory on the other
+     * classes.
+     *
+     * @param data The plain chord.
+     * @returns The wrapped chord (without key context).
+     */
+    static fromData(data: Chord$1): Chord;
+    /**
+     * Rebuild a chord from its {@link Chord.toJSON} output.
+     *
+     * The key context is not serialized, so the result carries none; re-attach
+     * one with {@link Chord.withKey}.
+     *
+     * @param data The serialized chord.
+     * @returns The wrapped chord.
+     */
+    static fromJSON(data: Chord$1): Chord;
     /**
      * Parse a lead-sheet chord symbol (e.g. `'Cmaj7'`, `'F#m7b5'`, `'C/G'`).
      *
@@ -398,16 +765,40 @@ declare class Chord {
      * Identify the chords matching a set of pitches, best interpretation first.
      *
      * @param pitches MIDI pitches or bare pitch classes.
+     * @param opts How to interpret the input; see {@link DetectChordOptions}.
      * @returns Ranked chord interpretations (may be empty).
      */
-    static detect(pitches: number[], opts?: DetectChordOptions): Chord[];
+    static detect(pitches: readonly number[], opts?: DetectChordOptions): Chord[];
+    /**
+     * Identify the chords matching a set of pitches, keeping each match's
+     * recognition metadata beside the chord.
+     *
+     * {@link Chord.detect} discards the confidence signals a recognition UI needs
+     * — whether the set matched exactly, which chord tones were missing, which
+     * input notes were foreign, and which inversion the bass implies.
+     *
+     * @param pitches MIDI pitches or bare pitch classes.
+     * @param opts How to interpret the input; see {@link DetectChordOptions}.
+     * @returns Ranked interpretations, each with its chord and its match record.
+     * @example
+     * ```ts
+     * import { Chord } from '@libraz/libcantus';
+     * const [best] = Chord.detectMatches([60, 64, 67]);
+     * best?.match.exact; // true
+     * ```
+     */
+    static detectMatches(pitches: readonly number[], opts?: DetectChordOptions): {
+        chord: Chord;
+        match: ChordMatch;
+    }[];
     /**
      * The single best chord interpretation of a pitch set.
      *
      * @param pitches MIDI pitches or bare pitch classes.
+     * @param opts How to interpret the input; see {@link DetectChordOptions}.
      * @returns The top-ranked chord, or null when nothing matches.
      */
-    static detectBest(pitches: number[], opts?: DetectChordOptions): Chord | null;
+    static detectBest(pitches: readonly number[], opts?: DetectChordOptions): Chord | null;
     /** The root pitch class (0..11). */
     get rootPc(): number;
     /** The chord quality. */
@@ -416,13 +807,22 @@ declare class Chord {
     get intervals(): number[];
     /** The slash-chord bass pitch class, or undefined in root position. */
     get bassPc(): number | undefined;
-    /** A copy of the underlying plain chord object. */
+    /**
+     * A copy of the underlying plain chord object, including the spellings
+     * derived from any attached key.
+     */
     get data(): Chord$1;
     /** The carried key context, if any. */
     get key(): Key | undefined;
     /**
      * A copy of this chord carrying the given key context.
      *
+     * Only a spelling the caller supplied (via `Chord.parse`, `Chord.of` with a
+     * named root, or plain data carrying a hint) survives; a spelling that came
+     * from a previously attached key is re-derived, so re-keying a progression
+     * during a modulation does not keep the old key's letters and the order of
+     * `withKey` calls does not affect the result.
+     *
      * @param key The key context to attach.
      * @returns The new chord.
      */
@@ -437,10 +837,11 @@ declare class Chord {
      * 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?: Key): string;
+    roman(key?: Key, opts?: ChordToRomanOptions): string;
     /**
      * The chord's harmonic function (tonic / subdominant / dominant) in a key.
      *
@@ -453,10 +854,11 @@ declare class Chord {
      * 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?: Key): ChordAnalysis;
+    analyze(key?: Key, opts?: ChordToRomanOptions): ChordAnalysis;
     /**
      * Whether the chord is borrowed from the parallel mode (modal interchange).
      *
@@ -485,6 +887,9 @@ declare class Chord {
     /**
      * Realize the chord as one MIDI pitch per voice, ascending.
      *
+     * A chord that carries a key passes it to the voicer, so the leading tone is
+     * not doubled; an explicit `opts.key` overrides it.
+     *
      * @param opts Voicing options; defaults to four SATB voices.
      * @returns MIDI pitches, ascending, one per voice.
      * @throws If no voicing fits the given ranges.
@@ -521,6 +926,23 @@ declare class Chord {
      * @throws If the chord has no intervals.
      */
     invert(n: number): Chord;
+    /**
+     * Transpose the chord by a number of semitones.
+     *
+     * The quality and interval template are carried over, so a chord that a
+     * symbol round-trip could not express — a custom interval set, an inversion —
+     * survives. A carried key moves with the chord, so the transposed chord keeps
+     * the same degree and function inside the transposed key.
+     *
+     * @param semitones The signed semitone offset.
+     * @returns The transposed chord, in the transposed key when one is carried.
+     * @example
+     * ```ts
+     * import { Chord } from '@libraz/libcantus';
+     * Chord.parse('C/G').transpose(2).symbol(); // 'D/A'
+     * ```
+     */
+    transpose(semitones: number): Chord;
     /**
      * The named scales that fit over this chord, best fit first, rooted on the
      * chord root.
@@ -534,23 +956,36 @@ declare class Chord {
      *
      * @param scaleName A named scale, rooted on the chord root.
      * @returns Tension pitch classes, ascending in [0, 11].
+     * @throws If `scaleName` is not a built-in scale.
      */
-    tensions(scaleName: string): number[];
+    tensions(scaleName: ScaleNameInput): number[];
     /**
      * The avoid notes (scale tones a semitone above a chord tone) of a scale
      * over this chord.
      *
      * @param scaleName A named scale, rooted on the chord root.
      * @returns Avoid-note pitch classes, ascending in [0, 11].
+     * @throws If `scaleName` is not a built-in scale.
      */
-    avoidNotes(scaleName: string): number[];
+    avoidNotes(scaleName: ScaleNameInput): number[];
     /**
      * Spell the chord tones with letter names, root first, in the key's spelling.
      *
+     * A chord that already knows how its root is spelled — one from
+     * `Chord.parse`, or `Chord.of` with a named root — can spell itself with no
+     * key at all; a key is only needed to choose a spelling for a bare pitch
+     * class.
+     *
+     * A slash bass outside the chord tones is appended, so the spelled notes
+     * are the notes the chord sounds — the same set {@link Chord.pitchClasses}
+     * reports.
+     *
      * @param key Key providing the spelled tonic; falls back to the carried
-     *   context.
-     * @returns Spelled octave-less notes in the chord's own (tertian) order.
-     * @throws If no key is given and none is carried.
+     *   context, then to the chord's own root spelling.
+     * @returns Spelled octave-less notes in the chord's own (tertian) order,
+     *   with any foreign slash bass last.
+     * @throws If no key is given, none is carried, and the chord has no root
+     *   spelling of its own.
      */
     spell(key?: Key): Note[];
     /**
@@ -575,57 +1010,12 @@ declare class Chord {
      * @returns A copy of the underlying plain chord object.
      */
     toJSON(): Chord$1;
-}
-
-/**
- * An immutable spelled interval value: a diatonic number, a quality label, and
- * a signed semitone span. A thin convenience wrapper over the pitch module's
- * plain interval result.
- *
- * @category Class API
- * @example
- * ```ts
- * import { Interval, Note } from '@libraz/libcantus';
- * Interval.between(Note.of('C4'), Note.of('G4')).name; // 'P5'
- * ```
- */
-declare class Interval {
-    #private;
-    private constructor();
     /**
-     * The spelled interval between two notes.
-     *
-     * @param a The first note.
-     * @param b The second note.
-     * @returns The interval from `a` to `b`.
-     */
-    static between(a: Note, b: Note): Interval;
-    /**
-     * Build an interval from explicit components.
-     *
-     * @param numberValue Diatonic size: 1 = unison, 2 = second, ... 8 = octave.
-     * @param quality Quality label: `'P'`, `'M'`, `'m'`, or repeated `'A'`/`'d'`.
-     * @param semitones Signed semitone span.
-     * @returns The interval.
-     */
-    static of(numberValue: number, quality: string, semitones: number): Interval;
-    /** Diatonic size: 1 = unison, 2 = second, ... 8 = octave, and beyond. */
-    get number(): number;
-    /** Quality label: `'P'`, `'M'`, `'m'`, or repeated `'A'`/`'d'`. */
-    get quality(): string;
-    /** Signed semitone span. */
-    get semitones(): number;
-    /** A readable label composed of quality and number, e.g. `'P5'` or `'M3'`. */
-    get name(): string;
-    /**
-     * The plain interval data, for JSON serialization.
+     * The chord symbol, so a template literal or a log line reads as the chord.
      *
-     * Private class fields do not serialize, so an explicit `toJSON` keeps
-     * `JSON.stringify(interval)` from collapsing to `{}`.
-     *
-     * @returns The diatonic number, quality, and semitone span.
+     * @returns The symbol, e.g. `'Cmaj7'`.
      */
-    toJSON(): SpelledInterval;
+    toString(): string;
 }
 
-export { Chord, Interval, Key, Note, Progression };
+export { BorrowedSource, Cadence, Chord, ChordAnalysis, Chord$1 as ChordData, ChordMatch, ChordQuality, ChordScaleMatch, ChordSpan, ChordToRomanOptions, DetectChordOptions, DetectKeyOptions, type DetectedKeyMatch, HarmonicFunction, Interval, IntervalQualityLabel, Key, KeyMatch, KeyScale, KeyVariant, Note, Note$1 as NoteData, Progression, ScaleChoice, ScaleNameInput, SpelledInterval, StyledVoicingOptions, VoicingOptions };