@libraz/libcantus 1.0.1 → 1.2.0

package/dist/theory/index.d.cts

@@ -1,21 +1,20 @@
-import { d as KeyScale, S as SpelledInterval, f as Note, h as NoteLike } from '../index-B9MNZboQ.cjs';
-export { B as BudgetExceededError, I as IntervalLike, b as IntervalQualityLabel, c as InvalidInputError, L as LibcantusError, N as NoSolutionError, i as NoteNameOptions, j as NoteNameSystem, P as ParseResult } from '../index-B9MNZboQ.cjs';
+import { e as KeyScale, j as NoteNameOptions, P as ParseResult, S as SpelledInterval, g as Note, i as NoteLike } from '../index-Cy15oTvh.cjs';
+export { B as BudgetExceededError, I as IntervalData, b as IntervalLike, c as IntervalQualityLabel, d as InvalidInputError, L as LibcantusError, N as NoSolutionError, k as NoteNameSystem } from '../index-Cy15oTvh.cjs';
 import { C as ConsonanceClass } from '../index-DInQqT8Q.cjs';
-import { K as KeyLike, c as ChordLike, b as Chord } from '../index-C_8o--VE.cjs';
-export { A as Alteration, a as AlteredDegree, C as ChordBase, d as ChordQuality, e as ChordSegment, f as ChordSeventh, g as ChordSpan, h as ChordSpec, i as ChordSymbolOptions, j as ChordToneRole, E as EvaluateSafetyOptions, k as KeyRelation, N as NoteSafety, P as PROFILE_WEIGHTS, l as PitchSpelling, m as ProfileWeights, R as ReasonFlag, S as SafetyProfile, n as SafetyQuery, o as SafetyResult, p as SpelledKey, V as VoiceSnapshot, q as chordFromDegree, r as chordFromSpan, s as chordFromSpec, t as chordPitchClasses, u as chordQualities, v as chordSpecIntervals, w as chordSpecOf, x as chordSpecQuality, y as chordToneRole, z as diatonicSeventh, B as diatonicTriad, D as dominantKeyOf, F as enharmonicKeyOf, G as enumerateSafePitches, H as evaluateSafety, I as formatChordSymbol, J as intervalAboveRoot, L as isChordMember, M as keyRelationBetween, O as makeChord, Q as parallelKeyOf, T as parseChordSymbol, U as profileWeights, W as relatedKeysOf, X as relativeKeyOf, Y as spanFromChord, Z as spelledKeyOf, _ as subdominantKeyOf, $ as toChordData, a0 as toKeyScale, a1 as transposeChord, a2 as transposeChordSymbol, a3 as tryParseChordSymbol } from '../index-C_8o--VE.cjs';
-import { q as VoicingOptions } from '../index-CCNJRG-P.cjs';
-export { A as AvailableTensionsOptions, a as AvoidNoteUse, b as AvoidNotesOptions, C as ChordScaleMatch, c as ChordScaleReportEntry, K as KeyMode, P as PartWritingOptions, d as PartWritingViolation, e as PartWritingViolationKind, S as SATB_RANGES, f as SCALE_SYSTEMS, g as ScaleChoice, h as ScaleSystem, i as Species, j as SpeciesOptions, k as SpelledVoicing, l as StyledVoicingOptions, T as TRANSPOSING_INSTRUMENTS, m as TransposingInstrument, n as TransposingInstrumentName, V as VoiceIndependenceOptions, o as VoiceIndependenceReport, p as VoiceRange, r as VoicingStyle, s as availableTensions, t as avoidNotes, u as checkPartWriting, v as checkSpecies, w as chordScaleReport, x as chordScales, y as instrumentTransposition, z as keyFromFifths, B as keySignatureFifths, D as scaleMatchesChord, E as scaleSystemOf, F as scalesForChanges, G as spellVoicing, H as supportsFunctionalHarmony, I as toSoundingPitch, J as toWrittenPitch, L as voiceChord, M as voiceChordStyled, N as voiceIndependence, O as voiceProgression } from '../index-CCNJRG-P.cjs';
-export { H as HarmonyRole, L as LockLevel, V as VoicedRole, r as roleOf } from '../index-B4o55NDr.cjs';
-import { s as ScaleNameInput } from '../masks-DYbE485J.cjs';
-export { A as ALTERED_MASK, B as BLUES_MASK, C as CHROMATIC_MASK, D as DORIAN_MASK, a as DOUBLE_HARMONIC_MASK, H as HARMONIC_MINOR_MASK, L as LOCRIAN_MASK, b as LOCRIAN_NATURAL2_MASK, c as LYDIAN_DOMINANT_MASK, d as LYDIAN_MASK, M as MAJOR_MASK, e as MAJOR_PENTATONIC_MASK, f as MARWA_MASK, g as MELODIC_MINOR_MASK, h as MINOR_PENTATONIC_MASK, i as MIXOLYDIAN_B13_MASK, j as MIXOLYDIAN_MASK, k as MIYAKO_BUSHI_MASK, N as NAMED_SCALES, l as NATURAL_MINOR_MASK, O as OCTATONIC_HALF_WHOLE_MASK, m as OCTATONIC_WHOLE_HALF_MASK, P as PHRYGIAN_DOMINANT_MASK, n as PHRYGIAN_MASK, o as PURVI_MASK, R as RITSU_MASK, p as RYUKYU_MASK, S as SCALE_ALIASES, q as ScaleAliasName, r as ScaleName, T as TODI_MASK, W as WHOLE_TONE_MASK, t as WORLD_SCALES, u as WorldScaleName, v as maskFromOffsets, w as namedScaleMask, x as requireScaleMask, y as resolveScaleName } from '../masks-DYbE485J.cjs';
+import { K as KeyLike, n as ResolvedKey, s as SpelledKeyScale, c as ChordLike, b as Chord, r as SpelledKeyLike } from '../coerce-DRERzdve.cjs';
+export { A as Alteration, a as AlteredDegree, C as ChordBase, d as ChordQuality, e as ChordSegment, f as ChordSeventh, g as ChordSpan, h as ChordSpec, i as ChordToneRole, E as EvaluateSafetyOptions, j as KeyRelation, k as KeyVariant, N as NoteSafety, P as PROFILE_WEIGHTS, l as PitchSpelling, m as ProfileWeights, R as ReasonFlag, S as SafetyPartner, o as SafetyProfile, p as SafetyQuery, q as SafetyResult, V as VoiceSnapshot, t as chordFromDegree, u as chordFromSpan, v as chordFromSpec, w as chordPitchClasses, x as chordQualities, y as chordSpecIntervals, z as chordSpecOf, B as chordSpecQuality, D as chordToneRole, F as diatonicSeventh, G as diatonicTriad, H as dominantKeyOf, I as enharmonicKeyOf, J as enumerateSafePitches, L as evaluateSafety, M as intervalAboveRoot, O as isChordMember, Q as keyRelationBetween, T as makeChord, U as parallelKeyOf, W as profileWeights, X as relatedKeysOf, Y as relativeKeyOf, Z as spanFromChord, _ as spelledKeyOf, $ as subdominantKeyOf, a0 as toChordData, a1 as toKeyScale, a2 as transposeChord } from '../coerce-DRERzdve.cjs';
+import { r as VoicingOptions } from '../index-B9QLziDe.cjs';
+export { A as AvailableTensionsOptions, a as AvoidNoteUse, b as AvoidNotesOptions, C as ChordScaleMatch, c as ChordScaleReportEntry, d as ChordSymbolOptions, K as KeyMode, P as PartWritingOptions, e as PartWritingViolation, f as PartWritingViolationKind, S as SATB_RANGES, g as SCALE_SYSTEMS, h as ScaleChoice, i as ScaleSystem, j as Species, k as SpeciesOptions, l as SpelledVoicing, m as StyledVoicingOptions, T as TRANSPOSING_INSTRUMENTS, n as TransposingInstrument, o as TransposingInstrumentName, V as VoiceIndependenceOptions, p as VoiceIndependenceReport, q as VoiceRange, s as VoicingStyle, t as availableTensions, u as avoidNotes, v as checkPartWriting, w as checkSpecies, x as chordScaleReport, y as chordScales, z as formatChordSymbol, B as instrumentTransposition, D as isSignatureKey, E as keyFromFifths, F as keySignatureFifths, G as parseChordSymbol, H as scaleMatchesChord, I as scaleSystemOf, J as scalesForChanges, L as spellVoicing, M as supportsFunctionalHarmony, N as toSoundingPitch, O as toWrittenPitch, Q as transposeChordSymbol, R as tryParseChordSymbol, U as voiceChord, W as voiceChordStyled, X as voiceIndependence, Y as voiceProgression } from '../index-B9QLziDe.cjs';
+export { H as HarmonyRole, L as LockLevel, V as VoicedRole, r as roleOf } from '../index-BL5N2Oyz.cjs';
+import { s as ScaleNameInput } from '../masks-pADfTOiD.cjs';
+export { A as ALTERED_MASK, B as BLUES_MASK, C as CHROMATIC_MASK, D as DORIAN_MASK, a as DOUBLE_HARMONIC_MASK, H as HARMONIC_MINOR_MASK, L as LOCRIAN_MASK, b as LOCRIAN_NATURAL2_MASK, c as LYDIAN_DOMINANT_MASK, d as LYDIAN_MASK, M as MAJOR_MASK, e as MAJOR_PENTATONIC_MASK, f as MARWA_MASK, g as MELODIC_MINOR_MASK, h as MINOR_PENTATONIC_MASK, i as MIXOLYDIAN_B13_MASK, j as MIXOLYDIAN_MASK, k as MIYAKO_BUSHI_MASK, N as NAMED_SCALES, l as NATURAL_MINOR_MASK, O as OCTATONIC_HALF_WHOLE_MASK, m as OCTATONIC_WHOLE_HALF_MASK, P as PHRYGIAN_DOMINANT_MASK, n as PHRYGIAN_MASK, o as PURVI_MASK, R as RITSU_MASK, p as RYUKYU_MASK, S as SCALE_ALIASES, q as ScaleAliasName, r as ScaleName, T as TODI_MASK, W as WHOLE_TONE_MASK, t as WORLD_SCALES, u as WorldScaleName, v as assertKeyVariant, w as assertModeMask, x as maskFromOffsets, y as namedScaleMask, z as requireScaleMask, E as resolveScaleName, F as variantOfMask } from '../masks-pADfTOiD.cjs';
 
 /**
  * Test whether a pitch belongs to the scale.
  *
  * @param pitch MIDI pitch or bare pitch class.
- * @param key The key/scale to test against. This predicate reads the mask as
- *   given rather than taking a key name: the spelling search runs it over
- *   masks that name no key, which resolving a name would refuse.
+ * @param key The key/scale to test against, as a key name, a key/scale, or a
+ *   `Key`.
  * @returns True if the pitch class is a member of the scale.
  *
  * @example
@@ -28,7 +27,7 @@ export { A as ALTERED_MASK, B as BLUES_MASK, C as CHROMATIC_MASK, D as DORIAN_MA
  *
  * @category Scales
  */
