@libraz/libcantus 1.0.1 → 1.2.0

package/dist/model/index.d.ts

@@ -1,23 +1,23 @@
-import { R as ReduceProgressionOptions, v as ReducedChord, D as DetectChordOptions, C as ChordMatch, i as KeyVariant, f as DetectKeyOptions, K as KeyMatch, t as PhraseOptions, P as Phrase, S as StructuralCadence, g as FormSectionOptions, F as FormSection, h as HypermeterOptions, H as Hypermeter, E as ExtractMotifsOptions, p as MotifData, k as MelodicContour, c as ArrangementTrack, a as ArrangementOptions, A as ArrangementAnalysis, d as Conflict, z as TrackEdit, T as TensionPoint, r as MotifRelation } from '../index-D57QRbVn.js';
-export { b as ArrangementSession, e as ContourDirection, l as MelodicContourShape, o as ModalScaleName, q as MotifOccurrence, s as MotifRelationKind, u as PhraseSignal, w as ReductionBasis, x as ReductionLevel, y as TrackAnalysis, B as TrackRole } from '../index-D57QRbVn.js';
-import { b as IntervalQualityLabel, S as SpelledInterval, P as ParseResult, f as Note$1, i as NoteNameOptions, I as IntervalLike, g as NoteEvent, h as NoteLike, d as KeyScale, a as Articulation } from '../index-B9MNZboQ.js';
-export { B as BudgetExceededError, c as InvalidInputError, L as LibcantusError, N as NoSolutionError, j as NoteNameSystem } from '../index-B9MNZboQ.js';
-import { K as KeyLike, e as ChordSegment, g as ChordSpan, b as Chord$1, d as ChordQuality, h as ChordSpec, j as ChordToneRole, i as ChordSymbolOptions, k as KeyRelation, c as ChordLike, n as SafetyQuery, E as EvaluateSafetyOptions, o as SafetyResult } from '../index-szBv3496.js';
-export { A as Alteration, a as AlteredDegree, C as ChordBase, f as ChordSeventh, N as NoteSafety, l as PitchSpelling, m as ProfileWeights, S as SafetyProfile, p as SpelledKey, V as VoiceSnapshot } from '../index-szBv3496.js';
-import { s as ScaleNameInput, r as ScaleName } from '../masks-DYbE485J.js';
-import { m as TransposingInstrument, q as VoicingOptions, g as ScaleChoice, l as StyledVoicingOptions, C as ChordScaleMatch, c as ChordScaleReportEntry, A as AvailableTensionsOptions, b as AvoidNotesOptions, K as KeyMode, h as ScaleSystem, p as VoiceRange, P as PartWritingOptions, d as PartWritingViolation, i as Species, j as SpeciesOptions, V as VoiceIndependenceOptions, o as VoiceIndependenceReport } from '../index-9wcMhG73.js';
-export { a as AvoidNoteUse, e as PartWritingViolationKind, n as TransposingInstrumentName, r as VoicingStyle } from '../index-9wcMhG73.js';
-import { k as KeyRegion, f as ChordTimelineOptions, C as CadenceHit, h as ChordToRomanOptions, e as ChordTimeline, H as HarmonicFunction, A as AnalyzeChordOptions, D as DetectCadenceOptions, c as ChordAnalysis, b as CadenceResult, E as ExplainRomanOptions, m as RomanExplanation, B as BorrowedSource, l as KeyTimelineOptions, a as AnalyzedNote, I as IdentifiedVoiceNote } from '../index-Chbst3Jx.js';
-export { d as ChordSegmentation, K as KeyContext, i as KeyProfileName, j as KeyProfilePair, P as PivotChord, R as RejectedCandidate, S as SuspensionFigure, T as TheoryLabel, V as VoiceNote } from '../index-Chbst3Jx.js';
-import { j as TuningTable, i as TempoMap, g as PlayabilityReport, b as NoteEventIndexOptions, a as NoteEventIndex, d as NoteValue, k as Tuplet, D as DurationData, S as SpelledDuration } from '../index-G1uwGGWQ.js';
-export { I as IndexedNoteEvent, c as NotePlacement, O as OnsetTieBreak, P as PlayabilityIssue, e as PlayabilityIssueType, f as PlayabilityLayer, h as TempoEvent } from '../index-G1uwGGWQ.js';
-import { b as InstrumentProfileLike, I as InstrumentProfile, e as StringFingering } from '../positional-Cptlj-xs.js';
-export { a as InstrumentProfileCommon, c as Limb, P as PercussionProfile, d as PositionalRng, S as SeedPath, f as StringedProfile } from '../positional-Cptlj-xs.js';
-import { c as MeterMap, b as MeterLike, B as BarPosition, T as TimeSignature } from '../index-Cj49F892.js';
-export { M as MeterChange } from '../index-Cj49F892.js';
-import { a2 as SubstitutionType, a0 as SubstituteOptions, a1 as Substitution, g as BorrowedChord, z as HumanizeOptions, L as OrnamentOptions, w as GrooveTemplate, d as BassLineOptions, C as Complexity, a3 as Vocabulary, T as ProgressionOptions, o as DrumsOptions, e as BassSegment, h as CounterMelodyOptions, H as HarmonizeOptions, p as GenerationContext, A as MotifCell, F as MotifContour, q as GenerationContextInput, I as MotifNote, K as MotifTransform, Y as RhythmEvent, Z as RhythmOptions } from '../index-CgHqxdps.js';
-export { f as BassStyle, l as DrumRole, E as EuclideanKick, r as Genre, s as GridEvent, t as GrooveFeel, u as GrooveSlot, v as GrooveStyle, x as HarmonizePlacement, M as MelodyNote, N as OrnamentStyle, Q as ProgFunction, R as ProgStyle, S as ProgressionDegree, U as ProgressionPreset, V as Provenance, W as ProvenanceBasis, $ as Section } from '../index-CgHqxdps.js';
-import '../index-CunYKLiu.js';
+import { R as ReduceProgressionOptions, v as ReducedChord, D as DetectChordOptions, C as ChordMatch, h as DetectKeyOptions, K as KeyMatch, d as AugmentedSixthKind, t as PhraseOptions, P as Phrase, S as StructuralCadence, i as FormSectionOptions, F as FormSection, j as HypermeterOptions, H as Hypermeter, E as ExtractMotifsOptions, p as MotifData, k as MelodicContour, c as ArrangementTrack, a as ArrangementOptions, A as ArrangementAnalysis, e as Conflict, z as TrackEdit, T as TensionPoint, r as MotifRelation } from '../index-BRMbPkHE.js';
+export { b as ArrangementSession, f as ConflictPartner, g as ContourDirection, l as MelodicContourShape, o as ModalScaleName, q as MotifOccurrence, s as MotifRelationKind, u as PhraseSignal, w as ReductionBasis, x as ReductionLevel, y as TrackAnalysis, B as TrackRole } from '../index-BRMbPkHE.js';
+import { k as KeyRegion, f as ChordTimelineOptions, C as CadenceHit, l as KeyTimelineOptions, h as ChordToRomanOptions, e as ChordTimeline, H as HarmonicFunction, A as AnalyzeChordOptions, D as DetectCadenceOptions, c as ChordAnalysis, b as CadenceResult, E as ExplainRomanOptions, m as RomanExplanation, B as BorrowedSource, a as AnalyzedNote, I as IdentifiedVoiceNote } from '../index-CJBBiAmU.js';
+export { d as ChordSegmentation, g as ChordTimelineResult, K as KeyContext, i as KeyProfileName, j as KeyProfilePair, P as PivotChord, R as RejectedCandidate, S as SuspensionFigure, T as TheoryLabel, V as VoiceNote } from '../index-CJBBiAmU.js';
+import { c as IntervalQualityLabel, I as IntervalData, P as ParseResult, S as SpelledInterval, g as Note$1, j as NoteNameOptions, b as IntervalLike, h as NoteEvent, i as NoteLike, e as KeyScale, a as Articulation } from '../index-Cy15oTvh.js';
+export { B as BudgetExceededError, d as InvalidInputError, L as LibcantusError, N as NoSolutionError, k as NoteNameSystem } from '../index-Cy15oTvh.js';
+import { K as KeyLike, e as ChordSegment, g as ChordSpan, b as Chord$1, d as ChordQuality, h as ChordSpec, i as ChordToneRole, n as ResolvedKey, k as KeyVariant, j as KeyRelation, c as ChordLike, r as SpelledKeyLike, p as SafetyQuery, E as EvaluateSafetyOptions, q as SafetyResult } from '../coerce-DP0vYu-x.js';
+export { A as Alteration, a as AlteredDegree, C as ChordBase, f as ChordSeventh, N as NoteSafety, l as PitchSpelling, m as ProfileWeights, S as SafetyPartner, o as SafetyProfile, s as SpelledKeyScale, V as VoiceSnapshot } from '../coerce-DP0vYu-x.js';
+import { j as TuningTable, i as TempoMap, g as PlayabilityReport, b as NoteEventIndexOptions, a as NoteEventIndex, d as NoteValue, k as Tuplet, D as DurationData, S as SpelledDuration } from '../index-9eoQs2C1.js';
+export { I as IndexedNoteEvent, c as NotePlacement, O as OnsetTieBreak, P as PlayabilityIssue, e as PlayabilityIssueType, f as PlayabilityLayer, h as TempoEvent } from '../index-9eoQs2C1.js';
+import { b as InstrumentProfileLike, d as PositionalRng, I as InstrumentProfile, e as StringFingering } from '../positional-DJgs6ltD.js';
+export { a as InstrumentProfileCommon, c as Limb, P as PercussionProfile, S as SeedPath, f as StringedProfile, V as ValidatedPercussionProfile, g as ValidatedProfile, h as ValidatedStringedProfile } from '../positional-DJgs6ltD.js';
+import { c as MeterMap, b as MeterLike, B as BarPosition, T as TimeSignature } from '../index-CL4b4gUQ.js';
+export { M as MeterChange } from '../index-CL4b4gUQ.js';
+import { s as ScaleNameInput, r as ScaleName } from '../masks-Cc7-MzzY.js';
+import { n as TransposingInstrument, r as VoicingOptions, h as ScaleChoice, d as ChordSymbolOptions, m as StyledVoicingOptions, C as ChordScaleMatch, c as ChordScaleReportEntry, A as AvailableTensionsOptions, b as AvoidNotesOptions, K as KeyMode, i as ScaleSystem, q as VoiceRange, P as PartWritingOptions, e as PartWritingViolation, j as Species, k as SpeciesOptions, V as VoiceIndependenceOptions, p as VoiceIndependenceReport } from '../index-BHIUyjhZ.js';
+export { a as AvoidNoteUse, f as PartWritingViolationKind, o as TransposingInstrumentName, s as VoicingStyle } from '../index-BHIUyjhZ.js';
+import { a2 as SubstitutionType, a0 as SubstituteOptions, a1 as Substitution, g as BorrowedChord, z as HumanizeOptions, L as OrnamentOptions, w as GrooveTemplate, d as BassLineOptions, C as Complexity, a4 as Vocabulary, T as ProgressionOptions, o as DrumsOptions, e as BassSegment, h as CounterMelodyOptions, H as HarmonizeOptions, p as GenerationContext, A as MotifCell, F as MotifContour, q as GenerationContextInput, I as MotifNote, K as MotifTransform, Y as RhythmEvent, Z as RhythmOptions } from '../index-BJgP97N1.js';
+export { f as BassStyle, l as DrumRole, E as EuclideanKick, r as Genre, s as GridEvent, t as GrooveFeel, u as GrooveSlot, v as GrooveStyle, x as HarmonizePlacement, M as MelodyNote, N as OrnamentStyle, Q as ProgFunction, R as ProgStyle, S as ProgressionDegree, U as ProgressionPreset, V as Provenance, W as ProvenanceBasis, $ as Section } from '../index-BJgP97N1.js';
+import '../index-Dw2DP7vm.js';
 
 /**
  * An immutable spelled interval value: a diatonic number, a quality label, and
@@ -66,7 +66,7 @@ declare class Interval {
      * @returns The wrapped interval.
      * @throws If the number, quality, and span do not describe the same interval.
      */
