@libraz/libcantus 0.9.0 → 0.9.1

package/dist/index.d.cts

@@ -27,16 +27,47 @@ type NoteEvent = {
     velocity?: number;
 };
 
-/** Chord quality identifiers understood by the chord builder. */
+/**
+ * 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';
-/** A chord expressed as a root pitch class plus semitone offsets. */
+/**
+ * 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).
+ * Mirrors the letter/alter half of the pitch module's `Note` without an octave.
+ *
+ * @category Chords
+ */
+type PitchSpelling = {
+    letter: number;
+    alter: number;
+};
+/**
+ * A chord expressed as a root pitch class plus semitone offsets.
+ *
+ * `rootSpelling`/`bassSpelling` are optional enharmonic hints recorded by
+ * parsers (e.g. `parseChordSymbol('Bb7')`) so formatters can reproduce the
+ * original spelling instead of defaulting to sharps. Consumers may ignore
+ * them; a hint is only trusted when its pitch class still matches the
+ * corresponding `rootPc`/`bassPc`.
+ *
+ * @category Chords
+ */
 type Chord$1 = {
     rootPc: number;
     quality: ChordQuality;
     intervals: number[];
     bassPc?: number;
+    rootSpelling?: PitchSpelling;
+    bassSpelling?: PitchSpelling;
 };
-/** All chord qualities the builder understands, longest templates last. */
+/**
+ * All chord qualities the builder understands, longest templates last.
+ *
+ * @category Chords
+ */
 declare function chordQualities(): ChordQuality[];
 /**
  * Build a chord rooted on a diatonic scale degree.
@@ -49,6 +80,8 @@ declare function chordQualities(): ChordQuality[];
  * @param ext Chord quality to apply.
  * @param key Key context supplying the diatonic root.
  * @returns The constructed chord.
+ *
+ * @category Chords
  */
 declare function chordFromDegree(degree: number, ext: ChordQuality, key: KeyScale): Chord$1;
 /**
@@ -58,6 +91,15 @@ declare function chordFromDegree(degree: number, ext: ChordQuality, key: KeyScal
  * @param quality Chord quality supplying the interval template.
  * @param bassPc Optional slash-chord bass pitch class.
  * @returns The constructed chord.
+ *
+ * @example
+ * ```ts
+ * import { makeChord } from '@libraz/libcantus';
+ * const cmaj7 = makeChord(0, 'maj7');
+ * // { rootPc: 0, quality: 'maj7', intervals: [0, 4, 7, 11] }
+ * ```
+ *
+ * @category Chords
  */
 declare function makeChord(rootPc: number, quality: ChordQuality, bassPc?: number): Chord$1;
 /**
@@ -65,6 +107,14 @@ declare function makeChord(rootPc: number, quality: ChordQuality, bassPc?: numbe
  *
  * @param chord The chord to enumerate.
  * @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]
+ * ```
+ *
+ * @category Chords
  */
 declare function chordPitchClasses(chord: Chord$1): number[];
 /**
@@ -78,6 +128,8 @@ declare function chordPitchClasses(chord: Chord$1): number[];
  * @param pitch MIDI pitch or bare pitch class.
  * @param chord The chord providing the root reference.
  * @returns The chord-tone role, or null if the pitch has no basic role.
+ *
+ * @category Chords
  */
 declare function chordToneRole(pitch: number, chord: Chord$1): 'root' | 'third' | 'fifth' | 'sixth' | 'seventh' | null;
 /**
@@ -91,6 +143,14 @@ declare function chordToneRole(pitch: number, chord: Chord$1): 'root' | 'third'
  * @param degree 0-based scale degree of the chord root.
  * @param key Key/scale context.
  * @returns The diatonic triad.
+ *
+ * @example
+ * ```ts
+ * import { majorKey, diatonicTriad } from '@libraz/libcantus';
+ * const tonic = diatonicTriad(0, majorKey(0)); // C major triad (degree 0 of C major)
+ * ```
+ *
+ * @category Chords
  */
 declare function diatonicTriad(degree: number, key: KeyScale): Chord$1;
 /**
@@ -99,18 +159,32 @@ declare function diatonicTriad(degree: number, key: KeyScale): Chord$1;
  * @param degree 0-based scale degree of the chord root.
  * @param key Key/scale context.
  * @returns The diatonic seventh chord.
+ *
+ * @category Chords
  */
 declare function diatonicSeventh(degree: number, key: KeyScale): Chord$1;
 
-/** Severity policy: `strict` counterpoint vs. lenient `pop` voice-leading. */
+/**
+ * Severity policy: `strict` counterpoint vs. lenient `pop` voice-leading.
+ *
+ * @category Arrangement & Analysis
+ */
 type SafetyProfile = 'strict' | 'pop';
-/** Overall placeability verdict for a candidate pitch. */
+/**
+ * Overall placeability verdict for a candidate pitch.
+ *
+ * @category Arrangement & Analysis
+ */
 declare enum NoteSafety {
     Safe = 0,
     Warning = 1,
     Dissonant = 2
 }
