@libraz/libcantus 1.0.1 → 1.2.0

package/dist/{index-CCNJRG-P.d.cts → index-B9QLziDe.d.cts}

@@ -1,6 +1,6 @@
-import { f as Note, d as KeyScale, h as NoteLike, I as IntervalLike, S as SpelledInterval } from './index-B9MNZboQ.cjs';
-import { r as ScaleName, u as WorldScaleName, s as ScaleNameInput } from './masks-DYbE485J.cjs';
-import { c as ChordLike, b as Chord, K as KeyLike } from './index-C_8o--VE.cjs';
+import { e as KeyScale, i as NoteLike, j as NoteNameOptions, P as ParseResult, g as Note, b as IntervalLike, S as SpelledInterval } from './index-Cy15oTvh.cjs';
+import { n as ResolvedKey, K as KeyLike, c as ChordLike, b as Chord, r as SpelledKeyLike } from './coerce-DRERzdve.cjs';
+import { r as ScaleName, u as WorldScaleName, s as ScaleNameInput } from './masks-pADfTOiD.cjs';
 
 /**
  * Which of the two modes a key signature is read in.
@@ -17,6 +17,21 @@ import { c as ChordLike, b as Chord, K as KeyLike } from './index-C_8o--VE.cjs';
  * @category Scales
  */
 type KeyMode = 'major' | 'minor';
+/**
+ * Whether a key is one that is actually written with a key signature.
+ *
+ * Each of the seven diatonic modes has a signature of its own, and the harmonic
+ * and melodic minor are the minor key with a degree or two raised: G# harmonic
+ * minor is written with G# minor's five sharps and an F## in front of the note,
+ * which is why it is spelled G# and not Ab. Every other scale only borrows the
+ * signature of its parallel major or minor as an approximation, so nothing
+ * about how it is written follows from that signature — and how such a scale is
+ * spelled has to be decided from the scale itself.
+ *
+ * @param key The key/scale.
+ * @returns True when the signature is the key's own rather than a stand-in.
+ */
+declare function isSignatureKey(key: KeyScale): boolean;
 /**
  * The key signature of a key, as a signed count of sharps (positive) or flats
  * (negative) — the `fifths` value a notation format such as MusicXML writes.
@@ -47,14 +62,14 @@ type KeyMode = 'major' | 'minor';
  * ```
  * @category Scales
  */
-declare function keySignatureFifths(tonic: NoteLike, key: KeyScale): number;
+declare function keySignatureFifths(tonic: NoteLike, key: KeyLike): number;
 /**
  * The key a signature denotes: the inverse of {@link keySignatureFifths} for
  * the two modes a signature is conventionally read in.
  *
  * 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# major).
+ * written, including the theoretical keys past ±7 (nine sharps is D# major).
  *
  * @param fifths The signed number of sharps (positive) or flats (negative).
  * @param mode Which of the signature's two keys to build; defaults to major.
@@ -69,10 +84,7 @@ declare function keySignatureFifths(tonic: NoteLike, key: KeyScale): number;
  * ```
  * @category Scales
  */
-declare function keyFromFifths(fifths: number, mode?: KeyMode): {
-    tonic: Note;
-    key: KeyScale;
-};
+declare function keyFromFifths(fifths: number, mode?: KeyMode): ResolvedKey;
 
 /**
  * Scale systems: which pitch organisations functional harmony was built for,
@@ -168,6 +180,175 @@ declare function scaleSystemOf(scale: KeyScale | ScaleNameInput): ScaleSystem |
  */
 declare function supportsFunctionalHarmony(scale: KeyScale | ScaleNameInput): boolean;
 