-declare function isScaleTone(pitch: number, key: KeyScale): boolean;
+declare function isScaleTone(pitch: number, key: KeyLike): boolean;
 /**
  * Find the nearest MIDI pitch whose pitch class is in the scale.
  *
@@ -42,6 +41,71 @@ declare function isScaleTone(pitch: number, key: KeyScale): boolean;
  * @category Scales
  */
 declare function nearestScaleTone(pitch: number, key: KeyLike): number;
+/**
+ * Where a pitch sits on the key's ladder of scale tones.
+ *
+ * `rung` counts scale tones from the tonic and continues across octaves, so
+ * adding to it moves by scale degrees; it is negative below the tonic of octave
+ * 0. `offset` is how many semitones the pitch sounds above that rung, which is 0
+ * for a scale tone and positive for one between two of them.
+ */
+type ScaleLadderPosition = {
+    rung: number;
+    offset: number;
+};
+/**
+ * Locate a pitch on the key's ladder of scale tones.
+ *
+ * Anything counting in scale degrees has to put a pitch on this ladder and back
+ * again afterwards. Keeping the chromatic offset apart from the rung is what
+ * lets a note between two scale tones survive the arithmetic as the note it was:
+ * without it a shift by any number of degrees — including none — would first
+ * flatten every chromatic pitch onto the scale.
+ *
+ * In C major, C# sits on the tonic's rung with an offset of one semitone.
+ *
+ * Layer-internal: the generators count degrees with it, and callers reach the
+ * same arithmetic through the transforms that use it.
+ *
+ * @param pitch MIDI pitch.
+ * @param key The key/scale to count along, as a key name, a key/scale, or a
+ *   `Key`.
+ * @returns The rung the pitch sits on and its semitone offset above it.
+ */
+declare function scaleLadderPosition(pitch: number, key: KeyLike): ScaleLadderPosition;
+/**
+ * The pitch a rung of the key's ladder of scale tones stands for.
+ *
+ * The inverse of {@link scaleLadderPosition}'s `rung`: adding the position's
+ * `offset` back to the result returns the pitch it came from.
+ *
+ * Layer-internal, like {@link scaleLadderPosition}.
+ *
+ * @param rung Scale tones counted from the tonic, negative below it.
+ * @param key The key/scale to count along, as a key name, a key/scale, or a
+ *   `Key`.
+ * @returns The MIDI pitch of that scale tone.
+ */
+declare function scaleLadderPitch(rung: number, key: KeyLike): number;
+/**
+ * Shift a pitch by scale degrees along the key's ladder of scale tones.
+ *
+ * A pitch between two scale tones keeps its distance above the one below it, so
+ * a chromatic passing note is still a chromatic passing note after the shift,
+ * and a shift of no degrees returns the pitch untouched: a step up the C-major
+ * ladder answers C# with D#, not with D.
+ *
+ * Layer-internal. It is what `transposeDiatonic` and a tonal imitation both
+ * count along, so the two answer the same shift the same way; a caller reaches
+ * it through either of them.
+ *
+ * @param pitch MIDI pitch to shift.
+ * @param degrees Scale degrees to move by; negative moves down.
+ * @param key The key/scale to count along, as a key name, a key/scale, or a
+ *   `Key`.
+ * @returns The shifted pitch.
+ */
+declare function shiftByScaleDegrees(pitch: number, degrees: number, key: KeyLike): number;
 /**
  * Get the scale degree of a pitch, counted from 1: the tonic is degree 1.
  *
@@ -60,28 +124,74 @@ declare function pitchToScaleDegree(pitch: number, key: KeyLike): number;
 /**
  * List the pitch classes of a key's scale.
  *
- * @param key The key/scale to enumerate. The two enumerators here take a plain
- *   key/scale rather than a key name: they read the mask as given, including
- *   the tonic-less masks the spelling search works through, which no key name
- *   describes.
+ * @param key The key/scale to enumerate, as a key name, a key/scale, or a `Key`.
  * @returns The member pitch classes, sorted ascending in [0, 11].
  *
  * @category Scales
  */