-/** Bit flags describing why a pitch received its verdict. */
+/**
+ * Bit flags describing why a pitch received its verdict.
+ *
+ * @category Arrangement & Analysis
+ */
 declare enum ReasonFlag {
     ChordTone = 1,
     Tension = 2,
@@ -129,12 +203,20 @@ declare enum ReasonFlag {
     Suspension = 16384,
     NeedsResolution = 32768
 }
-/** A neighbouring voice's current and previous pitch. */
+/**
+ * A neighbouring voice's current and previous pitch.
+ *
+ * @category Arrangement & Analysis
+ */
 type VoiceSnapshot = {
     pitch: number;
     prevPitch?: number;
 };
-/** Everything needed to evaluate one candidate pitch. */
+/**
+ * Everything needed to evaluate one candidate pitch.
+ *
+ * @category Arrangement & Analysis
+ */
 type SafetyQuery = {
     profile: SafetyProfile;
     candidatePitch: number;
@@ -146,7 +228,11 @@ type SafetyQuery = {
     vocalLow?: number;
     vocalHigh?: number;
 };
-/** The verdict, reason flags, and optional resolution guidance. */
+/**
+ * The verdict, reason flags, and optional resolution guidance.
+ *
+ * @category Arrangement & Analysis
+ */
 type SafetyResult = {
     safety: NoteSafety;
     reasons: number;
@@ -164,6 +250,20 @@ type SafetyResult = {
  *
  * @param q The candidate and its harmonic/voice-leading context.
  * @returns The verdict, reason bitmask, and optional resolution guidance.
+ * @example
+ * ```ts
+ * import { evaluateSafety, makeChord, majorKey, NoteSafety } from '@libraz/libcantus';
+ * const result = evaluateSafety({
+ *   profile: 'pop',
+ *   candidatePitch: 60, // C over a C major chord
+ *   chord: makeChord(0, 'maj'),
+ *   key: majorKey(0),
+ *   otherVoices: [],
+ *   strongBeat: true,
+ * });
+ * result.safety === NoteSafety.Safe; // true — C is a chord tone
+ * ```
+ * @category Arrangement & Analysis
  */
 declare function evaluateSafety(q: SafetyQuery): SafetyResult;
 /**
@@ -173,10 +273,25 @@ declare function evaluateSafety(q: SafetyQuery): SafetyResult;
  * @param pitchLow Lowest MIDI pitch to consider (inclusive).
  * @param pitchHigh Highest MIDI pitch to consider (inclusive).
  * @returns Placeable pitches (non-dissonant), chord tones before others, each group descending.
+ * @example
+ * ```ts
+ * import { enumerateSafePitches, makeChord, majorKey } from '@libraz/libcantus';
+ * const pitches = enumerateSafePitches(
+ *   { profile: 'pop', chord: makeChord(0, 'maj'), key: majorKey(0), otherVoices: [], strongBeat: true },
+ *   60,
+ *   72,
+ * );
+ * pitches; // placeable pitches in [60, 72], chord tones first, each group descending
+ * ```
+ * @category Arrangement & Analysis
  */
 declare function enumerateSafePitches(q: Omit<SafetyQuery, 'candidatePitch'>, pitchLow: number, pitchHigh: number): number[];
 
-/** A theory annotation attached to a note. */
+/**
+ * A theory annotation attached to a note.
+ *
+ * @category Arrangement & Analysis
+ */
 type TheoryLabel = {
     kind: 'chordTone';
     role: 'root' | 'third' | 'fifth' | 'sixth' | 'seventh';
@@ -204,13 +319,21 @@ type TheoryLabel = {
     kind: 'leadingTone';
     resolveTo: number;
 };
-/** A note with its theory labels and a short rationale. */
+/**
+ * A note with its theory labels and a short rationale.
+ *
+ * @category Arrangement & Analysis
+ */
 type AnalyzedNote = {
     noteId: number;
     labels: TheoryLabel[];
     rationale?: string;
 };
-/** A single note in a monophonic voice: a {@link NoteEvent} with a stable id. */
+/**
+ * A single note in a monophonic voice: a {@link NoteEvent} with a stable id.
+ *
+ * @category Arrangement & Analysis
+ */
 type VoiceNote = NoteEvent & {
     id: number;
 };
@@ -224,11 +347,30 @@ type VoiceNote = NoteEvent & {
  * avoid, or an unresolved-dissonance label. Leading-tone resolutions are noted
  * additionally.
  *
+ * The voice is expected to be monophonic (one note at a time). Notes sharing an
+ * onset are treated as simultaneous cluster members, not melodic neighbors, so
+ * they receive no melodic labels (suspension, passing, neighbor, anticipation,
+ * escape) — only harmonic ones. Callers with truly polyphonic material should
+ * split it into monophonic sub-voices first, as `analyzeArrangement` does.
+ *
  * @param voice The monophonic voice, in time order.
  * @param chordAtBeat Chord sounding at a given beat, or null.
  * @param key Key context for leading-tone detection.
  * @param otherVoicesAtBeat Other sounding voices at a given beat.
  * @returns One annotation per input note.
+ * @example
+ * ```ts
+ * import { analyzeVoice, makeChord, majorKey } from '@libraz/libcantus';
+ * const voice = [
+ *   { id: 0, pitch: 60, startBeat: 0, durationBeat: 1 },
+ *   { id: 1, pitch: 62, startBeat: 1, durationBeat: 1 },
+ *   { id: 2, pitch: 64, startBeat: 2, durationBeat: 1 },
+ * ];
+ * const cMajor = makeChord(0, 'maj');
+ * const labels = analyzeVoice(voice, () => cMajor, majorKey(0), () => []);
+ * labels; // one AnalyzedNote per input note, in the same order
+ * ```
+ * @category Arrangement & Analysis
  */
 declare function analyzeVoice(voice: VoiceNote[], chordAtBeat: (beat: number) => Chord$1 | null, key: KeyScale, otherVoicesAtBeat: (beat: number) => VoiceSnapshot[]): AnalyzedNote[];
 
@@ -239,12 +381,30 @@ declare function analyzeVoice(voice: VoiceNote[], chordAtBeat: (beat: number) =>
  * Positions and durations are measured in quarter-note beats, matching the rest
  * of the library's beat convention (four quarter-note beats per bar in 4/4).
  */
-/** A time signature as a numerator over a note-value denominator. */
+/**
+ * A time signature as a numerator over a note-value denominator.
+ *
+ * @category Rhythm & Meter
+ */
 type TimeSignature = {
     numerator: number;
     denominator: number;
+    /**
+     * Optional additive grouping of the bar's main pulses, as the felt-beat
+     * lengths in pulses — e.g. `[2, 2, 3]` for a 2+2+3 reading of 7/8, or
+     * `[3, 2]` for 5/8. The entries must be positive integers summing to
+     * {@link pulsesPerBar}. When present, the head pulse of each group (other
+     * than the downbeat) is treated as a secondary strong pulse by
+     * {@link metricWeight}/{@link isStrongBeat}; when absent, all main pulses
+     * are weighted equally as flat, evenly divided pulses.
+     */
+    grouping?: number[];
 };
-/** A position expressed as a bar index and a quarter-note offset within the bar. */
+/**
+ * A position expressed as a bar index and a quarter-note offset within the bar.
+ *
+ * @category Rhythm & Meter
+ */
 type BarPosition = {
     bar: number;
     /** Quarter-note offset from the start of the bar. */
@@ -256,9 +416,19 @@ type BarPosition = {
  * @param text The signature text.
  * @returns The parsed time signature.
  * @throws If the text is not `n/d` with positive integers.
+ * @example
+ * ```ts
+ * import { parseTimeSignature } from '@libraz/libcantus';
+ * parseTimeSignature('6/8'); // { numerator: 6, denominator: 8 }
+ * ```
+ * @category Rhythm & Meter
  */
 declare function parseTimeSignature(text: string): TimeSignature;
-/** Render a time signature as `"n/d"`. */
+/**
+ * Render a time signature as `"n/d"`.
+ *
+ * @category Rhythm & Meter
+ */
 declare function formatTimeSignature(ts: TimeSignature): string;
 /**
  * Whether a meter is compound: its main pulses each divide into three, as in
@@ -268,6 +438,7 @@ declare function formatTimeSignature(ts: TimeSignature): string;
  *
  * @param ts The time signature.
  * @returns True for compound meters.
+ * @category Rhythm & Meter
  */
 declare function isCompound(ts: TimeSignature): boolean;
 /**
@@ -275,14 +446,22 @@ declare function isCompound(ts: TimeSignature): boolean;
  *
  * @param ts The time signature.
  * @returns The bar length in quarter notes.
+ * @category Rhythm & Meter
  */
 declare function beatsPerBar(ts: TimeSignature): number;
 /**
  * Number of main pulses (felt beats) per bar: the numerator for simple meters,
  * a third of it for compound meters.
  *
+ * For additive/irregular meters such as 7/8 or 5/8 this counts the raw pulses
+ * (7 and 5 respectively), which are otherwise felt as flat, evenly divided and
+ * equally accented pulses. To recover a 2+2+3 or 3+2 felt-beat grouping, set
+ * {@link TimeSignature.grouping}; {@link metricWeight} then accents each
+ * group's head pulse.
+ *
  * @param ts The time signature.
  * @returns The pulse count per bar.
+ * @category Rhythm & Meter
  */
 declare function pulsesPerBar(ts: TimeSignature): number;
 /**
@@ -291,6 +470,13 @@ declare function pulsesPerBar(ts: TimeSignature): number;
  * @param beatInQuarters Absolute position in quarter-note beats.
  * @param ts The time signature.
  * @returns The bar and in-bar quarter-note offset.
+ * @example
+ * ```ts
+ * import { parseTimeSignature, beatToBarPosition } from '@libraz/libcantus';
+ * const ts = parseTimeSignature('4/4');
+ * beatToBarPosition(5, ts); // { bar: 1, beat: 1 }
+ * ```
+ * @category Rhythm & Meter
  */
 declare function beatToBarPosition(beatInQuarters: number, ts: TimeSignature): BarPosition;
 /**
@@ -300,16 +486,33 @@ declare function beatToBarPosition(beatInQuarters: number, ts: TimeSignature): B
  * @param pos The bar position.
  * @param ts The time signature.
  * @returns The absolute position in quarter-note beats.
+ * @category Rhythm & Meter
  */
 declare function barPositionToBeat(pos: BarPosition, ts: TimeSignature): number;
 /**
  * Metric weight of a position within its bar, on a 0–3 scale:
- * 3 the downbeat, 2 a secondary strong pulse (the bar's midpoint in even
- * meters), 1 any other main pulse, and 0 an off-pulse subdivision.
+ * 3 the downbeat, 2 a secondary strong pulse, 1 any other main pulse, and 0 an
+ * off-pulse subdivision.
+ *
+ * The secondary strong pulse is the bar's midpoint in even simple/compound
+ * meters. For an additive/irregular meter with {@link TimeSignature.grouping}
+ * set (e.g. `[2, 2, 3]` for 7/8), each group's head pulse other than the
+ * downbeat is the secondary strong pulse instead; without a grouping every
+ * non-downbeat main pulse of such a meter weighs 1 (flat, evenly divided
+ * pulses).
  *
  * @param beatInQuarters Absolute or in-bar quarter-note position.
  * @param ts The time signature.
  * @returns The metric weight (0–3).
+ * @throws If `ts.grouping` is present but is not a positive-integer list
+ *   summing to {@link pulsesPerBar}.
+ * @example
+ * ```ts
+ * import { parseTimeSignature, metricWeight } from '@libraz/libcantus';
+ * const ts = parseTimeSignature('4/4');
+ * metricWeight(0, ts); // 3 (the downbeat)
+ * ```
+ * @category Rhythm & Meter
  */
 declare function metricWeight(beatInQuarters: number, ts: TimeSignature): number;
 /**
@@ -319,6 +522,7 @@ declare function metricWeight(beatInQuarters: number, ts: TimeSignature): number
  * @param beatInQuarters Absolute or in-bar quarter-note position.
  * @param ts The time signature.
  * @returns True on strong beats.
+ * @category Rhythm & Meter
  */
 declare function isStrongBeat(beatInQuarters: number, ts: TimeSignature): boolean;
 /**
@@ -329,6 +533,7 @@ declare function isStrongBeat(beatInQuarters: number, ts: TimeSignature): boolea
  * @param count Number of equal parts.
  * @returns `count` equal durations summing to `totalBeats`.
  * @throws If `count` is not a positive integer.
+ * @category Rhythm & Meter
  */
 declare function tuplet(totalBeats: number, count: number): number[];
 
@@ -341,11 +546,23 @@ declare function tuplet(totalBeats: number, count: number): number[];
  * spelled key signature.
  */
 
-/** The three broad harmonic functions of tonal music. */
+/**
+ * The three broad harmonic functions of tonal music.
+ *
+ * @category Functional Harmony
+ */
 type HarmonicFunction = 'tonic' | 'subdominant' | 'dominant';
-/** A recognized cadence type, or null when a chord pair forms none. */
+/**
+ * A recognized cadence type, or null when a chord pair forms none.
+ *
+ * @category Functional Harmony
+ */
 type Cadence = 'authentic' | 'plagal' | 'half' | 'deceptive' | null;
-/** Whether a key's scale has a minor third and no major third (a minor key). */
+/**
+ * Whether a key's scale has a minor third and no major third (a minor key).
+ *
+ * @category Functional Harmony
+ */
 declare function isMinorKey(key: KeyScale): boolean;
 /**
  * Build the chord denoted by a Roman numeral in a key.
@@ -358,14 +575,24 @@ declare function isMinorKey(key: KeyScale): boolean;
  * carry a `bassPc`.
  *
  * The `ø` glyph always denotes the half-diminished seventh (`iiø` == `iiø7` ==
- * `m7b5`), since no half-diminished triad exists. Root-position extension
- * figures map to fixed qualities (`V9` -> `dom9`, `V11` -> `11`, `V13` -> `13`).
+ * `m7b5`), since no half-diminished triad exists. Extension and added-tone
+ * suffixes are the canonical case-sensitive forms emitted by
+ * {@link chordToRoman} and honor the numeral case: `V9` -> `dom9`, `ii9` ->
+ * `min9`, `Imaj9` -> `maj9`, `V11` -> `11`, `V13` -> `13`, `Iadd6`/`iadd6` ->
+ * `6`/`min6`, `I69` -> `6/9`, `Isus2`/`Isus4`, `Iadd9`/`Iadd11`, `Ib5` ->
+ * `majb5`, `I5` -> `5`, and the altered dominants `V7b9`/`V7#9`/`V7#11`/`V7b13`.
  * A figure string that is neither a recognized inversion nor a supported
- * extension throws rather than silently degrading to a triad.
+ * quality suffix throws rather than silently degrading to a triad.
  *
  * @param text The Roman numeral.
  * @param key The prevailing key.
  * @returns The chord.
+ * @example
+ * ```ts
+ * import { romanToChord, majorKey } from '@libraz/libcantus';
+ * romanToChord('V7', majorKey(0)); // G7 in C major: { rootPc: 7, quality: 'dom7', ... }
+ * ```
+ * @category Functional Harmony
  */
 declare function romanToChord(text: string, key: KeyScale): Chord$1;
 /**
@@ -375,11 +602,20 @@ declare function romanToChord(text: string, key: KeyScale): Chord$1;
  * correct in both major and minor keys (and any custom scale). The quality
  * selects the case and suffix; chromatic roots receive a flat/sharp spelling by
  * convention. When the chord carries a `bassPc` on a chord tone, a figured-bass
- * inversion (`6`, `64`, `65`, `43`, `42`) is emitted.
+ * inversion (`6`, `64`, `65`, `43`, `42`) is emitted for plain triads and true
+ * seventh chords; added-tone and extended qualities have no lossless figure and
+ * render in root position instead (the bass is dropped, pitch classes are
+ * preserved).
  *
  * @param chord The chord to name.
  * @param key The prevailing key.
  * @returns The Roman numeral string.
+ * @example
+ * ```ts
+ * import { chordToRoman, makeChord, majorKey } from '@libraz/libcantus';
+ * chordToRoman(makeChord(7, 'dom7'), majorKey(0)); // => 'V7' (G7 in C major)
+ * ```
+ * @category Functional Harmony
  */
 declare function chordToRoman(chord: Chord$1, key: KeyScale): string;
 /**
@@ -390,11 +626,20 @@ declare function chordToRoman(chord: Chord$1, key: KeyScale): string;
  * @param chord The chord.
  * @param key The prevailing key.
  * @returns The harmonic function.
+ * @category Functional Harmony
  */
 declare function functionOf(chord: Chord$1, key: KeyScale): HarmonicFunction;
-/** The origin of a recognized non-diatonic chord, or null when none applies. */
+/**
+ * The origin of a recognized non-diatonic chord, or null when none applies.
+ *
+ * @category Functional Harmony
+ */
 type BorrowedSource = 'parallel-minor' | 'parallel-major' | 'neapolitan' | null;
-/** The result of {@link analyzeChord}: function, borrowing, and Roman numeral. */
+/**
+ * The result of {@link analyzeChord}: function, borrowing, and Roman numeral.
+ *
+ * @category Functional Harmony
+ */
 type ChordAnalysis = {
     function: HarmonicFunction;
     borrowed: boolean;
@@ -412,6 +657,7 @@ type ChordAnalysis = {
  * @param chord The chord to test.
  * @param key The prevailing key.
  * @returns True if all chord pitch classes are scale tones.
+ * @category Functional Harmony
  */
 declare function isDiatonic(chord: Chord$1, key: KeyScale): boolean;
 /**
@@ -422,6 +668,7 @@ declare function isDiatonic(chord: Chord$1, key: KeyScale): boolean;
  *
  * @param key The key to mirror.
  * @returns The parallel major or natural-minor key on the same tonic.
+ * @category Functional Harmony
  */
 declare function parallelKey(key: KeyScale): KeyScale;
 /**
@@ -438,6 +685,7 @@ declare function parallelKey(key: KeyScale): KeyScale;
  * @param chord The chord to test.
  * @param key The prevailing key.
  * @returns True if the chord is borrowed from the parallel mode.
+ * @category Functional Harmony
  */
 declare function isBorrowedChord(chord: Chord$1, key: KeyScale): boolean;
 /**
@@ -451,6 +699,7 @@ declare function isBorrowedChord(chord: Chord$1, key: KeyScale): boolean;
  * @param chord The chord to classify.
  * @param key The prevailing key.
  * @returns The borrowing source, or null.
+ * @category Functional Harmony
  */
 declare function borrowedSource(chord: Chord$1, key: KeyScale): BorrowedSource;
 /**
@@ -465,6 +714,13 @@ declare function borrowedSource(chord: Chord$1, key: KeyScale): BorrowedSource;
  * @param chord The chord to analyze.
  * @param key The prevailing key.
  * @returns The chord analysis.
+ * @example
+ * ```ts
+ * import { analyzeChord, makeChord, majorKey } from '@libraz/libcantus';
+ * analyzeChord(makeChord(7, 'dom7'), majorKey(0));
+ * // { function: 'dominant', borrowed: false, source: null, roman: 'V7' }
+ * ```
+ * @category Functional Harmony
  */
 declare function analyzeChord(chord: Chord$1, key: KeyScale): ChordAnalysis;
 /**
@@ -482,6 +738,12 @@ declare function analyzeChord(chord: Chord$1, key: KeyScale): ChordAnalysis;
  * @param to The final chord.
  * @param key The prevailing key.
  * @returns The cadence type, or null.
+ * @example
+ * ```ts
+ * import { detectCadence, makeChord, majorKey } from '@libraz/libcantus';
+ * detectCadence(makeChord(7, 'maj'), makeChord(0, 'maj'), majorKey(0)); // => 'authentic'
+ * ```
+ * @category Functional Harmony
  */
 declare function detectCadence(from: Chord$1, to: Chord$1, key: KeyScale): Cadence;
 /**
@@ -490,14 +752,27 @@ declare function detectCadence(from: Chord$1, to: Chord$1, key: KeyScale): Caden
  * @param targetDegree 0-based scale degree to tonicize.
  * @param key The prevailing key.
  * @returns A dominant-seventh chord a fifth above the target's root.
+ * @category Functional Harmony
  */
 declare function secondaryDominant(targetDegree: number, key: KeyScale): Chord$1;
 
-/** Broad production style a progression preset suits. */
+/**
+ * Broad production style a progression preset suits.
+ *
+ * @category Composition
+ */
 type ProgStyle = 'minimal' | 'dance' | 'idol' | 'rock';
-/** Harmonic-function role of a progression as a whole. */
+/**
+ * Harmonic-function role of a progression as a whole.
+ *
+ * @category Composition
+ */
 type ProgFunction = 'loop' | 'tensionBuild' | 'cadenceStrong' | 'stable';
-/** A named chord-progression preset expressed in scale degrees. */
+/**
+ * A named chord-progression preset expressed in scale degrees.
+ *
+ * @category Composition
+ */
 type ProgressionPreset = {
     id: string;
     name: string;
@@ -505,7 +780,11 @@ type ProgressionPreset = {
     functional: ProgFunction;
     styles: ProgStyle[];
 };
-/** A chord placed on the timeline by {@link generateProgression}. */
+/**
+ * A chord placed on the timeline by {@link generateProgression}.
+ *
+ * @category Composition
+ */
 type GeneratedChord = {
     rootPc: number;
     quality: ChordQuality;
@@ -516,7 +795,11 @@ type GeneratedChord = {
     /** True when the chord is a secondary dominant tonicizing another degree. */
     secondaryDominant?: boolean;
 };
-/** Options controlling {@link generateProgression}. */
+/**
+ * Options controlling {@link generateProgression}.
+ *
+ * @category Composition
+ */
 type GenerateProgressionOptions = {
     key: KeyScale;
     style: ProgStyle;
@@ -524,17 +807,32 @@ type GenerateProgressionOptions = {
     presetId?: string;
     ext?: ChordQuality | 'auto';
     reharmonize?: boolean;
+    /**
+     * Seed for the deterministic preset choice and reharmonization.
+     *
+     * @defaultValue 0
+     */
     seed?: number;
 };
-/** All built-in progression presets. */
+/**
+ * All built-in progression presets.
+ *
+ * @category Composition
+ */
 declare function progressions(): ProgressionPreset[];
-/** Presets whose style list includes the given style. */
+/**
+ * Presets whose style list includes the given style.
+ *
+ * @category Composition
+ */
 declare function progressionsByStyle(style: ProgStyle): ProgressionPreset[];
 /**
  * Generate a chord progression laid out one chord per bar.
  *
  * A preset is chosen by `presetId` when given, otherwise deterministically from
- * the presets matching `style`, seeded by `seed`. The preset's degrees cycle to
+ * the presets matching `style`, seeded by `seed`. An unknown `presetId` is a
+ * caller error and throws rather than silently falling back to a random preset.
+ * The preset's degrees cycle to
  * fill `bars`; each bar is four beats, so `startBeat` is `barIndex * 4`. Chord
  * roots come from the key's diatonic scale-degree mapping. When `ext` is
  * omitted or `'auto'`, each chord takes its diatonic triad quality; otherwise
@@ -544,16 +842,34 @@ declare function progressionsByStyle(style: ProgStyle): ProgressionPreset[];
  *
  * @param opts Generation options.
  * @returns One chord per bar in timeline order.
+ * @throws If `presetId` is given but does not match any built-in preset.
+ *
+ * @example
+ * ```ts
+ * import { generateProgression, majorKey } from '@libraz/libcantus';
+ * const chords = generateProgression({ key: majorKey(0), style: 'dance', bars: 4 });
+ * // Deterministic for a given seed (defaults to 0); one GeneratedChord per bar.
+ * ```
+ *
+ * @category Composition
  */
 declare function generateProgression(opts: GenerateProgressionOptions): GeneratedChord[];
 
-/** A chord occupying a half-open beat span. */
+/**
+ * A chord occupying a half-open beat span.
+ *
+ * @category Arrangement & Analysis
+ */
 type ChordSegment = {
     startBeat: number;
     endBeat: number;
     chord: Chord$1;
 };
-/** A beat-indexed sequence of chord segments. */
+/**
+ * A beat-indexed sequence of chord segments.
+ *
+ * @category Arrangement & Analysis
+ */
 type ChordTimeline = {
     /** The chord sounding at a beat, or null when no segment covers it. */
     at: (beat: number) => Chord$1 | null;
@@ -570,20 +886,41 @@ type ChordTimeline = {
  * @param chords Placed chords in time order.
  * @param totalBeats End of the timeline in beats.
  * @returns A queryable chord timeline.
+ * @category Arrangement & Analysis
  */
 declare function chordTimelineFromChords(chords: GeneratedChord[], totalBeats: number): ChordTimeline;
-/** Options controlling {@link chordTimelineFromNotes}. */
+/**
+ * Options controlling {@link chordTimelineFromNotes}.
+ *
+ * @category Arrangement & Analysis
+ */
 type ChordTimelineOptions = {
     /** Key context; inferred from the notes with {@link detectKey} when omitted. */
     key?: KeyScale;
-    /** Time signature used for metric accents; defaults to 4/4. */
+    /**
+     * Time signature used for metric accents; defaults to 4/4.
+     *
+     * @defaultValue `4/4`
+     */
     ts?: TimeSignature;
-    /** Window length in beats per chord slot; defaults to one bar of `ts`. */
+    /**
+     * Window length in beats per chord slot; defaults to one bar of `ts`.
+     *
+     * @defaultValue one bar of `ts`
+     */
     harmonicRhythm?: number;
-    /** End of the analyzed span in beats; defaults to the end of the last note. */
+    /**
+     * End of the analyzed span in beats; defaults to the end of the last note.
+     *
+     * @defaultValue the end of the last note
+     */
     totalBeats?: number;
 };
-/** The result of {@link chordTimelineFromNotes}. */
+/**
+ * The result of {@link chordTimelineFromNotes}.
+ *
+ * @category Arrangement & Analysis
+ */
 type ChordTimelineResult = {
     /** The inferred timeline, with adjacent identical chords merged. */
     timeline: ChordTimeline;
@@ -604,13 +941,33 @@ type ChordTimelineResult = {
  * the fraction of the window weight explained by chord tones, reduced when the
  * match is inexact, and duration-weighted across merged windows.
  *
+ * Notes with a zero or negative duration never sound, so they are dropped at
+ * ingest: they contribute to neither the key inference, the span, nor any
+ * window's histogram.
+ *
  * @param notes The notes to analyze (any number of tracks, flattened).
  * @param opts Analysis options; see {@link ChordTimelineOptions}.
  * @returns The inferred timeline, the key used, and per-segment confidences.
  * @throws If `harmonicRhythm` is not positive.
+ * @example
+ * ```ts
+ * import { chordTimelineFromNotes } from '@libraz/libcantus';
+ * const notes = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 2 }, // C
+ *   { pitch: 64, startBeat: 0, durationBeat: 2 }, // E
+ *   { pitch: 67, startBeat: 0, durationBeat: 2 }, // G
+ * ];
+ * const { timeline, key } = chordTimelineFromNotes(notes);
+ * timeline.at(0); // the chord inferred over beat 0, or null
+ * ```
+ * @category Arrangement & Analysis
  */
 declare function chordTimelineFromNotes(notes: NoteEvent[], opts?: ChordTimelineOptions): ChordTimelineResult;
-/** A cadence found between two consecutive timeline segments. */
+/**
+ * A cadence found between two consecutive timeline segments.
+ *
+ * @category Arrangement & Analysis
+ */
 type CadenceHit = {
     /** The beat where the cadence arrives (the second chord's onset). */
     atBeat: number;
@@ -621,12 +978,25 @@ type CadenceHit = {
 /**
  * Find cadences between consecutive segments of a chord timeline.
  *
- * Each adjacent segment pair is classified with {@link detectCadence}; pairs
- * forming no cadence are skipped.
+ * Each temporally adjacent segment pair is classified with
+ * {@link detectCadence}; pairs forming no cadence are skipped. Segments
+ * separated by a gap (a rest in the timeline) are not a chord-to-chord
+ * progression, so they are never paired.
  *
  * @param timeline The chord timeline to scan.
  * @param key The prevailing key.
  * @returns The cadences found, in time order.
+ * @example
+ * ```ts
+ * import { chordTimelineFromNotes, detectCadences } from '@libraz/libcantus';
+ * const notes = [
+ *   { pitch: 67, startBeat: 0, durationBeat: 4 }, // G, a dominant
+ *   { pitch: 60, startBeat: 4, durationBeat: 4 }, // C, the tonic
+ * ];
+ * const { timeline, key } = chordTimelineFromNotes(notes);
+ * const cadences = detectCadences(timeline, key);
+ * ```
+ * @category Arrangement & Analysis
  */
 declare function detectCadences(timeline: ChordTimeline, key: KeyScale): CadenceHit[];
 
@@ -640,22 +1010,38 @@ declare function detectCadences(timeline: ChordTimeline, key: KeyScale): Cadence
  * curve is sampled across the piece.
  */
 
-/** The musical role a track plays in the arrangement. */
+/**
+ * The musical role a track plays in the arrangement.
+ *
+ * @category Arrangement & Analysis
+ */
 type TrackRole = 'melody' | 'harmony' | 'bass' | 'other';
-/** One input track: its notes plus optional name and role. */
+/**
+ * One input track: its notes plus optional name and role.
+ *
+ * @category Arrangement & Analysis
+ */
 type ArrangementTrack = {
     name?: string;
     role?: TrackRole;
     notes: NoteEvent[];
 };
-/** A track after analysis: its resolved name, role, and per-note annotations. */
+/**
+ * A track after analysis: its resolved name, role, and per-note annotations.
+ *
+ * @category Arrangement & Analysis
+ */
 type TrackAnalysis = {
     name: string;
     role: TrackRole;
     /** One {@link AnalyzedNote} per note, labelled against the inferred chords. */
     notes: AnalyzedNote[];
 };
-/** A note that clashes with the harmony sounding beneath it. */
+/**
+ * A note that clashes with the harmony sounding beneath it.
+ *
+ * @category Arrangement & Analysis
+ */
 type Conflict = {
     beat: number;
     trackName: string;
@@ -666,7 +1052,11 @@ type Conflict = {
     reasons: number;
     rationale?: string;
 };
-/** The full result of {@link analyzeArrangement}. */
+/**
+ * The full result of {@link analyzeArrangement}.
+ *
+ * @category Arrangement & Analysis
+ */
 type ArrangementAnalysis = {
     key: KeyScale;
     timeline: ChordTimeline;
@@ -676,15 +1066,31 @@ type ArrangementAnalysis = {
     /** Notes clashing with the sounding harmony, worst severity first. */
     conflicts: Conflict[];
 };
-/** Options controlling {@link analyzeArrangement} and {@link tensionCurve}. */
+/**
+ * Options controlling {@link analyzeArrangement} and {@link tensionCurve}.
+ *
+ * @category Arrangement & Analysis
+ */
 type ArrangementOptions = {
     /** Key context; inferred from the pooled notes when omitted. */
     key?: KeyScale;
-    /** Time signature; defaults to 4/4. */
+    /**
+     * Time signature; defaults to 4/4.
+     *
+     * @defaultValue `4/4`
+     */
     ts?: TimeSignature;
-    /** Chord-slot length in beats; defaults to one bar of `ts`. */
+    /**
+     * Chord-slot length in beats; defaults to one bar of `ts`.
+     *
+     * @defaultValue one bar of `ts`
+     */
     harmonicRhythm?: number;
-    /** Safety profile used for conflict detection; defaults to `pop`. */
+    /**
+     * Safety profile used for conflict detection; defaults to `pop`.
+     *
+     * @defaultValue `'pop'`
+     */
     profile?: SafetyProfile;
 };
 /**
@@ -693,18 +1099,42 @@ type ArrangementOptions = {
  * The chord timeline and key are inferred from the pooled notes of every track
  * (see {@link chordTimelineFromNotes}); pooling all voices is robust even when
  * roles are absent or a track doubles the harmony, so it is preferred over
- * deriving the harmony from a subset. Each track is then labelled note-by-note
- * against that harmony with {@link analyzeVoice}, seeing the other tracks as its
- * accompaniment, and every note is re-checked with {@link evaluateSafety}: those
- * that are not {@link NoteSafety.Safe} against the sounding chord become
- * conflicts, sorted worst severity first and then by beat.
+ * deriving the harmony from a subset. Zero- and negative-length notes never
+ * sound, so they are dropped at ingest and appear in neither the annotations
+ * nor the conflicts.
+ *
+ * Voice analysis assumes one monophonic voice at a time, so each track is
+ * first partitioned into monophonic sub-voices (a polyphonic block-chord track
+ * fans out into one sub-voice per simultaneous note; a monophonic track is
+ * unaffected). Each sub-voice is labelled note-by-note against the harmony
+ * with {@link analyzeVoice}, seeing every other sub-voice — including siblings
+ * within the same track — as its accompaniment. Every note is then re-checked
+ * with {@link evaluateSafety} at its onset and again at each chord change it
+ * sustains across, so a held note that clashes with a later chord is caught:
+ * evaluations that are not {@link NoteSafety.Safe} become conflicts, one per
+ * clashing beat, sorted worst severity first and then by beat.
  *
  * @param tracks The tracks to analyse.
  * @param opts Analysis options; see {@link ArrangementOptions}.
  * @returns The inferred harmony, per-track annotations, cadences, and conflicts.
+ * @example
+ * ```ts
+ * import { analyzeArrangement } from '@libraz/libcantus';
+ * const melody = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 2 },
+ *   { pitch: 67, startBeat: 2, durationBeat: 2 },
+ * ];
+ * const { key, conflicts } = analyzeArrangement([{ role: 'melody', notes: melody }]);
+ * conflicts; // notes clashing with the inferred harmony, worst severity first
+ * ```
+ * @category Arrangement & Analysis
  */
 declare function analyzeArrangement(tracks: ArrangementTrack[], opts?: ArrangementOptions): ArrangementAnalysis;
-/** A tension reading sampled at a beat. */
+/**
+ * A tension reading sampled at a beat.
+ *
+ * @category Arrangement & Analysis
+ */
 type TensionPoint = {
     beat: number;
     /** Combined tension in [0, 1]. */
@@ -729,6 +1159,14 @@ type TensionPoint = {
  * @param opts Analysis options plus an optional `step` (default one beat).
  * @returns One {@link TensionPoint} per sampled beat, in beat order.
  * @throws If `step` is not positive.
+ * @example
+ * ```ts
+ * import { tensionCurve } from '@libraz/libcantus';
+ * const notes = [{ pitch: 60, startBeat: 0, durationBeat: 4 }];
+ * const curve = tensionCurve([{ notes }], { step: 1 });
+ * curve; // one { beat, tension } sample per beat, in beat order
+ * ```
+ * @category Arrangement & Analysis
  */
 declare function tensionCurve(tracks: ArrangementTrack[], opts?: ArrangementOptions & {
     step?: number;
@@ -748,27 +1186,55 @@ declare function tensionCurve(tracks: ArrangementTrack[], opts?: ArrangementOpti
  * library-wide convention.
  */
 
-/** A chord sounding over a half-open beat span `[startBeat, endBeat)`. */
+/**
+ * A chord sounding over a half-open beat span `[startBeat, endBeat)`.
+ *
+ * @category Composition
+ */
 type BassSegment = {
     startBeat: number;
     endBeat: number;
     chord: Chord$1;
 };
-/** The bass-line idiom to generate. */
+/**
+ * The bass-line idiom to generate.
+ *
+ * @category Composition
+ */
 type BassStyle = 'root' | 'rootFifth' | 'pop' | 'walking' | 'arpeggio';
-/** Options controlling {@link generateBassLine}. */
+/**
+ * Options controlling {@link generateBassLine}.
+ *
+ * @category Composition
+ */
 type BassLineOptions = {
     /** Chord placement to follow; need not be pre-sorted. */
     segments: BassSegment[];
     /** Key/scale context, used for diatonic approach tones in `walking`. */
     key: KeyScale;
-    /** Time signature; used for metric accents. Default 4/4. */
+    /**
+     * Time signature; used for metric accents.
+     *
+     * @defaultValue `{ numerator: 4, denominator: 4 }`
+     */
     ts?: TimeSignature;
-    /** Bass-line idiom. Default `'root'`. */
+    /**
+     * Bass-line idiom.
+     *
+     * @defaultValue `'root'`
+     */
     style?: BassStyle;
-    /** Target register as a base MIDI octave; roots land around `octave*12+12`. Default 2. */
+    /**
+     * Target register as a base MIDI octave; roots land around `octave*12+12`.
+     *
+     * @defaultValue 2
+     */
     octave?: number;
-    /** Seed for the deterministic PRNG. Default 0. */
+    /**
+     * Seed for the deterministic PRNG.
+     *
+     * @defaultValue 0
+     */
     seed?: number;
 };
 /**
@@ -781,6 +1247,18 @@ type BassLineOptions = {
  *
  * @param opts Segments, key, and generation options.
  * @returns Bass notes sorted by onset, non-overlapping.
+ *
+ * @example
+ * ```ts
+ * import { generateBassLine, makeChord, majorKey } from '@libraz/libcantus';
+ * const segments = [
+ *   { startBeat: 0, endBeat: 4, chord: makeChord(0, 'maj') },
+ *   { startBeat: 4, endBeat: 8, chord: makeChord(7, 'maj') },
+ * ];
+ * const notes = generateBassLine({ segments, key: majorKey(0), style: 'walking' });
+ * ```
+ *
+ * @category Composition
  */
 declare function generateBassLine(opts: BassLineOptions): NoteEvent[];
 
@@ -791,9 +1269,15 @@ declare function generateBassLine(opts: BassLineOptions): NoteEvent[];
  * @param scaleMask The scale's 12-bit mode mask.
  * @param scaleRootPc The pitch class the mask is rooted on.
  * @returns True if the scale is a superset of the chord.
+ *
+ * @category Scales
  */
 declare function scaleMatchesChord(chordPcs: number[], scaleMask: number, scaleRootPc: number): boolean;
-/** A named scale rooted on a pitch class that fits over a chord. */
+/**
+ * A named scale rooted on a pitch class that fits over a chord.
+ *
+ * @category Scales
+ */
 type ChordScaleMatch = {
     name: string;
     rootPc: number;
@@ -803,13 +1287,26 @@ type ChordScaleMatch = {
  *
  * Only the chord root is considered as the scale root, matching the
  * conventional chord-scale relationship. Every entry of {@link NAMED_SCALES}
- * whose pitch-class set is a superset of the chord's is returned, ranked by
- * fewest extra scale tones beyond the chord, then by scale size (heptatonic
- * before larger scales), then by scale name. The chromatic scale is only
- * returned as a fallback when no other scale contains the chord.
+ * whose pitch-class set is a superset of the chord's is returned once per
+ * distinct pitch-class set (aliased masks such as major/ionian report only the
+ * modal name), ranked by fewest extra scale tones beyond the chord, then by
+ * scale size (heptatonic before larger scales), then by scale name. For bare
+ * triads and smaller chords, heptatonic scales rank before pentatonics and
+ * other sizes: a pentatonic adds no modal color over a triad, so the seven-note
+ * modes are the more useful answer. The chromatic scale is only returned as a
+ * fallback when no other scale contains the chord.
  *
  * @param chord The chord to fit scales over.
  * @returns The matching scales rooted on the chord root, best fit first.
+ *
+ * @example
+ * ```ts
+ * import { makeChord, chordScales } from '@libraz/libcantus';
+ * const scales = chordScales(makeChord(0, 'maj7'));
+ * // scales for Cmaj7, best fit first; each is { name, rootPc: 0 }
+ * ```
+ *
+ * @category Scales
  */
 declare function chordScales(chord: Chord$1): ChordScaleMatch[];
 /**
@@ -822,6 +1319,8 @@ declare function chordScales(chord: Chord$1): ChordScaleMatch[];
  * @param chord The chord providing the chord tones.
  * @param scaleName A key of {@link NAMED_SCALES}.
  * @returns The avoid-note pitch classes, sorted ascending in [0, 11].
+ *
+ * @category Scales
  */
 declare function avoidNotes(chord: Chord$1, scaleName: string): number[];
 /**
@@ -835,9 +1334,21 @@ declare function avoidNotes(chord: Chord$1, scaleName: string): number[];
  * @param chord The chord providing the chord tones.
  * @param scaleName A key of {@link NAMED_SCALES}.
  * @returns The available-tension pitch classes, sorted ascending in [0, 11].
+ *
+ * @example
+ * ```ts
+ * import { makeChord, availableTensions } from '@libraz/libcantus';
+ * availableTensions(makeChord(0, 'maj7'), 'ionian'); // [2, 9] — color tones over Cmaj7
+ * ```
+ *
+ * @category Scales
  */
 declare function availableTensions(chord: Chord$1, scaleName: string): number[];
-/** A scale fit over a chord together with its avoid notes and tensions. */
+/**
+ * A scale fit over a chord together with its avoid notes and tensions.
+ *
+ * @category Scales
+ */
 type ChordScaleReportEntry = {
     name: string;
     rootPc: number;
@@ -853,9 +1364,15 @@ type ChordScaleReportEntry = {
  * @param chord The chord to analyze.
  * @param limit Optional maximum number of scales to report; all by default.
  * @returns One entry per reported scale, best fit first.
+ *
+ * @category Scales
  */
 declare function chordScaleReport(chord: Chord$1, limit?: number): ChordScaleReportEntry[];
-/** A chord paired with the scale chosen for it by {@link scalesForChanges}. */
+/**
+ * A chord paired with the scale chosen for it by {@link scalesForChanges}.
+ *
+ * @category Scales
+ */
 type ScaleChoice = {
     chord: Chord$1;
     scale: ChordScaleMatch;
@@ -872,10 +1389,16 @@ type ScaleChoice = {
  *
  * @param chords The chord sequence to choose scales for.
  * @returns One scale choice per chord, in input order.
+ *
+ * @category Scales
  */
 declare function scalesForChanges(chords: Chord$1[]): ScaleChoice[];
 
-/** Options controlling {@link generateCounterMelody}. */
+/**
+ * Options controlling {@link generateCounterMelody}.
+ *
+ * @category Voicing & Counterpoint
+ */
 type CounterMelodyOptions = {
     /** The lead line to write against, in ascending onset order. */
     melody: NoteEvent[];
@@ -883,22 +1406,40 @@ type CounterMelodyOptions = {
     chordAt: (beat: number) => Chord$1 | null;
     /** Key/scale context for scale-tone decisions. */
     key: KeyScale;
-    /** Meter used for strong-beat decisions (default 4/4). */
+    /**
+     * Meter used for strong-beat decisions.
+     *
+     * @defaultValue 4/4
+     */
     ts?: TimeSignature;
-    /** Which side of the melody the counter line occupies (default `'below'`). */
+    /**
+     * Which side of the melody the counter line occupies.
+     *
+     * @defaultValue 'below'
+     */
     register?: 'above' | 'below';
     /**
-     * Onset strategy: `'complement'` (default) moves where the melody holds or
-     * rests and reinforces some strong beats; `'follow'` mirrors melody onsets.
+     * Onset strategy: `'complement'` moves where the melody holds or rests and
+     * reinforces some strong beats; `'follow'` mirrors melody onsets.
+     *
+     * @defaultValue 'complement'
      */
     rhythm?: 'complement' | 'follow';
-    /** Safety profile applied to candidate pitches (default `'pop'`). */
+    /**
+     * Safety profile applied to candidate pitches.
+     *
+     * @defaultValue 'pop'
+     */
     profile?: 'strict' | 'pop';
     /** Lowest MIDI pitch the counter line may use (default derived from `register`). */
     pitchLow?: number;
     /** Highest MIDI pitch the counter line may use (default derived from `register`). */
     pitchHigh?: number;
-    /** PRNG seed; the same seed always yields the same line (default 0). */
+    /**
+     * PRNG seed; the same seed always yields the same line.
+     *
+     * @defaultValue 0
+     */
     seed?: number;
 };
 /**
@@ -917,6 +1458,17 @@ type CounterMelodyOptions = {
  *
  * @param opts The lead line, chord context callback, key, and generation knobs.
  * @returns The counter line as note events sorted by onset; `[]` for an empty melody.
+ * @example
+ * ```ts
+ * import { generateCounterMelody, majorKey, parseChordSymbol } from '@libraz/libcantus';
+ * const melody = [{ pitch: 72, startBeat: 0, durationBeat: 2 }];
+ * const counter = generateCounterMelody({
+ *   melody,
+ *   chordAt: () => parseChordSymbol('C'),
+ *   key: majorKey(0),
+ * }); // note events below the melody, in onset order
+ * ```
+ * @category Voicing & Counterpoint
  */
 declare function generateCounterMelody(opts: CounterMelodyOptions): NoteEvent[];
 
@@ -926,6 +1478,7 @@ declare function generateCounterMelody(opts: CounterMelodyOptions): NoteEvent[];
  * @param upperPitch Pitch of the nominally higher voice.
  * @param lowerPitch Pitch of the nominally lower voice.
  * @returns True when the upper voice sits below the lower voice.
+ * @category Voicing & Counterpoint
  */
 declare function createsVoiceCrossing(upperPitch: number, lowerPitch: number): boolean;
 /**
@@ -935,6 +1488,7 @@ declare function createsVoiceCrossing(upperPitch: number, lowerPitch: number): b
  * @param b Second pitch.
  * @param twoVoice When true, the perfect fourth counts as dissonant.
  * @returns True when the vertical interval is dissonant.
+ * @category Voicing & Counterpoint
  */
 declare function createsVerticalDissonance(a: number, b: number, twoVoice: boolean): boolean;
 /**
@@ -947,6 +1501,7 @@ declare function createsVerticalDissonance(a: number, b: number, twoVoice: boole
  * @param prev Starting pitch.
  * @param cur Ending pitch.
  * @returns True when the leap is forbidden in strict counterpoint.
+ * @category Voicing & Counterpoint
  */
 declare function isForbiddenMelodicLeap(prev: number, cur: number): boolean;
 /**
@@ -962,16 +1517,29 @@ declare function isForbiddenMelodicLeap(prev: number, cur: number): boolean;
  * A fifth expanding to a twelfth counts (same perfect class); a fifth moving to
  * an octave does not (different perfect kinds — the direct/hidden case owned by
  * {@link createsHiddenParallelPerfect}).
+ *
+ * @category Voicing & Counterpoint
  */
 declare function createsParallelPerfect(aPrev: number, aCur: number, bPrev: number, bCur: number): boolean;
 /**
  * Whether two voices move in consecutive parallel octaves (or unisons) by
  * similar motion.
+ *
+ * This is a strict subset of {@link createsParallelPerfect}: a similar-motion
+ * octave-to-octave is the perfect-class-zero case that predicate already flags
+ * (and it additionally catches the contrary-motion anti-parallel). Callers that
+ * tally parallel violations should therefore use {@link createsParallelPerfect}
+ * alone to avoid double counting; this predicate remains for callers wanting a
+ * dedicated similar-motion octave test.
+ *
+ * @category Voicing & Counterpoint
  */
 declare function createsParallelOctave(aPrev: number, aCur: number, bPrev: number, bCur: number): boolean;
 /**
  * Whether two voices move in consecutive parallel unisons — both landing on the
  * same pitch, having shared a pitch on the previous move.
+ *
+ * @category Voicing & Counterpoint
  */
 declare function createsParallelUnison(aPrev: number, aCur: number, bPrev: number, bCur: number): boolean;
 /**
@@ -981,6 +1549,8 @@ declare function createsParallelUnison(aPrev: number, aCur: number, bPrev: numbe
  * 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.
+ *
+ * @category Voicing & Counterpoint
  */
 declare function createsHiddenParallelPerfect(aPrev: number, aCur: number, bPrev: number, bCur: number): boolean;
 /**
@@ -992,6 +1562,7 @@ declare function createsHiddenParallelPerfect(aPrev: number, aCur: number, bPrev
  * @param upperCur Current pitch of the upper voice.
  * @param lowerPrev Previous pitch of the lower voice.
  * @param lowerCur Current pitch of the lower voice.
+ * @category Voicing & Counterpoint
  */
 declare function createsVoiceOverlap(upperPrev: number, upperCur: number, lowerPrev: number, lowerCur: number): boolean;
 /**
@@ -1002,6 +1573,7 @@ declare function createsVoiceOverlap(upperPrev: number, upperCur: number, lowerP
  * @param upperPitch Pitch of the higher voice.
  * @param lowerPitch Pitch of the lower voice.
  * @param maxSemitones Maximum allowed spacing in semitones (default an octave).
+ * @category Voicing & Counterpoint
  */
 declare function exceedsSpacing(upperPitch: number, lowerPitch: number, maxSemitones?: number): boolean;
 /**
@@ -1011,6 +1583,7 @@ declare function exceedsSpacing(upperPitch: number, lowerPitch: number, maxSemit
  * @param cur The following pitch.
  * @param key Key context supplying the tonic.
  * @returns True when `prev` is the leading tone and `cur` is the tonic a step above.
+ * @category Voicing & Counterpoint
  */
 declare function isLeadingToneResolution(prev: number, cur: number, key: KeyScale): boolean;
 
@@ -1020,7 +1593,11 @@ declare function isLeadingToneResolution(prev: number, cur: number, key: KeyScal
  * which only go name -> notes.
  */
 
-/** A candidate chord interpretation of a pitch set. */
+/**
+ * A candidate chord interpretation of a pitch set.
+ *
+ * @category Recognition
+ */
 type ChordMatch = {
     rootPc: number;
     quality: ChordQuality;
@@ -1035,7 +1612,11 @@ type ChordMatch = {
     /** Bass pitch class when inverted (the lowest note is not the root). */
     bassPc?: number;
 };
-/** A candidate key interpretation of a pitch-class set. */
+/**
+ * A candidate key interpretation of a pitch-class set.
+ *
+ * @category Recognition
+ */
 type KeyMatch = {
     key: KeyScale;
     mode: 'major' | 'minor';
@@ -1054,6 +1635,13 @@ type KeyMatch = {
  *
  * @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: number[]): ChordMatch[];
 /**
@@ -1061,16 +1649,34 @@ declare function detectChord(pitches: number[]): ChordMatch[];
  *
  * @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: number[]): Chord$1 | null;
 /**
  * Rank major and minor keys by how well they contain a set of pitch classes.
  *
  * The tonic is weighted so that, among equally-fitting keys, the one whose root
- * appears in the input is preferred. Returns all 24 keys ranked best-first.
+ * appears in the input 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 returned key is always the natural-minor scale. 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.
+ * @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: number[]): KeyMatch[];
 
@@ -1085,27 +1691,87 @@ type DrumHit = {
 /** Groove feel controlling off-beat swing. */
 type Feel = 'straight' | 'swing' | 'shuffle';
 /** Public groove style identifiers. */
-type GrooveStyle = 'standard' | 'funk' | 'shuffle' | 'bossa' | 'trap' | 'halftime' | 'breakbeat';
+type GrooveStyle = 'standard' | 'funk' | 'shuffle' | 'bossa' | 'trap' | 'halftime' | 'breakbeat' | 'house' | 'synthpop';
 /** Public role identifiers gating which voices are present. */
 type DrumRole = 'full' | 'ambient' | 'minimal' | 'fxOnly';
 /** Public section identifiers. */
 type PublicSection = 'intro' | 'verse' | 'prechorus' | 'chorus' | 'bridge' | 'outro';
 
+/**
+ * Groove feel (the swing/straight rhythmic character) for {@link generateDrums}.
+ *
+ * @category Composition
+ */
 type GrooveFeel = Feel;
 
-/** Public section identifiers for {@link generateDrums}. */
+/**
+ * Public section identifiers for {@link generateDrums}.
+ *
+ * @category Composition
+ */
 type Section = PublicSection;
-/** Options controlling {@link generateDrums}. */
+/**
+ * A Euclidean (Bjorklund) kick pattern for {@link generateDrums}.
+ *
+ * @category Composition
+ */
+type EuclideanKick = {
+    /** Number of kick onsets, clamped to `[0, steps]`. */
+    pulses: number;
+    /**
+     * Total steps in the bar (1..16).
+     *
+     * @defaultValue 16
+     */
+    steps?: number;
+    /**
+     * Steps to rotate the onsets toward later positions.
+     *
+     * @defaultValue 0
+     */
+    rotation?: number;
+};
+/**
+ * Options controlling {@link generateDrums}.
+ *
+ * @category Composition
+ */
 type DrumGenOptions = {
     bars: number;
     bpm: number;
     style: GrooveStyle;
     section: Section;
     density: number;
+    /**
+     * Replace the final bar with a fill.
+     *
+     * @defaultValue false
+     */
     fills?: boolean;
     feel?: GrooveFeel;
+    /**
+     * Voicing role; `'fxOnly'` suppresses the main kick/snare/ghost/fill voices.
+     *
+     * @defaultValue `'full'`
+     */
     role?: DrumRole;
+    /**
+     * Seed for the deterministic PRNG.
+     *
+     * @defaultValue 0
+     */
     seed?: number;
+    /**
+     * Section the final-bar fill leads into. Shapes which fill archetype is
+     * chosen (into-chorus and out-of-intro fills differ from generic ones).
+     * Defaults to `section`, i.e. a within-section fill.
+     */
+    nextSection?: Section;
+    /**
+     * When set, the kick follows this Euclidean rhythm instead of the
+     * style/section pattern, giving direct access to evenly spread onsets.
+     */
+    euclideanKick?: EuclideanKick;
 };
 /**
  * Generate a drum performance as a flat list of onsets.
@@ -1115,11 +1781,23 @@ type DrumGenOptions = {
  * by its General MIDI pitch. Groove style selects an internal style and feel;
  * `density` sets the backing-density level; `section` shapes kick, hi-hat, ghost,
  * and percussion density. 16th-note hi-hats drop to 8ths at or above 150 BPM.
- * When `fills` is true the final bar is replaced with a fill. Output is fully
+ * When `fills` is true the final bar is replaced with a fill whose archetype is
+ * shaped by `nextSection`; a fill that would emit nothing on its beat falls back
+ * to the normal groove so the phrase end is never silent. `euclideanKick`
+ * overrides the kick with an evenly-spread Euclidean pattern. Output is fully
  * determined by the options plus `seed`.
  *
  * @param opts Generation options.
  * @returns Percussion onsets in bar order.
+ *
+ * @example
+ * ```ts
+ * import { generateDrums } from '@libraz/libcantus';
+ * const hits = generateDrums({ bars: 4, bpm: 120, style: 'standard', section: 'chorus', density: 0.6, fills: true });
+ * // Fully determined by the options plus seed (defaults to 0).
+ * ```
+ *
+ * @category Composition
  */
 declare function generateDrums(opts: DrumGenOptions): DrumHit[];
 
@@ -1133,19 +1811,47 @@ declare function generateDrums(opts: DrumGenOptions): DrumHit[];
  * seeded PRNG from the `random` module so results are fully reproducible.
  */
 
-/** Options controlling {@link humanize}. */
+/**
+ * Options controlling {@link humanize}.
+ *
+ * @category Rhythm & Meter
+ */
 type HumanizeOptions = {
-    /** Time signature used to derive metric accents. Default 4/4. */
+    /**
+     * Time signature used to derive metric accents.
+     *
+     * @defaultValue 4/4
+     */
     ts?: TimeSignature;
-    /** Maximum timing jitter in quarter-note beats, applied as ±this value. Default 0.02. */
+    /**
+     * Maximum timing jitter in quarter-note beats, applied as ±this value.
+     *
+     * @defaultValue 0.02
+     */
     timing?: number;
-    /** Maximum velocity jitter (MIDI units), applied as ±this value. Default 8. */
+    /**
+     * Maximum velocity jitter (MIDI units), applied as ±this value.
+     *
+     * @defaultValue 8
+     */
     velocity?: number;
-    /** How much louder strong beats get relative to weak ones, in MIDI velocity units. Default 12. */
+    /**
+     * How much louder strong beats get relative to weak ones, in MIDI velocity units.
+     *
+     * @defaultValue 12
+     */
     accent?: number;
-    /** Velocity assumed for events with no `velocity` of their own. Default 80. */
+    /**
+     * Velocity assumed for events with no `velocity` of their own.
+     *
+     * @defaultValue 80
+     */
     baseVelocity?: number;
-    /** Seed for the deterministic PRNG. Default 0. */
+    /**
+     * Seed for the deterministic PRNG.
+     *
+     * @defaultValue 0
+     */
     seed?: number;
 };
 /**
@@ -1166,16 +1872,35 @@ type HumanizeOptions = {
  * @param events The events to humanize.
  * @param opts Humanization options.
  * @returns Humanized copies of `events`, in input order.
+ * @example
+ * ```ts
+ * import { humanize } from '@libraz/libcantus';
+ * const events = [{ pitch: 60, startBeat: 0, durationBeat: 1, velocity: 80 }];
+ * humanize(events, { seed: 1, timing: 0.03 }); // copies with jittered timing and accented velocity
+ * ```
+ * @category Rhythm & Meter
  */
 declare function humanize(events: NoteEvent[], opts?: HumanizeOptions): NoteEvent[];
-/** The recorded feel at a single grid slot: an average timing deviation and velocity. */
+/**
+ * The recorded feel at a single grid slot: an average timing deviation and velocity.
+ *
+ * @category Rhythm & Meter
+ */
 type GrooveSlot = {
     /** Average `actualStartBeat - quantizedBeat` (in quarter-note beats) for events landing on this slot. */
     timingOffset: number;
-    /** Average velocity of events landing on this slot; 0 if none did. */
-    velocity: number;
+    /**
+     * Average velocity of events landing on this slot, or `null` if no event
+     * with a velocity did. `null` (not 0) is the "unrecorded" sentinel so that a
+     * genuine velocity of 0 is preserved and applied like any other value.
+     */
+    velocity: number | null;
 };
-/** A per-bar grid of timing and velocity deviations captured from a performance. */
+/**
+ * A per-bar grid of timing and velocity deviations captured from a performance.
+ *
+ * @category Rhythm & Meter
+ */
 type GrooveTemplate = {
     /** Grid resolution: equal grid steps per quarter-note beat. */
     subdivision: number;
@@ -1183,34 +1908,70 @@ type GrooveTemplate = {
     slotsPerBar: number;
     /** One entry per grid slot, in slot-index order (slot 0 is the downbeat). */
     slots: GrooveSlot[];
+    /**
+     * The time signature the template was extracted under. {@link applyGrooveTemplate}
+     * requires the apply-time meter to match this so the per-bar grid lines up
+     * instead of silently drifting. Optional for backward compatibility with
+     * templates constructed without it (in which case no check is performed).
+     */
+    ts?: TimeSignature;
 };
 /**
  * Extract a groove template from a set of note events: for each grid slot,
  * the average timing deviation from the quantized grid and the average
- * velocity of events landing on it. Slots with no events default to
- * `{ timingOffset: 0, velocity: 0 }`.
+ * velocity of events landing on it. Slots with no velocity-carrying event
+ * record `velocity: null` (the "unrecorded" sentinel); empty slots default to
+ * `{ timingOffset: 0, velocity: null }`. The time signature is stored on the
+ * template so {@link applyGrooveTemplate} can verify the meter matches.
  *
  * @param events The (typically "groovy", human-played) events to analyze.
  * @param ts The time signature, used to compute the bar length.
  * @param subdivision Grid resolution: equal grid steps per quarter-note beat.
  * @returns The extracted groove template.
+ * @category Rhythm & Meter
  */
 declare function extractGrooveTemplate(events: NoteEvent[], ts: TimeSignature, subdivision: number): GrooveTemplate;
 /**
  * Apply a groove template to a set of (typically quantized) note events: each
  * event is snapped to its grid slot and then offset by that slot's recorded
  * timing deviation, pushing stiff timing toward the template's feel.
- * Velocity is set to the slot's recorded average when it recorded any
- * (`velocity > 0`); otherwise the event's own velocity is left untouched.
+ * Velocity is set to the slot's recorded average when it recorded one (a
+ * non-`null` velocity, including a genuine 0); otherwise the event's own
+ * velocity is left untouched.
+ *
+ * If the template carries a time signature (see {@link GrooveTemplate.ts}) it
+ * must match `ts`, since a differing bar length would misalign the per-bar
+ * grid and drift the feel; a mismatch throws rather than corrupting timing
+ * silently.
  *
  * @param events The events to reshape.
  * @param template The groove template, from {@link extractGrooveTemplate}.
  * @param ts The time signature, used to compute the bar length.
  * @returns Reshaped copies of `events`, in input order.
+ * @throws If `template.ts` is set and does not match `ts`.
+ * @example
+ * ```ts
+ * import { extractGrooveTemplate, applyGrooveTemplate, parseTimeSignature } from '@libraz/libcantus';
+ * const ts = parseTimeSignature('4/4');
+ * // Learn the feel from a loosely played performance...
+ * const groovy = [
+ *   { pitch: 36, startBeat: 0.02, durationBeat: 1, velocity: 100 },
+ *   { pitch: 38, startBeat: 1.06, durationBeat: 1, velocity: 70 },
+ * ];
+ * const template = extractGrooveTemplate(groovy, ts, 4);
+ * // ...then impose it on stiff, quantized events.
+ * const quantized = [{ pitch: 36, startBeat: 0, durationBeat: 1, velocity: 80 }];
+ * applyGrooveTemplate(quantized, template, ts); // events nudged toward the captured feel
+ * ```
+ * @category Rhythm & Meter
  */
 declare function applyGrooveTemplate(events: NoteEvent[], template: GrooveTemplate, ts: TimeSignature): NoteEvent[];
 
-/** Harmonic role a pitch plays within a chord. */
+/**
+ * Harmonic role a pitch plays within a chord.
+ *
+ * @category Functional Harmony
+ */
 type HarmonyRole = 'root' | 'third' | 'fifth' | 'sixth' | 'seventh' | 'tension' | 'doubling';
 /**
  * How firmly a pitch is locked to the chord's identity.
@@ -1218,9 +1979,15 @@ type HarmonyRole = 'root' | 'third' | 'fifth' | 'sixth' | 'seventh' | 'tension'
  * - `identity`: moving it produces a different chord (the root).
  * - `quality`: moving it flips the chord quality (the third).
  * - `voicing`: it can move freely without changing chord identity or quality.
+ *
+ * @category Functional Harmony
  */
 type LockLevel = 'identity' | 'quality' | 'voicing';
-/** A pitch's role, lock level, and owning chord. */
+/**
+ * A pitch's role, lock level, and owning chord.
+ *
+ * @category Functional Harmony
+ */
 type VoicedRole = {
     role: HarmonyRole;
     lock: LockLevel;
@@ -1243,12 +2010,27 @@ type VoicedRole = {
  * @param chord The chord providing the root reference.
  * @param chordId Identifier stored on the result (defaults to 0).
  * @returns The pitch's role, lock level, and owning chord id.
+ * @example
+ * ```ts
+ * import { roleOf, makeChord } from '@libraz/libcantus';
+ * roleOf(64, makeChord(0, 'maj')); // E over C major
+ * // { role: 'third', lock: 'quality', belongsToChordId: 0 }
+ * ```
+ * @category Functional Harmony
  */
 declare function roleOf(pitch: number, chord: Chord$1, chordId?: number): VoicedRole;
 
-/** A melody note supplied to the harmonizer: a {@link NoteEvent}. */
+/**
+ * A melody note supplied to the harmonizer: a {@link NoteEvent}.
+ *
+ * @category Reharmonization
+ */
 type MelodyNote = NoteEvent;
-/** Options controlling {@link harmonizeMelody}. */
+/**
+ * Options controlling {@link harmonizeMelody}.
+ *
+ * @category Reharmonization
+ */
 type HarmonizeOptions = {
     melody: MelodyNote[];
     key: KeyScale | 'infer';
@@ -1258,9 +2040,18 @@ type HarmonizeOptions = {
         transposeSearch: boolean;
         octaveSearch: boolean;
     };
+    /**
+     * Seed for the deterministic tie-break perturbation.
+     *
+     * @defaultValue 0
+     */
     seed?: number;
 };
-/** The chosen transpose, key, chord path, and per-note roles. */
+/**
+ * The chosen transpose, key, chord path, and per-note roles.
+ *
+ * @category Reharmonization
+ */
 type HarmonizeResult = {
     transposeSemitones: number;
     key: KeyScale;
@@ -1281,13 +2072,39 @@ type HarmonizeResult = {
  * `(transpose, progression)` pair is returned; a small tessitura cost breaks
  * ties toward placements that keep the melody in a comfortable register.
  *
+ * The `seed` drives a deterministic tie-break only: it perturbs candidates by a
+ * magnitude far below any real cost difference (see {@link TIE_BREAK_JITTER}),
+ * so it can decide between chords or paths of otherwise-equal cost but never
+ * overrides melody fit or functional flow. For a well-determined melody the
+ * result is identical across seeds; the same seed always yields the same result.
+ *
  * @param opts Melody, key (or `'infer'`), harmonic rhythm, reharmonization
  *   strength, height-search flags, and seed.
  * @returns The chosen transpose, key, chord path, and per-note roles.
+ * @example
+ * ```ts
+ * import { harmonizeMelody, majorKey } from '@libraz/libcantus';
+ * const result = harmonizeMelody({
+ *   melody: [
+ *     { pitch: 60, startBeat: 0, durationBeat: 1 },
+ *     { pitch: 64, startBeat: 1, durationBeat: 1 },
+ *   ],
+ *   key: majorKey(0),
+ *   harmonicRhythm: 1,
+ *   reharmonize: 'diatonic',
+ *   placement: { transposeSearch: false, octaveSearch: false },
+ * });
+ * result.chords; // one GeneratedChord per harmonic-rhythm segment
+ * ```
+ * @category Reharmonization
  */
 declare function harmonizeMelody(opts: HarmonizeOptions): HarmonizeResult;
 
-/** Counterpoint classification of a harmonic interval. */
+/**
+ * Counterpoint classification of a harmonic interval.
+ *
+ * @category Pitch & Intervals
+ */
 declare enum IntervalQuality {
     PerfectConsonance = 0,
     ImperfectConsonance = 1,
@@ -1304,6 +2121,14 @@ declare enum IntervalQuality {
  * @param semitones Interval size in semitones (may be negative or compound).
  * @param twoVoice When true, the perfect fourth is treated as dissonant.
  * @returns The counterpoint quality of the interval.
+ * @example
+ * ```ts
+ * import { classifyInterval, IntervalQuality } from '@libraz/libcantus';
+ * classifyInterval(7); // IntervalQuality.PerfectConsonance
+ * classifyInterval(5); // IntervalQuality.Dissonance (two-voice)
+ * classifyInterval(5, false); // IntervalQuality.ImperfectConsonance
+ * ```
+ * @category Pitch & Intervals
  */
 declare function classifyInterval(semitones: number, twoVoice?: boolean): IntervalQuality;
 /**
@@ -1311,6 +2136,7 @@ declare function classifyInterval(semitones: number, twoVoice?: boolean): Interv
  *
  * @param semitones Interval size in semitones (may be negative or compound).
  * @returns True for the unison/octave (0) and the perfect fifth (7) mod 12.
+ * @category Pitch & Intervals
  */
 declare function isPerfectInterval(semitones: number): boolean;
 /**
@@ -1323,6 +2149,7 @@ declare function isPerfectInterval(semitones: number): boolean;
  * @param semitones Interval size in semitones (may be negative or compound).
  * @param twoVoice When true, the perfect fourth is treated as dissonant.
  * @returns True if the interval is consonant in the given context.
+ * @category Pitch & Intervals
  */
 declare function isConsonantInterval(semitones: number, twoVoice?: boolean): boolean;
 
@@ -1345,13 +2172,19 @@ declare function isConsonantInterval(semitones: number, twoVoice?: boolean): boo
  *   0 natural, +1 sharp, +2 double-sharp.
  * - `octave` follows scientific pitch notation (middle C = C4 = MIDI 60). When
  *   absent, the note denotes a bare pitch class.
+ *
+ * @category Pitch & Intervals
  */
 type Note$1 = {
     letter: number;
     alter: number;
     octave?: number;
 };
-/** A spelled interval: a diatonic number, a quality label, and its semitone span. */
+/**
+ * A spelled interval: a diatonic number, a quality label, and its semitone span.
+ *
+ * @category Pitch & Intervals
+ */
 type SpelledInterval = {
     /** Diatonic size: 1 = unison, 2 = second, ... 8 = octave, and beyond. */
     number: number;
@@ -1371,6 +2204,13 @@ type SpelledInterval = {
  * @param text The note text.
  * @returns The parsed note.
  * @throws If the text is not a valid note.
+ * @example
+ * ```ts
+ * import { parseNote, noteToMidi } from '@libraz/libcantus';
+ * const n = parseNote('C#4');
+ * noteToMidi(n); // 61
+ * ```
+ * @category Pitch & Intervals
  */
 declare function parseNote(text: string): Note$1;
 /**
@@ -1378,6 +2218,12 @@ declare function parseNote(text: string): Note$1;
  *
  * @param note The note to format.
  * @returns The note text, including the octave when present.
+ * @example
+ * ```ts
+ * import { formatNote, parseNote } from '@libraz/libcantus';
+ * formatNote(parseNote('C#4')); // 'C#4'
+ * ```
+ * @category Pitch & Intervals
  */
 declare function formatNote(note: Note$1): string;
 /**
@@ -1385,6 +2231,12 @@ declare function formatNote(note: Note$1): string;
  *
  * @param note The note.
  * @returns The pitch class.
+ * @example
+ * ```ts
+ * import { noteToPitchClass, parseNote } from '@libraz/libcantus';
+ * noteToPitchClass(parseNote('Db')); // 1
+ * ```
+ * @category Pitch & Intervals
  */
 declare function noteToPitchClass(note: Note$1): number;
 /**
@@ -1393,14 +2245,31 @@ declare function noteToPitchClass(note: Note$1): number;
  * @param note The note; must carry an octave.
  * @returns The MIDI number.
  * @throws If the note has no octave.
+ * @example
+ * ```ts
+ * import { noteToMidi, parseNote } from '@libraz/libcantus';
+ * noteToMidi(parseNote('A4')); // 69
+ * ```
+ * @category Pitch & Intervals
  */
 declare function noteToMidi(note: Note$1): number;
 /**
  * Name a MIDI number as a {@link Note}, choosing sharp or flat spelling.
  *
+ * The input is rounded to the nearest integer but is not clamped to the MIDI
+ * range 0..127: out-of-range values extrapolate linearly (e.g. `-1` -> `B-2`,
+ * `128` -> `G#9`) and remain an exact inverse of {@link noteToMidi}.
+ *
  * @param midi The MIDI number.
  * @param spelling Whether to prefer sharps or flats for black keys.
  * @returns The spelled note, with octave.
+ * @example
+ * ```ts
+ * import { midiToNote, formatNote } from '@libraz/libcantus';
+ * formatNote(midiToNote(61)); // 'C#4'
+ * formatNote(midiToNote(61, 'flat')); // 'Db4'
+ * ```
+ * @category Pitch & Intervals
  */
 declare function midiToNote(midi: number, spelling?: 'sharp' | 'flat'): Note$1;
 /**
@@ -1413,10 +2282,21 @@ declare function midiToNote(midi: number, spelling?: 'sharp' | 'flat'): Note$1;
  * @param a The lower/first note.
  * @param b The upper/second note.
  * @returns The diatonic number, quality, and semitone span.
+ * @example
+ * ```ts
+ * import { spelledInterval, parseNote } from '@libraz/libcantus';
+ * spelledInterval(parseNote('C4'), parseNote('G4'));
+ * // { number: 5, quality: 'P', semitones: 7 }
+ * ```
+ * @category Pitch & Intervals
  */
 declare function spelledInterval(a: Note$1, b: Note$1): SpelledInterval;
 
-/** An inclusive MIDI pitch range for a single voice. */
+/**
+ * An inclusive MIDI pitch range for a single voice.
+ *
+ * @category Voicing & Counterpoint
+ */
 type VoiceRange = {
     min: number;
     max: number;
@@ -1425,25 +2305,43 @@ type VoiceRange = {
  * Default four-voice SATB ranges, ascending (index 0 = lowest):
  * bass E2–C4 (40–60), tenor C3–G4 (48–67), alto G3–D5 (55–74),
  * soprano C4–G5 (60–79).
+ *
+ * @category Voicing & Counterpoint
  */
 declare const SATB_RANGES: readonly VoiceRange[];
-/** Options controlling {@link voiceChord} and {@link voiceProgression}. */
+/**
+ * Options controlling {@link voiceChord} and {@link voiceProgression}.
+ *
+ * @category Voicing & Counterpoint
+ */
 type VoicingOptions = {
-    /** Number of voices to realize (default 4). Ignored when `ranges` is given. */
+    /**
+     * Number of voices to realize. Ignored when `ranges` is given.
+     *
+     * @defaultValue 4
+     */
     voices?: number;
     /** Explicit per-voice ranges, ascending (index 0 = lowest). Takes precedence over `voices`. */
     ranges?: VoiceRange[];
-    /** Maximum spacing in semitones between adjacent upper voices (default 12). */
+    /**
+     * Maximum spacing in semitones between adjacent upper voices.
+     *
+     * @defaultValue 12
+     */
     maxSpacing?: number;
 };
 /**
  * Total voice-leading cost between two voicings: the sum of absolute semitone
- * motion across voices. The arrays must be the same length; when they differ
- * the voicings are not comparable and the cost is `Infinity`.
+ * motion across voices, plus a moderate {@link 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`.
  *
  * @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, or `Infinity` when lengths differ.
+ * @returns The summed absolute motion (plus any hidden-perfect penalty), or
+ *   `Infinity` when lengths differ.
+ * @category Voicing & Counterpoint
  */
 declare function voiceLeadingCost(from: number[], to: number[]): number;
 /**
@@ -1458,6 +2356,13 @@ declare function voiceLeadingCost(from: number[], to: number[]): number;
  * @param opts Voicing options; defaults to four voices in {@link SATB_RANGES}.
  * @returns MIDI pitches, ascending, one per voice.
  * @throws If no voicing fits the given ranges.
+ * @example
+ * ```ts
+ * import { parseChordSymbol, voiceChord } from '@libraz/libcantus';
+ * const chord = parseChordSymbol('Cmaj7');
+ * voiceChord(chord); // four ascending MIDI pitches within the SATB ranges
+ * ```
+ * @category Voicing & Counterpoint
  */
 declare function voiceChord(chord: Chord$1, opts?: VoicingOptions): number[];
 /**
@@ -1472,6 +2377,13 @@ declare function voiceChord(chord: Chord$1, opts?: VoicingOptions): number[];
  * @param opts Voicing options; defaults to four voices in {@link SATB_RANGES}.
  * @returns One voicing per chord, each ascending with one MIDI pitch per voice.
  * @throws If any chord admits no voicing within the given ranges.
+ * @example
+ * ```ts
+ * import { parseChordSymbol, voiceProgression } from '@libraz/libcantus';
+ * const chords = ['C', 'Am', 'F', 'G'].map((s) => parseChordSymbol(s));
+ * voiceProgression(chords); // one four-voice voicing per chord, smoothly led
+ * ```
+ * @category Voicing & Counterpoint
  */
 declare function voiceProgression(chords: Chord$1[], opts?: VoicingOptions): number[][];
 /**
@@ -1484,17 +2396,35 @@ declare function voiceProgression(chords: Chord$1[], opts?: VoicingOptions): num
  *   root/third/fifth for triads; the fifth and tensions are omitted.
  * - `rootless`: the root omitted, keeping third/fifth/seventh and tensions
  *   (a typical left-hand jazz voicing).
+ *
+ * @category Voicing & Counterpoint
  */
 type VoicingStyle = 'close' | 'drop2' | 'drop3' | 'shell' | 'rootless';
-/** Options controlling {@link voiceChordStyled}. */
+/**
+ * Options controlling {@link voiceChordStyled}.
+ *
+ * @category Voicing & Counterpoint
+ */
 type StyledVoicingOptions = {
-    /** Voicing style to build (default `close`). */
+    /**
+     * Voicing style to build.
+     *
+     * @defaultValue 'close'
+     */
     style?: VoicingStyle;
     /** Constrain the highest voice to this pitch class (0..11) when given. */
     topNote?: number;
-    /** Base octave for the close stack; the stack begins near `12 * octave` (default 4). */
+    /**
+     * Base octave for the close stack; the stack begins near `12 * octave`.
+     *
+     * @defaultValue 4
+     */
     octave?: number;
-    /** Omit the root regardless of style (relevant for jazz voicings). */
+    /**
+     * Omit the root regardless of style (relevant for jazz voicings).
+     *
+     * @defaultValue false
+     */
     rootless?: boolean;
 };
 /**
@@ -1512,6 +2442,13 @@ type StyledVoicingOptions = {
  * @param chord The chord to voice.
  * @param opts Styled voicing options; defaults to a close voicing at octave 4.
  * @returns MIDI pitches, ascending, one per retained voice.
+ * @example
+ * ```ts
+ * import { parseChordSymbol, voiceChordStyled } from '@libraz/libcantus';
+ * const chord = parseChordSymbol('Dm7');
+ * voiceChordStyled(chord, { style: 'drop2' }); // ascending MIDI pitches, drop-2 voicing
+ * ```
+ * @category Voicing & Counterpoint
  */
 declare function voiceChordStyled(chord: Chord$1, opts?: StyledVoicingOptions): number[];
 /**
@@ -1529,6 +2466,7 @@ declare function voiceChordStyled(chord: Chord$1, opts?: StyledVoicingOptions):
  * @param opts Voicing options; when omitted, ranges follow `current`'s span.
  * @returns The chosen voicing, ascending with one MIDI pitch per voice.
  * @throws If no voicing fits the derived ranges.
+ * @category Voicing & Counterpoint
  */
 declare function nextVoicing(current: number[], chord: Chord$1, opts?: VoicingOptions): number[];
 
@@ -1546,6 +2484,13 @@ declare function nextVoicing(current: number[], chord: Chord$1, opts?: VoicingOp
  * An immutable spelled note: a diatonic letter plus a chromatic alteration and
  * an optional octave. Wraps the plain note object and delegates to the pitch
  * module; every transformation returns a new instance.
+ *
+ * @category Class API
+ * @example
+ * ```ts
+ * import { Note } from '@libraz/libcantus';
+ * Note.of('C4').transpose(7).name; // 'G4'
+ * ```
  */
 declare class Note {
     #private;
@@ -1601,7 +2546,8 @@ declare class Note {
      *
      * When the note carries an octave the transposition happens in MIDI space and
      * the result is spelled with a sharp preference. An octave-less note stays
-     * octave-less: only its pitch class is moved.
+     * octave-less: only its pitch class is moved. Transposing by zero is the
+     * identity: the original spelling is preserved (no enharmonic respelling).
      *
      * @param semitones The signed semitone offset.
      * @returns The transposed note.
@@ -1621,11 +2567,27 @@ declare class Note {
      * @returns True if the spellings are identical.
      */
     equals(other: Note): boolean;
+    /**
+     * The plain note data, for JSON serialization.
+     *
+     * Private class fields do not serialize, so an explicit `toJSON` keeps
+     * `JSON.stringify(note)` from collapsing to `{}`.
+     *
+     * @returns A copy of the underlying plain note object.
+     */
+    toJSON(): Note$1;
 }
 /**
  * An immutable spelled interval value: a diatonic number, a quality label, and
  * a signed semitone span. A thin convenience wrapper over the pitch module's
  * plain interval result.
+ *
+ * @category Class API
+ * @example
+ * ```ts
+ * import { Interval, Note } from '@libraz/libcantus';
+ * Interval.between(Note.of('C4'), Note.of('G4')).name; // 'P5'
+ * ```
  */
 declare class Interval {
     #private;
@@ -1655,11 +2617,27 @@ declare class Interval {
     get semitones(): number;
     /** A readable label composed of quality and number, e.g. `'P5'` or `'M3'`. */
     get name(): string;
+    /**
+     * The plain interval data, for JSON serialization.
+     *
+     * Private class fields do not serialize, so an explicit `toJSON` keeps
+     * `JSON.stringify(interval)` from collapsing to `{}`.
+     *
+     * @returns The diatonic number, quality, and semitone span.
+     */
+    toJSON(): SpelledInterval;
 }
 /**
  * An immutable key/scale: a `KeyScale` (root pitch class plus mode mask) paired
  * with a spelled tonic that anchors letter-name spelling. Acts as the factory
  * for key-aware chords.
+ *
+ * @category Class API
+ * @example
+ * ```ts
+ * import { Key } from '@libraz/libcantus';
+ * Key.major('C').chord(4).symbol(); // 'G' (the diatonic triad on scale degree 4)
+ * ```
  */
 declare class Key {
     #private;
@@ -1673,16 +2651,18 @@ declare class Key {
     /**
      * A major key.
      *
-     * @param root Tonic as a note name (e.g. `'Eb'`) or a pitch class; numeric
-     *   roots are spelled with a sharp preference.
+     * @param root Tonic as a note name (e.g. `'Eb'`) or a pitch class; a numeric
+     *   root is spelled with whichever accidental side yields the fewest
+     *   accidentals across the scale.
      * @returns The major key.
      */
     static major(root: string | number): Key;
     /**
      * A natural-minor key.
      *
-     * @param root Tonic as a note name or a pitch class; numeric roots are
-     *   spelled with a flat preference.
+     * @param root Tonic as a note name or a pitch class; a numeric root is
+     *   spelled with whichever accidental side yields the fewest accidentals
+     *   across the scale.
      * @returns The minor key.
      */
     static minor(root: string | number): Key;
@@ -1778,12 +2758,33 @@ declare class Key {
      * @returns True if the pitch class is a scale tone.
      */
     contains(x: number | Note): boolean;
+    /**
+     * The plain key data, for JSON serialization.
+     *
+     * Private class fields do not serialize, so an explicit `toJSON` keeps
+     * `JSON.stringify(key)` from collapsing to `{}`. The result pairs the
+     * `KeyScale` with the spelled tonic, enough to reconstruct the key via
+     * {@link Key.of}.
+     *
+     * @returns The key/scale and its spelled tonic.
+     */
+    toJSON(): {
+        scale: KeyScale;
+        tonic: Note$1;
+    };
 }
 /**
  * An immutable chord: a root pitch class, quality, interval template, and
  * optional slash bass, optionally carrying a {@link Key} context. Analysis
  * methods (`roman`, `function`, `analyze`, ...) use an explicitly passed key
  * first and fall back to the carried context.
+ *
+ * @category Class API
+ * @example
+ * ```ts
+ * import { Chord } from '@libraz/libcantus';
+ * Chord.parse('Cmaj7').invert(1).symbol(); // 'Cmaj7/E' (third in the bass)
+ * ```
  */
 declare class Chord {
     #private;
@@ -1937,6 +2938,9 @@ declare class Chord {
      * root in the interval template (`invert(1)` puts the third in the bass).
      * `n` wraps around the template length; negative values count backwards.
      *
+     * `invert(0)` (and any `n` that wraps to it) is root position, so it carries
+     * no slash bass and equals the original chord.
+     *
      * @param n The inversion number.
      * @returns The inverted chord, keeping any key context.
      * @throws If the chord has no intervals.
@@ -2000,6 +3004,15 @@ declare class Chord {
 /**
  * An immutable ordered sequence of chords, optionally carrying a {@link Key}
  * context shared by its analysis methods.
+ *
+ * @category Class API
+ * @example
+ * ```ts
+ * import { Key } from '@libraz/libcantus';
+ * const key = Key.major('C');
+ * key.chord(1).progressionTo(key.chord(4), key.chord(0)).roman();
+ * // ['ii', 'V', 'I']
+ * ```
  */
 declare class Progression {
     #private;
@@ -2068,28 +3081,83 @@ declare class Progression {
         chords: ChordAnalysis[];
         cadence: Cadence;
     };
+    /**
+     * The plain progression data, for JSON serialization.
+     *
+     * Private class fields do not serialize, so an explicit `toJSON` keeps
+     * `JSON.stringify(progression)` from collapsing to `{}`. The chords are
+     * emitted as plain data and the carried key, when present, as its own data.
+     *
+     * @returns The chord data sequence and the carried key, if any.
+     */
+    toJSON(): {
+        chords: Chord$1[];
+        key: {
+            scale: KeyScale;
+            tonic: Note$1;
+        } | undefined;
+    };
 }
 
-/** A transformation applicable to a motif cell. */
+/**
+ * A transformation applicable to a motif cell.
+ *
+ * @category Composition
+ */
 type MotifTransform = 'transposeDiatonic' | 'transposeChromatic' | 'invert' | 'retrograde' | 'augment' | 'diminish' | 'sequence';
-/** A single note within a motif cell. */
+/**
+ * A single note within a motif cell.
+ *
+ * @category Composition
+ */
 type MotifNote = {
     pitch: number;
     startBeat: number;
     durationBeat: number;
 };
-/** A short melodic cell. */
+/**
+ * A short melodic cell.
+ *
+ * @category Composition
+ */
 type MotifCell = {
     notes: MotifNote[];
 };
-/** Melodic contour shape for {@link generateMotif}. */
+/**
+ * Melodic contour shape for {@link generateMotif}.
+ *
+ * @category Composition
+ */
 type MotifContour = 'arch' | 'ascending' | 'descending' | 'wave';
-/** Options controlling {@link generateMotif}. */
+/**
+ * Options controlling {@link generateMotif}.
+ *
+ * @category Composition
+ */
 type GenerateMotifOptions = {
     key: KeyScale;
     chord?: Chord$1 | null;
     bars: number;
+    /**
+     * Melodic contour shape the line follows.
+     *
+     * @defaultValue `'arch'`
+     */
     contour?: MotifContour;
+    /**
+     * Probability in [0, 1] that a note is nudged by a single diatonic step. The
+     * nudge direction is balanced (up or down with equal odds), so it adds
+     * variety without biasing the line off its contour. Default 0, which
+     * reproduces the requested contour exactly (no drift, tails return to tonic).
+     *
+     * @defaultValue 0
+     */
+    jitter?: number;
+    /**
+     * Seed for the deterministic PRNG.
+     *
+     * @defaultValue 0
+     */
     seed?: number;
 };
 /**
@@ -2097,10 +3165,21 @@ type GenerateMotifOptions = {
  *
  * The melody follows the requested contour in diatonic steps from the tonic,
  * snapped to the key. When a chord is supplied, notes landing on bar downbeats
- * are pulled to the nearest chord tone. Output is deterministic for a given seed.
+ * are pulled to the nearest chord tone. An optional `jitter` adds balanced
+ * per-note variation without biasing the contour; it is off by default, so the
+ * contour is reproduced exactly. Output is deterministic for a given seed.
  *
- * @param opts Key, optional chord, length, contour, and seed.
+ * @param opts Key, optional chord, length, contour, jitter, and seed.
  * @returns The generated motif cell.
+ *
+ * @example
+ * ```ts
+ * import { generateMotif, majorKey } from '@libraz/libcantus';
+ * const cell = generateMotif({ key: majorKey(0), bars: 2, contour: 'arch' });
+ * // cell.notes is a deterministic MotifCell (seed defaults to 0)
+ * ```
+ *
+ * @category Composition
  */
 declare function generateMotif(opts: GenerateMotifOptions): MotifCell;
 /**
@@ -2121,6 +3200,15 @@ declare function generateMotif(opts: GenerateMotifOptions): MotifCell;
  * @param key Key context for the diatonic transforms; without it,
  *   `transposeDiatonic` and `sequence` shift chromatically by semitones.
  * @returns The transformed cell.
+ *
+ * @example
+ * ```ts
+ * import { generateMotif, transformMotif, majorKey } from '@libraz/libcantus';
+ * const cell = generateMotif({ key: majorKey(0), bars: 1 });
+ * const inverted = transformMotif(cell, 'invert');
+ * ```
+ *
+ * @category Composition
  */
 declare function transformMotif(cell: MotifCell, t: MotifTransform, amount?: number, key?: KeyScale): MotifCell;
 /**
@@ -2135,6 +3223,16 @@ declare function transformMotif(cell: MotifCell, t: MotifTransform, amount?: num
  * @param key Key context (used to keep snapped pitches sensible).
  * @param bars Number of four-beat bars to fill.
  * @returns The developed, harmony-aware cell.
+ *
+ * @example
+ * ```ts
+ * import { chordTimelineFromChords, developMotif, generateMotif, majorKey } from '@libraz/libcantus';
+ * const key = majorKey(0);
+ * const timeline = chordTimelineFromChords([{ rootPc: 0, quality: 'maj', startBeat: 0 }], 8);
+ * const developed = developMotif(generateMotif({ key, bars: 1 }), timeline, key, 2);
+ * ```
+ *
+ * @category Composition
  */
 declare function developMotif(cell: MotifCell, timeline: ChordTimeline, key: KeyScale, bars: number): MotifCell;
 
@@ -2144,7 +3242,11 @@ declare function developMotif(cell: MotifCell, timeline: ChordTimeline, key: Key
  * mulberry32 core exposes the small set of samplers those modules need; given a
  * seed the stream is fully reproducible.
  */
-/** A deterministic PRNG with the sampling helpers the generators need. */
+/**
+ * A deterministic PRNG with the sampling helpers the generators need.
+ *
+ * @category Utilities
+ */
 type Rng = {
     /** Next float in [0, 1). */
     next: () => number;
@@ -2160,6 +3262,14 @@ type Rng = {
  *
  * @param seed The 32-bit seed; the same seed always yields the same stream.
  * @returns The seeded generator.
+ * @example
+ * ```ts
+ * import { createRng } from '@libraz/libcantus';
+ * const rng = createRng(42);
+ * rng.next(); // deterministic float in [0, 1)
+ * rng.range(1, 6); // deterministic integer in [1, 6]
+ * ```
+ * @category Utilities
  */
 declare function createRng(seed: number): Rng;
 
@@ -2172,16 +3282,28 @@ declare function createRng(seed: number): Rng;
  * Roots are pitch classes (0..11); no spelled key signature is required.
  */
 
-/** The kind of substitution relationship a candidate realizes. */
+/**
+ * The kind of substitution relationship a candidate realizes.
+ *
+ * @category Reharmonization
+ */
 type SubstitutionType = 'tritone' | 'relative' | 'borrowed' | 'chromatic-mediant' | 'secondary-dominant';
-/** A proposed chord substitution with its relationship, numeral, and function. */
+/**
+ * A proposed chord substitution with its relationship, numeral, and function.
+ *
+ * @category Reharmonization
+ */
 type Substitution = {
     chord: Chord$1;
     type: SubstitutionType;
     roman: string;
     function: HarmonicFunction;
 };
-/** Options controlling which substitutions {@link substituteChord} returns. */
+/**
+ * Options controlling which substitutions {@link substituteChord} returns.
+ *
+ * @category Reharmonization
+ */
 type SubstituteOptions = {
     /**
      * Melody pitch classes that must remain chord tones. When given, only
@@ -2212,9 +3334,20 @@ type SubstituteOptions = {
  * @param key The prevailing key.
  * @param opts Optional melody-preservation constraint.
  * @returns The deduplicated substitution candidates.
+ * @example
+ * ```ts
+ * import { substituteChord, makeChord, majorKey } from '@libraz/libcantus';
+ * const subs = substituteChord(makeChord(7, 'dom7'), majorKey(0));
+ * // includes the tritone sub Db7 (rootPc 1, quality 'dom7')
+ * ```
+ * @category Reharmonization
  */
 declare function substituteChord(chord: Chord$1, key: KeyScale, opts?: SubstituteOptions): Substitution[];
-/** A borrowed chord in the modal-interchange palette of a key. */
+/**
+ * A borrowed chord in the modal-interchange palette of a key.
+ *
+ * @category Reharmonization
+ */
 type BorrowedChord = {
     chord: Chord$1;
     roman: string;
@@ -2230,6 +3363,7 @@ type BorrowedChord = {
  *
  * @param key The prevailing key.
  * @returns The borrowed-chord palette.
+ * @category Reharmonization
  */
 declare function modalInterchangePalette(key: KeyScale): BorrowedChord[];
 /**
@@ -2244,6 +3378,13 @@ declare function modalInterchangePalette(key: KeyScale): BorrowedChord[];
  * @param chord The chord to reflect.
  * @param key The prevailing key.
  * @returns The negative-harmony counterpart of the chord.
+ * @example
+ * ```ts
+ * import { negativeHarmonyMirror, makeChord, majorKey } from '@libraz/libcantus';
+ * negativeHarmonyMirror(makeChord(7, 'maj'), majorKey(0));
+ * // G major reflected across C's axis => F minor (rootPc 5, quality 'min')
+ * ```
+ * @category Reharmonization
  */
 declare function negativeHarmonyMirror(chord: Chord$1, key: KeyScale): Chord$1;
 
@@ -2260,28 +3401,49 @@ declare function negativeHarmonyMirror(chord: Chord$1, key: KeyScale): Chord$1;
  * library-wide convention.
  */
 
-/** A single rhythmic note: an onset position and how long it sounds. */
+/**
+ * A single rhythmic note: an onset position and how long it sounds.
+ *
+ * @category Rhythm & Meter
+ */
 type RhythmEvent = {
     /** Onset position in quarter-note beats, absolute from the start of the span. */
     position: number;
     /** Duration in quarter-note beats, extending to the next onset. */
     duration: number;
 };
-/** Options controlling {@link generateRhythm}. */
+/**
+ * Options controlling {@link generateRhythm}.
+ *
+ * @category Rhythm & Meter
+ */
 type RhythmOptions = {
-    /** Seed for the deterministic PRNG. Default 0. */
+    /**
+     * Seed for the deterministic PRNG.
+     *
+     * @defaultValue 0
+     */
     seed?: number;
-    /** Number of bars to generate. Default 1. */
+    /**
+     * Number of bars to generate.
+     *
+     * @defaultValue 1
+     */
     bars?: number;
     /**
      * Grid resolution as the number of equal grid steps per quarter-note beat.
      * The default of 2 yields an eighth-note grid; 4 yields a sixteenth-note
      * grid, 3 an eighth-note triplet grid, and so on.
+     *
+     * @defaultValue 2
      */
     subdivision?: number;
     /**
      * Overall onset density in [0, 1]. Scales the per-slot onset probability, so
-     * higher values fill more grid slots. Default 0.5.
+     * higher values fill more grid slots. Values outside [0, 1] are clamped into
+     * range.
+     *
+     * @defaultValue 0.5
      */
     density?: number;
 };
@@ -2293,19 +3455,28 @@ type RhythmOptions = {
  *
  * @param weight The metric weight, 0 (off-pulse) to 3 (downbeat).
  * @returns A base onset probability in [0, 1].
+ * @category Rhythm & Meter
  */
 declare function onsetWeightCurve(weight: number): number;
 /**
  * Generate a deterministic rhythmic pattern over `bars` bars of a time
  * signature. A grid is built at the chosen subdivision; each slot becomes an
  * onset with a probability derived from its metric weight scaled by `density`
- * and sampled from the seeded PRNG. The first slot (the downbeat) is always an
- * onset. Each event's duration extends to the next onset, and the last event
- * extends to the end of the span.
+ * and sampled from the seeded PRNG. Every bar's downbeat is always an onset, so
+ * a pattern of any length has a reliable pulse independent of the seed. Each
+ * event's duration extends to the next onset, and the last event extends to the
+ * end of the span. `density` is clamped to [0, 1].
  *
  * @param ts The time signature.
  * @param opts Generation options.
  * @returns Onset events sorted by position, non-overlapping, covering the span.
+ * @example
+ * ```ts
+ * import { parseTimeSignature, generateRhythm } from '@libraz/libcantus';
+ * const ts = parseTimeSignature('4/4');
+ * generateRhythm(ts, { seed: 42, density: 0.6 }); // onset events over one bar
+ * ```
+ * @category Rhythm & Meter
  */
 declare function generateRhythm(ts: TimeSignature, opts?: RhythmOptions): RhythmEvent[];
 /**
@@ -2314,6 +3485,7 @@ declare function generateRhythm(ts: TimeSignature, opts?: RhythmOptions): Rhythm
  * @param events Events from {@link generateRhythm}.
  * @param ts The time signature.
  * @returns The onset count divided by the number of bars the events span.
+ * @category Rhythm & Meter
  */
 declare function rhythmDensity(events: RhythmEvent[], ts: TimeSignature): number;
 
@@ -2322,45 +3494,135 @@ declare function rhythmDensity(events: RhythmEvent[], ts: TimeSignature): number
  *
  * Bit 0 (the root) is always set, enforcing the `KeyScale` invariant that the
  * root is a scale tone even when the offset list omits 0.
+ *
+ * @category Scales
  */
 declare function maskFromOffsets(offsets: readonly number[]): number;
-/** Mode mask for the major (Ionian) scale: offsets {0, 2, 4, 5, 7, 9, 11}. */
+/**
+ * Mode mask for the major (Ionian) scale: offsets {0, 2, 4, 5, 7, 9, 11}.
+ *
+ * @category Scales
+ */
 declare const MAJOR_MASK = 2741;
-/** Mode mask for the natural minor (Aeolian) scale: offsets {0, 2, 3, 5, 7, 8, 10}. */
+/**
+ * Mode mask for the natural minor (Aeolian) scale: offsets {0, 2, 3, 5, 7, 8, 10}.
+ *
+ * @category Scales
+ */
 declare const NATURAL_MINOR_MASK = 1453;
-/** Harmonic minor: natural minor with a raised seventh — offsets {0,2,3,5,7,8,11}. */
+/**
+ * Harmonic minor: natural minor with a raised seventh — offsets {0,2,3,5,7,8,11}.
+ *
+ * @category Scales
+ */
 declare const HARMONIC_MINOR_MASK: number;
-/** Ascending melodic minor: offsets {0,2,3,5,7,9,11}. */
+/**
+ * Ascending melodic minor: offsets {0,2,3,5,7,9,11}.
+ *
+ * @category Scales
+ */
 declare const MELODIC_MINOR_MASK: number;
-/** Dorian mode: offsets {0,2,3,5,7,9,10}. */
+/**
+ * Dorian mode: offsets {0,2,3,5,7,9,10}.
+ *
+ * @category Scales
+ */
 declare const DORIAN_MASK: number;
-/** Phrygian mode: offsets {0,1,3,5,7,8,10}. */
+/**
+ * Phrygian mode: offsets {0,1,3,5,7,8,10}.
+ *
+ * @category Scales
+ */
 declare const PHRYGIAN_MASK: number;
-/** Lydian mode: offsets {0,2,4,6,7,9,11}. */
+/**
+ * Lydian mode: offsets {0,2,4,6,7,9,11}.
+ *
+ * @category Scales
+ */
 declare const LYDIAN_MASK: number;
-/** Mixolydian mode: offsets {0,2,4,5,7,9,10}. */
+/**
+ * Mixolydian mode: offsets {0,2,4,5,7,9,10}.
+ *
+ * @category Scales
+ */
 declare const MIXOLYDIAN_MASK: number;
-/** Locrian mode: offsets {0,1,3,5,6,8,10}. */
+/**
+ * Locrian mode: offsets {0,1,3,5,6,8,10}.
+ *
+ * @category Scales
+ */
 declare const LOCRIAN_MASK: number;
-/** Major pentatonic: offsets {0,2,4,7,9}. */
+/**
+ * Major pentatonic: offsets {0,2,4,7,9}.
+ *
+ * @category Scales
+ */
 declare const MAJOR_PENTATONIC_MASK: number;
-/** Minor pentatonic: offsets {0,3,5,7,10}. */
+/**
+ * Minor pentatonic: offsets {0,3,5,7,10}.
+ *
+ * @category Scales
+ */
 declare const MINOR_PENTATONIC_MASK: number;
-/** Hexatonic blues scale: minor pentatonic plus the flat-fifth — {0,3,5,6,7,10}. */
+/**
+ * Hexatonic blues scale: minor pentatonic plus the flat-fifth — {0,3,5,6,7,10}.
+ *
+ * @category Scales
+ */
 declare const BLUES_MASK: number;
-/** Whole-tone scale: offsets {0,2,4,6,8,10}. */
+/**
+ * Whole-tone scale: offsets {0,2,4,6,8,10}.
+ *
+ * @category Scales
+ */
 declare const WHOLE_TONE_MASK: number;
-/** Octatonic (half-step first): offsets {0,1,3,4,6,7,9,10}. */
+/**
+ * Octatonic (half-step first): offsets {0,1,3,4,6,7,9,10}.
+ *
+ * @category Scales
+ */
 declare const OCTATONIC_HALF_WHOLE_MASK: number;
-/** Octatonic (whole-step first): offsets {0,2,3,5,6,8,9,11}. */
+/**
+ * Octatonic (whole-step first): offsets {0,2,3,5,6,8,9,11}.
+ *
+ * @category Scales
+ */
 declare const OCTATONIC_WHOLE_HALF_MASK: number;
-/** Chromatic scale: all twelve pitch classes. */
+/**
+ * Chromatic scale: all twelve pitch classes.
+ *
+ * @category Scales
+ */
 declare const CHROMATIC_MASK = 4095;
-/** Named scale masks addressable by {@link scaleByName}. */
+/**
+ * Named scale masks addressable by {@link scaleByName}.
+ *
+ * @category Scales
+ */
 declare const NAMED_SCALES: Record<string, number>;
-/** Build a `KeyScale` for a major key on the given root pitch class. */
+/**
+ * Build a `KeyScale` for a major key on the given root pitch class.
+ *
+ * @example
+ * ```ts
+ * import { majorKey } from '@libraz/libcantus';
+ * const cMajor = majorKey(0); // C major: { rootPc: 0, modeMask12: MAJOR_MASK }
+ * ```
+ *
+ * @category Scales
+ */
 declare function majorKey(rootPc: number): KeyScale;
-/** Build a `KeyScale` for a natural-minor key on the given root pitch class. */
+/**
+ * Build a `KeyScale` for a natural-minor key on the given root pitch class.
+ *
+ * @example
+ * ```ts
+ * import { minorKey } from '@libraz/libcantus';
+ * const aMinor = minorKey(9); // A natural minor: { rootPc: 9, modeMask12: NATURAL_MINOR_MASK }
+ * ```
+ *
+ * @category Scales
+ */
 declare function minorKey(rootPc: number): KeyScale;
 /**
  * Build a `KeyScale` from a named scale (see {@link NAMED_SCALES}).
@@ -2369,6 +3631,14 @@ declare function minorKey(rootPc: number): KeyScale;
  * @param rootPc The root pitch class.
  * @returns The key/scale.
  * @throws If the name is not a known scale.
+ *
+ * @example
+ * ```ts
+ * import { scaleByName } from '@libraz/libcantus';
+ * const dDorian = scaleByName('dorian', 2); // D Dorian, rootPc 2
+ * ```
+ *
+ * @category Scales
  */
 declare function scaleByName(name: string, rootPc: number): KeyScale;
 /**
@@ -2377,6 +3647,16 @@ declare function scaleByName(name: string, rootPc: number): KeyScale;
  * @param pitch MIDI pitch or bare pitch class.
  * @param key The key/scale to test against.
  * @returns True if the pitch class is a member of the scale.
+ *
+ * @example
+ * ```ts
+ * import { majorKey, isScaleTone } from '@libraz/libcantus';
+ * const key = majorKey(0); // C major
+ * isScaleTone(64, key); // true — E is in C major
+ * isScaleTone(61, key); // false — C# is not
+ * ```
+ *
+ * @category Scales
  */
 declare function isScaleTone(pitch: number, key: KeyScale): boolean;
 /**
@@ -2388,6 +3668,8 @@ declare function isScaleTone(pitch: number, key: KeyScale): boolean;
  * @param pitch MIDI pitch to snap.
  * @param key The key/scale to snap to.
  * @returns The nearest in-scale MIDI pitch.
+ *
+ * @category Scales
  */
 declare function nearestScaleTone(pitch: number, key: KeyScale): number;
 /**
@@ -2396,6 +3678,8 @@ declare function nearestScaleTone(pitch: number, key: KeyScale): number;
  * @param pitch MIDI pitch or bare pitch class.
  * @param key The key/scale to measure against.
  * @returns The 0-based degree, or -1 if the pitch is not in the scale.
+ *
+ * @category Scales
  */
 declare function pitchToScaleDegree(pitch: number, key: KeyScale): number;
 /**
@@ -2403,6 +3687,8 @@ declare function pitchToScaleDegree(pitch: number, key: KeyScale): number;
  *
  * @param key The key/scale to enumerate.
  * @returns The member pitch classes, sorted ascending in [0, 11].
+ *
+ * @category Scales
  */
 declare function diatonicPitchClasses(key: KeyScale): number[];
 /**
@@ -2413,6 +3699,8 @@ declare function diatonicPitchClasses(key: KeyScale): number[];
  *
  * @param key The key/scale to enumerate.
  * @returns The member pitch classes ordered by scale degree.
+ *
+ * @category Scales
  */
 declare function scaleTonesInDegreeOrder(key: KeyScale): number[];
 
@@ -2437,6 +3725,7 @@ declare function scaleTonesInDegreeOrder(key: KeyScale): number[];
  * @param tonic The spelled tonic (its letter anchors the spelling).
  * @param key The key/scale.
  * @returns The spelled note (without octave).
+ * @category Pitch & Intervals
  */
 declare function spellPitchClass(pc: number, tonic: Note$1, key: KeyScale): Note$1;
 /**
@@ -2448,6 +3737,13 @@ declare function spellPitchClass(pc: number, tonic: Note$1, key: KeyScale): Note
  * @param tonic The spelled tonic.
  * @param key The key/scale.
  * @returns Spelled notes, one per scale degree.
+ * @example
+ * ```ts
+ * import { spellScale, noteNames, parseNote, majorKey } from '@libraz/libcantus';
+ * noteNames(spellScale(parseNote('C'), majorKey(0)));
+ * // ['C', 'D', 'E', 'F', 'G', 'A', 'B']
+ * ```
+ * @category Pitch & Intervals
  */
 declare function spellScale(tonic: Note$1, key: KeyScale): Note$1[];
 /**
@@ -2457,6 +3753,7 @@ declare function spellScale(tonic: Note$1, key: KeyScale): Note$1[];
  * @param tonic The spelled tonic.
  * @param key The key/scale.
  * @returns Spelled notes, in input order.
+ * @category Pitch & Intervals
  */
 declare function spellPitchClasses(pcs: number[], tonic: Note$1, key: KeyScale): Note$1[];
 /**
@@ -2471,6 +3768,14 @@ declare function spellPitchClasses(pcs: number[], tonic: Note$1, key: KeyScale):
  * @param tonic The spelled tonic of the key.
  * @param key The key/scale.
  * @returns Spelled chord tones, root first.
+ * @example
+ * ```ts
+ * import { spellChord, noteNames, parseNote, majorKey, makeChord } from '@libraz/libcantus';
+ * // G7 in C major
+ * noteNames(spellChord(makeChord(7, 'dom7'), parseNote('C'), majorKey(0)));
+ * // ['G', 'B', 'D', 'F']
+ * ```
+ * @category Pitch & Intervals
  */
 declare function spellChord(chord: Chord$1, tonic: Note$1, key: KeyScale): Note$1[];
 /**
@@ -2478,6 +3783,7 @@ declare function spellChord(chord: Chord$1, tonic: Note$1, key: KeyScale): Note$
  *
  * @param notes The notes.
  * @returns Their formatted names.
+ * @category Pitch & Intervals
  */
 declare function noteNames(notes: Note$1[]): string[];
 
@@ -2493,13 +3799,26 @@ declare function noteNames(notes: Note$1[]): string[];
  * Parse a lead-sheet chord symbol into a {@link Chord}.
  *
  * Accepts `<root><quality>[/<bass>]`, e.g. `Cmaj7`, `F#m7b5`, `Bb7`, `C/G`,
- * `C6/9`. The `/` after a quality is ambiguous between a slash bass and the
- * `6/9` quality; it resolves to a bass only when the token following it is
- * itself a valid note.
+ * `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 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.
  * @returns The parsed chord.
  * @throws If the root or quality is not recognized.
+ * @example
+ * ```ts
+ * import { parseChordSymbol, formatChordSymbol } from '@libraz/libcantus';
+ * const c = parseChordSymbol('Bbmaj7');
+ * formatChordSymbol(c); // 'Bbmaj7' — flat spelling is preserved on round-trip
+ * ```
+ * @category Chords
  */
 declare function parseChordSymbol(text: string): Chord$1;
 /**
@@ -2507,12 +3826,21 @@ declare function parseChordSymbol(text: string): Chord$1;
  *
  * The inverse of {@link parseChordSymbol}: each quality maps to one canonical
  * suffix spelling, and a slash bass is appended only when it differs from the
- * root.
+ * root. 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.
  *
  * @param chord The chord to format.
  * @param opts Formatting options.
- * @param opts.flats Prefer flat spellings over sharps for altered roots/basses.
+ * @param opts.flats Prefer flat spellings over sharps for altered roots/basses;
+ *   passing either `true` or `false` overrides any spelling hints.
  * @returns The chord symbol text.
+ * @example
+ * ```ts
+ * import { makeChord, formatChordSymbol } from '@libraz/libcantus';
+ * formatChordSymbol(makeChord(0, 'min7')); // 'Cm7'
+ * ```
+ * @category Chords
  */
 declare function formatChordSymbol(chord: Chord$1, opts?: {
     flats?: boolean;
@@ -2525,6 +3853,12 @@ declare function formatChordSymbol(chord: Chord$1, opts?: {
  * @param opts Formatting options for the result; see {@link formatChordSymbol}.
  * @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'
+ * ```
+ * @category Chords
  */
 declare function transposeChordSymbol(text: string, semitones: number, opts?: {
     flats?: boolean;
@@ -2542,6 +3876,8 @@ declare function transposeChordSymbol(text: string, semitones: number, opts?: {
 /**
  * An equal-tempered tuning: a reference pitch and a number of equal divisions of
  * the octave. With `divisions === 12` a step index is an ordinary MIDI number.
+ *
+ * @category Pitch & Intervals
  */
 type Tuning = {
     /** Step index (MIDI number when `divisions` is 12) whose frequency is `refFreq`. */
@@ -2551,7 +3887,11 @@ type Tuning = {
     /** Equal divisions of the octave (12 standard; e.g. 19 or 31 for microtonal). */
     divisions: number;
 };
-/** Standard twelve-tone equal temperament, A4 (MIDI 69) = 440 Hz. */
+/**
+ * Standard twelve-tone equal temperament, A4 (MIDI 69) = 440 Hz.
+ *
+ * @category Pitch & Intervals
+ */
 declare const TWELVE_TET: Tuning;
 /**
  * Build an equal temperament with `n` divisions of the octave.
@@ -2560,6 +3900,13 @@ declare const TWELVE_TET: Tuning;
  * @param refFreq Reference frequency in Hz (default 440).
  * @param refStep Step index of the reference (default 69).
  * @returns The tuning.
+ * @example
+ * ```ts
+ * import { edo, frequencyOf } from '@libraz/libcantus';
+ * const et19 = edo(19); // { refStep: 69, refFreq: 440, divisions: 19 }
+ * frequencyOf(70, et19); // one 19-EDO step above A4
+ * ```
+ * @category Pitch & Intervals
  */
 declare function edo(n: number, refFreq?: number, refStep?: number): Tuning;
 /**
@@ -2568,6 +3915,13 @@ declare function edo(n: number, refFreq?: number, refStep?: number): Tuning;
  * @param step Step index (a MIDI number under 12-EDO).
  * @param tuning The tuning (default 12-TET).
  * @returns The frequency in Hz.
+ * @example
+ * ```ts
+ * import { frequencyOf } from '@libraz/libcantus';
+ * frequencyOf(69); // 440 (A4 in 12-TET)
+ * frequencyOf(60); // middle C in Hz
+ * ```
+ * @category Pitch & Intervals
  */
 declare function frequencyOf(step: number, tuning?: Tuning): number;
 /**
@@ -2577,6 +3931,7 @@ declare function frequencyOf(step: number, tuning?: Tuning): number;
  * @param freq Frequency in Hz.
  * @param tuning The tuning (default 12-TET).
  * @returns The nearest step index.
+ * @category Pitch & Intervals
  */
 declare function nearestStep(freq: number, tuning?: Tuning): number;
 /**
@@ -2585,6 +3940,7 @@ declare function nearestStep(freq: number, tuning?: Tuning): number;
  * @param a Lower/first frequency in Hz.
  * @param b Upper/second frequency in Hz.
  * @returns Cents from `a` to `b` (negative if `b` is lower).
+ * @category Pitch & Intervals
  */
 declare function centsBetweenFreq(a: number, b: number): number;
 /**
@@ -2593,6 +3949,7 @@ declare function centsBetweenFreq(a: number, b: number): number;
  * @param steps Number of steps.
  * @param tuning The tuning (default 12-TET).
  * @returns The cents.
+ * @category Pitch & Intervals
  */
 declare function centsOfSteps(steps: number, tuning?: Tuning): number;
 /**
@@ -2602,11 +3959,14 @@ declare function centsOfSteps(steps: number, tuning?: Tuning): number;
  * @param numerator Ratio numerator.
  * @param denominator Ratio denominator.
  * @returns The interval in cents.
+ * @category Pitch & Intervals
  */
 declare function ratioToCents(numerator: number, denominator: number): number;
 /**
  * Five-limit just-intonation ratios for the twelve interval classes above a
  * unison, indexed by semitone class (0..12).
+ *
+ * @category Pitch & Intervals
  */
 declare const JUST_RATIOS: Record<number, [number, number]>;
 /**
@@ -2615,7 +3975,8 @@ declare const JUST_RATIOS: Record<number, [number, number]>;
  *
  * @param semitoneClass Semitone class in [0, 12].
  * @returns The deviation in cents, or NaN if the class has no listed ratio.
+ * @category Pitch & Intervals
  */
 declare function justDeviationCents(semitoneClass: number): number;
 
-export { type AnalyzedNote, type ArrangementAnalysis, type ArrangementOptions, type ArrangementTrack, BLUES_MASK, type BarPosition, type BassLineOptions, type BassSegment, type BassStyle, type BorrowedChord, type BorrowedSource, CHROMATIC_MASK, type Cadence, type CadenceHit, Chord, type ChordAnalysis, type Chord$1 as ChordData, type ChordMatch, type ChordQuality, type ChordScaleMatch, type ChordScaleReportEntry, type ChordSegment, type ChordTimeline, type ChordTimelineOptions, type ChordTimelineResult, type Conflict, type CounterMelodyOptions, DORIAN_MASK, type DrumGenOptions, type DrumHit, type DrumRole, type GenerateMotifOptions, type GenerateProgressionOptions, type GeneratedChord, type GrooveFeel, type GrooveSlot, type GrooveStyle, type GrooveTemplate, HARMONIC_MINOR_MASK, type HarmonicFunction, type HarmonizeOptions, type HarmonizeResult, type HarmonyRole, type HumanizeOptions, Interval, IntervalQuality, JUST_RATIOS, Key, type KeyMatch, type KeyScale, LOCRIAN_MASK, LYDIAN_MASK, type LockLevel, MAJOR_MASK, MAJOR_PENTATONIC_MASK, MELODIC_MINOR_MASK, MINOR_PENTATONIC_MASK, MIXOLYDIAN_MASK, type MelodyNote, type MotifCell, type MotifContour, type MotifNote, type MotifTransform, NAMED_SCALES, NATURAL_MINOR_MASK, Note, type Note$1 as NoteData, type NoteEvent, NoteSafety, OCTATONIC_HALF_WHOLE_MASK, OCTATONIC_WHOLE_HALF_MASK, PHRYGIAN_MASK, type ProgFunction, type ProgStyle, Progression, type ProgressionPreset, ReasonFlag, type RhythmEvent, type RhythmOptions, type Rng, SATB_RANGES, type SafetyProfile, type SafetyQuery, type SafetyResult, type ScaleChoice, type Section, type SpelledInterval, type StyledVoicingOptions, type SubstituteOptions, type Substitution, type SubstitutionType, TWELVE_TET, type TensionPoint, type TheoryLabel, type TimeSignature, type TrackAnalysis, type TrackRole, type Tuning, type VoiceNote, type VoiceRange, type VoiceSnapshot, type VoicedRole, type VoicingOptions, type VoicingStyle, WHOLE_TONE_MASK, analyzeArrangement, analyzeChord, analyzeVoice, applyGrooveTemplate, availableTensions, avoidNotes, barPositionToBeat, beatToBarPosition, beatsPerBar, borrowedSource, centsBetweenFreq, centsOfSteps, chordFromDegree, chordPitchClasses, chordQualities, chordScaleReport, chordScales, chordTimelineFromChords, chordTimelineFromNotes, chordToRoman, chordToneRole, classifyInterval, createRng, createsHiddenParallelPerfect, createsParallelOctave, createsParallelPerfect, createsParallelUnison, createsVerticalDissonance, createsVoiceCrossing, createsVoiceOverlap, detectCadence, detectCadences, detectChord, detectChordBest, detectKey, developMotif, diatonicPitchClasses, diatonicSeventh, diatonicTriad, edo, enumerateSafePitches, evaluateSafety, exceedsSpacing, extractGrooveTemplate, formatChordSymbol, formatNote, formatTimeSignature, frequencyOf, functionOf, generateBassLine, generateCounterMelody, generateDrums, generateMotif, generateProgression, generateRhythm, harmonizeMelody, humanize, isBorrowedChord, isCompound, isConsonantInterval, isDiatonic, isForbiddenMelodicLeap, isLeadingToneResolution, isMinorKey, isPerfectInterval, isScaleTone, isStrongBeat, justDeviationCents, majorKey, makeChord, maskFromOffsets, metricWeight, midiToNote, minorKey, modalInterchangePalette, nearestScaleTone, nearestStep, negativeHarmonyMirror, nextVoicing, noteNames, noteToMidi, noteToPitchClass, onsetWeightCurve, parallelKey, parseChordSymbol, parseNote, parseTimeSignature, pitchToScaleDegree, progressions, progressionsByStyle, pulsesPerBar, ratioToCents, rhythmDensity, roleOf, romanToChord, scaleByName, scaleMatchesChord, scaleTonesInDegreeOrder, scalesForChanges, secondaryDominant, spellChord, spellPitchClass, spellPitchClasses, spellScale, spelledInterval, substituteChord, tensionCurve, transformMotif, transposeChordSymbol, tuplet, voiceChord, voiceChordStyled, voiceLeadingCost, voiceProgression };
+export { type AnalyzedNote, type ArrangementAnalysis, type ArrangementOptions, type ArrangementTrack, BLUES_MASK, type BarPosition, type BassLineOptions, type BassSegment, type BassStyle, type BorrowedChord, type BorrowedSource, CHROMATIC_MASK, type Cadence, type CadenceHit, Chord, type ChordAnalysis, type Chord$1 as ChordData, type ChordMatch, type ChordQuality, type ChordScaleMatch, type ChordScaleReportEntry, type ChordSegment, type ChordTimeline, type ChordTimelineOptions, type ChordTimelineResult, type Conflict, type CounterMelodyOptions, DORIAN_MASK, type DrumGenOptions, type DrumHit, type DrumRole, type EuclideanKick, type GenerateMotifOptions, type GenerateProgressionOptions, type GeneratedChord, type GrooveFeel, type GrooveSlot, type GrooveStyle, type GrooveTemplate, HARMONIC_MINOR_MASK, type HarmonicFunction, type HarmonizeOptions, type HarmonizeResult, type HarmonyRole, type HumanizeOptions, Interval, IntervalQuality, JUST_RATIOS, Key, type KeyMatch, type KeyScale, LOCRIAN_MASK, LYDIAN_MASK, type LockLevel, MAJOR_MASK, MAJOR_PENTATONIC_MASK, MELODIC_MINOR_MASK, MINOR_PENTATONIC_MASK, MIXOLYDIAN_MASK, type MelodyNote, type MotifCell, type MotifContour, type MotifNote, type MotifTransform, NAMED_SCALES, NATURAL_MINOR_MASK, Note, type Note$1 as NoteData, type NoteEvent, NoteSafety, OCTATONIC_HALF_WHOLE_MASK, OCTATONIC_WHOLE_HALF_MASK, PHRYGIAN_MASK, type ProgFunction, type ProgStyle, Progression, type ProgressionPreset, ReasonFlag, type RhythmEvent, type RhythmOptions, type Rng, SATB_RANGES, type SafetyProfile, type SafetyQuery, type SafetyResult, type ScaleChoice, type Section, type SpelledInterval, type StyledVoicingOptions, type SubstituteOptions, type Substitution, type SubstitutionType, TWELVE_TET, type TensionPoint, type TheoryLabel, type TimeSignature, type TrackAnalysis, type TrackRole, type Tuning, type VoiceNote, type VoiceRange, type VoiceSnapshot, type VoicedRole, type VoicingOptions, type VoicingStyle, WHOLE_TONE_MASK, analyzeArrangement, analyzeChord, analyzeVoice, applyGrooveTemplate, availableTensions, avoidNotes, barPositionToBeat, beatToBarPosition, beatsPerBar, borrowedSource, centsBetweenFreq, centsOfSteps, chordFromDegree, chordPitchClasses, chordQualities, chordScaleReport, chordScales, chordTimelineFromChords, chordTimelineFromNotes, chordToRoman, chordToneRole, classifyInterval, createRng, createsHiddenParallelPerfect, createsParallelOctave, createsParallelPerfect, createsParallelUnison, createsVerticalDissonance, createsVoiceCrossing, createsVoiceOverlap, detectCadence, detectCadences, detectChord, detectChordBest, detectKey, developMotif, diatonicPitchClasses, diatonicSeventh, diatonicTriad, edo, enumerateSafePitches, evaluateSafety, exceedsSpacing, extractGrooveTemplate, formatChordSymbol, formatNote, formatTimeSignature, frequencyOf, functionOf, generateBassLine, generateCounterMelody, generateDrums, generateMotif, generateProgression, generateRhythm, harmonizeMelody, humanize, isBorrowedChord, isCompound, isConsonantInterval, isDiatonic, isForbiddenMelodicLeap, isLeadingToneResolution, isMinorKey, isPerfectInterval, isScaleTone, isStrongBeat, justDeviationCents, majorKey, makeChord, maskFromOffsets, metricWeight, midiToNote, minorKey, modalInterchangePalette, nearestScaleTone, nearestStep, negativeHarmonyMirror, nextVoicing, noteNames, noteToMidi, noteToPitchClass, onsetWeightCurve, parallelKey, parseChordSymbol, parseNote, parseTimeSignature, pitchToScaleDegree, progressions, progressionsByStyle, pulsesPerBar, ratioToCents, rhythmDensity, roleOf, romanToChord, scaleByName, scaleMatchesChord, scaleTonesInDegreeOrder, scalesForChanges, secondaryDominant, spellChord, spellPitchClass, spellPitchClasses, spellScale, spelledInterval, substituteChord, tensionCurve, transformMotif, transposeChordSymbol, tuplet, voiceChord, voiceChordStyled, voiceLeadingCost, voiceProgression };