-    static fromData(data: SpelledInterval): Interval;
+    static fromData(data: IntervalData): Interval;
     /**
      * Rebuild an interval from its {@link Interval.toJSON} output.
      *
@@ -74,7 +74,7 @@ declare class Interval {
      * @returns The wrapped interval.
      * @throws If the number, quality, and span do not describe the same interval.
      */
-    static fromJSON(data: SpelledInterval): Interval;
+    static fromJSON(data: IntervalData): Interval;
     /**
      * Parse an interval name such as `'P5'`, `'m3'`, `'AA4'`, or `'-m3'`.
      *
@@ -114,7 +114,14 @@ declare class Interval {
      * semitones, so this flag is the only record of its direction.
      */
     get isDescending(): boolean;
-    /** A readable label composed of quality and number, e.g. `'P5'` or `'M3'`. */
+    /**
+     * A readable label composed of quality and number, e.g. `'P5'` or `'M3'`,
+     * prefixed with `'-'` when the interval descends.
+     *
+     * The name is written in the grammar {@link Interval.parse} reads, so an
+     * interval that has been logged, written to a column, or interpolated into a
+     * template comes back as the same interval — direction included.
+     */
     get name(): string;
     /** A copy of the underlying plain interval data. */
     get data(): SpelledInterval;