+/**
+ * Lead-sheet chord symbol parsing and formatting.
+ *
+ * Bridges the informal `<root><quality>[/<bass>]` notation musicians write
+ * (`Cmaj7`, `F#m7b5`, `Bb7`, `C/G`) and the library's structured {@link Chord}
+ * type, so callers can accept/emit plain text at the edges of the API.
+ *
+ * The root and the slash bass are note names, so they are read and written in
+ * whichever notation system the caller names — a German chart's `H7`, `As7` and
+ * `Ges/B` included. Unlike a note name, a chord symbol is never attributed to a
+ * system on its own: German `B` is a B flat and English `B` a B natural, and a
+ * symbol carries no `dur`/`moll` word to break the tie, so the most common
+ * symbol in the vocabulary would otherwise change chord with the source it came
+ * from. With no system given a symbol is English.
+ */
+
+/**
+ * Parse a lead-sheet chord symbol into a {@link Chord}.
+ *
+ * Accepts `<root><quality>[/<bass>]`, e.g. `Cmaj7`, `F#m7b5`, `Bb7`, `C/G`,
+ * `C6/9`, `C6/9/E`. Root and bass letters are case-insensitive, matching
+ * {@link parseNote}. A `/` is ambiguous between a slash bass and the `6/9`
+ * quality; the text splits at the last `/` whose right-hand side is a valid
+ * bare note preceded by a recognized quality, so `6/9` (with or without a
+ * further slash bass) parses as a quality.
+ *
+ * The root and bass are read in `system`, so a German chart's `H7`, `As7` and
+ * `Ges/B` are read by asking for `'german'`. The system is never inferred: with
+ * none given the symbol is English, where `B` is the B natural and `H` no note
+ * at all. Case carries nothing in a chord symbol — unlike a German key name,
+ * where the case of the tonic is the mode — so the quality suffix alone says
+ * major or minor. Where a German root's flat suffix could equally open the
+ * quality, the longest root that leaves a known quality behind wins: `Asus4` is
+ * an A suspended chord and `Assus4` the A flat one.
+ *
+ * The quality suffix is read structurally when no name covers it, so a chart's
+ * bracketed tensions parse as readily as the names do: `Cmaj7(#11)`,
+ * `C7(b9,#11)`, `C7(13)`, `Csus4(add9)`, `C-Δ9`, `C6/9(#11)`. A `/` between two
+ * figures separates them as it does inside brackets, which is what the sixth
+ * and ninth of a `6/9` are. Such a chord carries the tones it names and reports
+ * the nearest quality name (see {@link chordSpecQuality}); read
+ * {@link chordSpecOf} for its structure.
+ *
+ * The parsed chord carries the root/bass spellings as enharmonic hints
+ * (`rootSpelling`/`bassSpelling`) so {@link formatChordSymbol} can reproduce
+ * flat spellings such as `Bbmaj7` instead of respelling them with sharps.
+ *
+ * @param text The chord symbol text.
+ * @param opts `system` reads the root and bass in that notation system instead
+ *   of English.
+ * @returns The parsed chord.
+ * @throws If the root or quality is not recognized in that system. Use
+ *   {@link tryParseChordSymbol} where failure is ordinary, such as a chord
+ *   field read on every keystroke.
+ * @example
+ * ```ts
+ * import { parseChordSymbol, formatChordSymbol } from '@libraz/libcantus';
+ * const c = parseChordSymbol('Bbmaj7');
+ * formatChordSymbol(c); // 'Bbmaj7' — flat spelling is preserved on round-trip
+ * parseChordSymbol('H7', { system: 'german' }).rootPc; // 11 — the B natural
+ * parseChordSymbol('B', { system: 'german' }).rootPc; // 10 — the German B flat
+ * ```
+ * @category Chords
+ */
+declare function parseChordSymbol(text: string, opts?: NoteNameOptions): Chord;
+/**
+ * Parse a lead-sheet chord symbol, reporting failure instead of throwing it.
+ *
+ * The same reading as {@link parseChordSymbol} — that function is this one with
+ * its error thrown — for the callers where a symbol that does not parse yet is
+ * the normal state of the input rather than a fault: a chord field says what is
+ * wrong with what has been typed so far, and does not need a `try` around every
+ * keystroke to do it.
+ *
+ * @param text The chord symbol text.
+ * @param opts `system` reads the root and bass in that notation system instead
+ *   of English.
+ * @returns The chord, or the error explaining why the text is not one.
+ * @example
+ * ```ts
+ * import { tryParseChordSymbol } from '@libraz/libcantus';
+ * const result = tryParseChordSymbol('Cmaj7(#11)');
+ * result.ok ? result.value.intervals : result.error.message;
+ * ```
+ * @category Chords
+ */
+declare function tryParseChordSymbol(text: string, opts?: NoteNameOptions): ParseResult<Chord>;
+/**
+ * How a chord symbol is written: in which notation system, and on which side of
+ * the enharmonic fence.
+ *
+ * @category Chords
+ */
+type ChordSymbolOptions = NoteNameOptions & {
+    /**
+     * Which side of the staff the whole symbol is written on: `true` writes it in
+     * flats, `false` in sharps. The root, the slash bass and the chord's tones are
+     * spelled together, so a symbol never pairs a flat root with a sharp bass, and
+     * a spelling hint already on the requested side is kept rather than renamed.
+     * Where that side cannot spell the chord at all, the spelling a chart writes
+     * wins over an unwritable one.
+     */
+    flats?: boolean;
+};
+/**
+ * Format a {@link Chord} as a lead-sheet chord symbol.
+ *
+ * The inverse of {@link parseChordSymbol} in every notation system: each
+ * quality maps to one canonical suffix spelling, the root and bass are written
+ * in `system`, and a slash bass is appended only when it differs from the root.
+ * Every symbol written here reads back through {@link parseChordSymbol} as the
+ * same root, sounding bass and tones apart from the degrees the chord omits —
+ * whatever combination of tensions it carries, and whether or not a quality
+ * name covers it. Those omissions are the one difference the round trip has: a
+ * chord that leaves a degree out is written without saying so, so reading the
+ * symbol back puts the degree in.
+ * When the chord carries `rootSpelling`/`bassSpelling` hints (as chords from
+ * {@link parseChordSymbol} do) and no explicit `flats` preference is given, the
+ * hints are reused so flat symbols round-trip unchanged.
+ *
+ * The suffix is written from the chord's own tones (see {@link chordSpecOf}),
+ * not from its quality name, so a chord carrying alterations no name covers is
+ * written out in full — `C7(b9,#11)` — rather than under the nearest name. A
+ * tone the chord leaves out is not written: the symbol names the harmony, so a
+ * fifth-less dominant is still `C7`.
+ *
+ * @param chord The chord to format, as a chord symbol, chord data, or a
+ *   `Chord`.
+ * @param opts `system` writes the root and bass in that notation system instead
+ *   of English; `flats` chooses the side of the staff the whole symbol is
+ *   written on, as {@link ChordSymbolOptions} describes.
+ * @returns The chord symbol text.
+ * @example
+ * ```ts
+ * import { makeChord, formatChordSymbol, parseChordSymbol } from '@libraz/libcantus';
+ * formatChordSymbol(makeChord(0, 'min7')); // 'Cm7'
+ * formatChordSymbol(parseChordSymbol('Bb7'), { system: 'german' }); // 'B7'
+ * formatChordSymbol(parseChordSymbol('B7'), { system: 'german' }); // 'H7'
+ * ```
+ * @category Chords
+ */
+declare function formatChordSymbol(chord: ChordLike, opts?: ChordSymbolOptions): string;
+/**
+ * Transpose a chord symbol by a number of semitones.
+ *
+ * The symbol is read in the same system it is written back in, so a German
+ * chart stays German across the transposition.
+ *
+ * The root and the bass are respelled where moving them by letter would leave
+ * a name no chart writes, so raising a flat chart a semitone gives `Bmaj7`
+ * rather than `Cbmaj7`. Pass `flats` to write the whole symbol on one side of
+ * the staff, root and bass together.
+ *
+ * @param text The chord symbol text.
+ * @param semitones Signed semitone offset to apply to the root and bass.
+ * @param opts Options for reading and writing the symbol; see
+ *   {@link ChordSymbolOptions}.
+ * @returns The transposed chord symbol text.
+ * @throws If `text` does not parse as a chord symbol.
+ * @example
+ * ```ts
+ * import { transposeChordSymbol } from '@libraz/libcantus';
+ * transposeChordSymbol('C/G', 2); // 'D/A'
+ * transposeChordSymbol('H7', 1, { system: 'german' }); // 'C7'
+ * ```
+ * @category Chords
+ */
+declare function transposeChordSymbol(text: string, semitones: number, opts?: ChordSymbolOptions): string;
+
 /**
  * Test whether every chord pitch class is contained in a scale.
  *
@@ -195,18 +376,28 @@ type ChordScaleMatch = {
  * conventional chord-scale relationship. Every entry of {@link NAMED_SCALES}
  * whose pitch-class set is a superset of the chord's is returned once per
  * distinct pitch-class set (aliased masks such as major/ionian report only the
- * modal name), ranked by fewest extra scale tones beyond the chord and then by
- * conventional
- * preference. For bare triads and smaller chords, heptatonic scales rank before
- * pentatonics and other sizes: a pentatonic adds no modal color over a triad,
- * so the seven-note modes are the more useful answer. The chromatic scale is
- * only returned as a fallback when no other scale contains the chord.
- *
- * The ranking is by fit, so the first entry is the tightest-fitting scale
- * rather than the idiomatic choice: a four-note chord that a pentatonic covers
- * exactly puts that pentatonic ahead of the mode a player would name. Read the
- * whole list, or pick by name, when the idiomatic scale is what is wanted;
- * {@link scalesForChanges} makes that choice for a progression.
+ * modal name). The chromatic scale is only returned as a fallback when no other
+ * scale contains the chord.
+ *
+ * The ranking applies these keys in order:
+ *
+ * 1. The idiomatic scales for the chord quality, in the order they are named
+ *    there, ahead of every scale that is not one of them.
+ * 2. For bare triads and smaller chords, heptatonic scales ahead of pentatonics
+ *    and other sizes: a pentatonic adds no modal color over a triad, so the
+ *    seven-note modes are the more useful answer.
+ * 3. Fewest extra scale tones beyond the chord.
+ * 4. Conventional modal preference.
+ * 5. Fewest avoid notes, which separates the symmetric and melodic-minor
+ *    scales the modal preference does not name.
+ * 6. Alphabetical order, so the list is stable.
+ *
+ * The idiomatic key comes first, so the head of the list is the scale a player
+ * would name rather than the tightest fit: over `Cm7b5` the locrian mode leads
+ * even though the blues scale adds fewer tones, because locrian is what a
+ * half-diminished chord is read as. Read further down the list, or pick by name,
+ * when the closest fit is what is wanted; {@link scalesForChanges} makes the
+ * choice for a whole progression.
  *
  * @param chord The chord to fit scales over, as a chord symbol, chord data, or
  *   a `Chord`.
@@ -256,7 +447,9 @@ type AvoidNotesOptions = {
  *
  * @param chord The chord providing the chord tones, as a chord symbol, chord
  *   data, or a `Chord`.
- * @param scaleName A key of {@link NAMED_SCALES}.
+ * @param scaleName A key of {@link NAMED_SCALES}, or an alias of one. A world
+ *   scale is not one: chord-scale theory is a Western practice, so a raga named
+ *   here is rejected rather than answered with a number.
  * @param opts Set `use: 'melodic'` to judge a line rather than a voicing.
  * @returns The avoid-note pitch classes, sorted ascending in [0, 11].
  * @throws If `scaleName` is not a built-in scale. An empty result already
@@ -301,7 +494,8 @@ type AvailableTensionsOptions = {
  *
  * @param chord The chord providing the chord tones, as a chord symbol, chord
  *   data, or a `Chord`.
- * @param scaleName A key of {@link NAMED_SCALES}.
+ * @param scaleName A key of {@link NAMED_SCALES}, or an alias of one; a world
+ *   scale is outside chord-scale theory, as in {@link avoidNotes}.
  * @param opts Set `resolvesTo` to the chord this one resolves to.
  * @returns The available-tension pitch classes, sorted ascending in [0, 11].
  * @throws If `scaleName` is not a built-in scale, as {@link avoidNotes} does.
@@ -551,14 +745,22 @@ type VoicingOptions = {
     /**
      * The prevailing key, as a key name, a key/scale, or a `Key`. Supplying it
      * enables the rules that only make sense relative to a tonic: the leading
-     * tone is neither doubled nor left unresolved. Without it, voicings are
-     * chosen from chord structure and voice-leading distance alone.
+     * tone is not doubled, and — where the chord being left is known as well —
+     * it is not left unresolved. Without it, voicings are chosen from chord
+     * structure and voice-leading distance alone.
      */
     key?: KeyLike;
     /**
-     * The chord that produced the current voicing passed to {@link nextVoicing},
-     * as a chord symbol, chord data, or a `Chord`. When supplied, chordal-seventh
-     * resolution is scored exactly as it is by {@link voiceProgression}.
+     * The chord the current voicing was written on, as a chord symbol, chord
+     * data, or a `Chord`.
+     *
+     * It enables every rule that is read from the chord being left: the
+     * resolution of a chordal seventh, the resolution of a leading tone, and the
+     * cross relation between the two chords. All three are scored exactly as
+     * {@link voiceProgression} scores them, and none of them is scored without
+     * it — a leading tone cannot be told from the third of a chord that merely
+     * contains it until the chord it belongs to is known. Supply it whenever the
+     * caller has the chord, not only where that chord carried a seventh.
      */
     previousChord?: ChordLike;
 };
