@libraz/libcantus 0.9.3 → 0.9.5

package/dist/generate/index.js

@@ -1,6 +1,10 @@
 import {
+  BASS_STYLES,
+  BORROWED_DEGREES,
+  DRUM_NOTES,
   applyGrooveTemplate,
   developMotif,
+  drumVoiceOf,
   extractGrooveTemplate,
   generateBassLine,
   generateCounterMelody,
@@ -10,27 +14,34 @@ import {
   generateRhythm,
   harmonizeMelody,
   humanize,
+  motifToNoteEvents,
   onsetWeightCurve,
+  pickProgressionPreset,
   progressions,
   progressionsByStyle,
   rhythmDensity,
+  rhythmToNoteEvents,
   transformMotif
-} from "../chunk-4MHA432G.js";
-import "../chunk-62QZKCJQ.js";
-import "../chunk-I5R7ZBJS.js";
+} from "../chunk-AID75RN3.js";
+import "../chunk-ZGLJM4A4.js";
+import "../chunk-2PTFGVD7.js";
 import {
   modalInterchangePalette,
   negativeHarmonyMirror,
   substituteChord
-} from "../chunk-IT2O4XFE.js";
-import "../chunk-CHMXELDS.js";
-import "../chunk-2ZWMSJH6.js";
-import "../chunk-EH6EM37U.js";
-import "../chunk-MIWO425M.js";
-import "../chunk-FBQK3ZQN.js";
+} from "../chunk-7JEP3MFY.js";
+import "../chunk-NNB67XA2.js";
+import "../chunk-HN2OEUN2.js";
+import "../chunk-DZMHIGI4.js";
+import "../chunk-KBTTEX7Q.js";
+import "../chunk-R2VVFAIN.js";
 export {
+  BASS_STYLES,
+  BORROWED_DEGREES,
+  DRUM_NOTES,
   applyGrooveTemplate,
   developMotif,
+  drumVoiceOf,
   extractGrooveTemplate,
   generateBassLine,
   generateCounterMelody,
@@ -41,11 +52,14 @@ export {
   harmonizeMelody,
   humanize,
   modalInterchangePalette,
+  motifToNoteEvents,
   negativeHarmonyMirror,
   onsetWeightCurve,
+  pickProgressionPreset,
   progressions,
   progressionsByStyle,
   rhythmDensity,
+  rhythmToNoteEvents,
   substituteChord,
   transformMotif
 };

package/dist/{index-Jc0Ryi79.d.ts → index-B2Ulxxpo.d.cts}

@@ -1,5 +1,5 @@
-import { K as KeyScale } from './types-MGP29r3t.js';
-import { C as Chord } from './index-Bt4tOUD9.js';
+import { K as KeyScale } from './types-BN6_Q9Kl.cjs';
+import { C as Chord } from './index-oTQbYYIs.cjs';
 
 /**
  * Severity policy: `strict` counterpoint vs. lenient `pop` voice-leading.
@@ -38,7 +38,8 @@ declare enum ReasonFlag {
     HiddenParallel = 4096,
     VoiceCrossing = 8192,
     Suspension = 16384,
-    NeedsResolution = 32768
+    NeedsResolution = 32768,
+    MelodicTritone = 65536
 }
 /**
  * A neighbouring voice's current and previous pitch.
@@ -102,7 +103,22 @@ type SafetyResult = {
  * ```
  * @category Arrangement & Analysis
  */
-declare function evaluateSafety(q: SafetyQuery): SafetyResult;
+declare function evaluateSafety(q: SafetyQuery, opts?: EvaluateSafetyOptions): SafetyResult;
+/**
+ * Options for {@link evaluateSafety}.
+ *
+ * @category Arrangement & Analysis
+ */
+type EvaluateSafetyOptions = {
+    /**
+     * Whether to search for safe replacement pitches when the verdict is not
+     * safe. Turning it off skips up to two dozen extra evaluations per rejected
+     * pitch, which is worth doing when only the verdict is wanted.
+     *
+     * @defaultValue true
+     */
+    suggestions?: boolean;
+};
 /**
  * Enumerate placeable pitches in a range, chord tones first, descending.
  *
@@ -125,4 +141,4 @@ declare function evaluateSafety(q: SafetyQuery): SafetyResult;
  */
 declare function enumerateSafePitches(q: Omit<SafetyQuery, 'candidatePitch'>, pitchLow: number, pitchHigh: number): number[];
 
-export { NoteSafety as N, ReasonFlag as R, type SafetyProfile as S, type VoiceSnapshot as V, type SafetyQuery as a, type SafetyResult as b, evaluateSafety as c, enumerateSafePitches as e };
+export { type EvaluateSafetyOptions as E, NoteSafety as N, ReasonFlag as R, type SafetyProfile as S, type VoiceSnapshot as V, type SafetyQuery as a, type SafetyResult as b, evaluateSafety as c, enumerateSafePitches as e };

package/dist/{index-CpOsP1y9.d.cts → index-BkYJ0xMq.d.cts}

@@ -1,18 +1,8 @@
-import { T as TimeSignature } from './index-Cl7mhOFM.cjs';
-import { K as KeyScale, N as NoteEvent } from './types-MGP29r3t.cjs';
-import { C as Chord, b as ChordSpan } from './index-BNlGP86A.cjs';
-import { C as Cadence } from './function-DYt4iKsn.cjs';
+import { T as TimeSignature } from './index-DXd9JikN.cjs';
+import { K as KeyScale, N as NoteEvent } from './types-BN6_Q9Kl.cjs';
+import { C as Chord, b as ChordSegment, c as ChordSpan } from './index-oTQbYYIs.cjs';
+import { C as Cadence } from './function-CxixTB02.cjs';
 
-/**
- * A chord occupying a half-open beat span.
- *
- * @category Arrangement & Analysis
- */
-type ChordSegment = {
-    startBeat: number;
-    endBeat: number;
-    chord: Chord;
-};
 /**
  * A beat-indexed sequence of chord segments.
  *
@@ -36,14 +26,14 @@ type ChordTimeline = {
  * @returns A queryable chord timeline.
  * @category Arrangement & Analysis
  */
-declare function chordTimelineFromChords(chords: ChordSpan[], totalBeats: number): ChordTimeline;
+declare function chordTimelineFromChords(chords: readonly ChordSpan[], totalBeats: number): ChordTimeline;
 /**
  * Options controlling {@link chordTimelineFromNotes}.
  *
  * @category Arrangement & Analysis
  */
 type ChordTimelineOptions = {
-    /** Key context; inferred from the notes with {@link detectKey} when omitted. */
+    /** Key context; inferred from the notes with {@link detectKeyFromNotes} when omitted. */
     key?: KeyScale;
     /**
      * Time signature used for metric accents; defaults to 4/4.
@@ -63,6 +53,17 @@ type ChordTimelineOptions = {
      * @defaultValue the end of the last note
      */
     totalBeats?: number;
+    /**
+     * Upper bound on the work this call may do — note counts, windows, and
+     * candidate counts are each checked against it before anything is allocated.
+     *
+     * Raise it to analyse a piece larger than the default allows; the default is
+     * {@link DEFAULT_GENERATION_BUDGET}, chosen so a runaway input fails fast
+     * rather than blocking the thread.
+     *
+     * @defaultValue {@link DEFAULT_GENERATION_BUDGET}
+     */
+    budget?: number;
 };
 /**
  * The result of {@link chordTimelineFromNotes}.
@@ -148,4 +149,4 @@ type CadenceHit = {
  */
 declare function detectCadences(timeline: ChordTimeline, key: KeyScale): CadenceHit[];
 
-export { type CadenceHit as C, type ChordSegment as a, type ChordTimeline as b, type ChordTimelineOptions as c, type ChordTimelineResult as d, chordTimelineFromChords as e, chordTimelineFromNotes as f, detectCadences as g };
+export { type CadenceHit as C, type ChordTimeline as a, type ChordTimelineOptions as b, type ChordTimelineResult as c, chordTimelineFromChords as d, chordTimelineFromNotes as e, detectCadences as f };

package/dist/{index-CxqBQtH1.d.cts → index-BuaB-ypt.d.ts}

@@ -1,5 +1,5 @@
-import { K as KeyScale } from './types-MGP29r3t.cjs';
-import { C as Chord } from './index-BNlGP86A.cjs';
+import { K as KeyScale } from './types-BN6_Q9Kl.js';
+import { C as Chord } from './index-COw1Ky9g.js';
 
 /**
  * Severity policy: `strict` counterpoint vs. lenient `pop` voice-leading.
@@ -38,7 +38,8 @@ declare enum ReasonFlag {
     HiddenParallel = 4096,
     VoiceCrossing = 8192,
     Suspension = 16384,
-    NeedsResolution = 32768
+    NeedsResolution = 32768,
+    MelodicTritone = 65536
 }
 /**
  * A neighbouring voice's current and previous pitch.
@@ -102,7 +103,22 @@ type SafetyResult = {
  * ```
  * @category Arrangement & Analysis
  */
-declare function evaluateSafety(q: SafetyQuery): SafetyResult;
+declare function evaluateSafety(q: SafetyQuery, opts?: EvaluateSafetyOptions): SafetyResult;
+/**
+ * Options for {@link evaluateSafety}.
+ *
+ * @category Arrangement & Analysis
+ */
+type EvaluateSafetyOptions = {
+    /**
+     * Whether to search for safe replacement pitches when the verdict is not
+     * safe. Turning it off skips up to two dozen extra evaluations per rejected
+     * pitch, which is worth doing when only the verdict is wanted.
+     *
+     * @defaultValue true
+     */
+    suggestions?: boolean;
+};
 /**
  * Enumerate placeable pitches in a range, chord tones first, descending.
  *
@@ -125,4 +141,4 @@ declare function evaluateSafety(q: SafetyQuery): SafetyResult;
  */
 declare function enumerateSafePitches(q: Omit<SafetyQuery, 'candidatePitch'>, pitchLow: number, pitchHigh: number): number[];
 
-export { NoteSafety as N, ReasonFlag as R, type SafetyProfile as S, type VoiceSnapshot as V, type SafetyQuery as a, type SafetyResult as b, evaluateSafety as c, enumerateSafePitches as e };
+export { type EvaluateSafetyOptions as E, NoteSafety as N, ReasonFlag as R, type SafetyProfile as S, type VoiceSnapshot as V, type SafetyQuery as a, type SafetyResult as b, evaluateSafety as c, enumerateSafePitches as e };

package/dist/index-CAN7v-kw.d.ts

@@ -0,0 +1,199 @@
+import { K as KeyScale, N as NoteEvent } from './types-BN6_Q9Kl.js';
+import { a as ChordQuality, C as Chord } from './index-COw1Ky9g.js';
+
+/**
+ * Recognition: infer a chord name from a set of pitches, or a key from a set of
+ * pitch classes. This is the inverse direction of the chord/scale builders,
+ * which only go name -> notes.
+ */
+
+/**
+ * A candidate chord interpretation of a pitch set.
+ *
+ * @category Recognition
+ */
+type ChordMatch = {
+    rootPc: number;
+    quality: ChordQuality;
+    /** Chord tones absent from the input (an incomplete voicing). */
+    missingPcs: number[];
+    /** Input pitch classes not belonging to the chord. */
+    extraPcs: number[];
+    /** True when the input pitch-class set equals the chord exactly. */
+    exact: boolean;
+    /**
+     * Inversion implied by a known bass: 0 for root position, 1..n for an
+     * inversion. Null when no inversion can be named — either the input is an
+     * unordered pitch-class set with no bass, or the bass is not a chord tone (a
+     * pedal or passing bass), in which case `bassPc` still reports it.
+     */
+    inversion: number | null;
+    /** Bass pitch class when the lowest note is not the root. */
+    bassPc?: number;
+};
+/**
+ * Input interpretation for {@link detectChord} and {@link detectChordBest}.
+ *
+ * @category Recognition
+ */
+type DetectChordOptions = {
+    /**
+     * `midi` uses the numerically lowest pitch as bass; `pitchClass` treats the
+     * input as unordered. `auto` (default) selects pitch-class mode only when all
+     * values lie in 0..11.
+     */
+    input?: 'auto' | 'midi' | 'pitchClass';
+    /** Explicit bass pitch class, including for an unordered pitch-class set. */
+    bassPc?: number;
+};
+/**
+ * A candidate key interpretation of a pitch-class set.
+ *
+ * @category Recognition
+ */
+type KeyMatch = {
+    /** The scale that scored best for this tonic and mode, `variant` included. */
+    key: KeyScale;
+    mode: 'major' | 'minor';
+    /** Which scale form `key` uses; minor keys pick the best-scoring of the three. */
+    variant: KeyVariant;
+    /**
+     * Fraction of the distinct input pitch classes that belong to `key`, in
+     * [0, 1]. Measured against the returned scale, so it always agrees with
+     * `isScaleTone(pc, match.key)`. This is a coverage figure, not the ranking:
+     * see `score`.
+     */
+    fit: number;
+    /**
+     * The value the results are ranked by, in [0, 1.5]. Unlike `fit` it counts
+     * every occurrence rather than every distinct pitch class, so a repeated tone
+     * weighs more, and it adds half a count per sounding of the tonic itself to
+     * break ties between keys that contain the same notes.
+     */
+    score: number;
+};
+/**
+ * Which form of a scale a {@link KeyMatch} settled on.
+ *
+ * @category Recognition
+ */
+type KeyVariant = 'major' | 'natural' | 'harmonic' | 'melodic';
+/**
+ * Input weighting for {@link detectKey}.
+ *
+ * @category Recognition
+ */
+type DetectKeyOptions = {
+    /**
+     * How much each pitch counts toward the histogram, one entry per pitch.
+     * Defaults to one per pitch, which weighs a thirty-second-note ornament as
+     * heavily as the whole note under it. {@link detectKeyFromNotes} supplies
+     * duration times velocity, matching how chord inference weighs its own
+     * histogram.
+     */
+    weights?: readonly number[];
+    /**
+     * Upper bound on the input pitches processed by this detection call.
+     *
+     * @defaultValue {@link DEFAULT_GENERATION_BUDGET}
+     */
+    budget?: number;
+};
+/**
+ * Identify chords matching a set of pitches.
+ *
+ * Every input pitch class is tried as a root against every known chord quality.
+ * A match is reported when all of the chord's tones are present in the input, or
+ * when the only absent tone is the perfect fifth (a common omission in shell
+ * voicings); matches are ranked best-first by fewest extra notes, then fewest
+ * missing notes, then most specific (largest) chord. An exact match (no extras,
+ * no missing) is flagged and ranked first.
+ *
+ * @param pitches MIDI pitches or bare pitch classes (octave-agnostic).
+ * @returns Ranked chord interpretations (may be empty).
+ * @example
+ * ```ts
+ * import { detectChord } from '@libraz/libcantus';
+ * const matches = detectChord([60, 64, 67]); // C E G
+ * matches[0]; // { rootPc: 0, quality: 'maj', exact: true, ... }
+ * ```
+ * @category Recognition
+ */
+declare function detectChord(pitches: readonly number[], opts?: DetectChordOptions): ChordMatch[];
+/**
+ * The single best chord interpretation of a pitch set, or null if none.
+ *
+ * @param pitches MIDI pitches or bare pitch classes.
+ * @returns The top-ranked chord, or null when nothing matches.
+ * @example
+ * ```ts
+ * import { detectChordBest } from '@libraz/libcantus';
+ * detectChordBest([60, 64, 67]); // C major triad: { rootPc: 0, quality: 'maj', ... }
+ * ```
+ * @category Recognition
+ */
+declare function detectChordBest(pitches: readonly number[], opts?: DetectChordOptions): Chord | null;
+/**
+ * Rank major and minor keys by how well they contain a set of pitch classes.
+ *
+ * Ranking is by `score`, which counts repetitions and adds a tonic weight so
+ * that, among equally-fitting keys, the one whose root is actually sounded is
+ * preferred. Minor candidates are scored against the natural, harmonic, and
+ * melodic minor variants and keep the best of the three, so a minor cadence
+ * containing the leading tone still resolves to its own tonic; the winning
+ * variant is what `key` and `variant` report, so `fit` describes the scale the
+ * caller receives. Returns all 24 keys ranked best-first, or an empty array for
+ * an empty input (mirroring {@link detectChord}).
+ *
+ * @param pitches MIDI pitches or bare pitch classes.
+ * @returns Ranked key interpretations (empty for an empty input).
+ * @example
+ * ```ts
+ * import { detectKey } from '@libraz/libcantus';
+ * const keys = detectKey([60, 62, 64, 65, 67, 69, 71]); // C major scale
+ * keys[0].mode; // 'major', with keys[0].key.rootPc === 0
+ * ```
+ * @category Recognition
+ */
+declare function detectKey(pitches: readonly number[], opts?: DetectKeyOptions): KeyMatch[];
+/**
+ * Rank keys by how well they contain a set of note events, weighting each note
+ * by how much of the music it actually occupies.
+ *
+ * {@link detectKey} counts every pitch once, which lets a run of fast ornamental
+ * notes outvote the sustained harmony that establishes the key. This weighs
+ * each note by duration times velocity, the same measure chord inference uses,
+ * so the two agree on what the music emphasises. Notes that never sound (zero
+ * or negative duration) are ignored.
+ *
+ * @param notes The note events to weigh.
+ * @param opts Budget for processing imported note events.
+ * @returns Ranked key interpretations (empty when nothing sounds).
+ * @example
+ * ```ts
+ * import { detectKeyFromNotes } from '@libraz/libcantus';
+ * detectKeyFromNotes([{ pitch: 60, startBeat: 0, durationBeat: 4 }])[0]?.key.rootPc; // 0
+ * ```
+ * @category Recognition
+ */
+declare function detectKeyFromNotes(notes: readonly NoteEvent[], opts?: Omit<DetectKeyOptions, 'weights'>): KeyMatch[];
+/**
+ * The single best key interpretation of a pitch set.
+ *
+ * The counterpart of {@link detectChordBest}: the ranked list is the general
+ * answer, but a caller that just wants "what key is this" should not have to
+ * index into it and assert the result is there.
+ *
+ * @param pitches MIDI pitches or bare pitch classes.
+ * @param opts How to weigh the input; see {@link DetectKeyOptions}.
+ * @returns The top-ranked key, or null when nothing sounds.
+ * @example
+ * ```ts
+ * import { detectKeyBest } from '@libraz/libcantus';
+ * detectKeyBest([0, 2, 4, 5, 7, 9, 11])?.mode; // 'major'
+ * ```
+ * @category Recognition
+ */
+declare function detectKeyBest(pitches: readonly number[], opts?: DetectKeyOptions): KeyMatch | null;
+
+export { type ChordMatch as C, type DetectChordOptions as D, type KeyMatch as K, type DetectKeyOptions as a, type KeyVariant as b, detectChordBest as c, detectChord as d, detectKey as e, detectKeyBest as f, detectKeyFromNotes as g };

package/dist/{index-Bt4tOUD9.d.ts → index-COw1Ky9g.d.ts}

@@ -1,11 +1,20 @@
-import { K as KeyScale } from './types-MGP29r3t.js';
+import { K as KeyScale } from './types-BN6_Q9Kl.js';
 
 /**
  * Chord quality identifiers understood by the chord builder.
  *
  * @category Chords
  */
-type ChordQuality = 'maj' | 'min' | 'dim' | 'aug' | 'maj7' | 'min7' | 'dom7' | 'dim7' | 'm7b5' | 'minMaj7' | 'aug7' | 'augMaj7' | 'majb5' | '6' | 'min6' | '6/9' | 'sus2' | 'sus4' | 'add9' | 'add11' | 'maj9' | 'min9' | 'dom9' | '7b9' | '7#9' | '7#11' | '7b13' | '11' | '13' | '5';
+type ChordQuality = 'maj' | 'min' | 'dim' | 'aug' | 'maj7' | 'min7' | 'dom7' | 'dim7' | 'm7b5' | 'minMaj7' | 'minMaj9' | 'minMaj11' | 'minMaj13' | 'aug7' | 'augMaj7' | 'majb5' | '6' | 'min6' | '6/9' | 'sus2' | 'sus4' | 'add9' | 'add11' | 'maj9' | 'min9' | 'dom9' | '7b9' | '7#9' | '7#11' | '7b13' | '11' | '13' | '5' | '7sus4' | '7b5' | '7alt' | '13b9' | 'maj13' | 'maj7#11' | 'min11' | 'min13' | 'minAdd9' | 'min6/9';
+/**
+ * The basic role a chord tone plays: the degrees a chord's own template names.
+ *
+ * The shared vocabulary behind {@link chordToneRole}, the harmony layer's
+ * `HarmonyRole`, and the voice analyser's labels, so the three cannot drift.
+ *
+ * @category Chords
+ */
+type ChordToneRole = 'root' | 'third' | 'fifth' | 'sixth' | 'seventh';
 /**
  * A bare spelled pitch used as an enharmonic hint: a diatonic letter
  * (0..6 = C..B) plus a chromatic alteration (-2 double-flat .. +2 double-sharp).
@@ -54,7 +63,26 @@ type ChordSpan = {
     secondaryDominant?: boolean;
 };
 /**
- * All chord qualities the builder understands, longest templates last.
+ * A chord occupying a half-open beat span `[startBeat, endBeat)`.
+ *
+ * The exchange record between anything that lays chords out in time — a
+ * timeline analysis, a bass-line plan, an accompaniment generator — so those
+ * surfaces share one definition instead of agreeing by coincidence.
+ *
+ * @category Composition
+ */
+type ChordSegment = {
+    startBeat: number;
+    endBeat: number;
+    chord: Chord;
+};
+/**
+ * All chord qualities the builder understands, in declaration order.
+ *
+ * The order is stable but carries no meaning: it is neither alphabetical nor
+ * sorted by template size. {@link detectChord} uses it as its final tie-break,
+ * so it is part of the observable behaviour and does not get reshuffled
+ * casually — but do not read it as a ranking.
  *
  * @category Chords
  */
@@ -92,21 +120,73 @@ declare function chordFromDegree(degree: number, ext: ChordQuality, key: KeyScal
  * @category Chords
  */
 declare function makeChord(rootPc: number, quality: ChordQuality, bassPc?: number): Chord;
+/**
+ * Transpose a chord by a number of semitones.
+ *
+ * The interval template is carried over untouched, so a chord whose intervals
+ * were customised keeps them, and a slash bass moves with the root. Enharmonic
+ * spelling hints are dropped rather than shifted: the letter a transposed root
+ * should take depends on the destination key, which a semitone count does not
+ * carry. Pass the result through {@link spellChord} to respell it.
+ *
+ * @param chord The chord to transpose.
+ * @param semitones The signed semitone offset.
+ * @returns The transposed chord.
+ * @throws If `semitones` is not finite.
+ *
+ * @example
+ * ```ts
+ * import { formatChordSymbol, parseChordSymbol, transposeChord } from '@libraz/libcantus';
+ * formatChordSymbol(transposeChord(parseChordSymbol('C/G'), 2)); // 'D/A'
+ * ```
+ *
+ * @category Chords
+ */
+declare function transposeChord(chord: Chord, semitones: number): Chord;
 /**
  * Get the sorted, deduplicated pitch classes of a chord.
  *
+ * A slash bass is one of them: `F/G` sounds a G, the voicers put it in the
+ * bass, and a set that omitted it would not re-detect as the chord it came
+ * from. Pass `includeBass: false` to enumerate the interval template alone.
+ *
  * @param chord The chord to enumerate.
+ * @param opts Set `includeBass: false` to omit a slash bass.
  * @returns The chord's pitch classes, sorted ascending in [0, 11].
  *
  * @example
  * ```ts
  * import { makeChord, chordPitchClasses } from '@libraz/libcantus';
  * chordPitchClasses(makeChord(0, 'maj7')); // [0, 4, 7, 11]
+ * chordPitchClasses(makeChord(5, 'maj', 7)); // [0, 5, 7, 9] — F/G, G included
  * ```
  *
  * @category Chords
  */
-declare function chordPitchClasses(chord: Chord): number[];
+declare function chordPitchClasses(chord: Chord, opts?: {
+    includeBass?: boolean;
+}): number[];
+/**
+ * A pitch's interval class above the chord root, in [0, 11].
+ *
+ * The shared reading of "where does this pitch sit in the chord", used by the
+ * safety evaluator and the voice analyser alike so they cannot disagree.
+ *
+ * @param pitch MIDI pitch or bare pitch class.
+ * @param chord The chord providing the root reference.
+ * @returns The interval class above the root.
+ * @category Chords
+ */
+declare function intervalAboveRoot(pitch: number, chord: Chord): number;
+/**
+ * Whether a pitch is one of a chord's tones, ignoring octave.
+ *
+ * @param pitch MIDI pitch or bare pitch class.
+ * @param chord The chord, or null for no sounding harmony.
+ * @returns True when the pitch class belongs to the chord.
+ * @category Chords
+ */
+declare function isChordMember(pitch: number, chord: Chord | null): boolean;
 /**
  * Determine a pitch's harmonic role within a chord.
  *
@@ -121,18 +201,21 @@ declare function chordPitchClasses(chord: Chord): number[];
  *
  * @category Chords
  */
-declare function chordToneRole(pitch: number, chord: Chord): 'root' | 'third' | 'fifth' | 'sixth' | 'seventh' | null;
+declare function chordToneRole(pitch: number, chord: Chord): ChordToneRole | null;
 /**
  * Build the diatonic triad rooted on a scale degree by stacking scale thirds.
  *
  * Unlike {@link chordFromDegree}, the chord quality is derived from the scale
  * rather than supplied, so degrees yield their scale-correct triads (e.g. a
- * diminished triad on the leading tone of a major key). Intended for heptatonic
- * scales; other scales stack by scale step regardless.
+ * diminished triad on the leading tone of a major key).
  *
  * @param degree 0-based scale degree of the chord root.
  * @param key Key/scale context.
  * @returns The diatonic triad.
+ * @throws If the scale is not heptatonic. Stacking thirds means skipping every
+ *   other degree, which only lands on a triad when there are seven of them, so
+ *   the pentatonic, blues, whole-tone, octatonic and chromatic scales have no
+ *   diatonic triad; use {@link chordFromDegree} with an explicit quality there.
  *
  * @example
  * ```ts
@@ -149,9 +232,11 @@ declare function diatonicTriad(degree: number, key: KeyScale): Chord;
  * @param degree 0-based scale degree of the chord root.
  * @param key Key/scale context.
  * @returns The diatonic seventh chord.
+ * @throws If the scale is not heptatonic, for the reason given on
+ *   {@link diatonicTriad}.
  *
  * @category Chords
  */
 declare function diatonicSeventh(degree: number, key: KeyScale): Chord;
 
-export { type Chord as C, type PitchSpelling as P, type ChordQuality as a, type ChordSpan as b, chordFromDegree as c, chordPitchClasses as d, chordQualities as e, chordToneRole as f, diatonicSeventh as g, diatonicTriad as h, makeChord as m };
+export { type Chord as C, type PitchSpelling as P, type ChordQuality as a, type ChordSegment as b, type ChordSpan as c, type ChordToneRole as d, chordFromDegree as e, chordPitchClasses as f, chordQualities as g, chordToneRole as h, diatonicSeventh as i, diatonicTriad as j, intervalAboveRoot as k, isChordMember as l, makeChord as m, transposeChord as t };

package/dist/{index-Dikst44v.d.cts → index-Cfx8xgH0.d.ts}

@@ -1,11 +1,11 @@
-import { C as Chord } from './index-BNlGP86A.cjs';
+import { d as ChordToneRole, C as Chord } from './index-COw1Ky9g.js';
 
 /**
  * Harmonic role a pitch plays within a chord.
  *
  * @category Functional Harmony
  */
-type HarmonyRole = 'root' | 'third' | 'fifth' | 'sixth' | 'seventh' | 'tension' | 'doubling';
+type HarmonyRole = ChordToneRole | 'tension' | 'doubling';
 /**
  * How firmly a pitch is locked to the chord's identity.
  *
@@ -29,15 +29,18 @@ type VoicedRole = {
 /**
  * Classify a pitch's harmonic role and lock level within a chord.
  *
- * The role comes from the pitch's interval class above the chord root: root (0),
- * third (3/4), fifth (6/7/8), seventh (10/11), and 9/11/13 tensions (2/5/9, and
- * the flat ninth 1). The root locks the chord identity, the third locks its
- * quality, and everything else is free voicing. In a suspended chord (a chord
- * whose intervals include a 4th (5) or 2nd (2) but no third), the suspended tone
- * takes the third's place as the quality-defining tone and is locked to
- * `quality`, since moving it changes the chord. Detecting an octave doubling
- * requires the surrounding voicing, which this single-pitch query does not carry,
- * so `doubling` is part of the type but not returned here.
+ * The role comes from the pitch's interval class above the chord root, read
+ * against the chord's own template: root (0), third (3/4), fifth (6/7/8),
+ * sixth or seventh (9/10/11). Every pitch the template does not claim is
+ * `'tension'` — including one that is simply foreign to the chord, which this
+ * single-pitch query cannot tell from a colour tone. The root locks the chord
+ * identity, the third locks its quality, and everything else is free voicing.
+ * In a suspended chord (a chord whose intervals include a 4th (5) or 2nd (2)
+ * but no third), the suspended tone takes the third's place as the
+ * quality-defining tone and is locked to `quality`, since moving it changes the
+ * chord. Detecting an octave doubling requires the surrounding voicing, which
+ * this query does not carry, so `'doubling'` is part of the type — the shared
+ * vocabulary of harmonic roles — but is never returned here.
  *
  * @param pitch MIDI pitch or bare pitch class.
  * @param chord The chord providing the root reference.