@libraz/libcantus 1.0.1 → 1.2.0

package/dist/{index-C_8o--VE.d.cts → coerce-DRERzdve.d.cts}

@@ -1,15 +1,156 @@
-import { d as KeyScale, f as Note, h as NoteLike, i as NoteNameOptions, P as ParseResult } from './index-B9MNZboQ.cjs';
+import { e as KeyScale, g as Note, i as NoteLike } from './index-Cy15oTvh.cjs';
 
 /**
- * Anything that names a key: a key name, a plain {@link KeyScale}, or a value
- * that serializes to one such as the `Key` class.
+ * The vocabulary a key is described in.
+ *
+ * Kept in a module of its own, below the masks that define the scale forms, the
+ * name reader that produces a key from text, and the coercion that accepts one
+ * from a caller. All three name these types and none of them can be the others'
+ * home without importing one back.
+ */
+/**
+ * Which scale form a key stands in.
+ *
+ * `'modal'` is the honest answer for a key standing in none of the four, and it
+ * is an answer rather than an absence.
+ *
+ * @category Scales
+ */
+type KeyVariant = 'major' | 'natural' | 'harmonic' | 'melodic' | 'modal';
+/**
+ * The complete identity of a key: what it sounds, how it is written, and which
+ * scale form it stands in.
+ *
+ * What {@link resolveKey} hands back, and the shape a key is passed on in. Every
+ * field is present: a key that reaches here has been read, so there is nothing
+ * left undecided about it, and a reader never has to ask whether a missing
+ * field means `'modal'` or means nobody looked.
  *
  * @category Scales
  */