@@ -587,8 +789,9 @@ declare function voiceChord(chord: ChordLike, opts?: VoicingOptions): number[];
  * Voice a chord progression with smooth, bounded SATB-style leading.
  *
  * Each chord is chosen from a deterministic candidate set, minimizing motion
- * while penalizing counterpoint violations. A supplied key additionally
- * resolves leading tones and chordal sevenths.
+ * while penalizing counterpoint violations, and weighing the violations the
+ * move onto the following chord would then be forced into. A supplied key
+ * additionally resolves leading tones and chordal sevenths.
  *
  * @param chords The chords to voice in order.
  * @param opts Voicing options; defaults to four voices in {@link SATB_RANGES}.
@@ -604,12 +807,21 @@ declare function voiceProgression(chords: readonly ChordLike[], opts?: VoicingOp
  *
  * - `close`: the plain close-position tertian stack.
  * - `drop2`: the second voice from the top dropped an octave (drop-2 voicing).
+ *   It takes at least three voices, since the voice it names has to have
+ *   another below it for the drop to open the stack at all.
  * - `drop3`: the third voice from the top dropped an octave (drop-3 voicing).
+ *   It takes at least four voices, for the same reason.
  * - `shell`: root plus guide tones (third and seventh) for seventh chords, or
  *   root/third/fifth for triads; the fifth and tensions are omitted.
  * - `rootless`: the root omitted, keeping third/fifth/seventh and tensions
  *   (a typical left-hand jazz voicing).
  *
+ * A chord with too few voices for the drop it asks for is voiced in close
+ * position instead: a three-note `drop3` is the close stack, not a stack with
+ * its bottom voice pushed an octave down. A slash bass the chord does not
+ * contain sounds under the stack rather than in it, and is not one of the
+ * voices counted here.
+ *
  * @category Voicing & Counterpoint
  */
 type VoicingStyle = 'close' | 'drop2' | 'drop3' | 'shell' | 'rootless';
@@ -653,23 +865,32 @@ type StyledVoicingOptions = {
  * {@link VoicingStyle} then transforms the stack, and the result is returned as
  * ascending MIDI pitches (index 0 = lowest).
  *
+ * A drop voicing lowers one voice below the rest, so that voice is its bass —
+ * which is what tells the drop-2 voicings of one chord apart. When the chord
+ * names a bass tone of its own, the close stack is therefore rotated so the
+ * style drops that tone, and the result is the drop voicing whose bass is the
+ * tone asked for; the named bass is not lowered under an already dropped voice
+ * afterwards, which would leave a hole wider than an octave in the middle. A
+ * bass the chord does not contain is no voice of the stack and cannot be the
+ * dropped one, so it keeps the bottom and the drop happens above it.
+ *
  * Every returned pitch is a valid MIDI number: an octave whose stack would run
  * off either end of the 0..127 range is rejected rather than voiced out of
  * range, matching {@link nextVoicing}, which clamps its derived ranges.
  *
- * @param chord The chord to voice.
+ * @param given The chord to voice, in whatever form it is held: a chord symbol,
+ *   plain chord data, or a `Chord`.
  * @param opts Styled voicing options; defaults to a close voicing at octave 4.
  * @returns MIDI pitches, ascending, one per retained voice.
  * @throws If the voicing would not fit inside MIDI 0..127 at the given octave.
  * @example
  * ```ts
- * import { parseChordSymbol, voiceChordStyled } from '@libraz/libcantus';
- * const chord = parseChordSymbol('Dm7');
- * voiceChordStyled(chord, { style: 'drop2' }); // ascending MIDI pitches, drop-2 voicing
+ * import { voiceChordStyled } from '@libraz/libcantus';
+ * voiceChordStyled('Dm7', { style: 'drop2' }); // ascending MIDI pitches, drop-2 voicing
  * ```
  * @category Voicing & Counterpoint
  */
-declare function voiceChordStyled(chord: Chord, opts?: StyledVoicingOptions): number[];
+declare function voiceChordStyled(given: ChordLike, opts?: StyledVoicingOptions): number[];
 
 /**
  * Species counterpoint: mark a two-voice exercise against the sixteenth-century
@@ -727,8 +948,12 @@ type SpeciesOptions = {
  * Judged are the vertical intervals under each species' dissonance licence
  * (none in the first, a passing dissonance on the weak half in the second and
  * third, a prepared suspension on the downbeat in the fourth, both in the
- * fifth; the third and fifth species also write the *nota cambiata* and the
- * double neighbour, which quit a dissonance by leap), parallel and hidden
+ * fifth; the neighbour that turns back on its own note belongs to the
+ * quarter-note line of the third and fifth species, which also write the *nota
+ * cambiata* and the double neighbour, quitting a dissonance by leap). A note
+ * still sounding when the next cantus-firmus note is struck is judged against
+ * that note too, so a ligature carried across the bar line is read where it
+ * lands as well as where it began. Judged besides are parallel and hidden
  * perfects and the *battuta* between the voices, augmented and otherwise
  * forbidden leaps along the counterpoint, the shape of the counterpoint as a
  * line, and the opening and closing formulas. Violations name the cantus firmus
@@ -737,7 +962,7 @@ type SpeciesOptions = {
  * @param cantusFirmus The given voice, one spelled note per measure.
  * @param counterpoint The written voice, in spelled notes.
  * @param species Which species the exercise is written in.
- * @param mode The mode the exercise is in.
+ * @param modeLike The mode the exercise is in.
  * @param opts Note lengths, and which side the counterpoint is written on.
  * @returns Every violation found, in the order the exercise commits them; an
  *   empty array for a clean exercise.
@@ -752,7 +977,7 @@ type SpeciesOptions = {
  * ```
  * @category Voicing & Counterpoint
  */
-declare function checkSpecies(cantusFirmus: readonly Note[], counterpoint: readonly Note[], species: Species, mode: KeyScale, opts?: SpeciesOptions): PartWritingViolation[];
+declare function checkSpecies(cantusFirmus: readonly Note[], counterpoint: readonly Note[], species: Species, modeLike: KeyLike, opts?: SpeciesOptions): PartWritingViolation[];
 
 /**
  * Part writing: grade a finished exercise against the classical four-part rules.
@@ -774,7 +999,10 @@ declare function checkSpecies(cantusFirmus: readonly Note[], counterpoint: reado
  *   kind between one pair of voices. A parallel unison is reported as a
  *   `parallelOctave`, since it is the same perfect class.
  * - `hiddenPerfect`: the outer voices reach a perfect fifth or octave by similar
- *   motion with a leap in the upper voice.
+ *   motion with a leap in the upper voice. The leap is what exposes it in a
+ *   four-part texture; in a two-voice species exercise nothing covers the
+ *   arrival, so similar motion into a perfect interval is reported however the
+ *   upper voice got there.
  * - `crossRelation`: one letter carries two different accidentals in two
  *   different voices across a chord change, exposed — neither note led into by
  *   step, at least one of them in an outer voice, and neither chord one of the
@@ -787,8 +1015,11 @@ declare function checkSpecies(cantusFirmus: readonly Note[], counterpoint: reado
  * The rest are raised by {@link checkSpecies} alone, since they describe faults
  * only a species exercise can commit:
  *
- * - `wrongRhythmicRatio`: the counterpoint does not present the number of notes
- *   per cantus-firmus note its species requires.
+ * - `wrongRhythmicRatio`: the counterpoint's rhythm does not read against the
+ *   cantus firmus as its species requires — the wrong number of notes per
+ *   cantus-firmus note, and, in the fifth species, note values the style does
+ *   not write or a `durations` array that does not describe the counterpoint it
+ *   was given.
  * - `unpreparedDissonance`: a dissonance falls where the species allows none, or
  *   is reached or left by leap where it must be passed through by step.
  * - `unresolvedSuspension`: a fourth-species suspension that does not fall by
@@ -835,8 +1066,9 @@ type PartWritingViolation = {
     rationale: string;
 };
 /**
- * A chord realized as one spelled note per voice, ascending (index 0 = lowest),
- * matching the voice order {@link voiceChord} and {@link SATB_RANGES} use.
+ * A chord realized as one spelled note per voice, in voice order (index 0 =
+ * bass), matching the order {@link voiceChord} and {@link SATB_RANGES} use.
+ * Pitches need not ascend; a crossing is a reportable violation.
  *
  * Every note must carry an octave: the rules measure real distances between
  * sounding pitches, which a bare pitch class does not have.
@@ -872,11 +1104,14 @@ type PartWritingOptions = {
  * {@link checkPartWriting}.
  *
  * Each pitch is named against the chord sounding under it and then the key, so a
- * chord tone takes the letter its interval above the root implies: the third of
- * a D major chord in C major spells F#, not Gb. The octave is kept, since the
+ * chord tone takes the letter the degree it plays in that chord implies: the
+ * third of a D major chord in C major spells F#, not Gb. The chord is passed
+ * whole rather than by its root, so a chord carrying its own spelling names its
+ * tones here exactly as {@link spellChord} names them — the German sixth keeps
+ * the F# that resolves outward to the dominant. The octave is kept, since the
  * rules measure real distances.
  *
- * @param voicing MIDI pitches, ascending (index 0 = lowest).
+ * @param voicing MIDI pitches in voice order (index 0 = bass).
  * @param chord The chord sounding, supplying the enharmonic evidence.
  * @param key The key the exercise is written in.
  * @returns One spelled note per pitch, in the same order.
@@ -888,13 +1123,14 @@ type PartWritingOptions = {
  * ```
  * @category Voicing & Counterpoint
  */
-declare function spellVoicing(voicing: readonly number[], chord: Chord, key: KeyScale): SpelledVoicing;
+declare function spellVoicing(voicing: readonly number[], chord: Chord, key: SpelledKeyLike): SpelledVoicing;
 /**
  * Check a finished part-writing exercise and report every rule it breaks.
  *
- * The voicings are given one per chord, each ascending with one spelled note per
- * voice (index 0 = lowest, the bass), the voice order {@link voiceChord} and
- * {@link SATB_RANGES} already use. Notes must carry octaves.
+ * The voicings are given one per chord, each with one spelled note per voice in
+ * voice order (index 0 = bass), the order {@link voiceChord} and
+ * {@link SATB_RANGES} already use. Notes must carry octaves. A crossing is
+ * reported rather than rejected.
  *
  * Each chord is checked for voice crossing, over-wide spacing between adjacent
  * upper voices, and voices outside their range; each pair of consecutive chords
@@ -902,9 +1138,9 @@ declare function spellVoicing(voicing: readonly number[], chord: Chord, key: Key
  * melodic intervals, and unresolved tendency tones. Violations come back in
  * musical order: the rules inside a chord, then the rules taking it to the next.
  *
- * @param voicings One voicing per chord, ascending, in spelled notes.
+ * @param voicings One voicing per chord, in voice order, in spelled notes.
  * @param chords The chords those voicings realize, in the same order.
- * @param key The key the exercise is written in; it names the leading tone.
+ * @param keyLike The key the exercise is written in; it names the leading tone.
  * @param opts Ranges and the upper-voice spacing limit. Both are validated
  *   before any rule runs: an empty result has to mean that nothing was broken,
  *   never that a rule could not be evaluated.
@@ -927,7 +1163,7 @@ declare function spellVoicing(voicing: readonly number[], chord: Chord, key: Key
  * ```
  * @category Voicing & Counterpoint
  */
-declare function checkPartWriting(voicings: readonly SpelledVoicing[], chords: readonly Chord[], key: KeyScale, opts?: PartWritingOptions): PartWritingViolation[];
+declare function checkPartWriting(voicings: readonly SpelledVoicing[], chords: readonly Chord[], keyLike: KeyLike, opts?: PartWritingOptions): PartWritingViolation[];
 
 /**
  * Transposing instruments: the fixed interval between the pitch a player reads
@@ -1032,7 +1268,8 @@ type TransposingInstrument = TransposingInstrumentName | (string & {}) | Exclude
  * import { instrumentTransposition } from '@libraz/libcantus';
  * instrumentTransposition('clarinetA');
  * // { number: 3, quality: 'm', semitones: -3, descending: true }
- * instrumentTransposition('piccolo'); // { number: 8, quality: 'P', semitones: 12 }
+ * instrumentTransposition('piccolo');
+ * // { number: 8, quality: 'P', semitones: 12, descending: false }
  * ```
  * @category Pitch & Intervals
  */
@@ -1092,4 +1329,4 @@ declare function toSoundingPitch(note: NoteLike, instrument: TransposingInstrume
  */
 declare function toWrittenPitch(note: NoteLike, instrument: TransposingInstrument): Note;
 
-export { type AvailableTensionsOptions as A, keySignatureFifths as B, type ChordScaleMatch as C, scaleMatchesChord as D, scaleSystemOf as E, scalesForChanges as F, spellVoicing as G, supportsFunctionalHarmony as H, toSoundingPitch as I, toWrittenPitch as J, type KeyMode as K, voiceChord as L, voiceChordStyled as M, voiceIndependence as N, voiceProgression as O, type PartWritingOptions as P, SATB_RANGES as S, TRANSPOSING_INSTRUMENTS as T, type VoiceIndependenceOptions as V, type AvoidNoteUse as a, type AvoidNotesOptions as b, type ChordScaleReportEntry as c, type PartWritingViolation as d, type PartWritingViolationKind as e, SCALE_SYSTEMS as f, type ScaleChoice as g, type ScaleSystem as h, type Species as i, type SpeciesOptions as j, type SpelledVoicing as k, type StyledVoicingOptions as l, type TransposingInstrument as m, type TransposingInstrumentName as n, type VoiceIndependenceReport as o, type VoiceRange as p, type VoicingOptions as q, type VoicingStyle as r, availableTensions as s, avoidNotes as t, checkPartWriting as u, checkSpecies as v, chordScaleReport as w, chordScales as x, instrumentTransposition as y, keyFromFifths as z };
+export { type AvailableTensionsOptions as A, instrumentTransposition as B, type ChordScaleMatch as C, isSignatureKey as D, keyFromFifths as E, keySignatureFifths as F, parseChordSymbol as G, scaleMatchesChord as H, scaleSystemOf as I, scalesForChanges as J, type KeyMode as K, spellVoicing as L, supportsFunctionalHarmony as M, toSoundingPitch as N, toWrittenPitch as O, type PartWritingOptions as P, transposeChordSymbol as Q, tryParseChordSymbol as R, SATB_RANGES as S, TRANSPOSING_INSTRUMENTS as T, voiceChord as U, type VoiceIndependenceOptions as V, voiceChordStyled as W, voiceIndependence as X, voiceProgression as Y, type AvoidNoteUse as a, type AvoidNotesOptions as b, type ChordScaleReportEntry as c, type ChordSymbolOptions as d, type PartWritingViolation as e, type PartWritingViolationKind as f, SCALE_SYSTEMS as g, type ScaleChoice as h, type ScaleSystem as i, type Species as j, type SpeciesOptions as k, type SpelledVoicing as l, type StyledVoicingOptions as m, type TransposingInstrument as n, type TransposingInstrumentName as o, type VoiceIndependenceReport as p, type VoiceRange as q, type VoicingOptions as r, type VoicingStyle as s, availableTensions as t, avoidNotes as u, checkPartWriting as v, checkSpecies as w, chordScaleReport as x, chordScales as y, formatChordSymbol as z };