-declare function diatonicPitchClasses(key: KeyScale): number[];
+declare function diatonicPitchClasses(key: KeyLike): number[];
 /**
  * List the pitch classes of a key's scale in ascending scale-degree order.
  *
  * The first entry is the root (degree 1); degrees follow the mask bits in
  * offset order rather than sorted pitch-class order.
  *
- * @param key The key/scale to enumerate, read as given for the reason
- *   {@link diatonicPitchClasses} gives.
+ * @param key The key/scale to enumerate, as a key name, a key/scale, or a `Key`.
  * @returns The member pitch classes ordered by scale degree.
  *
  * @category Scales
  */
-declare function scaleTonesInDegreeOrder(key: KeyScale): number[];
+declare function scaleTonesInDegreeOrder(key: KeyLike): number[];
+
+/**
+ * Resolve any key-shaped value to the whole key it names.
+ *
+ * The counterpart of {@link toKeyScale}, and the one to prefer: both read the
+ * same shapes, but this one keeps what it read. A caller that genuinely wants
+ * only the pitch classes asks for them with {@link scaleOf}, which says so at
+ * the place it happens.
+ *
+ * What the value does not carry is derived rather than dropped: a bare scale is
+ * spelled by {@link spelledKeyOf}, the same reading the rest of the library
+ * uses, and its form is read from its mask. A key that carries a spelled tonic
+ * keeps that one — the caller's spelling outranks any the library would pick.
+ * A name carries one too, and it is kept: `'Ab minor'` resolves to an A flat
+ * minor rather than being reduced to pitch classes and spelled back as the G#
+ * minor those read best as.
+ *
+ * What it carries is checked rather than trusted. Accepting a wide range of
+ * shapes is not the same as accepting whatever those shapes hold, and a key
+ * whose tonic or form contradicts its own scale is refused here in the words
+ * `Key.of` refuses it — the two APIs answer the same input alike, and the
+ * refusal reaches every entry point built on this one.
+ *
+ * @param value A key name, a plain key/scale, a resolved key, or a value whose
+ *   `toJSON` returns one of those.
+ * @returns The key, whole.
+ * @throws If the value names no key, its mask is out of range or excludes its
+ *   own root, its tonic spells a pitch class its scale is not rooted on, or its
+ *   form is not one that mask holds.
+ * @example
+ * ```ts
+ * import { formatNote, resolveKey } from '@libraz/libcantus';
+ * formatNote(resolveKey('Ab minor').tonic); // 'Ab'
+ * resolveKey('C major').tonic.letter; // 0
+ * ```
+ * @category Scales
+ */
+declare function resolveKey(value: KeyLike): ResolvedKey;
+/**
+ * The pitch classes of a key, with its spelling and form deliberately dropped.
+ *
+ * Named so that dropping them is something a reader can see. A layer that
+ * reduces a key silently is where an Ab minor becomes a G# minor, and the only
+ * way to keep finding those is to make the reduction say its own name.
+ *
+ * @param key The key to read.
+ * @returns Its pitch classes alone.
+ * @category Scales
+ */
+declare function scaleOf(key: ResolvedKey): KeyScale;
 
 /**
  * Build a `KeyScale` for a major key on the given root pitch class.
@@ -94,7 +204,7 @@ declare function scaleTonesInDegreeOrder(key: KeyScale): number[];
  *
  * @category Scales
  */
