@libraz/libcantus 0.9.0 → 0.9.1

package/src/scale/index.ts

@@ -5,6 +5,8 @@ import type { KeyScale } from '../types.js';
  *
  * 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
  */
 export function maskFromOffsets(offsets: readonly number[]): number {
   let mask = 1;
@@ -14,55 +16,123 @@ export function maskFromOffsets(offsets: readonly number[]): number {
   return mask;
 }
 
-/** 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
+ */
 export const MAJOR_MASK = 0b101010110101;
 
-/** 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
+ */
 export const NATURAL_MINOR_MASK = 0b010110101101;
 
-/** 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
+ */
 export const HARMONIC_MINOR_MASK = maskFromOffsets([0, 2, 3, 5, 7, 8, 11]);
 
-/** Ascending melodic minor: offsets {0,2,3,5,7,9,11}. */
+/**
+ * Ascending melodic minor: offsets {0,2,3,5,7,9,11}.
+ *
+ * @category Scales
+ */
 export const MELODIC_MINOR_MASK = maskFromOffsets([0, 2, 3, 5, 7, 9, 11]);
 
-/** Dorian mode: offsets {0,2,3,5,7,9,10}. */
+/**
+ * Dorian mode: offsets {0,2,3,5,7,9,10}.
+ *
+ * @category Scales
+ */
 export const DORIAN_MASK = maskFromOffsets([0, 2, 3, 5, 7, 9, 10]);
 
-/** Phrygian mode: offsets {0,1,3,5,7,8,10}. */
+/**
+ * Phrygian mode: offsets {0,1,3,5,7,8,10}.
+ *
+ * @category Scales
+ */
 export const PHRYGIAN_MASK = maskFromOffsets([0, 1, 3, 5, 7, 8, 10]);
 
-/** Lydian mode: offsets {0,2,4,6,7,9,11}. */
+/**
+ * Lydian mode: offsets {0,2,4,6,7,9,11}.
+ *
+ * @category Scales
+ */
 export const LYDIAN_MASK = maskFromOffsets([0, 2, 4, 6, 7, 9, 11]);
 
-/** Mixolydian mode: offsets {0,2,4,5,7,9,10}. */
+/**
+ * Mixolydian mode: offsets {0,2,4,5,7,9,10}.
+ *
+ * @category Scales
+ */
 export const MIXOLYDIAN_MASK = maskFromOffsets([0, 2, 4, 5, 7, 9, 10]);
 
-/** Locrian mode: offsets {0,1,3,5,6,8,10}. */
+/**
+ * Locrian mode: offsets {0,1,3,5,6,8,10}.
+ *
+ * @category Scales
+ */
 export const LOCRIAN_MASK = maskFromOffsets([0, 1, 3, 5, 6, 8, 10]);
 
-/** Major pentatonic: offsets {0,2,4,7,9}. */
+/**
+ * Major pentatonic: offsets {0,2,4,7,9}.
+ *
+ * @category Scales
+ */
 export const MAJOR_PENTATONIC_MASK = maskFromOffsets([0, 2, 4, 7, 9]);
 
-/** Minor pentatonic: offsets {0,3,5,7,10}. */
+/**
+ * Minor pentatonic: offsets {0,3,5,7,10}.
+ *
+ * @category Scales
+ */
 export const MINOR_PENTATONIC_MASK = maskFromOffsets([0, 3, 5, 7, 10]);
 
-/** 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
+ */
 export const BLUES_MASK = maskFromOffsets([0, 3, 5, 6, 7, 10]);
 
-/** Whole-tone scale: offsets {0,2,4,6,8,10}. */
+/**
+ * Whole-tone scale: offsets {0,2,4,6,8,10}.
+ *
+ * @category Scales
+ */
 export const WHOLE_TONE_MASK = maskFromOffsets([0, 2, 4, 6, 8, 10]);
 
-/** 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
+ */
 export const OCTATONIC_HALF_WHOLE_MASK = maskFromOffsets([0, 1, 3, 4, 6, 7, 9, 10]);
 
-/** 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
+ */
 export const OCTATONIC_WHOLE_HALF_MASK = maskFromOffsets([0, 2, 3, 5, 6, 8, 9, 11]);
 
-/** Chromatic scale: all twelve pitch classes. */
+/**
+ * Chromatic scale: all twelve pitch classes.
+ *
+ * @category Scales
+ */
 export const CHROMATIC_MASK = 0b111111111111;
 
-/** Named scale masks addressable by {@link scaleByName}. */
+/**
+ * Named scale masks addressable by {@link scaleByName}.
+ *
+ * @category Scales
+ */
 export const NAMED_SCALES: Record<string, number> = {
   major: MAJOR_MASK,
   ionian: MAJOR_MASK,
@@ -84,12 +154,32 @@ export const NAMED_SCALES: Record<string, number> = {
   chromatic: CHROMATIC_MASK,
 };
 
-/** 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
+ */
 export function majorKey(rootPc: number): KeyScale {
   return { rootPc: ((rootPc % 12) + 12) % 12, modeMask12: MAJOR_MASK };
 }
 
-/** 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
+ */
 export function minorKey(rootPc: number): KeyScale {
   return { rootPc: ((rootPc % 12) + 12) % 12, modeMask12: NATURAL_MINOR_MASK };
 }
@@ -101,6 +191,14 @@ export 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
  */
 export function scaleByName(name: string, rootPc: number): KeyScale {
   const mask = NAMED_SCALES[name];
@@ -126,6 +224,16 @@ function scaleOffset(pitch: number, key: KeyScale): number {
  * @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
  */
 export function isScaleTone(pitch: number, key: KeyScale): boolean {
   return ((key.modeMask12 >> scaleOffset(pitch, key)) & 1) === 1;
@@ -140,6 +248,8 @@ export 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
  */
 export function nearestScaleTone(pitch: number, key: KeyScale): number {
   const base = Math.round(pitch);
@@ -162,6 +272,8 @@ export 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
  */
 export function pitchToScaleDegree(pitch: number, key: KeyScale): number {
   const offset = scaleOffset(pitch, key);
@@ -182,6 +294,8 @@ export 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
  */
 export function diatonicPitchClasses(key: KeyScale): number[] {
   const root = pitchClass(key.rootPc);
@@ -202,6 +316,8 @@ export function diatonicPitchClasses(key: KeyScale): number[] {
  *
  * @param key The key/scale to enumerate.
  * @returns The member pitch classes ordered by scale degree.
+ *
+ * @category Scales
  */
 export function scaleTonesInDegreeOrder(key: KeyScale): number[] {
   const root = pitchClass(key.rootPc);

package/src/spelling/index.ts

@@ -79,6 +79,7 @@ function isHeptatonic(key: KeyScale): boolean {
  * @param tonic The spelled tonic (its letter anchors the spelling).
  * @param key The key/scale.
  * @returns The spelled note (without octave).
+ * @category Pitch & Intervals
  */
 export function spellPitchClass(pc: number, tonic: Note, key: KeyScale): Note {
   const tonicPc = mod12(naturalPc(tonic.letter) + tonic.alter);
@@ -117,6 +118,13 @@ export function spellPitchClass(pc: number, tonic: Note, 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
  */
 export function spellScale(tonic: Note, key: KeyScale): Note[] {
   return scaleTonesInDegreeOrder(key).map((pc) => spellPitchClass(pc, tonic, key));
@@ -129,6 +137,7 @@ export function spellScale(tonic: Note, key: KeyScale): Note[] {
  * @param tonic The spelled tonic.
  * @param key The key/scale.
  * @returns Spelled notes, in input order.
+ * @category Pitch & Intervals
  */
 export function spellPitchClasses(pcs: number[], tonic: Note, key: KeyScale): Note[] {
   return pcs.map((pc) => spellPitchClass(pc, tonic, key));
@@ -146,6 +155,14 @@ export function spellPitchClasses(pcs: number[], tonic: Note, key: KeyScale): No
  * @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
  */
 export function spellChord(chord: Chord, tonic: Note, key: KeyScale): Note[] {
   return chord.intervals.map((interval) =>
@@ -158,6 +175,7 @@ export function spellChord(chord: Chord, tonic: Note, key: KeyScale): Note[] {
  *
  * @param notes The notes.
  * @returns Their formatted names.
+ * @category Pitch & Intervals
  */
 export function noteNames(notes: Note[]): string[] {
   return notes.map(formatNote);

package/src/symbol/index.ts

@@ -5,14 +5,17 @@
  * (`Cmaj7`, `F#m7b5`, `Bb7`, `C/G`) and the library's structured {@link Chord}
  * type, so callers can accept/emit plain text at the edges of the API.
  */
-import { type Chord, type ChordQuality, makeChord } from '../chord/index.js';
-import { formatNote, midiToNote, noteToPitchClass, parseNote } from '../pitch/index.js';
+import { type Chord, type ChordQuality, makeChord, type PitchSpelling } from '../chord/index.js';
+import { formatNote, midiToNote, type Note, noteToPitchClass, parseNote } from '../pitch/index.js';
 
-/** Matches a chord root: a letter A-G with an optional single-direction accidental. */
-const ROOT_RE = /^[A-G](?:#{1,2}|b{1,2})?/;
+/**
+ * Matches a chord root: a letter A-G (case-insensitive, like {@link parseNote})
+ * with an optional single-direction accidental.
+ */
+const ROOT_RE = /^[A-Ga-g](?:#{1,2}|b{1,2})?/;
 
 /** Matches a bare note usable as a slash-chord bass (no octave). */
-const BASS_RE = /^[A-G](?:#{1,2}|b{1,2})?$/;
+const BASS_RE = /^[A-Ga-g](?:#{1,2}|b{1,2})?$/;
 
 /** Recognized quality suffixes, keyed by their exact lead-sheet spelling. */
 const QUALITY_MAP: Record<string, ChordQuality> = {
@@ -114,22 +117,44 @@ function pitchClass(value: number): number {
   return ((Math.trunc(value) % 12) + 12) % 12;
 }
 
-/** Pitch class of a bare note token (letter plus optional accidental). */
-function bassPitchClass(token: string): number {
-  return noteToPitchClass(parseNote(token));
+/** Build a chord and record the parsed spellings as enharmonic hints. */
+function makeSpelledChord(root: Note, quality: ChordQuality, bass?: Note): Chord {
+  const chord = makeChord(
+    noteToPitchClass(root),
+    quality,
+    bass === undefined ? undefined : noteToPitchClass(bass),
+  );
+  chord.rootSpelling = { letter: root.letter, alter: root.alter };
+  if (bass !== undefined) {
+    chord.bassSpelling = { letter: bass.letter, alter: bass.alter };
+  }
+  return chord;
 }
 
 /**
  * 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
  */
 export function parseChordSymbol(text: string): Chord {
   const trimmed = text.trim();
@@ -138,31 +163,41 @@ export function parseChordSymbol(text: string): Chord {
     throw new Error(`Invalid chord symbol: ${text}`);
   }
   const rootToken = rootMatch[0];
-  const rootPc = noteToPitchClass(parseNote(rootToken));
+  const rootNote = parseNote(rootToken);
   const rest = trimmed.slice(rootToken.length);
 
-  const slashIndex = rest.indexOf('/');
-  if (slashIndex === -1) {
-    const quality = QUALITY_MAP[rest];
-    if (quality === undefined) {
-      throw new Error(`Unrecognized chord quality: ${text}`);
+  // Split at the last '/' so the '6/9' quality's own slash never masks a
+  // trailing slash bass (e.g. 'C6/9/E').
+  const slashIndex = rest.lastIndexOf('/');
+  if (slashIndex !== -1) {
+    const before = rest.slice(0, slashIndex);
+    const after = rest.slice(slashIndex + 1);
+    const beforeQuality = QUALITY_MAP[before];
+    if (beforeQuality !== undefined && BASS_RE.test(after)) {
+      return makeSpelledChord(rootNote, beforeQuality, parseNote(after));
     }
-    return makeChord(rootPc, quality);
   }
 
-  const before = rest.slice(0, slashIndex);
-  const after = rest.slice(slashIndex + 1);
-  const beforeQuality = QUALITY_MAP[before];
-  if (beforeQuality !== undefined && BASS_RE.test(after)) {
-    return makeChord(rootPc, beforeQuality, bassPitchClass(after));
+  const quality = QUALITY_MAP[rest];
+  if (quality === undefined) {
+    throw new Error(`Unrecognized chord quality: ${text}`);
   }
+  return makeSpelledChord(rootNote, quality);
+}
 
-  const combinedQuality = QUALITY_MAP[rest];
-  if (combinedQuality !== undefined) {
-    return makeChord(rootPc, combinedQuality);
+/**
+ * Name a pitch class, preferring a spelling hint when it is still valid.
+ *
+ * A hint is used only when no explicit sharp/flat preference was given and the
+ * hint still resolves to `pc` (a stale hint left over after transposition is
+ * ignored). Otherwise the pitch class is respelled from the requested table.
+ */
+function pitchClassName(pc: number, hint: PitchSpelling | undefined, flats?: boolean): string {
+  if (flats === undefined && hint !== undefined && noteToPitchClass(hint) === pc) {
+    return formatNote(hint);
   }
-
-  throw new Error(`Unrecognized chord quality: ${text}`);
+  const note = midiToNote(60 + pc, flats ? 'flat' : 'sharp');
+  return formatNote({ letter: note.letter, alter: note.alter });
 }
 
 /**
@@ -170,22 +205,29 @@ export function parseChordSymbol(text: string): Chord {
  *
  * 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
  */
 export function formatChordSymbol(chord: Chord, opts?: { flats?: boolean }): string {
-  const spelling = opts?.flats ? 'flat' : 'sharp';
-  const rootNote = midiToNote(60 + pitchClass(chord.rootPc), spelling);
-  const rootName = formatNote({ letter: rootNote.letter, alter: rootNote.alter });
+  const rootPc = pitchClass(chord.rootPc);
+  const rootName = pitchClassName(rootPc, chord.rootSpelling, opts?.flats);
   const suffix = CANONICAL_SUFFIX[chord.quality];
   let symbol = `${rootName}${suffix}`;
-  if (chord.bassPc !== undefined && pitchClass(chord.bassPc) !== pitchClass(chord.rootPc)) {
-    const bassNote = midiToNote(60 + pitchClass(chord.bassPc), spelling);
-    symbol += `/${formatNote({ letter: bassNote.letter, alter: bassNote.alter })}`;
+  if (chord.bassPc !== undefined && pitchClass(chord.bassPc) !== rootPc) {
+    symbol += `/${pitchClassName(pitchClass(chord.bassPc), chord.bassSpelling, opts?.flats)}`;
   }
   return symbol;
 }
@@ -198,6 +240,12 @@ export function formatChordSymbol(chord: Chord, opts?: { flats?: boolean }): str
  * @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
  */
 export function transposeChordSymbol(
   text: string,

package/src/timeline/index.ts

@@ -10,14 +10,22 @@ import type { GeneratedChord } from '../progression/index.js';
 import { isScaleTone, majorKey } from '../scale/index.js';
 import type { KeyScale, NoteEvent } from '../types.js';
 
-/** A chord occupying a half-open beat span. */
+/**
+ * A chord occupying a half-open beat span.
+ *
+ * @category Arrangement & Analysis
+ */
 export type ChordSegment = {
   startBeat: number;
   endBeat: number;
   chord: Chord;
 };
 
-/** A beat-indexed sequence of chord segments. */
+/**
+ * A beat-indexed sequence of chord segments.
+ *
+ * @category Arrangement & Analysis
+ */
 export type ChordTimeline = {
   /** The chord sounding at a beat, or null when no segment covers it. */
   at: (beat: number) => Chord | null;
@@ -35,6 +43,7 @@ export 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
  */
 export function chordTimelineFromChords(
   chords: GeneratedChord[],
@@ -96,19 +105,39 @@ function pitchClass(value: number): number {
   return ((Math.trunc(value) % 12) + 12) % 12;
 }
 
-/** Options controlling {@link chordTimelineFromNotes}. */
+/**
+ * Options controlling {@link chordTimelineFromNotes}.
+ *
+ * @category Arrangement & Analysis
+ */
 export 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
+ */
 export type ChordTimelineResult = {
   /** The inferred timeline, with adjacent identical chords merged. */
   timeline: ChordTimeline;
@@ -266,10 +295,26 @@ function sameChord(a: Chord, b: Chord): boolean {
  * 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
  */
 export function chordTimelineFromNotes(
   notes: NoteEvent[],
@@ -280,9 +325,11 @@ export function chordTimelineFromNotes(
   if (!(harmonicRhythm > 0)) {
     throw new Error(`Invalid harmonic rhythm: ${harmonicRhythm}`);
   }
-  const lastNoteEnd = notes.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), 0);
+  // Zero/negative-length notes never sound; drop them before any inference.
+  const sounding = notes.filter((note) => note.durationBeat > 0);
+  const lastNoteEnd = sounding.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), 0);
   const totalBeats = opts.totalBeats ?? lastNoteEnd;
-  const key = opts.key ?? detectKey(notes.map((n) => n.pitch))[0]?.key ?? majorKey(0);
+  const key = opts.key ?? detectKey(sounding.map((n) => n.pitch))[0]?.key ?? majorKey(0);
 
   const segments: ChordSegment[] = [];
   const segmentConfidence: number[] = [];
@@ -290,7 +337,7 @@ export function chordTimelineFromNotes(
   for (let i = 0; i < windowCount; i += 1) {
     const start = i * harmonicRhythm;
     const end = Math.min(start + harmonicRhythm, totalBeats);
-    const inferred = analyzeWindow(notes, start, end, ts, key);
+    const inferred = analyzeWindow(sounding, start, end, ts, key);
     if (!inferred) {
       continue;
     }
@@ -316,7 +363,11 @@ export function chordTimelineFromNotes(
   };
 }
 
-/** A cadence found between two consecutive timeline segments. */
+/**
+ * A cadence found between two consecutive timeline segments.
+ *
+ * @category Arrangement & Analysis
+ */
 export type CadenceHit = {
   /** The beat where the cadence arrives (the second chord's onset). */
   atBeat: number;
@@ -328,12 +379,25 @@ export 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
  */
 export function detectCadences(timeline: ChordTimeline, key: KeyScale): CadenceHit[] {
   const hits: CadenceHit[] = [];
@@ -343,6 +407,9 @@ export function detectCadences(timeline: ChordTimeline, key: KeyScale): CadenceH
     if (!prev || !cur) {
       continue;
     }
+    if (Math.abs(cur.startBeat - prev.endBeat) > EPS) {
+      continue; // A rest separates the chords; no cadential motion across it.
+    }
     const type = detectCadence(prev.chord, cur.chord, key);
     if (type !== null) {
       hits.push({ atBeat: cur.startBeat, type, from: prev.chord, to: cur.chord });