@@ -146,7 +153,7 @@ declare class Interval {
      * @example
      * ```ts
      * import { Interval } from '@libraz/libcantus';
-     * Interval.parse('M3').negate().toString(); // 'M3', descending
+     * Interval.parse('M3').negate().toString(); // '-M3'
      * ```
      */
     negate(): Interval;
@@ -173,19 +180,20 @@ declare class Interval {
      *
      * Private class fields do not serialize, so an explicit `toJSON` keeps
      * `JSON.stringify(interval)` from collapsing to `{}`. The result is the
-     * canonical shape the pitch module produces: `descending` appears only on an
-     * interval that descends, so a measured interval, a parsed name, and this
-     * method all serialize to the same object.
+     * canonical shape the pitch module produces: `descending` is always there, so
+     * a measured interval, a parsed name, and this method all serialize to the
+     * same object and none of them leaves the direction to be guessed.
      *
-     * @returns The diatonic number, quality, and semitone span, with
-     *   `descending` when the interval descends.
+     * @returns The diatonic number, quality, and semitone span, with `descending`
+     *   telling which way the interval goes.
      */
     toJSON(): SpelledInterval;
     /**
      * The interval's name, so a template literal or a log line reads as the
      * interval.
      *
-     * @returns The name, e.g. `'M3'`.
+     * @returns The name, e.g. `'M3'` or `'-M3'` for the same third taken
+     *   downward.
      */
     toString(): string;
 }
@@ -628,8 +636,10 @@ declare class Timeline {
      * Place a progression's chords on a regular grid.
      *
      * The chords cross over as harmony alone: a spelling one of them carried is
-     * dropped, and a carried key becomes the plain key/scale of the one region
-     * under the span, without its spelled tonic or its detected scale form.
+     * dropped, since a chord placed on the grid is a `ChordSpan` and a span
+     * carries none. A carried key becomes the one key region under the span,
+     * spelled tonic and scale form included — an Ab minor comes back Ab minor,
+     * which is what the numerals over the region are read from.
      *
      * @param progression The chords, in order.
      * @param beatsEach How long each chord sounds.
@@ -660,7 +670,16 @@ declare class Timeline {
     get totalBeats(): number;
     /** The key held longest across the span, when the analysis found one. */
     get key(): Key | undefined;
-    /** Every key region under the span, in time order. */
+    /**
+     * Every key region under the span, in time order.
+     *
+     * These are the regions the timeline was built with: the ones
+     * {@link Timeline.fromNotes} read off the notes, or the single region a key
+     * given to {@link Timeline.fromChords} describes. A timeline holding chords
+     * alone carries none until it is asked to read them —
+     * {@link Timeline.modulations} is where the chords are searched for the keys
+     * they imply.
+     */
     get keys(): readonly KeyRegion[];
     /**
      * How sure the analysis is of each segment's chord, in [0, 1] and in segment
@@ -719,6 +738,33 @@ declare class Timeline {
      * @throws If the timeline carries no key region to read the chords against.
      */
     cadences(): CadenceHit[];
+    /**
+     * The keys the chords themselves imply, in time order.
+     *
+     * The chord route to key regions, for a timeline that holds harmony without
+     * the notes it was played from — a lead sheet, or a progression laid out in
+     * time. A chord argues for a key far more strongly than its three or four
+     * pitch classes do, so a modulation is read off the chords rather than off a
+     * pitch-class profile, and the chord that reads in both keys is reported as
+     * the pivot the modulation turned on.
+     *
+     * The regions are searched for here rather than kept on the timeline:
+     * {@link Timeline.keys} answers with what the timeline was built with, which
+     * for placed chords is the key the caller stated or nothing at all.
+     *
+     * @param opts Analysis options; see {@link KeyTimelineOptions}.
+     * @returns The key regions the chords imply; empty when there are no chords.
+     * @example
+     * ```ts
+     * import { Chord, Key, Progression, Timeline } from '@libraz/libcantus';
+     * const progression = new Progression(
+     *   [Chord.parse('C'), Chord.parse('G7'), Chord.parse('C')],
+     *   Key.major('C'),
+     * );
+     * Timeline.fromProgression(progression, 4).modulations().length; // 1
+     * ```
+     */
+    modulations(opts?: KeyTimelineOptions): KeyRegion[];
     /**
      * The chords as roman numerals in a key.
      *
@@ -818,9 +864,10 @@ declare class Progression {
      * Wrap a chord sequence.
      *
      * @param chords The chords in order; the array is copied.
-     * @param key Optional key context for analysis methods.
+     * @param key Optional key context for analysis methods, in whatever form the
+     *   caller holds it: a key name, a plain key/scale, or a {@link Key}.
      */
-    constructor(chords: readonly Chord[], key?: Key);
+    constructor(chords: readonly Chord[], key?: KeyLike);
     /**
      * Start from a chord sequence, matching the `of` factory on the other
      * classes.
@@ -838,7 +885,7 @@ declare class Progression {
      * // ['I', 'V7']
      * ```
      */
-    static of(chords: readonly Chord[], key?: Key): Progression;
+    static of(chords: readonly Chord[], key?: KeyLike): Progression;
     /**
      * Build a progression from the {@link ChordSpan} records the generators
      * return, keeping their order.
@@ -854,11 +901,11 @@ declare class Progression {
      * ```ts
      * import { generateProgression, Key, Progression } from '@libraz/libcantus';
      * const key = Key.major('C');
-     * const spans = generateProgression({ key: key.scale, style: 'dance', bars: 4 });
+     * const spans = generateProgression({ key, style: 'dance', bars: 4 });
      * Progression.fromSpans(spans, key).roman();
      * ```
      */
-    static fromSpans(spans: readonly ChordSpan[], key?: Key): Progression;
+    static fromSpans(spans: readonly ChordSpan[], key?: KeyLike): Progression;
     /**
      * Rebuild a progression from its {@link Progression.toJSON} output.
      *
@@ -1019,10 +1066,11 @@ declare class Progression {
     /**
      * A copy of this progression carrying the given key context.
      *
-     * @param key The key context to attach.
+     * @param key The key context to attach; a key name, a plain key/scale, or a
+     *   {@link Key}.
      * @returns The new progression.
      */
-    withKey(key: Key): Progression;
+    withKey(key: KeyLike): Progression;
     /**
      * Voice the progression with smooth voice leading.
      *
@@ -1034,20 +1082,22 @@ 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 key Key to analyze in, as a key name, a plain key/scale, or a
+     *   {@link Key}; 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, opts?: ChordToRomanOptions): string[];
+    roman(key?: KeyLike, opts?: ChordToRomanOptions): string[];
     /**
      * The harmonic function of each chord in a key.
      *
-     * @param key Key to analyze in; falls back to the carried context.
+     * @param key Key to analyze in, as a key name, a plain key/scale, or a
+     *   {@link Key}; falls back to the carried context.
      * @returns One function per chord.
      * @throws If no key is given and none is carried.
      */
-    functions(key?: Key): HarmonicFunction[];
+    functions(key?: KeyLike): HarmonicFunction[];
     /**
      * Analyze every chord and classify the closing cadence.
      *
@@ -1055,12 +1105,15 @@ declare class Progression {
      * progression has fewer than two chords.
      *
      * The options reach both analyses: `applied` and `alternatives` go to every
-     * chord, and `voicing` — the pitches of the last two chords, as
-     * {@link Progression.voice} produces them — to the cadence, which cannot tell
-     * a perfect authentic cadence from an imperfect one without knowing the
-     * soprano.
-     *
-     * @param key Key to analyze in; falls back to the carried context.
+     * chord, and `voicing` — the pitches sounding under the progression, one
+     * voicing per chord as {@link Progression.voice} produces them — to the
+     * cadence, which cannot tell a perfect authentic cadence from an imperfect
+     * one without knowing the soprano. It is the same shape
+     * {@link Progression.cadences} takes, and the closing pair is cut from it
+     * here; a two-element array is read as that pair itself.
+     *
+     * @param key Key to analyze in, as a key name, a plain key/scale, or a
+     *   {@link Key}; falls back to the carried context.
      * @param opts Applied-numeral rendering options, `alternatives` for the
      *   readings both analyses turned down, and `voicing` for the cadence's
      *   voice-leading detail; see {@link AnalyzeChordOptions} and
@@ -1071,12 +1124,13 @@ declare class Progression {
      * ```ts
      * import { Chord, Key, Progression } from '@libraz/libcantus';
      * const progression = new Progression([Chord.parse('G7'), Chord.parse('C')], Key.major('C'));
-     * const voiced = progression.voice();
-     * progression.analyze(undefined, { voicing: [voiced[0] ?? [], voiced[1] ?? []] }).cadence
-     *   ?.strength; // 'perfect'
+     * progression.analyze(undefined, { voicing: progression.voice() }).cadence?.strength;
+     * // 'perfect'
      * ```
      */
-    analyze(key?: Key, opts?: AnalyzeChordOptions & DetectCadenceOptions): {
+    analyze(key?: KeyLike, opts?: AnalyzeChordOptions & Omit<DetectCadenceOptions, 'voicing'> & {
+        voicing?: number[][];
+    }): {
         chords: ChordAnalysis[];
         cadence: CadenceResult | null;
     };
@@ -1098,7 +1152,8 @@ declare class Progression {
      * The chord before each pair is supplied from the progression itself, so a
      * cadential six-four is recognized as one wherever it stands.
      *
-     * @param key Key to analyze in; falls back to the carried context.
+     * @param key Key to analyze in, as a key name, a plain key/scale, or a
+     *   {@link Key}; falls back to the carried context.
      * @param opts `voicing` is the pitches sounding under the whole progression,
      *   one voicing per chord as {@link Progression.voice} produces them, from
      *   which each pair takes its own two — without it no authentic cadence can be
@@ -1118,11 +1173,9 @@ declare class Progression {
      * progression.cadences().map((cadence) => cadence.type); // [null, 'half', 'authentic']
      * ```
      */
-    cadences(key?: Key, opts?: {
+    cadences(key?: KeyLike, opts?: {
         voicing?: number[][];
-        alternatives?: boolean;
-        approach?: Chord;
-    }): CadenceResult[];
+    } & Pick<DetectCadenceOptions, 'alternatives' | 'approach'>): CadenceResult[];
     /**
      * A copy of this progression with one chord replaced by a substitute.
      *
@@ -1209,7 +1262,8 @@ declare class Progression {
      * a target in another mode — a relative, parallel, or modal key — is the key
      * the progression is then analyzed in.
      *
-     * @param target The key the transposed progression should be in.
+     * @param target The key the transposed progression should be in, as a key
+     *   name, a plain key/scale, or a {@link Key}.
      * @returns The transposed progression, carrying `target` as its key.
      * @throws If the progression carries no key context to measure from.
      * @example
@@ -1219,7 +1273,7 @@ declare class Progression {
      * progression.transposeTo(Key.major('Eb')).toString(); // 'Eb Bb7'
      * ```
      */
-    transposeTo(target: Key): Progression;
+    transposeTo(target: KeyLike): Progression;
     /**
      * The chord symbols separated by spaces, so a template literal or a log line
      * reads as the progression.
@@ -1257,9 +1311,10 @@ declare class Chord {
      * Wrap a plain chord object.
      *
      * @param data The chord; it is copied, never retained or mutated.
-     * @param key Optional key context for analysis methods.
+     * @param key Optional key context for analysis methods, in whatever form the
+     *   caller holds it: a key name, a plain key/scale, or a {@link Key}.
      */
-    constructor(data: Chord$1, key?: Key);
+    constructor(data: Chord$1, key?: KeyLike);
     /**
      * Build a chord from a root and quality.
      *
@@ -1315,7 +1370,7 @@ declare class Chord {
      * ```ts
      * import { Chord } from '@libraz/libcantus';
      * Chord.fromFiguredBass('B', '6', 'C major').symbol(); // 'G/B'
-     * Chord.fromFiguredBass('G', '#', 'C minor').symbol(); // 'G'
+     * Chord.fromFiguredBass('G', 'n', 'C minor').symbol(); // 'G'
      * ```
      */
     static fromFiguredBass(bass: NoteLike, figures: string, key: KeyLike): Chord;
@@ -1441,10 +1496,11 @@ declare class Chord {
      * 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.
+     * @param key The key context to attach; a key name, a plain key/scale, or a
+     *   {@link Key}.
      * @returns The new chord.
      */
-    withKey(key: Key): Chord;
+    withKey(key: KeyLike): Chord;
     /**
      * The chord's sorted, deduplicated pitch classes.
      *
@@ -1503,12 +1559,13 @@ declare class Chord {
     /**
      * The chord's Roman numeral in a key.
      *
-     * @param key Key to analyze in; falls back to the carried context.
+     * @param key Key to analyze in, as a key name, a plain key/scale, or a
+     *   {@link Key}; 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, opts?: ChordToRomanOptions): string;
+    roman(key?: KeyLike, opts?: ChordToRomanOptions): string;
     /**
      * The chord's Roman numeral together with the reasoning behind it: the degree
      * its root was read as, the quality that set the numeral's case and suffix,
@@ -1538,16 +1595,18 @@ declare class Chord {
     /**
      * The chord's harmonic function (tonic / subdominant / dominant) in a key.
      *
-     * @param key Key to analyze in; falls back to the carried context.
+     * @param key Key to analyze in, as a key name, a plain key/scale, or a
+     *   {@link Key}; falls back to the carried context.
      * @returns The harmonic function.
      * @throws If no key is given and none is carried.
      */
-    function(key?: Key): HarmonicFunction;
+    function(key?: KeyLike): HarmonicFunction;
     /**
      * Full functional analysis: function, borrowing, Roman numeral, and the
      * rationale behind them.
      *
-     * @param key Key to analyze in; falls back to the carried context.
+     * @param key Key to analyze in, as a key name, a plain key/scale, or a
+     *   {@link Key}; falls back to the carried context.
      * @param opts Applied-numeral rendering options, plus `alternatives` to
      *   collect the readings this analysis turned down; see
      *   {@link AnalyzeChordOptions}.
@@ -1559,23 +1618,25 @@ declare class Chord {
      * Chord.parse('D7').analyze(Key.major('C'), { alternatives: true }).alternatives.length;
      * ```
      */
-    analyze(key?: Key, opts?: AnalyzeChordOptions): ChordAnalysis;
+    analyze(key?: KeyLike, opts?: AnalyzeChordOptions): ChordAnalysis;
     /**
      * Whether the chord is borrowed from the parallel mode (modal interchange).
      *
-     * @param key Key to analyze in; falls back to the carried context.
+     * @param key Key to analyze in, as a key name, a plain key/scale, or a
+     *   {@link Key}; falls back to the carried context.
      * @returns True if the chord is borrowed.
      * @throws If no key is given and none is carried.
      */
-    isBorrowed(key?: Key): boolean;
+    isBorrowed(key?: KeyLike): boolean;
     /**
      * The origin of a non-diatonic chord (parallel mode or Neapolitan), or null.
      *
-     * @param key Key to analyze in; falls back to the carried context.
+     * @param key Key to analyze in, as a key name, a plain key/scale, or a
+     *   {@link Key}; falls back to the carried context.
      * @returns The borrowing source, or null.
      * @throws If no key is given and none is carried.
      */
-    borrowedSource(key?: Key): BorrowedSource;
+    borrowedSource(key?: KeyLike): BorrowedSource;
     /**
      * The chord written as the figures a bass would carry under it: `6`, `64`,
      * `7`, `65`, `43`, `42`, or nothing at all for a root-position triad, with an
@@ -1683,12 +1744,12 @@ declare class Chord {
      * The negative-harmony mirror of the chord about the key's tonic–dominant
      * axis (major becomes minor and vice versa).
      *
-     * @param key Key providing the reflection axis; falls back to the carried
-     *   context.
+     * @param key Key providing the reflection axis, as a key name, a plain
+     *   key/scale, or a {@link Key}; falls back to the carried context.
      * @returns The mirrored chord, keeping any key context.
      * @throws If no key is given and none is carried.
      */
-    negativeHarmony(key?: Key): Chord;
+    negativeHarmony(key?: KeyLike): Chord;
     /**
      * The V7 that tonicizes this chord: a dominant seventh a perfect fifth above
      * this chord's root.
@@ -1759,6 +1820,10 @@ declare class Chord {
      * The named scales that fit over this chord, best fit first, rooted on the
      * chord root.
      *
+     * Only the scales of {@link NAMED_SCALES} are ranked: chord-scale theory is a
+     * Western practice, so the scales of {@link WORLD_SCALES} are left out rather
+     * than offered as answers over a chord.
+     *
      * @returns The matching scales.
      */
     scales(): ChordScaleMatch[];
@@ -1786,12 +1851,16 @@ declare class Chord {
      * The available tensions (usable non-chord, non-avoid scale tones) of a
      * scale over this chord.
      *
-     * @param scaleName A named scale, rooted on the chord root.
+     * @param scaleName A scale of {@link NAMED_SCALES}, or one of its aliases,
+     *   rooted on the chord root. The scales of {@link WORLD_SCALES} are refused
+     *   here as they are by {@link Chord.scales}: chord-scale theory is a Western
+     *   practice, and a scale from another tradition offered over a chord would
+     *   read as an answer while being a category error.
      * @param opts Set `resolvesTo` to the plain chord this one resolves to, so a
      *   dominant resolving down a fifth onto a minor tonic takes the tensions
      *   that resolution makes available; see {@link AvailableTensionsOptions}.
      * @returns Tension pitch classes, ascending in [0, 11].
-     * @throws If `scaleName` is not a built-in scale.
+     * @throws If `scaleName` is not one of the named scales or their aliases.
      * @example
      * ```ts
      * import { Chord } from '@libraz/libcantus';
@@ -1805,12 +1874,16 @@ declare class Chord {
      * 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.
+     * @param scaleName A scale of {@link NAMED_SCALES}, or one of its aliases,
+     *   rooted on the chord root. The scales of {@link WORLD_SCALES} are refused
+     *   here as they are by {@link Chord.scales}: chord-scale theory is a Western
+     *   practice, and a scale from another tradition offered over a chord would
+     *   read as an answer while being a category error.
      * @param opts Set `use: 'melodic'` to judge a line rather than a voicing, so
      *   a tone a line may pass through is not counted; see
      *   {@link AvoidNotesOptions}.
      * @returns Avoid-note pitch classes, ascending in [0, 11].
-     * @throws If `scaleName` is not a built-in scale.
+     * @throws If `scaleName` is not one of the named scales or their aliases.
      * @example
      * ```ts
      * import { Chord } from '@libraz/libcantus';
@@ -1831,14 +1904,16 @@ declare class Chord {
      * 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, then to the chord's own root spelling.
+     * @param key Key providing the spelled tonic, as a key name, a plain
+     *   key/scale, or a {@link Key} — the tonic its letters are spelled from is
+     *   derived from the key rather than asked of the caller. Falls back to the
+     *   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[];
+    spell(key?: KeyLike): Note[];
     /**
      * Start a progression with this chord followed by others, carrying this
      * chord's key context (if any).
@@ -1894,17 +1969,13 @@ type DetectedKeyMatch = Omit<KeyMatch, 'key'> & {
 };
 /**
  * The plain form of a {@link Key}: the key/scale, the spelled tonic that
- * anchors its letter names, and the detected scale form when it has one.
+ * anchors its letter names, and the scale form it stands in.
  *
- * The variant travels with the data because a detected harmonic or melodic
- * minor is not recoverable from the scale mask and tonic alone, and a key that
- * loses it prints as a plain minor after a round trip through a project file.
+ * The same shape the theory layer resolves a key to, so a key crossing between
+ * the two carries the same three facts under the same names, and a project file
+ * holds what every layer reads.
  */
-type KeyData = {
-    scale: KeyScale;
-    tonic: Note$1;
-    variant?: KeyVariant;
-};
+type KeyData = ResolvedKey;
 /**
  * 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
@@ -1924,7 +1995,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.
+     * @param variant The scale form. Read from the mask when none is named: a
+     *   major mask is a major key whoever built it, and a key with no form at all
+     *   is a state a reader would have to guess about.
      */
     constructor(scale: KeyScale, tonic: Note, variant?: KeyVariant);
     /**
@@ -1966,8 +2039,12 @@ declare class Key {
      * is G sharp major and `'gis'` G sharp minor; see {@link parseKeyName} for
      * how a name whose case and mode word disagree is read.
      *
-     * The result is always a plain major or minor key. Only the tonic's spelling
-     * survives from the name, so `'ges dur'` is G flat major, not F sharp major.
+     * An English name may also name a built-in scale instead of a mode —
+     * `'D harmonic minor'`, `'D dorian'`, `'C major pentatonic'` — which is what
+     * {@link Key.toString} writes for a key that is neither a plain major nor a
+     * plain minor, so a key survives being written down and read back. Only the
+     * tonic's spelling survives from the name, so `'ges dur'` is G flat major,
+     * not F sharp major.
      *
      * @param text The key name.
      * @param opts `system` reads the name in that notation system instead of
@@ -2009,7 +2086,7 @@ declare class Key {
      *
      * A signature names two keys — three sharps is both A major and F# minor — so
      * the mode decides which one is built. The tonic is spelled the way that key
-     * is written, including the theoretical keys past ±7 (nine sharps is B#
+     * is written, including the theoretical keys past ±7 (nine sharps is D#
      * major).
      *
      * @param fifths The signed number of sharps (positive) or flats (negative).
@@ -2034,12 +2111,18 @@ declare class Key {
      * 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; must spell the scale's root pitch class.
+     * A value that already carries a spelling keeps it — a key region's key, the
+     * data a key serializes to — so wrapping one is not where an Ab minor becomes
+     * a G# minor. Only a bare key/scale has a tonic chosen for it, because only a
+     * bare key/scale is missing one.
+     *
+     * @param key The key to wrap, in any form a key is held in.
+     * @param tonic Optional spelled tonic, overriding any the value carries; 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;
+    static of(key: KeyLike, tonic?: Note): Key;
     /**
      * Rebuild a key from its {@link Key.toJSON} output.
      *
@@ -2143,7 +2226,7 @@ declare class Key {
     /** A copy of the underlying plain key data. */
     get data(): KeyData;
     /** The detected scale form, when this key came from key detection. */
-    get variant(): KeyVariant | undefined;
+    get variant(): KeyVariant;
     /**
      * The scale's pitch classes.
      *
@@ -2209,12 +2292,18 @@ declare class Key {
      */
     supportsFunctionalHarmony(): boolean;
     /**
-     * The relative key: the same key signature read in the other mode.
+     * The relative key: for a plain major or minor key, the same key signature
+     * read in the other mode.
      *
      * Because the new tonic is read off the circle of fifths rather than
      * transposed by semitones, the relative of Db major is Bb minor and not its
      * enharmonic A# minor.
      *
+     * A key that is not a plain major or minor is read through the mode its third
+     * names and stepped from where its tonic stands on the circle: the relative of
+     * D dorian is F major. The shared signature does not carry over to those —
+     * D dorian is written with no accidentals and F major with one.
+     *
      * @returns The relative key, always a plain major or minor key.
      * @throws If this key's signature falls outside [-12, 12] fifths.
      * @example
@@ -2286,10 +2375,16 @@ declare class Key {
      *
      * These are the keys the German and Japanese teaching tradition counts as a
      * key's near relations: the relative and parallel keys, the dominant and the
-     * subdominant, and the relatives of those two. Five of them are written
-     * within one accidental of this key's signature — the relative shares it
-     * exactly and the other four stand one away; the parallel key stands three
-     * away and belongs to the set for the tonic it shares instead.
+     * subdominant, and the relatives of those two. For a plain major or minor key
+     * five of them are written within one accidental of this key's signature — the
+     * relative shares it exactly and the other four stand one away; the parallel
+     * key stands three away and belongs to the set for the tonic it shares
+     * instead.
+     *
+     * A key that is not a plain major or minor is read through the mode its third
+     * names, so its relations are walked from where its tonic stands on the circle
+     * rather than from its own signature, and those accidental counts do not
+     * describe them.
      *
      * @returns The related keys in relation order.
      * @throws If a neighbouring signature falls outside [-12, 12] fifths.
@@ -2328,6 +2423,34 @@ declare class Key {
      * ```
      */
     relationTo(other: Key): KeyRelation | null;
+    /**
+     * The chords a modulation from this key into another can pivot on.
+     *
+     * A pivot belongs to both keys at once, so it is heard as a degree of this
+     * key and reinterpreted as a degree of the key being entered. The candidates
+     * are this key's diatonic triads, kept when every one of their pitch classes
+     * is also a scale tone of `other`; each is reported with its numeral in both
+     * keys. A key that stacks no diatonic triads offers nothing to pivot on and
+     * yields an empty list rather than an error.
+     *
+     * @param other The key being entered, as a key name, a plain key/scale, or a
+     *   {@link Key}.
+     * @returns The shared triads, ascending by their degree in this key, each
+     *   chord carrying this key as its context.
+     * @example
+     * ```ts
+     * import { Key } from '@libraz/libcantus';
+     * Key.major('C')
+     *   .pivotsTo('G major')
+     *   .map((pivot) => `${pivot.romanFrom}=${pivot.romanTo}`);
+     * // ['I=IV', 'iii=vi', 'V=I', 'vi=ii']
+     * ```
+     */
+    pivotsTo(other: KeyLike): {
+        chord: Chord;
+        romanFrom: string;
+        romanTo: string;
+    }[];
     /**
      * A scale degree, counted from 1 the way musicians name degrees: `degree(1)`
      * is the tonic and `degree(5)` the dominant.
@@ -2352,6 +2475,11 @@ declare class Key {
      * of C major gives F major. A scale with no diatonic triads — anything that
      * is not heptatonic — falls back to this key's own mode.
      *
+     * The tonic is derived rather than given, so the result is respelled to its
+     * enharmonic key whenever the letter arithmetic lands past the signatures keys
+     * are written with: the fourth degree of a C blues scale reads as F# minor,
+     * not as the Gb minor and its nine flats.
+     *
      * @param n The 1-based scale degree, as {@link Key.degree} counts them.
      * @param mode The mode of the resulting key; inferred when omitted.
      * @returns The key on that degree.
@@ -2454,7 +2582,11 @@ declare class Key {
      * lower than it reads — has its part written a major second higher, and a
      * concert C major becomes D major. The tonic is spelled by the interval, so
      * a concert E flat major reads as F major on that instrument rather than as
-     * E sharp major, and the mode mask is untouched.
+     * E sharp major, and the mode mask is untouched. What the interval spells is
+     * then respelled to its enharmonic key whenever it would not be written that
+     * way, since a part is what a player is actually handed: a concert F# major
+     * on a B flat clarinet reads as A flat major rather than as a G# major with an
+     * F double sharp in its signature.
      *
      * The opposite reading, a written key back to the key it sounds in, is
      * {@link Key.transposeBy} applied to {@link instrumentTransposition} — the
@@ -2469,6 +2601,7 @@ declare class Key {
      * import { Key, instrumentTransposition } from '@libraz/libcantus';
      * Key.major('C').forInstrument('clarinetBb').toString(); // 'D major'
      * Key.major('C').forInstrument('hornF').toString(); // 'G major'
+     * Key.major('F#').forInstrument('clarinetBb').toString(); // 'Ab major'
      * // And back: what a part written in C major on a clarinet in A sounds as.
      * Key.major('C').transposeBy(instrumentTransposition('clarinetA')).toString(); // 'A major'
      * ```
@@ -2574,6 +2707,25 @@ declare class Key {
      * @throws If the numeral is not valid.
      */
     roman(text: string): Chord;
+    /**
+     * The augmented sixth chord of a kind, built in this key.
+     *
+     * The three kinds share the augmented sixth between the lowered sixth degree
+     * and the raised fourth and differ in what fills it: the Italian doubles the
+     * tonic, the French adds the second degree, and the German the third. The
+     * chord is spelled as the interval demands rather than as its enharmonic
+     * dominant seventh, which is what keeps its outward resolution readable.
+     *
+     * @param kind Which augmented sixth to build.
+     * @returns The chord, with this key attached.
+     * @throws If the kind names none of the three.
+     * @example
+     * ```ts
+     * import { Key } from '@libraz/libcantus';
+     * Key.major('C').augmentedSixth('german').rootPc; // 8 (the lowered sixth degree)
+     * ```
+     */
+    augmentedSixth(kind: AugmentedSixthKind): Chord;
     /**
      * Build a progression from Roman numerals in this key.
      *
@@ -2647,13 +2799,20 @@ declare class Key {
      */
     toJSON(): KeyData;
     /**
-     * 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.
+     * The key's tonic and the scale it is read in, so a template literal or a log
+     * line reads as the key.
+     *
+     * The scale word is a function of the scale alone — its root pitch class and
+     * mode mask — rather than of how the key was built, so two keys holding the
+     * same scale print the same name: a harmonic minor names itself one whether
+     * it was detected or asked for by name, and a mode names its mode instead of
+     * the major or minor key its third would make it. What is printed is what
+     * {@link Key.parse} reads back.
      *
      * A `system` names the key the way that notation system writes it, including
-     * German's case convention. The scale form is an English-only qualifier —
-     * the other systems have no word for it — so a detected harmonic minor names
-     * its parallel plain minor there.
+     * German's case convention. The scale word is an English-only qualifier —
+     * the other systems have no word for it — so a harmonic minor names its
+     * parallel plain minor there.
      *
      * @param opts `system` writes the name in that notation system instead of
      *   English.
@@ -2662,8 +2821,8 @@ declare class Key {
      * ```ts
      * import { Key } from '@libraz/libcantus';
      * Key.minor('G#').toString(); // 'G# minor'
+     * Key.named('dorian', 'D').toString(); // 'D dorian'
      * Key.minor('G#').toString({ system: 'german' }); // 'gis moll'
-     * Key.minor('G#').toString({ system: 'japanese' }); // '嬰ト短調'
      * ```
      */
     toString(opts?: NoteNameOptions): string;
@@ -2822,6 +2981,11 @@ declare class Score {
     /**
      * The score moved by a number of semitones.
      *
+     * A carried key moves with the notes, so the score that comes back is read in
+     * the key it now sounds in and every analysis taken from it — its timeline,
+     * its numerals, its phrases — is taken against that key rather than against
+     * the one it was written in.
+     *
      * @param semitones The signed semitone offset.
      * @returns The transposed score.
      * @throws If a note would leave the MIDI range.
@@ -2832,7 +2996,9 @@ declare class Score {
      *
      * Note events carry a MIDI pitch and no spelling of their own, so the
      * interval contributes its size and its direction; a carried key is what
-     * keeps the spelling, and it moves with the notes.
+     * keeps the spelling, and it moves with the notes — by the interval itself,
+     * so an augmented fourth and a diminished fifth land on differently spelled
+     * keys.
      *
      * @param interval An interval name (e.g. `'A4'`, `'-m3'`), plain interval
      *   data, or an {@link Interval}; a descending interval moves down.
@@ -2946,6 +3112,13 @@ declare class Score {
     /**
      * Every key region the score passes through, in time order.
      *
+     * A score that was told its key answers with that key across the whole of it,
+     * as {@link Score.key} and {@link Score.timeline} do: the caller has already
+     * answered the question, and searching for a modulation away from a stated
+     * key would make the option read as a hint where it was given as an
+     * instruction. Only `totalBeats` is read from the options there, since the
+     * rest tune a search that is not run.
+     *
      * @param opts Analysis options; see {@link KeyTimelineOptions}.
      * @returns The regions; empty when nothing sounds.
      */
@@ -2973,7 +3146,7 @@ declare class Score {
      * score.detectKeys()[0]?.key.rootPc; // 0
      * ```
      */
-    detectKeys(opts?: Omit<DetectKeyOptions, 'weights'>): KeyMatch[];
+    detectKeys(opts?: Omit<DetectKeyOptions, 'weights'>): DetectedKeyMatch[];
     /**
      * The phrases the notes fall into.
      *
@@ -3008,6 +3181,10 @@ declare class Score {
     /**
      * The bar-level pulse above the meter.
      *
+     * The cadences come from the score's own harmony unless the caller passes
+     * their own, so this reads the same grouping {@link Score.phrases} builds its
+     * phrases on rather than a second one that ignores where the music closes.
+     *
      * @param opts Analysis options; see {@link HypermeterOptions}.
      * @returns The grouping, its downbeats, a confidence, and a rationale.
      */
@@ -3023,6 +3200,12 @@ declare class Score {
      * A record is a cell, so `Motif.fromData(found)` reaches the
      * transformations without anything being rebuilt by hand.
      *
+     * A melody is one line, so a score holding several is read as its top voice:
+     * notes struck together are one event and the highest of them stands for it.
+     * A piano part read whole therefore answers for the voice a listener follows
+     * rather than for a line assembled from the insides of its chords. Split the
+     * score into lines first to have each of them answered for.
+     *
      * @param opts Cell-length bounds and the recurrence threshold; see
      *   {@link ExtractMotifsOptions}.
      * @returns The motifs found, longest first.
@@ -3043,7 +3226,15 @@ declare class Score {
      * ```
      */
     motifs(opts?: ExtractMotifsOptions): MotifData[];
-    /** The shape the melody traces. */
+    /**
+     * The shape the melody traces.
+     *
+     * A contour is the shape of one line, so a score holding several is read as
+     * its top voice: notes struck together are one event and the highest of them
+     * stands for it, which keeps a chord from being measured as a climb through
+     * its own notes. Split the score into lines first to have each of them
+     * answered for; {@link Score.voices} is what reads the polyphony as polyphony.
+     */
     contour(): MelodicContour;
     /**
      * Each note's role in the harmony sounding under it.
@@ -3055,7 +3246,14 @@ declare class Score {
      * chord — reads every note against C major and no chord at all, which labels
      * the notes as the non-chord tones they are rather than failing.
      *
-     * @param key The key to read the notes in; defaults to the score's own.
+     * A score holds a whole piece rather than a single line, so the notes are read
+     * as the polyphony they are: each note is classified in its own voice, against
+     * everything else sounding under it. That is what a suspension needs — a
+     * dissonance is dissonant against something — and it is what keeps a note of
+     * one voice from being heard as the passing tone of another.
+     *
+     * @param key The key to read the notes in, as a key name, a plain key/scale,
+     *   or a {@link Key}; defaults to the score's own.
      * @returns One annotation per note, in the score's own time order.
      */
     voices(key?: KeyLike): AnalyzedNote[];
@@ -3074,7 +3272,11 @@ declare class Score {
     /**
      * Whether an instrument can play the score, and what makes it hard.
      *
-     * The tempo the third layer needs is the score's own, read at beat 0.
+     * The third layer asks how much time separates two notes, and the score
+     * answers it from its whole tempo map: a passage under an accelerando is
+     * judged at the tempo actually in force across it, the same integral
+     * {@link Score.secondsAt} reports. The beats the issues name are the score's
+     * own.
      *
      * @param instrument The instrument to play it on: a plain
      *   {@link InstrumentProfile} or an {@link Instrument}.
@@ -3338,6 +3540,10 @@ declare class Arrangement {
      * annotations describe the same chords rather than two readings of the same
      * notes.
      *
+     * Naming a key, its regions, or the tracks the harmony is read from asks for
+     * a harmony this arrangement did not find, so the curve is read under the one
+     * named rather than over the one it holds.
+     *
      * @param opts The sampling step, and any setting to lay over the
      *   arrangement's own; a meter named here replaces the arrangement's, since
      *   `ts` and `meters` name the same thing.
@@ -3410,6 +3616,24 @@ type ComposerOptions = {
     instruments?: Record<string, InstrumentProfileLike>;
     /** Extra material the generators may draw from. */
     vocabulary?: readonly Vocabulary<unknown>[];
+    /**
+     * The algorithm version the parts are generated under; defaults to the
+     * version this build produces. Naming it is what closes a reproduction
+     * recipe: a seed alone reproduces a piece only for as long as the algorithms
+     * behind it stay where they were, and a project that recorded the version it
+     * was written under can ask for that version back.
+     */
+    algorithmVersion?: number;
+    /**
+     * Draw from this source instead of one derived from `seed`. Each part still
+     * addresses its own namespace, so parts do not collide.
+     *
+     * A live handle rather than settings, so it is held by reference and left out
+     * of the plain data {@link Composer.data} hands back: a source cannot be
+     * written to a project file, and copying one would hand back a second stream
+     * rather than the same one.
+     */
+    rng?: PositionalRng;
 };
 /**
  * How a bass line is written: what {@link BassLineOptions} asks for minus the
@@ -3469,6 +3693,14 @@ type HarmonizedMelody = {
  * tempo, and the pitched ones in its key, so the scores it hands back line up
  * with each other without being re-contextualized one at a time.
  *
+ * A composer that names no key writes no pitched part: {@link Composer.bass},
+ * {@link Composer.progression} and {@link Composer.counterMelody} refuse rather
+ * than fall back on a key of the library's choosing, which would be a piece in
+ * a key nobody asked for with nothing to say so. {@link Composer.drums} carries
+ * no key and is written either way, and {@link Composer.harmonize} reads a key
+ * off the melody it is given; `with({ key })` carries that key over to the
+ * parts written after it.
+ *
  * Immutable like every other class here: `withSeed` and friends return a new
  * composer rather than reconfiguring this one, so a variation can be written
  * beside the original instead of replacing it.
@@ -3516,15 +3748,23 @@ declare class Composer {
     /**
      * A chord progression, in time.
      *
-     * The chords are laid out one per four-beat bar, which is the grid
-     * {@link generateProgression} writes on whatever meter the composer holds, so
-     * the timeline spans `bars` of four beats and carries the composer's key.
+     * The chords are laid out one per bar of the composer's own meter, so a chord
+     * change falls on a bar line of the piece and the timeline spans `bars` of it:
+     * four beats each in 4/4, three in 3/4, and three in 6/8. Every other part is
+     * written against that grid, and harmony that is not on it drifts further from
+     * the bar line with every repeat.
      *
-     * @param opts Everything the progression generator takes but the key and the
-     *   context, which are the composer's.
+     * @param opts Everything the progression generator takes but the key, the
+     *   meter and the context, which are the composer's.
      * @returns The chords over the beats they sound for.
+     * @throws If the composer names no key: the chords are degrees of one, and
+     *   there is no melody here to read a key from the way
+     *   {@link Composer.harmonize} does.
+     * @throws If the composer's meter changes: one chord per bar has no single bar
+     *   length to be laid out on, and the chords would leave the bar lines at the
+     *   first change rather than follow them.
      */
-    progression(opts: Omit<ProgressionOptions, 'key' | 'ctx'>): Timeline;
+    progression(opts: Omit<ProgressionOptions, 'key' | 'ctx' | 'ts'>): Timeline;
     /**
      * A drum part.
      *
@@ -3536,8 +3776,10 @@ declare class Composer {
      * @param opts Everything the drum generator takes but the meter and the
      *   context, which are the composer's.
      * @returns The hits, as a score.
-     * @throws If the composer's meter is not 4/4, which is the only meter the
-     *   drum patterns are written against.
+     * @throws If the composer's meter is not 4/4 throughout, which is the only
+     *   meter the drum patterns are written against: a piece that opens in 4/4
+     *   and changes later has bars the patterns cannot be laid out on, so the
+     *   request is refused rather than answered with 4/4 bars over the change.
      */
     drums(opts: Omit<DrumsOptions, 'ts' | 'ctx'>): Score;
     /**
@@ -3548,6 +3790,8 @@ declare class Composer {
      * @param opts Everything the bass generator takes but the segments, the key,
      *   the meter and the context; see {@link BassLineSettings}.
      * @returns The line, as a score in the composer's key.
+     * @throws If the composer names no key: the line is written in one, and a
+     *   default key would put the part in a key the caller never asked for.
      * @throws If the instrument names a kit, which has no strings for a bass line
      *   to be placed on.
      * @example
@@ -3574,6 +3818,9 @@ declare class Composer {
      * @param opts Everything the counter-melody generator takes but the melody,
      *   the key, the meter and the context; see {@link CounterMelodySettings}.
      * @returns The counter line, as a score in the composer's key.
+     * @throws If the composer names no key: the line is written in one, and the
+     *   melody it answers is not read for a key here — {@link Composer.harmonize}
+     *   is the member that does that.
      */
     counterMelody(melody: Score, opts?: CounterMelodySettings): Score;
     /**
@@ -3590,8 +3837,7 @@ declare class Composer {
      *   that melody and the one handed in.
      * @example
      * ```ts
-     * import { Composer } from '@libraz/libcantus';
-     * import { Score } from '../../src/model/score.js';
+     * import { Composer, Score } from '@libraz/libcantus';
      * const composer = Composer.of({ key: 'C major' });
      * const melody = Score.of([{ pitch: 60, startBeat: 0, durationBeat: 4 }]);
      * composer.harmonize(melody).transposeSemitones; // 0
@@ -3602,7 +3848,14 @@ declare class Composer {
      * Whether another composer holds the same settings.
      *
      * The comparison is made through the other composer's public data, so two
-     * composers built by different copies of the module still compare.
+     * composers built by different copies of the module still compare. Both sides
+     * are projected the same way: comparing the settings held here against the
+     * data the other hands out answered "different" for a composer holding a
+     * source and "same" for two that draw from different ones.
+     *
+     * A source is compared by identity, being a handle on a stream rather than a
+     * setting: two composers drawing from different sources write different
+     * parts, and the numbers a source will hand out cannot be read from it.
      *
      * @param other The composer to compare.
      * @returns True when both would generate the same parts.
@@ -3610,7 +3863,15 @@ declare class Composer {
     equals(other: Composer): boolean;
     /** The resolved context, for handing back to the function API. */
     get context(): GenerationContext;
-    /** A copy of the settings this composer holds. */
+    /**
+     * A copy of the settings this composer holds: the seed, the resolved
+     * algorithm version and the rest of the recipe, so a piece can be written
+     * again from what a project file stored.
+     *
+     * The source a composer was handed is left out, being a live handle rather
+     * than plain data; a composer built with one keeps it across
+     * {@link Composer.with} and its siblings.
+     */
     get data(): ComposerOptions;
     /** The plain form of the settings, for `JSON.stringify`. */
     toJSON(): ComposerOptions;
@@ -3800,7 +4061,7 @@ declare class Instrument {
      *   tuning, stretch or voice count that is not finite.
      * @example
      * ```ts
-     * import { GUITAR_DROP_D } from '../../src/core/index.js';
+     * import { GUITAR_DROP_D } from '@libraz/libcantus/core';
      * import { Instrument } from '@libraz/libcantus';
      * Instrument.of(GUITAR_DROP_D).range().low; // 38
      * ```
@@ -3902,8 +4163,9 @@ declare class Instrument {
      * what a player does with a line written below the instrument.
      *
      * @param pitch MIDI pitch to place.
-     * @returns The nearest octave transposition the instrument sounds, searching
-     *   upward first; the pitch unchanged when no transposition is available.
+     * @returns The nearest octave transposition the instrument sounds, taking the
+     *   upper one when two are equally near; the pitch unchanged when no
+     *   transposition is available.
      * @example
      * ```ts
      * import { Instrument } from '@libraz/libcantus';
@@ -4087,7 +4349,7 @@ declare class Meter {
     get isCompound(): boolean;
     /** Length of a bar in quarter-note beats. */
     get beatsPerBar(): number;
-    /** Main pulses (felt beats) in a bar: 3 in 6/8, 4 in 4/4. */
+    /** Main pulses (felt beats) in a bar: 2 in 6/8, 4 in 4/4. */
     get pulsesPerBar(): number;
     /**
      * Length of one felt beat in quarter-note beats: a quarter note in simple
@@ -4099,13 +4361,19 @@ declare class Meter {
      * additive grouping and one is asked for.
      *
      * @param opts Set `grouping: true` to render an additive grouping. A
-     *   grouping counted in main pulses cannot be written additively and falls
-     *   back to the plain form.
+     *   grouping counted in main pulses has no additive spelling: one whose
+     *   groups are all the same length states the division the bare signature
+     *   already has and falls back to the plain form, and one whose groups differ
+     *   is refused rather than printed as a bar that weighs its pulses otherwise.
      * @returns The formatted signature.
+     * @throws If `grouping: true` is asked of a grouping that no signature text
+     *   can spell: one counted in main pulses, on a compound numerator, whose
+     *   groups are not all the same length — 12/8 as `[1, 1, 2]`.
      * @example
      * ```ts
      * import { Meter } from '@libraz/libcantus';
      * Meter.of(7, 8, [2, 2, 3]).format({ grouping: true }); // '2+2+3/8'
+     * Meter.of(12, 8, [1, 1, 1, 1]).format({ grouping: true }); // '12/8'
      * ```
      */
     format(opts?: {
@@ -4145,13 +4413,18 @@ declare class Meter {
      *
      * @param beatInQuarters Position in quarter-note beats.
      * @param decimals Digits of the fractional beat to keep.
-     * @returns The formatted position, e.g. `'3.2'` for bar 3, felt beat 2.
+     * @returns The formatted position in one of two forms: `bar.beat` on a felt
+     *   beat, e.g. `'3.2'` for bar 3, felt beat 2; and `bar.beat+fraction`
+     *   between felt beats, e.g. `'3.2+0.5'` halfway from the second felt beat to
+     *   the third. A reader of these strings has to take both, since most onsets
+     *   of an ordinary piece fall between pulses.
      * @throws If the position is not finite or `decimals` is not an integer in
      *   0..100.
      * @example
      * ```ts
      * import { Meter } from '@libraz/libcantus';
      * Meter.parse('6/8').formatPosition(7.5); // '3.2'
+     * Meter.parse('6/8').formatPosition(8.25); // '3.2+0.5'
      * ```
      */
     formatPosition(beatInQuarters: number, decimals?: number): string;
@@ -4212,11 +4485,12 @@ type MotifGenerateOptions = {
     /** Length of the motif in bars of `ts`. */
     bars: number;
     /**
-     * Meter the bars are counted in, which sets the bar length.
+     * Meter the bars are counted in, which sets the bar length, in any form
+     * that names one.
      *
      * @defaultValue 4/4
      */
-    ts?: TimeSignature;
+    ts?: MeterLike;
     /**
      * Melodic contour shape the line follows.
      *
@@ -4314,12 +4588,16 @@ declare class Motif {
     /**
      * The cell put through one of the classical transformations.
      *
-     * `invert` reflects the pitches about the first note and `retrograde` mirrors
-     * the onsets about the cell's span, both self-inverse; `augment` and
+     * `invert` reflects the pitches about the earliest note and `retrograde`
+     * mirrors the onsets about the cell's span, both self-inverse; `augment` and
      * `diminish` scale the note values by `amount` and its reciprocal;
      * `transposeChromatic` moves by semitones; `transposeDiatonic` and `sequence`
      * move by scale degrees with a key in hand, and by semitones without one.
      *
+     * The result's notes run in time order whichever way the source cell was
+     * written, so an inversion of a retrograde reflects about the note that now
+     * sounds first.
+     *
      * @param kind The transformation.
      * @param amount Semitones, scale degrees, or the time factor, as the
      *   transformation reads it.
@@ -4349,21 +4627,26 @@ declare class Motif {
      *   plain chord timeline the analysis layer hands out.
      * @param key The key the passing notes are kept in.
      * @param bars How many bars to fill.
-     * @param ts Meter the bars are counted in; 4/4 when none is named.
+     * @param ts Meter the bars are counted in, in any form that names one. A
+     *   motif carries no meter of its own — it is a run of notes — so there is
+     *   nothing to fall back on, and a development laid on the wrong bar length
+     *   drifts off the part it plays under.
      * @returns The developed motif.
      * @throws If the bar count is not a positive integer.
      */
-    develop(timeline: Timeline | ChordTimeline, key: KeyLike, bars: number, ts?: TimeSignature): Motif;
+    develop(timeline: Timeline | ChordTimeline, key: KeyLike, bars: number, ts: MeterLike): Motif;
     /**
      * How this motif stands to another: the transformation that turns one into
      * the other, named.
      *
      * @param other The statement to name against this one.
-     * @param key Key context for the tonal reading; without it, an answer that
-     *   only holds diatonically is not recognised.
+     * @param key Key context for the tonal reading. Without one an answer holding
+     *   only diatonically is left unnamed unless its interval pattern also fits
+     *   the retrograde family, in which case it is named there; a motif carries no
+     *   key of its own, so this is the only way to have the tonal reading offered.
      * @returns The relation, or null when the two stand in none.
      */
-    relateTo(other: Motif, key?: KeyLike): MotifRelation | null;
+    relateTo(other: Motif, key?: SpelledKeyLike): MotifRelation | null;
     /**
      * How alike two lines are, in [0, 1].
      *
@@ -4458,32 +4741,39 @@ declare class Rhythm {
     /**
      * Generate a pattern over a meter.
      *
-     * @param ts The time signature the bars are counted in.
+     * @param ts The time signature the bars are counted in, in any form that
+     *   names one; a meter map is read as the signature it opens in.
      * @param opts Length, grid resolution and the context; see
      *   {@link RhythmOptions}. The context's `complexity.rhythmic` is the onset
      *   density, and its `seed` fixes which grid slots are taken.
      * @returns The generated pattern.
      * @example
      * ```ts
-     * import { parseTimeSignature } from '@libraz/libcantus';
      * import { Rhythm } from '@libraz/libcantus';
-     * const rhythm = Rhythm.generate(parseTimeSignature('4/4'), {
+     * const rhythm = Rhythm.generate('4/4', {
      *   bars: 2,
      *   ctx: { seed: 7, complexity: { rhythmic: 0.6 } },
      * });
      * rhythm.totalBeats; // 8
      * ```
      */
-    static generate(ts: TimeSignature, opts?: RhythmOptions): Rhythm;
+    static generate(ts: MeterLike, opts?: RhythmOptions): Rhythm;
     /**
      * Build a pattern from onsets that already exist.
      *
+     * The meter is asked for rather than assumed. A pattern in 6/8 read as 4/4
+     * answers every metric question — which beats are strong, where the bars
+     * fall, how dense it is — on the wrong pulse, and nothing downstream can tell
+     * that reading from a meter the caller meant. Its two siblings,
+     * {@link Rhythm.generate} and `generateRhythm`, ask for it the same way.
+     *
      * @param events The onsets, in any order.
-     * @param ts The meter they are counted in; 4/4 when none is named, as every
-     *   meter-aware function in the library assumes.
+     * @param ts The meter they are counted in, in any form that names one.
      * @returns The pattern.
+     * @throws If the meter names no signature, or an onset carries a value a
+     *   pattern cannot hold.
      */
-    static of(events: readonly RhythmEvent[], ts?: TimeSignature): Rhythm;
+    static of(events: readonly RhythmEvent[], ts: MeterLike): Rhythm;
     /** Rebuild a pattern from the plain data {@link Rhythm.data} hands out. */
     static fromData(data: RhythmData): Rhythm;
     /** Rebuild a pattern from its {@link Rhythm.toJSON} output. */
@@ -4505,6 +4795,10 @@ declare class Rhythm {
     /**
      * Drop the onsets carrying the least of the metre.
      *
+     * The metre is the pattern's own: the ranks are read from {@link Rhythm.ts},
+     * so a pattern in 6/8 keeps its dotted-quarter pulses and one in 3/4 keeps its
+     * three-beat downbeats rather than the beats a four-beat bar would have.
+     *
      * @param amount How much to thin, in [0, 1]; at 0 nothing goes, and a full
      *   turn leaves the downbeats alone.
      * @returns The thinned pattern.
@@ -4514,8 +4808,11 @@ declare class Rhythm {
     /**
      * Anticipate beats, one sixteenth early.
      *
-     * The anticipations are added rather than displaced, so raising the amount
-     * only ever adds onsets and the ones already sounding stay where they are.
+     * The beats anticipated are the ones {@link Rhythm.ts} counts as main pulses
+     * or stronger, so a pattern is not syncopated against accents its own meter
+     * does not have. The anticipations are added rather than displaced, so raising
+     * the amount only ever adds onsets and the ones already sounding stay where
+     * they are.
      *
      * @param amount How much syncopation, in [0, 1].
      * @param ctx The context, or the seed alone; it fixes which beats are
@@ -4593,7 +4890,9 @@ declare class Rhythm {
      * @param pitch The MIDI pitch to give every onset.
      * @param velocity Velocity for every onset; a mezzo-forte 96 by default.
      * @returns The score holding the pattern.
-     * @throws If the pitch is not finite or the velocity is outside [0, 127].
+     * @throws If the pitch or the velocity is not a whole MIDI value in [0, 127];
+     *   both are the numbers a note event carries, and a fractional one is not a
+     *   note anything downstream can sound.
      * @example
      * ```ts
      * import { parseTimeSignature } from '@libraz/libcantus';
@@ -4774,18 +5073,20 @@ declare class Tuning {
     /**
      * Wrap a plain tuning table.
      *
-     * The table is checked the way {@link Tuning.edo} checks its arguments, so a
-     * deserialized or hand-written one cannot enter carrying a division count or
-     * a reference frequency no frequency follows from.
+     * Every field is read off the table, so a deserialized or hand-written one
+     * cannot enter carrying a division count or a reference frequency no
+     * frequency follows from. None of the three has a default here, unlike
+     * {@link Tuning.edo}: a table that lost its reference frequency on the way
+     * through storage is refused rather than quietly retuned to A=440.
      *
      * @param table The plain tuning table.
      * @returns The wrapped tuning.
-     * @throws If the divisions are not a positive integer, or the reference step
-     *   or frequency is not a finite positive number.
+     * @throws If a field is missing, the divisions are not a positive integer,
+     *   the reference frequency is not a finite positive number, or the reference
+     *   step is not finite.
      * @example
      * ```ts
-     * import { TWELVE_TET } from '../../src/core/tuning/index.js';
-     * import { Tuning } from '@libraz/libcantus';
+     * import { TWELVE_TET, Tuning } from '@libraz/libcantus';
      * Tuning.of(TWELVE_TET).divisions; // 12
      * ```
      */
@@ -4798,8 +5099,10 @@ declare class Tuning {
      * @param refStep Step index of the reference; 69 by default, the MIDI number
      *   of A4.
      * @returns The tuning.
-     * @throws If the divisions are not a positive integer, or the reference step
-     *   or frequency is not a finite positive number.
+     * @throws If the divisions are not a positive integer, the reference
+     *   frequency is not a finite positive number, or the reference step is not
+     *   finite. A negative or fractional reference step is accepted: it is what a
+     *   tuner reading or a pitch-bend calibration lands on.
      * @example
      * ```ts
      * import { Tuning } from '@libraz/libcantus';
@@ -4858,7 +5161,8 @@ declare class Tuning {
      *
      * @param cents The interval in cents.
      * @returns The frequency ratio.
-     * @throws If `cents` is not finite.
+     * @throws If `cents` is not finite, or the ratio it spans falls outside the
+     *   range a number holds.
      * @example
      * ```ts
      * import { Tuning } from '@libraz/libcantus';
@@ -5057,7 +5361,13 @@ declare class Tuning {
 }
 
 /**
- * The plain form of a {@link Voicing}: the sounding MIDI pitches, ascending.
+ * The plain form of a {@link Voicing}: the sounding MIDI pitches in voice
+ * order, lowest voice first.
+ *
+ * Voice order, not sorted order. A voicing is normally ascending, and one that
+ * is not is exactly what a voice crossing is — the class keeps the order it was
+ * built with so the crossing survives to be reported, so a caller reading the
+ * lowest sounding pitch takes the minimum rather than the first entry.
  *
  * The voicing functions all speak this array, so the class hands out exactly
  * what they take rather than a wrapper of its own.
@@ -5171,6 +5481,10 @@ declare class Voicing {
      * The bass takes the chord's slash bass when it has one, otherwise the root;
      * the result is compact, centred in its ranges, and free of voice crossing.
      *
+     * A chord that carries a key passes it to the voicer, so the leading tone is
+     * not doubled; an explicit `opts.key` overrides it. That is the order
+     * {@link Chord.voice} resolves them in, and the two answer alike.
+     *
      * @param chord A chord symbol, plain chord data, or a {@link Chord}.
      * @param opts Voicing options; defaults to four voices in {@link SATB_RANGES}.
      * @returns The voicing, ascending.
@@ -5228,7 +5542,7 @@ declare class Voicing {
      * @param key A key name, a plain key/scale, or a {@link Key}.
      * @param chord The chord sounding, supplying the enharmonic evidence; without
      *   it the key alone decides.
-     * @returns One spelled note per pitch, ascending.
+     * @returns One spelled note per pitch, in voice order.
      * @throws If the value names no key or no chord.
      * @example
      * ```ts
@@ -5245,7 +5559,13 @@ declare class Voicing {
      * `voices` nor `ranges` is given — within a one-octave window around each of
      * these pitches, so the answer keeps this voicing's voice count. Each is
      * scored by structural quality, motion from here, and a large penalty per
-     * counterpoint violation.
+     * counterpoint violation. A chord that carries a key passes it to the voicer
+     * unless `opts.key` names another one.
+     *
+     * The rules read from the chord being left — a chordal seventh's resolution,
+     * a leading tone's resolution, and the cross relation between the two chords
+     * — are scored only when `opts.previousChord` names that chord: a voicing
+     * does not say what it was written on.
      *
      * @param chord A chord symbol, plain chord data, or a {@link Chord}.
      * @param opts Voicing options; when omitted, the ranges follow this voicing.
@@ -5262,8 +5582,8 @@ declare class Voicing {
     next(chord: ChordLike, opts?: VoicingOptions): Voicing;
     /**
      * The voice-leading cost from this voicing to another: the summed absolute
-     * semitone motion across voices, plus a penalty when the outer voices reach a
-     * perfect fifth or octave by similar motion.
+     * semitone motion across voices, and nothing besides. What the motion breaks
+     * is {@link Voicing.checkTo}'s question.
      *
      * @param other The voicing moved to.
      * @returns The cost, or `Infinity` when the two hold a different number of
@@ -5352,7 +5672,8 @@ declare class Voicing {
      * @param pitch The candidate MIDI pitch.
      * @param query The candidate's harmonic and voice-leading context.
      * @param opts Set `suggestions: false` to skip the search for safe
-     *   replacements when the verdict is not safe.
+     *   replacements when the verdict is not safe, and `partners: true` to learn
+     *   which voice of this voicing, by index, raised each pairwise flag.
      * @returns The verdict, reason bitmask, and optional resolution guidance.
      * @throws If the profile is unknown, a value names no chord or key, or a
      *   pitch is not a MIDI pitch in 0..127.
@@ -5384,13 +5705,14 @@ declare class Voicing {
      * times over.
      *
      * A negative `n` takes the highest voice down an octave as many times, and
-     * `invert(0)` is the voicing itself. Unlike {@link Chord.invert}, which
-     * rotates a chord's interval template, this moves real voices: inverting a
-     * four-voice texture four times leaves the same chord an octave higher. The
-     * result is ascending, since the voice that moved is no longer where it was.
+     * `invert(0)` is the voicing itself, voice order and all. Unlike
+     * {@link Chord.invert}, which rotates a chord's interval template, this moves
+     * real voices: inverting a four-voice texture four times leaves the same chord
+     * an octave higher. A voicing that actually inverts comes back ascending,
+     * since the voice that moved is no longer where it was.
      *
      * @param n How many voices to move, upward when positive.
-     * @returns The inverted voicing, ascending.
+     * @returns The inverted voicing, ascending; this voicing itself when `n` is 0.
      * @throws If `n` is not an integer in [-128, 128], or a voice would leave
      *   MIDI 0..127.
      * @example
@@ -5416,16 +5738,16 @@ declare class Voicing {
      * Private class fields do not serialize, so an explicit `toJSON` keeps
      * `JSON.stringify(voicing)` from collapsing to `{}`.
      *
-     * @returns A copy of the sounding MIDI pitches, ascending.
+     * @returns A copy of the sounding MIDI pitches, in voice order.
      */
     toJSON(): VoicingData;
     /**
      * The pitches separated by spaces, so a template literal or a log line reads
      * as the voicing.
      *
-     * @returns The pitches ascending, e.g. `'60 64 67'`.
+     * @returns The pitches in voice order, e.g. `'60 64 67'`.
      */
     toString(): string;
 }
 
-export { AnalyzeChordOptions, AnalyzedNote, Arrangement, ArrangementAnalysis, type ArrangementData, ArrangementOptions, type ArrangementSettings, type ArrangementSetup, type ArrangementTensionOptions, ArrangementTrack, Articulation, AvailableTensionsOptions, AvoidNotesOptions, BarPosition, BassLineOptions, type BassLineSettings, BassSegment, BorrowedChord, BorrowedSource, CadenceHit, CadenceResult, Chord, ChordAnalysis, Chord$1 as ChordData, ChordLike, ChordMatch, ChordQuality, ChordScaleMatch, ChordScaleReportEntry, ChordSegment, ChordSpan, ChordSpec, ChordSymbolOptions, ChordTimeline, ChordTimelineOptions, ChordToRomanOptions, ChordToneRole, Complexity, Composer, type ComposerOptions, Conflict, CounterMelodyOptions, type CounterMelodySettings, DetectCadenceOptions, DetectChordOptions, DetectKeyOptions, type DetectedKeyMatch, DrumsOptions, Duration, DurationData, EvaluateSafetyOptions, ExplainRomanOptions, ExtractMotifsOptions, FormSection, FormSectionOptions, GenerationContext, GenerationContextInput, GrooveTemplate, HarmonicFunction, HarmonizeOptions, type HarmonizedMelody, HumanizeOptions, Hypermeter, HypermeterOptions, IdentifiedVoiceNote, Instrument, InstrumentProfile, InstrumentProfileLike, Interval, IntervalLike, IntervalQualityLabel, Key, type KeyData, KeyLike, KeyMatch, KeyMode, KeyRegion, KeyRelation, KeyScale, KeyTimelineOptions, KeyVariant, MelodicContour, Meter, MeterLike, MeterMap, Motif, MotifCell, MotifContour, MotifData, type MotifGenerateOptions, MotifNote, MotifRelation, MotifTransform, Note, Note$1 as NoteData, NoteEvent, NoteEventIndex, NoteEventIndexOptions, NoteLike, NoteNameOptions, NoteValue, OrnamentOptions, ParseResult, PartWritingOptions, PartWritingViolation, Phrase, PhraseOptions, PlayabilityReport, Progression, type ProgressionData, ProgressionOptions, ReduceProgressionOptions, ReducedChord, Rhythm, type RhythmData, type RhythmDeformOptions, RhythmEvent, RhythmOptions, RomanExplanation, SafetyQuery, SafetyResult, ScaleChoice, ScaleName, ScaleNameInput, ScaleSystem, Score, type ScoreData, type ScoreOptions, Species, SpeciesOptions, SpelledDuration, SpelledInterval, StringFingering, StructuralCadence, StyledVoicingOptions, SubstituteOptions, Substitution, SubstitutionType, Tempo, type TempoData, TempoMap, TensionPoint, TimeSignature, Timeline, type TimelineData, type TimelineRoman, TrackEdit, TransposingInstrument, Tuning, TuningTable, Tuplet, Vocabulary, VoiceIndependenceOptions, VoiceIndependenceReport, VoiceRange, Voicing, type VoicingData, type VoicingIndependenceOptions, VoicingOptions, type VoicingSafetyQuery };
+export { AnalyzeChordOptions, AnalyzedNote, Arrangement, ArrangementAnalysis, type ArrangementData, ArrangementOptions, type ArrangementSettings, type ArrangementSetup, type ArrangementTensionOptions, ArrangementTrack, Articulation, AugmentedSixthKind, AvailableTensionsOptions, AvoidNotesOptions, BarPosition, BassLineOptions, type BassLineSettings, BassSegment, BorrowedChord, BorrowedSource, CadenceHit, CadenceResult, Chord, ChordAnalysis, Chord$1 as ChordData, ChordLike, ChordMatch, ChordQuality, ChordScaleMatch, ChordScaleReportEntry, ChordSegment, ChordSpan, ChordSpec, ChordSymbolOptions, ChordTimeline, ChordTimelineOptions, ChordToRomanOptions, ChordToneRole, Complexity, Composer, type ComposerOptions, Conflict, CounterMelodyOptions, type CounterMelodySettings, DetectCadenceOptions, DetectChordOptions, DetectKeyOptions, type DetectedKeyMatch, DrumsOptions, Duration, DurationData, EvaluateSafetyOptions, ExplainRomanOptions, ExtractMotifsOptions, FormSection, FormSectionOptions, GenerationContext, GenerationContextInput, GrooveTemplate, HarmonicFunction, HarmonizeOptions, type HarmonizedMelody, HumanizeOptions, Hypermeter, HypermeterOptions, IdentifiedVoiceNote, Instrument, InstrumentProfile, InstrumentProfileLike, Interval, IntervalData, IntervalLike, IntervalQualityLabel, Key, type KeyData, KeyLike, KeyMatch, KeyMode, KeyRegion, KeyRelation, KeyScale, KeyTimelineOptions, KeyVariant, MelodicContour, Meter, MeterLike, MeterMap, Motif, MotifCell, MotifContour, MotifData, type MotifGenerateOptions, MotifNote, MotifRelation, MotifTransform, Note, Note$1 as NoteData, NoteEvent, NoteEventIndex, NoteEventIndexOptions, NoteLike, NoteNameOptions, NoteValue, OrnamentOptions, ParseResult, PartWritingOptions, PartWritingViolation, Phrase, PhraseOptions, PlayabilityReport, PositionalRng, Progression, type ProgressionData, ProgressionOptions, ReduceProgressionOptions, ReducedChord, ResolvedKey, Rhythm, type RhythmData, type RhythmDeformOptions, RhythmEvent, RhythmOptions, RomanExplanation, SafetyQuery, SafetyResult, ScaleChoice, ScaleName, ScaleNameInput, ScaleSystem, Score, type ScoreData, type ScoreOptions, Species, SpeciesOptions, SpelledDuration, SpelledInterval, SpelledKeyLike, StringFingering, StructuralCadence, StyledVoicingOptions, SubstituteOptions, Substitution, SubstitutionType, Tempo, type TempoData, TempoMap, TensionPoint, TimeSignature, Timeline, type TimelineData, type TimelineRoman, TrackEdit, TransposingInstrument, Tuning, TuningTable, Tuplet, Vocabulary, VoiceIndependenceOptions, VoiceIndependenceReport, VoiceRange, Voicing, type VoicingData, type VoicingIndependenceOptions, VoicingOptions, type VoicingSafetyQuery };