-declare function majorKey(rootPc: number): KeyScale;
+declare function majorKey(rootPc: number): SpelledKeyScale;
 /**
  * Build a `KeyScale` for a natural-minor key on the given root pitch class.
  *
@@ -106,7 +216,7 @@ declare function majorKey(rootPc: number): KeyScale;
  *
  * @category Scales
  */
-declare function minorKey(rootPc: number): KeyScale;
+declare function minorKey(rootPc: number): SpelledKeyScale;
 /**
  * Build a `KeyScale` from a named scale (see {@link NAMED_SCALES}).
  *
@@ -123,7 +233,31 @@ declare function minorKey(rootPc: number): KeyScale;
  *
  * @category Scales
  */
-declare function scaleByName(name: ScaleNameInput, rootPc: number): KeyScale;
+declare function scaleByName(name: ScaleNameInput, rootPc: number): SpelledKeyScale;
+
+/**
+ * Read a key name, reporting failure instead of throwing it.
+ *
+ * The scale-word form is tried first, because a name ending in a mode word —
+ * `'D harmonic minor'` — would otherwise be read as the plain minor key that
+ * word names and lose the scale it was written with. It is English-only, so a
+ * name asked for in another notation system goes straight to the key-name
+ * parser, which reads that system.
+ *
+ * @param text The key name.
+ * @param opts `system` reads the name in that notation system instead of
+ *   detecting it.
+ * @returns The key the name denotes, or the error explaining why the text is
+ *   not one.
+ * @example
+ * ```ts
+ * import { tryResolveKeyName } from '@libraz/libcantus';
+ * const result = tryResolveKeyName('D dorian');
+ * result.ok ? result.value.variant : result.error.message; // 'modal'
+ * ```
+ * @category Scales
+ */
+declare function tryResolveKeyName(text: string, opts?: NoteNameOptions): ParseResult<ResolvedKey>;
 
 /**
  * Shared interval reading for the counterpoint rules.
@@ -177,6 +311,20 @@ declare function classifySpelledInterval(interval: SpelledInterval, twoVoice?: b
  * written. Those keep their integer form as an equal partner.
  */
 