-type KeyLike = string | KeyScale | {
-    /** The key data this value stands for, carrying the scale it denotes. */
+/**
+ * A key/scale with the spelling it is conventionally written in beside it.
+ *
+ * What the key builders hand back. It is a {@link KeyScale} — every reader that
+ * wants only the pitch classes takes it unchanged — and it carries the tonic
+ * those pitch classes are conventionally written on, so it also satisfies the
+ * entry points whose answer depends on how the key is written.
+ *
+ * Carrying the spelling here is what lets those entry points refuse a bare
+ * `KeyScale` without refusing the library's own builders. A bare scale reaching
+ * one of them has had a spelling and lost it, which is the defect; a built key
+ * never lost one.
+ *
+ * @category Scales
+ */
+type SpelledKeyScale = KeyScale & {
+    /** The tonic the key is conventionally written on. */
+    tonic: Note;
+    /** The scale form the mask stands in. */
+    variant: KeyVariant;
+};
+/**
+ * A key read into the three things every reader of one needs: the pitch
+ * classes it is built from, the spelled tonic its letter names are anchored on,
+ * and the scale form it stands in.
+ *
+ * What a key-shaped argument becomes once it has been read, whatever form the
+ * caller held it in — a name, a scale, a `Key`. Carrying the tonic beside the
+ * scale is what keeps an A flat minor an A flat minor rather than the G sharp
+ * minor its pitch classes alone would be spelled back as.
+ *
+ * @category Scales
+ */
+type ResolvedKey = {
+    /** The pitch classes the key is built from. */
+    readonly scale: KeyScale;
+    /** The spelled tonic every letter name derived from this key is anchored on. */
+    readonly tonic: Note;
+    /** The scale form the key stands in. */
+    readonly variant: KeyVariant;
+};
+
+/**
+ * Anything that names a key: a key name, a plain {@link KeyScale}, the plain
+ * data a key serializes to, or a value that serializes to one such as the `Key`
+ * class.
+ *
+ * The plain-data form is here because a project file holds a key that way, and
+ * reading one back has to be the same call as passing the class it came from.
+ *
+ * Deliberately wider than what a resolver hands back: a caller may hand in a
+ * bare scale, or data written before the spelling travelled with it, and the
+ * resolver fills in what is missing rather than refusing it. Narrowing this to
+ * the resolved shape would make the acceptance of every entry point shrink the
+ * day the resolved shape gained a field.
+ *
+ * A scale is accepted with the spelling and the form written beside it as well
+ * as without them, because a key region carries its key that way — asked
+ * positional questions wherever a plain scale would be. The resolver reads them
+ * when they are there, and this says so: a shape a resolver reads and a type
+ * denies is one refactoring away from being dropped silently.
+ *
+ * @category Scales
+ */
+type KeyLike = string | (KeyScale & {
+    /** The spelled tonic the key is written with, when it travels beside it. */
+    tonic?: Note;
+    /** The scale form the key stands in, when it travels beside it. */
+    variant?: KeyVariant;
+}) | {
+    /** The scale this key data denotes. */
+    scale: KeyScale;
+    /** The spelled tonic the key is written with, when the caller named one. */
+    tonic?: Note;
+    /** The scale form the key was read under, when it was read under one. */
+    variant?: KeyVariant;
+} | {
+    /** The key data this value stands for, carrying everything it knows. */
+    toJSON(): {
+        scale: KeyScale;
+        tonic?: Note;
+        variant?: KeyVariant;
+    };
+};
+/**
+ * A key that says how it is written, for the entry points whose answer depends
+ * on it.
+ *
+ * The shapes {@link KeyLike} accepts, minus the one that cannot carry a
+ * spelling: a bare {@link KeyScale}. An A flat minor and a G sharp minor are one
+ * set of pitch classes and two keys, so an entry point whose answer differs
+ * between them cannot be handed the shape that does not distinguish them and
+ * still be right. Declaring this makes that a compile error rather than a
+ * defect found later — and `Key`, `ResolvedKey`, a key name and stored key data
+ * all satisfy it, so the narrowing costs a caller nothing it was doing
+ * correctly.
+ *
+ * Which entry points declare this is measured rather than chosen: an entry point
+ * belongs here exactly when varying its key argument alone — between the two
+ * spellings of one sound — changes its answer. A scale a caller genuinely wants
+ * to hand in is spelled first, at the place it happens, which is the same rule
+ * the reduction in the other direction already follows.
+ *
+ * @category Scales
+ */
+type SpelledKeyLike = string | (KeyScale & {
+    /** The spelled tonic the key is written with. Required: it is the point. */
+    tonic: Note;
+    /** The scale form the key stands in, when it travels beside it. */
+    variant?: KeyVariant;
+}) | {
+    /** The scale this key data denotes. */
+    scale: KeyScale;
+    /** The spelled tonic the key is written with, when the caller named one. */
+    tonic?: Note;
+    /** The scale form the key was read under, when it was read under one. */
+    variant?: KeyVariant;
+} | {
+    /** The key data this value stands for, carrying everything it knows. */
     toJSON(): {
         scale: KeyScale;
+        tonic?: Note;
+        variant?: KeyVariant;
     };
 };
 /**
@@ -21,12 +162,12 @@ type KeyLike = string | KeyScale | {
  * instance is accepted through its `toJSON` method rather than by its type, so
  * the layers below the model can read a class without importing it.
  *
- * A name is read by {@link parseKeyName} and nothing else, so every entry point
- * that takes a key accepts exactly the names a key field already accepts, in
- * every notation system it already reads. The mode word decides the scale: a
- * major name gives the major scale, a minor name the natural minor. The
- * harmonic and melodic forms have no name of their own, so a caller who needs
- * one builds it with {@link scaleByName} and passes the scale.
+ * A name is read by the one reader {@link resolveKey} and `Key.parse` also use,
+ * so every entry point that takes a key accepts exactly the same names: a mode
+ * word in every notation system that reader knows, and a built-in scale's own
+ * word — `'D dorian'`, `'D harmonic minor'` — in English.
+ * The spelling the name carries is dropped here along with the scale form,
+ * which is what {@link resolveKey} is for.
  *
  * @param value A key name, a plain key/scale, or a value whose `toJSON`
  *   returns data carrying one.
@@ -74,16 +215,13 @@ declare function toKeyScale(value: KeyLike): KeyScale;
  *
  * @example
  * ```ts
- * import type { SpelledKey } from '@libraz/libcantus';
- * import { majorKey, parseNote } from '@libraz/libcantus';
- * const dbMajor: SpelledKey = { tonic: parseNote('Db'), key: majorKey(1) };
+ * import type { ResolvedKey } from '@libraz/libcantus';
+ * import { formatNote, majorKey, spelledKeyOf } from '@libraz/libcantus';
+ * const dbMajor: ResolvedKey = spelledKeyOf(majorKey(1));
+ * formatNote(dbMajor.tonic); // 'Db'
  * ```
  * @category Scales
  */
-type SpelledKey = {
-    tonic: Note;
-    key: KeyScale;
-};
 /**
  * How one key stands to another, as reported by {@link keyRelationBetween} and
  * tagged onto every entry of {@link relatedKeysOf}.
@@ -144,21 +282,29 @@ type KeyRelation = 'same' | 'enharmonic' | 'relative' | 'parallel' | 'dominant'
  * ```
  * @category Scales
  */
-declare function spelledKeyOf(key: KeyScale): SpelledKey;
+declare function spelledKeyOf(key: KeyScale): ResolvedKey;
 /**
- * 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.
  *
  * C major and A minor share a signature, and so are each other's relative; the
  * relation is its own inverse for a plain major or minor key. 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 origin every
+ * relation here shares: the relative of D dorian is F major, the relative of the
+ * D minor its third names. The shared-signature reading does not carry over to
+ * those — D dorian is written with no accidentals and F major with one — and the
+ * modes have no relative of their own for it to be measured against.
+ *
  * @param tonic The spelled tonic of the key, as a note name, note data, or a
  *   `Note`.
  * @param key The key/scale, as a key name, a key/scale, or a `Key`; its mask
  *   decides which mode the relative is in.
  * @returns The relative key and the tonic spelling it is written with.
- * @throws If the tonic or the mask is malformed, or if the key's signature
+ * @throws If the tonic or the mask is malformed, or if the resulting signature
  *   falls outside [-12, 12] fifths.
  * @example
  * ```ts
@@ -168,7 +314,7 @@ declare function spelledKeyOf(key: KeyScale): SpelledKey;
  * ```
  * @category Scales
  */
-declare function relativeKeyOf(tonic: NoteLike, key: KeyLike): SpelledKey;
+declare function relativeKeyOf(tonic: NoteLike, key: KeyLike): ResolvedKey;
 /**
  * The parallel key: the other mode on the same tonic.
  *
@@ -190,7 +336,7 @@ declare function relativeKeyOf(tonic: NoteLike, key: KeyLike): SpelledKey;
  * ```
  * @category Scales
  */
-declare function parallelKeyOf(tonic: NoteLike, key: KeyLike): SpelledKey;
+declare function parallelKeyOf(tonic: NoteLike, key: KeyLike): ResolvedKey;
 /**
  * The dominant key: the key a fifth above, in the mode this key's third names.
  *
@@ -212,7 +358,7 @@ declare function parallelKeyOf(tonic: NoteLike, key: KeyLike): SpelledKey;
  * ```
  * @category Scales
  */
-declare function dominantKeyOf(tonic: NoteLike, key: KeyLike): SpelledKey;
+declare function dominantKeyOf(tonic: NoteLike, key: KeyLike): ResolvedKey;
 /**
  * The subdominant key: the key a fifth below, in the mode this key's third
  * names, and the exact inverse of {@link dominantKeyOf} on the tonic spelling.
@@ -231,7 +377,7 @@ declare function dominantKeyOf(tonic: NoteLike, key: KeyLike): SpelledKey;
  * ```
  * @category Scales
  */
-declare function subdominantKeyOf(tonic: NoteLike, key: KeyLike): SpelledKey;
+declare function subdominantKeyOf(tonic: NoteLike, key: KeyLike): ResolvedKey;
 /**
  * The same sounding key written the other way round the circle of fifths, or
  * null when it has no second spelling.
@@ -268,18 +414,25 @@ declare function subdominantKeyOf(tonic: NoteLike, key: KeyLike): SpelledKey;
  * ```
  * @category Scales
  */
-declare function enharmonicKeyOf(tonic: NoteLike, key: KeyLike): SpelledKey | null;
+declare function enharmonicKeyOf(tonic: NoteLike, key: KeyLike): ResolvedKey | null;
 /**
  * The six closely related keys of a key, each tagged with its relation.
  *
  * 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. For C major they are A minor,
- * C minor, G major, F major, E minor and D minor, in that order. Five of them
- * are written within one accidental of the key's own signature — the relative
- * shares it exactly and the other four stand one away; the parallel key does
- * not — C minor is three flats away from C major — and belongs to the set for
- * the tonic it shares rather than for the signature it carries.
+ * C minor, G major, F major, E minor and D minor, in that order. For a plain
+ * major or minor key five of them are written within one accidental of the key's
+ * own signature — the relative shares it exactly and the other four stand one
+ * away; the parallel key does not — C minor is three flats away from C major —
+ * and belongs to the set for the tonic it shares rather than for the signature
+ * it carries.
+ *
+ * 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 the accidental counts above do not
+ * describe them: the relative of D dorian is F major, one flat against dorian's
+ * none.
  *
  * @param tonic The spelled tonic of the key, as a note name, note data, or a
  *   `Note`.
@@ -296,7 +449,7 @@ declare function enharmonicKeyOf(tonic: NoteLike, key: KeyLike): SpelledKey | nu
  * ```
  * @category Scales
  */
-declare function relatedKeysOf(tonic: NoteLike, key: KeyLike): (SpelledKey & {
+declare function relatedKeysOf(tonic: NoteLike, key: KeyLike): (ResolvedKey & {
     relation: KeyRelation;
 })[];
 /**
@@ -321,14 +474,14 @@ declare function relatedKeysOf(tonic: NoteLike, key: KeyLike): (SpelledKey & {
  *   falls outside [-12, 12] fifths.
  * @example
  * ```ts
- * import { keyRelationBetween, majorKey, minorKey, parseNote } from '@libraz/libcantus';
- * const cMajor = { tonic: parseNote('C'), key: majorKey(0) };
- * keyRelationBetween(cMajor, { tonic: parseNote('A'), key: minorKey(9) }); // 'relative'
- * keyRelationBetween(cMajor, { tonic: parseNote('Eb'), key: minorKey(3) }); // null
+ * import { keyRelationBetween, majorKey, minorKey, spelledKeyOf } from '@libraz/libcantus';
+ * const cMajor = spelledKeyOf(majorKey(0));
+ * keyRelationBetween(cMajor, spelledKeyOf(minorKey(9))); // 'relative'
+ * keyRelationBetween(cMajor, spelledKeyOf(minorKey(3))); // null
  * ```
  * @category Scales
  */
-declare function keyRelationBetween(a: SpelledKey, b: SpelledKey): KeyRelation | null;
+declare function keyRelationBetween(a: ResolvedKey, b: ResolvedKey): KeyRelation | null;
 
 /**
  * The structured reading of a chord: what it is built from, not what it is
@@ -783,10 +936,14 @@ declare function isChordMember(pitch: number, chord: Chord | null): boolean;
 /**
  * Determine a pitch's harmonic role within a chord.
  *
- * The role is derived from the pitch's interval above the chord root, reduced
- * modulo 12. A major sixth (9) reads as a `sixth` for sixth chords but as a
- * `seventh` for a diminished-seventh chord; ninths and other tensions have no
- * basic role and return null.
+ * A chord carrying its own tone spellings is read by them, since the degree it
+ * writes a tone as is the degree that tone plays: the ten semitones above the
+ * root of a German sixth are written five letters up, so they are its sixth and
+ * not a seventh owing a step downward. Everywhere else the role is derived from
+ * the pitch's interval above the chord root, reduced modulo 12. A major sixth
+ * (9) reads as a `sixth` for sixth chords but as a `seventh` for a
+ * diminished-seventh chord; ninths and other tensions have no basic role and
+ * return null.
  *
  * @param pitch MIDI pitch or bare pitch class.
  * @param chord The chord providing the root reference.
@@ -899,10 +1056,13 @@ declare const PROFILE_WEIGHTS: Readonly<Record<SafetyProfile, Readonly<ProfileWe
  *
  * @param profile The profile whose table to start from.
  * @param overrides Fields to replace; anything absent keeps the profile's value.
+ *   A field written as an explicit `undefined` is absent, not a replacement.
  * @returns The complete weight table to score with.
- * @throws If `profile` is not one of the profile names
- *   ({@link InvalidInputError}). A misspelled profile scored under a default
- *   table would rank candidates by a style the caller did not ask for.
+ * @throws If `profile` is not one of the profile names, or an override is not a
+ *   finite number ({@link InvalidInputError}). A misspelled profile scored under
+ *   a default table would rank candidates by a style the caller did not ask for,
+ *   and a single non-finite weight poisons every candidate's score, which turns
+ *   the ranking into the order the candidates happened to be enumerated in.
  * @example
  * ```ts
  * import { profileWeights } from '@libraz/libcantus';
@@ -924,25 +1084,73 @@ declare enum NoteSafety {
 /**
  * Bit flags describing why a pitch received its verdict.
  *
+ * Several flags can describe one pitch, so test the combination rather than a
+ * flag alone: an avoid eleventh carries `Tension` as well as `AvoidNote`, and a
+ * usable tension is `Tension` without `AvoidNote`. `ChordTone`, `MinorSecond`
+ * and `MajorSeventh` are informational and never lower the verdict on their
+ * own; every other flag sets at least a warning, and the profile decides how
+ * far past that it goes.
+ *
  * @category Arrangement & Analysis
  */
 declare enum ReasonFlag {
+    /** The candidate is a member of the chord. Informational. */
     ChordTone = 1,
+    /**
+     * The candidate is a ninth, eleventh or thirteenth above the root, not a chord
+     * tone. Also set alongside `AvoidNote` when the avoid note is the eleventh.
+     */
     Tension = 2,
+    /**
+     * The eleventh over a chord with a major third and no fourth, or the major
+     * seventh over a dominant. Always set with `NeedsResolution`, and with
+     * `Tension` for the eleventh.
+     */
     AvoidNote = 4,
+    /** The candidate is in the key but neither a chord tone nor a tension. */
     ScaleTone = 8,
+    /** The candidate is outside the key and not a chord tone. */
     NonScale = 16,
+    /** The candidate lies outside `vocalLow`..`vocalHigh`. */
     OutOfRange = 32,
+    /** The candidate, not itself a chord tone, is a tritone from one. */
     Tritone = 64,
+    /**
+     * The move from `prevPitch` is a forbidden melodic leap as
+     * {@link isForbiddenMelodicLeap} defines it: a tritone, either seventh, or
+     * anything wider than an octave. An octave itself is not. The profile sets
+     * the severity, not the set of leaps. Set with `MelodicTritone` on a tritone
+     * and with `MajorSeventh` on a major seventh.
+     */
     LargeLeap = 128,
+    /** The move from `prevPitch` reduces to a semitone, the minor ninth included. Informational. */
     MinorSecond = 256,
+    /** The move from `prevPitch` reduces to a major seventh; always with `LargeLeap`. Informational. */
     MajorSeventh = 512,
+    /**
+     * On a strong beat, the candidate is dissonant against at least one of
+     * `otherVoices`, apart from the tritone or seventh two chord tones spell. A
+     * perfect fourth counts only when one of the two is the lowest sounding voice,
+     * and under `pop` not when both are chord tones — an inverted chord.
+     */
     VerticalDissonance = 1024,
+    /** The candidate moves in parallel perfect intervals with at least one of `otherVoices`. */
     ParallelPerfect = 2048,
+    /**
+     * The candidate and another voice, the two outer voices of the texture, reach
+     * a perfect interval by similar motion with the upper one leaping.
+     */
     HiddenParallel = 4096,
+    /** The candidate crosses at least one of `otherVoices` since the previous step. */
     VoiceCrossing = 8192,
+    /**
+     * A held pitch, consonant with a voice on the previous step, now dissonant
+     * against it. Always with `VerticalDissonance`.
+     */
     Suspension = 16384,
+    /** The candidate should move by step to `resolveTo`. Set with `AvoidNote`. */
     NeedsResolution = 32768,
+    /** The move from `prevPitch` reduces to a tritone; always with `LargeLeap`. */
     MelodicTritone = 65536
 }
 /**
@@ -970,6 +1178,20 @@ type SafetyQuery = {
     vocalLow?: number;
     vocalHigh?: number;
 };
+/**
+ * The reasons one of `otherVoices` contributes to a verdict.
+ *
+ * @category Arrangement & Analysis
+ */
+type SafetyPartner = {
+    /** The voice's index in {@link SafetyQuery.otherVoices}. */
+    index: number;
+    /**
+     * The pairwise flags this voice raises: `VerticalDissonance`, `Suspension`,
+     * `ParallelPerfect`, `HiddenParallel` and `VoiceCrossing`.
+     */
+    reasons: number;
+};
 /**
  * The verdict, reason flags, and optional resolution guidance.
  *
@@ -980,6 +1202,12 @@ type SafetyResult = {
     reasons: number;
     resolveTo?: number;
     suggestions?: number[];
+    /**
+     * The voices behind the pairwise flags in `reasons`, in `otherVoices` order,
+     * when {@link EvaluateSafetyOptions.partners} asked for them and any voice
+     * raised one. Their `reasons` together are exactly the pairwise flags set.
+     */
+    partners?: SafetyPartner[];
     rationale?: string;
 };
 /**
@@ -1024,6 +1252,14 @@ type EvaluateSafetyOptions = {
      * @defaultValue true
      */
     suggestions?: boolean;
+    /**
+     * Whether to report which of `otherVoices` raised each pairwise flag, as
+     * {@link SafetyResult.partners}. The bitmask alone says a parallel fifth is
+     * there; this says against which voice.
+     *
+     * @defaultValue false
+     */
+    partners?: boolean;
 };
 /**
  * Enumerate placeable pitches in a range, chord tones first, descending.
@@ -1049,92 +1285,12 @@ type EvaluateSafetyOptions = {
 declare function enumerateSafePitches(q: Omit<SafetyQuery, 'candidatePitch'>, pitchLow: number, pitchHigh: number): number[];
 
 /**
- * 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
+ * Reading a caller's chord into the one shape the library works in.
+ *
+ * The widening counterpart of the other `to*Data` coercers, kept beside the
+ * grammar it falls back on rather than inside it: what a chord symbol means is
+ * the parser's question, and what shapes stand for a chord is this one's.
  */
-declare function tryParseChordSymbol(text: string, opts?: NoteNameOptions): ParseResult<Chord>;
 /**
  * Anything that names a chord: a chord symbol, plain chord data, or a value
  * that serializes to chord data such as the `Chord` class.
@@ -1169,74 +1325,5 @@ type ChordLike = string | Chord | {
  * @category Chords
  */
 declare function toChordData(value: ChordLike): Chord;
-/**
- * How a chord symbol is written: in which notation system, and on which side of
- * the enharmonic fence.
- *
- * @category Chords
- */
-type ChordSymbolOptions = NoteNameOptions & {
-    /**
-     * Prefer flat spellings over sharps for an altered root or bass; passing
-     * either `true` or `false` overrides any spelling hint the chord carries.
-     */
-    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 — whatever combination of tensions the
- * chord carries, and whether or not a quality name covers it.
- * 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` overrides the spelling hints, 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.
- *
- * @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;
 
-export { toChordData as $, type Alteration as A, diatonicTriad as B, type ChordBase as C, dominantKeyOf as D, type EvaluateSafetyOptions as E, enharmonicKeyOf as F, enumerateSafePitches as G, evaluateSafety as H, formatChordSymbol as I, intervalAboveRoot as J, type KeyLike as K, isChordMember as L, keyRelationBetween as M, NoteSafety as N, makeChord as O, PROFILE_WEIGHTS as P, parallelKeyOf as Q, ReasonFlag as R, type SafetyProfile as S, parseChordSymbol as T, profileWeights as U, type VoiceSnapshot as V, relatedKeysOf as W, relativeKeyOf as X, spanFromChord as Y, spelledKeyOf as Z, subdominantKeyOf as _, type AlteredDegree as a, toKeyScale as a0, transposeChord as a1, transposeChordSymbol as a2, tryParseChordSymbol as a3, type Chord as b, type ChordLike as c, type ChordQuality as d, type ChordSegment as e, type ChordSeventh as f, type ChordSpan as g, type ChordSpec as h, type ChordSymbolOptions as i, type ChordToneRole as j, type KeyRelation as k, type PitchSpelling as l, type ProfileWeights as m, type SafetyQuery as n, type SafetyResult as o, type SpelledKey as p, chordFromDegree as q, chordFromSpan as r, chordFromSpec as s, chordPitchClasses as t, chordQualities as u, chordSpecIntervals as v, chordSpecOf as w, chordSpecQuality as x, chordToneRole as y, diatonicSeventh as z };
+export { subdominantKeyOf as $, type Alteration as A, chordSpecQuality as B, type ChordBase as C, chordToneRole as D, type EvaluateSafetyOptions as E, diatonicSeventh as F, diatonicTriad as G, dominantKeyOf as H, enharmonicKeyOf as I, enumerateSafePitches as J, type KeyLike as K, evaluateSafety as L, intervalAboveRoot as M, NoteSafety as N, isChordMember as O, PROFILE_WEIGHTS as P, keyRelationBetween as Q, ReasonFlag as R, type SafetyPartner as S, makeChord as T, parallelKeyOf as U, type VoiceSnapshot as V, profileWeights as W, relatedKeysOf as X, relativeKeyOf as Y, spanFromChord as Z, spelledKeyOf as _, type AlteredDegree as a, toChordData as a0, toKeyScale as a1, transposeChord as a2, type Chord as b, type ChordLike as c, type ChordQuality as d, type ChordSegment as e, type ChordSeventh as f, type ChordSpan as g, type ChordSpec as h, type ChordToneRole as i, type KeyRelation as j, type KeyVariant as k, type PitchSpelling as l, type ProfileWeights as m, type ResolvedKey as n, type SafetyProfile as o, type SafetyQuery as p, type SafetyResult as q, type SpelledKeyLike as r, type SpelledKeyScale as s, chordFromDegree as t, chordFromSpan as u, chordFromSpec as v, chordPitchClasses as w, chordQualities as x, chordSpecIntervals as y, chordSpecOf as z };