+/**
+ * The readings {@link createsHiddenParallelPerfect} judges an approach by.
+ *
+ * Named once so the three places the choice is spelled — the two overloads and
+ * the implementation — cannot fall out of step with the check that a caller's
+ * value is one of them.
+ */
+declare const HIDDEN_PARALLEL_READINGS: readonly ["fourPart", "twoVoice"];
+/**
+ * Which reading of hidden parallels an approach is judged by.
+ *
+ * @category Voicing & Counterpoint
+ */
+type HiddenParallelReading = (typeof HIDDEN_PARALLEL_READINGS)[number];
 /**
  * Whether an upper voice has crossed below a lower voice.
  *
@@ -309,14 +457,24 @@ declare function createsParallelUnison(aPrev: number, aCur: number, bPrev: numbe
  * Whether two voices reach a perfect interval by similar motion from an
  * imperfect one (a hidden/direct fifth or octave).
  *
- * The traditional step exception is applied: the approach is allowed when the
- * upper of the two voices moves by step, so only leaps into the perfect
- * interval are flagged.
+ * How strictly the approach is judged is the caller's to say, because the two
+ * textures do not agree about it:
  *
+ * - `fourPart` (the default) applies the step exception of the chorale — the
+ *   approach is allowed when the upper of the two voices moves by step, so only
+ *   leaps into the perfect interval are flagged. That exception is written for
+ *   the outer voices of a four-part texture, where the other two cover the
+ *   arrival.
+ * - `twoVoice` exempts no approach. With nothing between them, two voices
+ *   moving the same way into a perfect fifth or octave expose it however the
+ *   upper one got there, and strict sixteenth-century writing forbids it
+ *   outright.
+ *
+ * @param strictness Which reading to judge the approach by.
  * @category Voicing & Counterpoint
  */
-declare function createsHiddenParallelPerfect(aPrev: Note, aCur: Note, bPrev: Note, bCur: Note): boolean;
-declare function createsHiddenParallelPerfect(aPrev: number, aCur: number, bPrev: number, bCur: number): boolean;
+declare function createsHiddenParallelPerfect(aPrev: Note, aCur: Note, bPrev: Note, bCur: Note, strictness?: HiddenParallelReading): boolean;
+declare function createsHiddenParallelPerfect(aPrev: number, aCur: number, bPrev: number, bCur: number, strictness?: HiddenParallelReading): boolean;
 /**
  * Whether two voices arrive at a perfect octave or unison by contrary motion
  * with the upper voice leaping down — the *ottava battuta* the sixteenth-century
@@ -324,6 +482,10 @@ declare function createsHiddenParallelPerfect(aPrev: number, aCur: number, bPrev
  *
  * The stepwise arrival is allowed, as is the same octave reached with the upper
  * voice rising, so only the downward leap into the perfect class is flagged.
+ * Arriving at a perfect class the voices were already sitting on (e.g. octave
+ * to octave by contrary motion) is the anti-parallel case owned by
+ * {@link createsParallelPerfect}; battuta is reserved for a perfect class that
+ * was not already there.
  *
  * @category Voicing & Counterpoint
  */
@@ -363,20 +525,20 @@ declare function exceedsSpacing(upper: number, lower: number, maxSemitones?: num
  * @returns True when `prev` is the leading tone and `cur` is the tonic a step above.
  * @category Voicing & Counterpoint
  */
-declare function isLeadingToneResolution(prev: Note, cur: Note, key: KeyScale): boolean;
-declare function isLeadingToneResolution(prev: number, cur: number, key: KeyScale): boolean;
+declare function isLeadingToneResolution(prev: Note, cur: Note, key: KeyLike): boolean;
+declare function isLeadingToneResolution(prev: number, cur: number, key: KeyLike): boolean;
 
 /**
  * Total voice-leading cost between two voicings: the sum of absolute semitone
- * motion across voices, plus a moderate hidden-perfect penalty when the
- * outer-voice (bass–soprano) pair reaches a hidden/direct perfect fifth or
- * octave by similar motion. The arrays must be the same length; when they
- * differ the voicings are not comparable and the cost is `Infinity`.
+ * motion across voices, and nothing besides. The rules the search also weighs —
+ * parallels, hidden perfects, unresolved tendency tones — are judged and
+ * reported by {@link checkPartWriting}, so measuring distance stays a
+ * measurement. The arrays must be the same length; when they differ the
+ * voicings are not comparable and the cost is `Infinity`.
  *
  * @param from The previous voicing, one MIDI pitch per voice.
  * @param to The next voicing, one MIDI pitch per voice.
- * @returns The summed absolute motion (plus any hidden-perfect penalty), or
- *   `Infinity` when lengths differ.
+ * @returns The summed absolute motion, or `Infinity` when lengths differ.
  * @category Voicing & Counterpoint
  */
 declare function voiceLeadingCost(from: number[], to: number[]): number;
@@ -390,6 +552,14 @@ declare function voiceLeadingCost(from: number[], to: number[]): number;
  * from `current`, and a large penalty per counterpoint violation; the lowest
  * scoring candidate is returned, ascending.
  *
+ * The rules 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 — are scored only when `opts.previousChord` names it: what a
+ * voicing is written on cannot be read back from the pitches it holds. An
+ * editor moving from one chord to the next has that chord, and passing it is
+ * what keeps this generator and {@link checkPartWriting} agreeing about the
+ * pair.
+ *
  * @param current The current voicing to lead from, ascending (index 0 = lowest).
  * @param chord The next chord to voice, as a chord symbol, chord data, or a
  *   `Chord`.
@@ -411,9 +581,13 @@ declare function nextVoicing(current: number[], chord: ChordLike, opts?: Voicing
  * major triad over one degree of C major and a diminished one over another.
  *
  * The bass arrives spelled, so the intervals above it are spelled too. The
- * third above a G in C minor is the Bb the signature gives, and the bare `#`
- * that raises it names B natural rather than an enharmonic Cb — which is what
- * makes the figures of a real exercise readable as written.
+ * third above a G in C minor is the Bb the signature gives, and the accidental
+ * that changes it is the one a score prints in front of that note: the leading
+ * tone there is a B natural, so the figure is `n`. That is the whole convention
+ * for accidentals here — a sign on a figure names its note exactly as it does on
+ * the staff — and it is what makes the figures of a real exercise readable as
+ * written. The crossed or slashed figure, typed `+`, is the one sign that raises
+ * instead of naming.
  */
 
 /**
@@ -468,13 +642,18 @@ type FiguredBassRealization = {
  *   `653`, `643` and `642` name the same four chords.
  * - Stacked figures may be written run together (`64`) or separated by a slash,
  *   a comma or a space (`6/4`), which is the same figure either way.
- * - An accidental in front of a figure alters that interval: `#6`, `b7`, `#43`.
- *   A slashed or crossed figure raises its interval, and is typed `+` — `+6` is
- *   `#6`. An accidental with no figure alters the third above the bass, so a
- *   lone `#` over the dominant of a minor key raises its third to the leading
- *   tone. `#` and `b` move the interval a semitone from what the key gives,
- *   `##` and `bb` a whole tone, and `n` names the natural note whatever the key
- *   gives. The Unicode accidentals are accepted alongside the typed ones.
+ * - An accidental in front of a figure names that interval's note, exactly as
+ *   the same sign does on the staff: `#6`, `b7`, `#43`, and `n3` for a note the
+ *   signature would otherwise flatten. `##` and `bb` name the double
+ *   accidentals. An accidental with no figure applies to the third above the
+ *   bass, so a lone `n` over the dominant of C minor names its leading tone. The
+ *   Unicode accidentals are accepted alongside the typed ones.
+ * - A slashed or crossed figure raises the interval the key gives by a semitone,
+ *   whatever accidental that lands on, and is typed `+`. It is the one sign here
+ *   that moves an interval rather than naming it, which is why the notation
+ *   carries it beside the printed accidentals: `+3` over the dominant of C minor
+ *   and `+3` over the dominant of A minor are each that key's leading tone,
+ *   written `n3` and `#3` respectively.
  * - A figure that moves is written with a hyphen: `4-3`, `9-8`, `7-6`, and any
  *   other pair. Each side may carry its own accidental, as `4-#3` does in a
  *   minor key. Moving figures may stand beside static ones (`5 4-3`).
@@ -542,8 +721,8 @@ declare function figuredBassRealization(bass: NoteLike, figures: string, key: Ke
  * import { majorKey, minorKey, parseNote, realizeFiguredBass } from '@libraz/libcantus';
  * realizeFiguredBass(parseNote('B'), '6', majorKey(0));
  * // G major with B in the bass: { rootPc: 7, quality: 'maj', bassPc: 11, ... }
- * realizeFiguredBass(parseNote('G'), '#', minorKey(0));
- * // G major in C minor: the raised third is a B natural
+ * realizeFiguredBass(parseNote('G'), 'n', minorKey(0));
+ * // G major in C minor: the leading tone is the B natural the score prints
  * ```
  * @category Functional Harmony
  */
@@ -554,15 +733,21 @@ declare function realizeFiguredBass(bass: NoteLike, figures: string, key: KeyLik
  * The inverse of {@link realizeFiguredBass} for every chord the figure grammar
  * reaches: the conventional abbreviation for the inversion (`6`, `64`, `7`,
  * `65`, `43`, `42`, or nothing at all for a root-position triad), with an
- * accidental on any interval the key does not already give. An altered
- * interval the abbreviation would leave implied is written out, so the raised
- * third of a dominant in a minor key emits `#3` rather than the bare `#` a
- * score would print — the figures this returns read back as the same chord.
+ * accidental on any interval the key does not already give. The accidental is
+ * the sign the score prints in front of that note, so the third of the dominant
+ * in C minor — a B natural under a signature carrying B flat — is written `n3`
+ * rather than as a raise from the flat the key gives. An altered interval the
+ * abbreviation would leave implied is written out, so the figure names the
+ * interval it lands on rather than the bare accidental a score puts under the
+ * bass — the figures this returns read back as the same chord.
  *
  * What this returns is read back before it is returned, so the two directions
- * cannot disagree: a chord the digits would name only approximately — an
- * augmented sixth, whose tones do not stack in thirds over its bass — has no
- * figures rather than figures that fail to realize.
+ * cannot disagree: a chord the digits would name only approximately has no
+ * figures rather than figures that fail to realize. What that excludes is a
+ * stack, not a family of chords — the Italian and German sixths stack in thirds
+ * over no root of their own and have no figures, while the French sixth stacks
+ * from its lowered supertonic and is written `#643`, which realizes back to the
+ * chord it was written from.
  *
  * @param chord The chord to figure, as a chord symbol, chord data, or a
  *   `Chord`; its `bassPc`, when present, is the bass the intervals are measured
@@ -583,7 +768,7 @@ declare function realizeFiguredBass(bass: NoteLike, figures: string, key: KeyLik
  * ```
  * @category Functional Harmony
  */
-declare function figuredBassOf(chord: ChordLike, key: KeyLike): string;
+declare function figuredBassOf(chord: ChordLike, key: SpelledKeyLike): string;
 
 /**
  * Spelling: derive letter-name notes for scales and chords from a spelled tonic.
@@ -608,6 +793,15 @@ declare function figuredBassOf(chord: ChordLike, key: KeyLike): string;
  * @category Pitch & Intervals
  */
 type SpellingContext = {
+    /**
+     * The chord sounding under the pitch, when the caller holds it.
+     *
+     * A chord names its own tones better than its root alone can: it carries the
+     * degree it writes each tone as, so a pitch that is one of its tones is
+     * spelled exactly as {@link spellChord} spells it. Supersedes `chordRoot`,
+     * which stays for callers holding nothing but a root pitch class.
+     */
+    chord?: Chord;
     /** Root pitch class of the chord sounding under the pitch, when known. */
     chordRoot?: number;
     /** The pitch immediately before this one (MIDI pitch or bare pitch class). */
@@ -682,10 +876,11 @@ declare function spellPitchClass(pc: number, tonic: NoteLike, key: KeyLike, cont
  *
  * @param tonic The spelled tonic, as a note name, a MIDI number, note data, or a
  *   `Note`.
- * @param key The key/scale. This one stays a plain key/scale: the key-spelling
- *   search reads scales through it that no key name describes.
+ * @param key The key/scale, as a key name, a key/scale, or a `Key` — the same
+ *   forms its sibling spellers take.
  * @returns Spelled notes, one per scale degree.
- * @throws If `tonic` does not sound the key's root pitch class.
+ * @throws If `key` names no key, or if `tonic` does not sound the key's root
+ *   pitch class.
  * @example
  * ```ts
  * import { spellScale, noteNames, parseNote, majorKey } from '@libraz/libcantus';
@@ -694,7 +889,7 @@ declare function spellPitchClass(pc: number, tonic: NoteLike, key: KeyLike, cont
  * ```
  * @category Pitch & Intervals
  */
-declare function spellScale(tonic: NoteLike, key: KeyScale): Note[];
+declare function spellScale(tonic: NoteLike, key: KeyLike): Note[];
 /**
  * Spell an arbitrary list of pitch classes relative to a key.
  *
@@ -790,4 +985,4 @@ declare function spellPitch(pitch: number, tonic: NoteLike, key: KeyLike, contex
  */
 declare function noteNames(notes: readonly NoteLike[]): string[];
 
-export { Chord as ChordData, ChordLike, ConsonanceClass, type FiguredBassRealization, type FiguredBassSuspension, KeyLike, KeyScale, Note as NoteData, NoteLike, ScaleNameInput, SpelledInterval, type SpellingContext, VoicingOptions, classifySpelledInterval, createsBattuta, createsHiddenParallelPerfect, createsParallelOctave, createsParallelPerfect, createsParallelUnison, createsVerticalDissonance, createsVoiceCrossing, createsVoiceOverlap, diatonicPitchClasses, exceedsSpacing, figuredBassOf, figuredBassRealization, isAugmentedMelodicInterval, isForbiddenMelodicLeap, isLeadingToneResolution, isScaleTone, majorKey, minorKey, nearestScaleTone, nextVoicing, noteNames, pitchToScaleDegree, realizeFiguredBass, scaleByName, scaleTonesInDegreeOrder, spellChord, spellChordFromRoot, spellPitch, spellPitchClass, spellPitchClasses, spellScale, voiceLeadingCost };
+export { Chord as ChordData, ChordLike, ConsonanceClass, type FiguredBassRealization, type FiguredBassSuspension, type HiddenParallelReading, KeyLike, KeyScale, Note as NoteData, NoteLike, NoteNameOptions, ParseResult, ResolvedKey, type ScaleLadderPosition, ScaleNameInput, SpelledInterval, SpelledKeyLike, SpelledKeyScale, type SpellingContext, VoicingOptions, classifySpelledInterval, createsBattuta, createsHiddenParallelPerfect, createsParallelOctave, createsParallelPerfect, createsParallelUnison, createsVerticalDissonance, createsVoiceCrossing, createsVoiceOverlap, diatonicPitchClasses, exceedsSpacing, figuredBassOf, figuredBassRealization, isAugmentedMelodicInterval, isForbiddenMelodicLeap, isLeadingToneResolution, isScaleTone, majorKey, minorKey, nearestScaleTone, nextVoicing, noteNames, pitchToScaleDegree, realizeFiguredBass, resolveKey, scaleByName, scaleLadderPitch, scaleLadderPosition, scaleOf, scaleTonesInDegreeOrder, shiftByScaleDegrees, spellChord, spellChordFromRoot, spellPitch, spellPitchClass, spellPitchClasses, spellScale, tryResolveKeyName, voiceLeadingCost };